1 /** @file 2 Provides interface to shell functionality for shell commands and applications. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 Copyright 2018 Dell Technologies.<BR> 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 **/ 9 10 #ifndef __SHELL_LIB__ 11 #define __SHELL_LIB__ 12 13 #include <Uefi.h> 14 #include <Guid/FileInfo.h> 15 #include <Protocol/SimpleFileSystem.h> 16 #include <Protocol/LoadedImage.h> 17 #include <Protocol/EfiShellInterface.h> 18 #include <Protocol/EfiShellEnvironment2.h> 19 #include <Protocol/Shell.h> 20 #include <Protocol/ShellParameters.h> 21 22 #define SHELL_FREE_NON_NULL(Pointer) \ 23 do { \ 24 if ((Pointer) != NULL) { \ 25 FreePool((Pointer)); \ 26 (Pointer) = NULL; \ 27 } \ 28 } while(FALSE) 29 30 extern EFI_SHELL_PARAMETERS_PROTOCOL *gEfiShellParametersProtocol; 31 extern EFI_SHELL_PROTOCOL *gEfiShellProtocol; 32 33 /** 34 Return a clean, fully-qualified version of an input path. If the return value 35 is non-NULL the caller must free the memory when it is no longer needed. 36 37 If asserts are disabled, and if the input parameter is NULL, NULL is returned. 38 39 If there is not enough memory available to create the fully-qualified path or 40 a copy of the input path, NULL is returned. 41 42 If there is no working directory, a clean copy of Path is returned. 43 44 Otherwise, the current file system or working directory (as appropriate) is 45 prepended to Path and the resulting path is cleaned and returned. 46 47 NOTE: If the input path is an empty string, then the current working directory 48 (if it exists) is returned. In other words, an empty input path is treated 49 exactly the same as ".". 50 51 @param[in] Path A pointer to some file or directory path. 52 53 @retval NULL The input path is NULL or out of memory. 54 55 @retval non-NULL A pointer to a clean, fully-qualified version of Path. 56 If there is no working directory, then a pointer to a 57 clean, but not necessarily fully-qualified version of 58 Path. The caller must free this memory when it is no 59 longer needed. 60 **/ 61 CHAR16* 62 EFIAPI 63 FullyQualifyPath( 64 IN CONST CHAR16 *Path 65 ); 66 67 /** 68 This function will retrieve the information about the file for the handle 69 specified and store it in allocated pool memory. 70 71 This function allocates a buffer to store the file's information. It is the 72 caller's responsibility to free the buffer. 73 74 @param[in] FileHandle The file handle of the file for which information is 75 being requested. 76 77 @retval NULL Information could not be retrieved. 78 79 @return The information about the file. 80 **/ 81 EFI_FILE_INFO* 82 EFIAPI 83 ShellGetFileInfo ( 84 IN SHELL_FILE_HANDLE FileHandle 85 ); 86 87 /** 88 This function sets the information about the file for the opened handle 89 specified. 90 91 @param[in] FileHandle The file handle of the file for which information 92 is being set. 93 94 @param[in] FileInfo The information to set. 95 96 @retval EFI_SUCCESS The information was set. 97 @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. 98 @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. 99 @retval EFI_NO_MEDIA The device has no medium. 100 @retval EFI_DEVICE_ERROR The device reported an error. 101 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 102 @retval EFI_WRITE_PROTECTED The file or medium is write protected. 103 @retval EFI_ACCESS_DENIED The file was opened read only. 104 @retval EFI_VOLUME_FULL The volume is full. 105 **/ 106 EFI_STATUS 107 EFIAPI 108 ShellSetFileInfo ( 109 IN SHELL_FILE_HANDLE FileHandle, 110 IN EFI_FILE_INFO *FileInfo 111 ); 112 113 /** 114 This function will open a file or directory referenced by DevicePath. 115 116 This function opens a file with the open mode according to the file path. The 117 Attributes is valid only for EFI_FILE_MODE_CREATE. 118 119 @param[in, out] FilePath On input, the device path to the file. On output, 120 the remaining device path. 121 @param[out] FileHandle Pointer to the file handle. 122 @param[in] OpenMode The mode to open the file with. 123 @param[in] Attributes The file's file attributes. 124 125 @retval EFI_SUCCESS The information was set. 126 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. 127 @retval EFI_UNSUPPORTED Could not open the file path. 128 @retval EFI_NOT_FOUND The specified file could not be found on the 129 device or the file system could not be found on 130 the device. 131 @retval EFI_NO_MEDIA The device has no medium. 132 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the 133 medium is no longer supported. 134 @retval EFI_DEVICE_ERROR The device reported an error. 135 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 136 @retval EFI_WRITE_PROTECTED The file or medium is write protected. 137 @retval EFI_ACCESS_DENIED The file was opened read only. 138 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the 139 file. 140 @retval EFI_VOLUME_FULL The volume is full. 141 **/ 142 EFI_STATUS 143 EFIAPI 144 ShellOpenFileByDevicePath( 145 IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, 146 OUT SHELL_FILE_HANDLE *FileHandle, 147 IN UINT64 OpenMode, 148 IN UINT64 Attributes 149 ); 150 151 /** 152 This function will open a file or directory referenced by filename. 153 154 If return is EFI_SUCCESS, the Filehandle is the opened file's handle; 155 otherwise, the Filehandle is NULL. Attributes is valid only for 156 EFI_FILE_MODE_CREATE. 157 158 @param[in] FileName The pointer to file name. 159 @param[out] FileHandle The pointer to the file handle. 160 @param[in] OpenMode The mode to open the file with. 161 @param[in] Attributes The file's file attributes. 162 163 @retval EFI_SUCCESS The information was set. 164 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. 165 @retval EFI_UNSUPPORTED Could not open the file path. 166 @retval EFI_NOT_FOUND The specified file could not be found on the 167 device or the file system could not be found 168 on the device. 169 @retval EFI_NO_MEDIA The device has no medium. 170 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the 171 medium is no longer supported. 172 @retval EFI_DEVICE_ERROR The device reported an error. 173 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 174 @retval EFI_WRITE_PROTECTED The file or medium is write protected. 175 @retval EFI_ACCESS_DENIED The file was opened read only. 176 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the 177 file. 178 @retval EFI_VOLUME_FULL The volume is full. 179 **/ 180 EFI_STATUS 181 EFIAPI 182 ShellOpenFileByName( 183 IN CONST CHAR16 *FileName, 184 OUT SHELL_FILE_HANDLE *FileHandle, 185 IN UINT64 OpenMode, 186 IN UINT64 Attributes 187 ); 188 189 /** 190 This function creates a directory. 191 192 If return is EFI_SUCCESS, the Filehandle is the opened directory's handle; 193 otherwise, the Filehandle is NULL. If the directory already existed, this 194 function opens the existing directory. 195 196 @param[in] DirectoryName The pointer to Directory name. 197 @param[out] FileHandle The pointer to the file handle. 198 199 @retval EFI_SUCCESS The information was set. 200 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. 201 @retval EFI_UNSUPPORTED Could not open the file path. 202 @retval EFI_NOT_FOUND The specified file could not be found on the 203 device, or the file system could not be found 204 on the device. 205 @retval EFI_NO_MEDIA The device has no medium. 206 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the 207 medium is no longer supported. 208 @retval EFI_DEVICE_ERROR The device reported an error. 209 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 210 @retval EFI_WRITE_PROTECTED The file or medium is write protected. 211 @retval EFI_ACCESS_DENIED The file was opened read only. 212 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the 213 file. 214 @retval EFI_VOLUME_FULL The volume is full. 215 **/ 216 EFI_STATUS 217 EFIAPI 218 ShellCreateDirectory( 219 IN CONST CHAR16 *DirectoryName, 220 OUT SHELL_FILE_HANDLE *FileHandle 221 ); 222 223 /** 224 This function reads information from an opened file. 225 226 If FileHandle is not a directory, the function reads the requested number of 227 bytes from the file at the file's current position and returns them in Buffer. 228 If the read goes beyond the end of the file, the read length is truncated to the 229 end of the file. The file's current position is increased by the number of bytes 230 returned. If FileHandle is a directory, the function reads the directory entry 231 at the file's current position and returns the entry in Buffer. If the Buffer 232 is not large enough to hold the current directory entry, then 233 EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. 234 BufferSize is set to be the size of the buffer needed to read the entry. On 235 success, the current position is updated to the next directory entry. If there 236 are no more directory entries, the read returns a zero-length buffer. 237 EFI_FILE_INFO is the structure returned as the directory entry. 238 239 @param[in] FileHandle The opened file handle. 240 @param[in, out] ReadSize On input the size of buffer in bytes. On return 241 the number of bytes written. 242 @param[out] Buffer The buffer to put read data into. 243 244 @retval EFI_SUCCESS Data was read. 245 @retval EFI_NO_MEDIA The device has no media. 246 @retval EFI_DEVICE_ERROR The device reported an error. 247 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 248 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required 249 size. 250 251 **/ 252 EFI_STATUS 253 EFIAPI 254 ShellReadFile( 255 IN SHELL_FILE_HANDLE FileHandle, 256 IN OUT UINTN *ReadSize, 257 OUT VOID *Buffer 258 ); 259 260 /** 261 Write data to a file. 262 263 This function writes the specified number of bytes to the file at the current 264 file position. The current file position is advanced the actual number of bytes 265 written, which is returned in BufferSize. Partial writes only occur when there 266 has been a data error during the write attempt (such as "volume space full"). 267 The file is automatically grown to hold the data if required. Direct writes to 268 opened directories are not supported. 269 270 @param[in] FileHandle The opened file for writing. 271 272 @param[in, out] BufferSize On input the number of bytes in Buffer. On output 273 the number of bytes written. 274 275 @param[in] Buffer The buffer containing data to write is stored. 276 277 @retval EFI_SUCCESS Data was written. 278 @retval EFI_UNSUPPORTED Writes to an open directory are not supported. 279 @retval EFI_NO_MEDIA The device has no media. 280 @retval EFI_DEVICE_ERROR The device reported an error. 281 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 282 @retval EFI_WRITE_PROTECTED The device is write-protected. 283 @retval EFI_ACCESS_DENIED The file was open for read only. 284 @retval EFI_VOLUME_FULL The volume is full. 285 **/ 286 EFI_STATUS 287 EFIAPI 288 ShellWriteFile( 289 IN SHELL_FILE_HANDLE FileHandle, 290 IN OUT UINTN *BufferSize, 291 IN VOID *Buffer 292 ); 293 294 /** 295 Close an open file handle. 296 297 This function closes a specified file handle. All "dirty" cached file data is 298 flushed to the device, and the file is closed. In all cases the handle is 299 closed. 300 301 @param[in] FileHandle The file handle to close. 302 303 @retval EFI_SUCCESS The file handle was closed sucessfully. 304 @retval INVALID_PARAMETER One of the parameters has an invalid value. 305 **/ 306 EFI_STATUS 307 EFIAPI 308 ShellCloseFile ( 309 IN SHELL_FILE_HANDLE *FileHandle 310 ); 311 312 /** 313 Delete a file and close the handle 314 315 This function closes and deletes a file. In all cases the file handle is closed. 316 If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is 317 returned, but the handle is still closed. 318 319 @param[in] FileHandle The file handle to delete. 320 321 @retval EFI_SUCCESS The file was closed sucessfully. 322 @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not 323 deleted. 324 @retval INVALID_PARAMETER One of the parameters has an invalid value. 325 **/ 326 EFI_STATUS 327 EFIAPI 328 ShellDeleteFile ( 329 IN SHELL_FILE_HANDLE *FileHandle 330 ); 331 332 /** 333 Set the current position in a file. 334 335 This function sets the current file position for the handle to the position 336 supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only 337 absolute positioning is supported, and moving past the end of the file is 338 allowed (a subsequent write would grow the file). Moving to position 339 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file. 340 If FileHandle is a directory, the only position that may be set is zero. This 341 has the effect of starting the read process of the directory entries over. 342 343 @param[in] FileHandle The file handle on which the position is being set. 344 345 @param[in] Position The byte position from the begining of the file. 346 347 @retval EFI_SUCCESS Operation completed sucessfully. 348 @retval EFI_UNSUPPORTED The seek request for non-zero is not valid on 349 directories. 350 @retval INVALID_PARAMETER One of the parameters has an invalid value. 351 **/ 352 EFI_STATUS 353 EFIAPI 354 ShellSetFilePosition ( 355 IN SHELL_FILE_HANDLE FileHandle, 356 IN UINT64 Position 357 ); 358 359 /** 360 Gets a file's current position 361 362 This function retrieves the current file position for the file handle. For 363 directories, the current file position has no meaning outside of the file 364 system driver and as such the operation is not supported. An error is returned 365 if FileHandle is a directory. 366 367 @param[in] FileHandle The open file handle on which to get the position. 368 @param[out] Position The byte position from the begining of the file. 369 370 @retval EFI_SUCCESS The operation completed sucessfully. 371 @retval INVALID_PARAMETER One of the parameters has an invalid value. 372 @retval EFI_UNSUPPORTED The request is not valid on directories. 373 **/ 374 EFI_STATUS 375 EFIAPI 376 ShellGetFilePosition ( 377 IN SHELL_FILE_HANDLE FileHandle, 378 OUT UINT64 *Position 379 ); 380 381 /** 382 Flushes data on a file 383 384 This function flushes all modified data associated with a file to a device. 385 386 @param[in] FileHandle The file handle on which to flush data. 387 388 @retval EFI_SUCCESS The data was flushed. 389 @retval EFI_NO_MEDIA The device has no media. 390 @retval EFI_DEVICE_ERROR The device reported an error. 391 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 392 @retval EFI_WRITE_PROTECTED The file or medium is write protected. 393 @retval EFI_ACCESS_DENIED The file was opened for read only. 394 **/ 395 EFI_STATUS 396 EFIAPI 397 ShellFlushFile ( 398 IN SHELL_FILE_HANDLE FileHandle 399 ); 400 401 /** Retrieve first entry from a directory. 402 403 This function takes an open directory handle and gets information from the 404 first entry in the directory. A buffer is allocated to contain 405 the information and a pointer to the buffer is returned in *Buffer. The 406 caller can use ShellFindNextFile() to get subsequent directory entries. 407 408 The buffer will be freed by ShellFindNextFile() when the last directory 409 entry is read. Otherwise, the caller must free the buffer, using FreePool, 410 when finished with it. 411 412 @param[in] DirHandle The file handle of the directory to search. 413 @param[out] Buffer The pointer to the buffer for the file's information. 414 415 @retval EFI_SUCCESS Found the first file. 416 @retval EFI_NOT_FOUND Cannot find the directory. 417 @retval EFI_NO_MEDIA The device has no media. 418 @retval EFI_DEVICE_ERROR The device reported an error. 419 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 420 @return Others Status of ShellGetFileInfo, ShellSetFilePosition, 421 or ShellReadFile. 422 423 @sa ShellReadFile 424 **/ 425 EFI_STATUS 426 EFIAPI 427 ShellFindFirstFile ( 428 IN SHELL_FILE_HANDLE DirHandle, 429 OUT EFI_FILE_INFO **Buffer 430 ); 431 432 /** Retrieve next entries from a directory. 433 434 To use this function, the caller must first call the ShellFindFirstFile() 435 function to get the first directory entry. Subsequent directory entries are 436 retrieved by using the ShellFindNextFile() function. This function can 437 be called several times to get each entry from the directory. If the call of 438 ShellFindNextFile() retrieved the last directory entry, the next call of 439 this function will set *NoFile to TRUE and free the buffer. 440 441 @param[in] DirHandle The file handle of the directory. 442 @param[in, out] Buffer The pointer to buffer for file's information. 443 @param[in, out] NoFile The pointer to boolean when last file is found. 444 445 @retval EFI_SUCCESS Found the next file. 446 @retval EFI_NO_MEDIA The device has no media. 447 @retval EFI_DEVICE_ERROR The device reported an error. 448 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 449 450 @sa ShellReadFile 451 **/ 452 EFI_STATUS 453 EFIAPI 454 ShellFindNextFile( 455 IN SHELL_FILE_HANDLE DirHandle, 456 IN OUT EFI_FILE_INFO *Buffer, 457 IN OUT BOOLEAN *NoFile 458 ); 459 460 /** 461 Retrieve the size of a file. 462 463 This function extracts the file size info from the FileHandle's EFI_FILE_INFO 464 data. 465 466 @param[in] FileHandle The file handle from which size is retrieved. 467 @param[out] Size The pointer to size. 468 469 @retval EFI_SUCCESS The operation was completed sucessfully. 470 @retval EFI_DEVICE_ERROR Cannot access the file. 471 **/ 472 EFI_STATUS 473 EFIAPI 474 ShellGetFileSize ( 475 IN SHELL_FILE_HANDLE FileHandle, 476 OUT UINT64 *Size 477 ); 478 479 /** 480 Retrieves the status of the break execution flag 481 482 This function is useful to check whether the application is being asked to halt by the shell. 483 484 @retval TRUE The execution break is enabled. 485 @retval FALSE The execution break is not enabled. 486 **/ 487 BOOLEAN 488 EFIAPI 489 ShellGetExecutionBreakFlag( 490 VOID 491 ); 492 493 /** 494 Return the value of an environment variable. 495 496 This function gets the value of the environment variable set by the 497 ShellSetEnvironmentVariable function. 498 499 @param[in] EnvKey The key name of the environment variable. 500 501 @retval NULL The named environment variable does not exist. 502 @return != NULL The pointer to the value of the environment variable. 503 **/ 504 CONST CHAR16* 505 EFIAPI 506 ShellGetEnvironmentVariable ( 507 IN CONST CHAR16 *EnvKey 508 ); 509 510 /** 511 Set the value of an environment variable. 512 513 This function changes the current value of the specified environment variable. If the 514 environment variable exists and the Value is an empty string, then the environment 515 variable is deleted. If the environment variable exists and the Value is not an empty 516 string, then the value of the environment variable is changed. If the environment 517 variable does not exist and the Value is an empty string, there is no action. If the 518 environment variable does not exist and the Value is a non-empty string, then the 519 environment variable is created and assigned the specified value. 520 521 This is not supported pre-UEFI Shell 2.0. 522 523 @param[in] EnvKey The key name of the environment variable. 524 @param[in] EnvVal The Value of the environment variable 525 @param[in] Volatile Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE). 526 527 @retval EFI_SUCCESS The operation completed sucessfully 528 @retval EFI_UNSUPPORTED This operation is not allowed in pre-UEFI 2.0 Shell environments. 529 **/ 530 EFI_STATUS 531 EFIAPI 532 ShellSetEnvironmentVariable ( 533 IN CONST CHAR16 *EnvKey, 534 IN CONST CHAR16 *EnvVal, 535 IN BOOLEAN Volatile 536 ); 537 538 /** 539 Cause the shell to parse and execute a command line. 540 541 This function creates a nested instance of the shell and executes the specified 542 command (CommandLine) with the specified environment (Environment). Upon return, 543 the status code returned by the specified command is placed in StatusCode. 544 If Environment is NULL, then the current environment is used and all changes made 545 by the commands executed will be reflected in the current environment. If the 546 Environment is non-NULL, then the changes made will be discarded. 547 The CommandLine is executed from the current working directory on the current 548 device. 549 550 The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0 551 environment. The values pointed to by the parameters will be unchanged by the 552 ShellExecute() function. The Output parameter has no effect in a 553 UEFI Shell 2.0 environment. 554 555 @param[in] ParentHandle The parent image starting the operation. 556 @param[in] CommandLine The pointer to a NULL terminated command line. 557 @param[in] Output True to display debug output. False to hide it. 558 @param[in] EnvironmentVariables Optional pointer to array of environment variables 559 in the form "x=y". If NULL, the current set is used. 560 @param[out] Status The status of the run command line. 561 562 @retval EFI_SUCCESS The operation completed sucessfully. Status 563 contains the status code returned. 564 @retval EFI_INVALID_PARAMETER A parameter contains an invalid value. 565 @retval EFI_OUT_OF_RESOURCES Out of resources. 566 @retval EFI_UNSUPPORTED The operation is not allowed. 567 **/ 568 EFI_STATUS 569 EFIAPI 570 ShellExecute ( 571 IN EFI_HANDLE *ParentHandle, 572 IN CHAR16 *CommandLine, 573 IN BOOLEAN Output, 574 IN CHAR16 **EnvironmentVariables, 575 OUT EFI_STATUS *Status 576 ); 577 578 /** 579 Retreives the current directory path. 580 581 If the DeviceName is NULL, it returns the current device's current directory 582 name. If the DeviceName is not NULL, it returns the current directory name 583 on specified drive. 584 585 Note that the current directory string should exclude the tailing backslash character. 586 587 @param[in] DeviceName The name of the file system to get directory on. 588 589 @retval NULL The directory does not exist. 590 @retval != NULL The directory. 591 **/ 592 CONST CHAR16* 593 EFIAPI 594 ShellGetCurrentDir ( 595 IN CHAR16 * CONST DeviceName OPTIONAL 596 ); 597 598 /** 599 Sets (enabled or disabled) the page break mode. 600 601 When page break mode is enabled the screen will stop scrolling 602 and wait for operator input before scrolling a subsequent screen. 603 604 @param[in] CurrentState TRUE to enable and FALSE to disable. 605 **/ 606 VOID 607 EFIAPI 608 ShellSetPageBreakMode ( 609 IN BOOLEAN CurrentState 610 ); 611 612 /** 613 Opens a group of files based on a path. 614 615 This function uses the Arg to open all the matching files. Each matched 616 file has a SHELL_FILE_ARG structure to record the file information. These 617 structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG 618 structures from ListHead to access each file. This function supports wildcards 619 and will process '?' and '*' as such. The list must be freed with a call to 620 ShellCloseFileMetaArg(). 621 622 If you are NOT appending to an existing list *ListHead must be NULL. If 623 *ListHead is NULL then it must be callee freed. 624 625 @param[in] Arg The pointer to path string. 626 @param[in] OpenMode Mode to open files with. 627 @param[in, out] ListHead Head of linked list of results. 628 629 @retval EFI_SUCCESS The operation was sucessful and the list head 630 contains the list of opened files. 631 @retval != EFI_SUCCESS The operation failed. 632 633 @sa InternalShellConvertFileListType 634 **/ 635 EFI_STATUS 636 EFIAPI 637 ShellOpenFileMetaArg ( 638 IN CHAR16 *Arg, 639 IN UINT64 OpenMode, 640 IN OUT EFI_SHELL_FILE_INFO **ListHead 641 ); 642 643 /** 644 Free the linked list returned from ShellOpenFileMetaArg. 645 646 @param[in, out] ListHead The pointer to free. 647 648 @retval EFI_SUCCESS The operation was sucessful. 649 @retval EFI_INVALID_PARAMETER A parameter was invalid. 650 **/ 651 EFI_STATUS 652 EFIAPI 653 ShellCloseFileMetaArg ( 654 IN OUT EFI_SHELL_FILE_INFO **ListHead 655 ); 656 657 /** 658 Find a file by searching the CWD and then the path. 659 660 If FileName is NULL, then ASSERT. 661 662 If the return value is not NULL then the memory must be caller freed. 663 664 @param[in] FileName Filename string. 665 666 @retval NULL The file was not found. 667 @retval !NULL The path to the file. 668 **/ 669 CHAR16 * 670 EFIAPI 671 ShellFindFilePath ( 672 IN CONST CHAR16 *FileName 673 ); 674 675 /** 676 Find a file by searching the CWD and then the path with a variable set of file 677 extensions. If the file is not found it will append each extension in the list 678 in the order provided and return the first one that is successful. 679 680 If FileName is NULL, then ASSERT. 681 If FileExtension is NULL, then the behavior is identical to ShellFindFilePath. 682 683 If the return value is not NULL then the memory must be caller freed. 684 685 @param[in] FileName The filename string. 686 @param[in] FileExtension Semicolon delimited list of possible extensions. 687 688 @retval NULL The file was not found. 689 @retval !NULL The path to the file. 690 **/ 691 CHAR16 * 692 EFIAPI 693 ShellFindFilePathEx ( 694 IN CONST CHAR16 *FileName, 695 IN CONST CHAR16 *FileExtension 696 ); 697 698 typedef enum { 699 TypeFlag = 0, ///< A flag that is present or not present only (IE "-a"). 700 TypeValue, ///< A flag that has some data following it with a space (IE "-a 1"). 701 TypePosition, ///< Some data that did not follow a parameter (IE "filename.txt"). 702 TypeStart, ///< A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...). 703 TypeDoubleValue, ///< A flag that has 2 space seperated value data following it (IE "-a 1 2"). 704 TypeMaxValue, ///< A flag followed by all the command line data before the next flag. 705 TypeTimeValue, ///< A flag that has a time value following it (IE "-a -5:00"). 706 TypeMax, 707 } SHELL_PARAM_TYPE; 708 709 typedef struct { 710 CHAR16 *Name; 711 SHELL_PARAM_TYPE Type; 712 } SHELL_PARAM_ITEM; 713 714 715 /// Helper structure for no parameters (besides -? and -b) 716 extern SHELL_PARAM_ITEM EmptyParamList[]; 717 718 /// Helper structure for -sfo only (besides -? and -b) 719 extern SHELL_PARAM_ITEM SfoParamList[]; 720 721 /** 722 Checks the command line arguments passed against the list of valid ones. 723 Optionally removes NULL values first. 724 725 If no initialization is required, then return RETURN_SUCCESS. 726 727 @param[in] CheckList The pointer to list of parameters to check. 728 @param[out] CheckPackage The package of checked values. 729 @param[out] ProblemParam Optional pointer to pointer to unicode string for 730 the paramater that caused failure. 731 @param[in] AutoPageBreak Will automatically set PageBreakEnabled. 732 @param[in] AlwaysAllowNumbers Will never fail for number based flags. 733 734 @retval EFI_SUCCESS The operation completed sucessfully. 735 @retval EFI_OUT_OF_RESOURCES A memory allocation failed. 736 @retval EFI_INVALID_PARAMETER A parameter was invalid. 737 @retval EFI_VOLUME_CORRUPTED The command line was corrupt. 738 @retval EFI_DEVICE_ERROR The commands contained 2 opposing arguments. One 739 of the command line arguments was returned in 740 ProblemParam if provided. 741 @retval EFI_NOT_FOUND A argument required a value that was missing. 742 The invalid command line argument was returned in 743 ProblemParam if provided. 744 **/ 745 EFI_STATUS 746 EFIAPI 747 ShellCommandLineParseEx ( 748 IN CONST SHELL_PARAM_ITEM *CheckList, 749 OUT LIST_ENTRY **CheckPackage, 750 OUT CHAR16 **ProblemParam OPTIONAL, 751 IN BOOLEAN AutoPageBreak, 752 IN BOOLEAN AlwaysAllowNumbers 753 ); 754 755 /// Make it easy to upgrade from older versions of the shell library. 756 #define ShellCommandLineParse(CheckList,CheckPackage,ProblemParam,AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE) 757 758 /** 759 Frees shell variable list that was returned from ShellCommandLineParse. 760 761 This function will free all the memory that was used for the CheckPackage 762 list of postprocessed shell arguments. 763 764 If CheckPackage is NULL, then return. 765 766 @param[in] CheckPackage The list to de-allocate. 767 **/ 768 VOID 769 EFIAPI 770 ShellCommandLineFreeVarList ( 771 IN LIST_ENTRY *CheckPackage 772 ); 773 774 /** 775 Checks for presence of a flag parameter. 776 777 Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key. 778 779 If CheckPackage is NULL then return FALSE. 780 If KeyString is NULL then ASSERT(). 781 782 @param[in] CheckPackage The package of parsed command line arguments. 783 @param[in] KeyString The Key of the command line argument to check for. 784 785 @retval TRUE The flag is on the command line. 786 @retval FALSE The flag is not on the command line. 787 **/ 788 BOOLEAN 789 EFIAPI 790 ShellCommandLineGetFlag ( 791 IN CONST LIST_ENTRY * CONST CheckPackage, 792 IN CONST CHAR16 * CONST KeyString 793 ); 794 795 /** 796 Returns value from command line argument. 797 798 Value parameters are in the form of "-<Key> value" or "/<Key> value". 799 800 If CheckPackage is NULL, then return NULL. 801 802 @param[in] CheckPackage The package of parsed command line arguments. 803 @param[in] KeyString The Key of the command line argument to check for. 804 805 @retval NULL The flag is not on the command line. 806 @retval !=NULL The pointer to unicode string of the value. 807 **/ 808 CONST CHAR16* 809 EFIAPI 810 ShellCommandLineGetValue ( 811 IN CONST LIST_ENTRY *CheckPackage, 812 IN CHAR16 *KeyString 813 ); 814 815 /** 816 Returns raw value from command line argument. 817 818 Raw value parameters are in the form of "value" in a specific position in the list. 819 820 If CheckPackage is NULL, then return NULL. 821 822 @param[in] CheckPackage The package of parsed command line arguments. 823 @param[in] Position The position of the value. 824 825 @retval NULL The flag is not on the command line. 826 @retval !=NULL The pointer to unicode string of the value. 827 **/ 828 CONST CHAR16* 829 EFIAPI 830 ShellCommandLineGetRawValue ( 831 IN CONST LIST_ENTRY * CONST CheckPackage, 832 IN UINTN Position 833 ); 834 835 /** 836 Returns the number of command line value parameters that were parsed. 837 838 This will not include flags. 839 840 @param[in] CheckPackage The package of parsed command line arguments. 841 842 @retval (UINTN)-1 No parsing has occurred. 843 @retval other The number of value parameters found. 844 **/ 845 UINTN 846 EFIAPI 847 ShellCommandLineGetCount( 848 IN CONST LIST_ENTRY *CheckPackage 849 ); 850 851 /** 852 Determines if a parameter is duplicated. 853 854 If Param is not NULL, then it will point to a callee-allocated string buffer 855 with the parameter value, if a duplicate is found. 856 857 If CheckPackage is NULL, then ASSERT. 858 859 @param[in] CheckPackage The package of parsed command line arguments. 860 @param[out] Param Upon finding one, a pointer to the duplicated parameter. 861 862 @retval EFI_SUCCESS No parameters were duplicated. 863 @retval EFI_DEVICE_ERROR A duplicate was found. 864 **/ 865 EFI_STATUS 866 EFIAPI 867 ShellCommandLineCheckDuplicate ( 868 IN CONST LIST_ENTRY *CheckPackage, 869 OUT CHAR16 **Param 870 ); 871 872 /** 873 This function causes the shell library to initialize itself. If the shell library 874 is already initialized it will de-initialize all the current protocol pointers and 875 re-populate them again. 876 877 When the library is used with PcdShellLibAutoInitialize set to true this function 878 will return EFI_SUCCESS and perform no actions. 879 880 This function is intended for internal access for shell commands only. 881 882 @retval EFI_SUCCESS The initialization was complete sucessfully. 883 884 **/ 885 EFI_STATUS 886 EFIAPI 887 ShellInitialize ( 888 VOID 889 ); 890 891 /** 892 Print at a specific location on the screen. 893 894 This function will move the cursor to a given screen location and print the specified string. 895 896 If -1 is specified for either the Row or Col the current screen location for BOTH 897 will be used. 898 899 If either Row or Col is out of range for the current console, then ASSERT. 900 If Format is NULL, then ASSERT. 901 902 In addition to the standard %-based flags as supported by UefiLib Print() this supports 903 the following additional flags: 904 %N - Set output attribute to normal 905 %H - Set output attribute to highlight 906 %E - Set output attribute to error 907 %B - Set output attribute to blue color 908 %V - Set output attribute to green color 909 910 Note: The background color is controlled by the shell command cls. 911 912 @param[in] Col The column to print at. 913 @param[in] Row The row to print at. 914 @param[in] Format The format string. 915 @param[in] ... The variable argument list. 916 917 @return EFI_SUCCESS The printing was successful. 918 @return EFI_DEVICE_ERROR The console device reported an error. 919 **/ 920 EFI_STATUS 921 EFIAPI 922 ShellPrintEx( 923 IN INT32 Col OPTIONAL, 924 IN INT32 Row OPTIONAL, 925 IN CONST CHAR16 *Format, 926 ... 927 ); 928 929 /** 930 Print at a specific location on the screen. 931 932 This function will move the cursor to a given screen location and print the specified string. 933 934 If -1 is specified for either the Row or Col the current screen location for BOTH 935 will be used. 936 937 If either Row or Col is out of range for the current console, then ASSERT. 938 If Format is NULL, then ASSERT. 939 940 In addition to the standard %-based flags as supported by UefiLib Print() this supports 941 the following additional flags: 942 %N - Set output attribute to normal. 943 %H - Set output attribute to highlight. 944 %E - Set output attribute to error. 945 %B - Set output attribute to blue color. 946 %V - Set output attribute to green color. 947 948 Note: The background color is controlled by the shell command cls. 949 950 @param[in] Col The column to print at. 951 @param[in] Row The row to print at. 952 @param[in] Language The language of the string to retrieve. If this parameter 953 is NULL, then the current platform language is used. 954 @param[in] HiiFormatStringId The format string Id for getting from Hii. 955 @param[in] HiiFormatHandle The format string Handle for getting from Hii. 956 @param[in] ... The variable argument list. 957 958 @return EFI_SUCCESS The printing was successful. 959 @return EFI_DEVICE_ERROR The console device reported an error. 960 **/ 961 EFI_STATUS 962 EFIAPI 963 ShellPrintHiiEx( 964 IN INT32 Col OPTIONAL, 965 IN INT32 Row OPTIONAL, 966 IN CONST CHAR8 *Language OPTIONAL, 967 IN CONST EFI_STRING_ID HiiFormatStringId, 968 IN CONST EFI_HANDLE HiiFormatHandle, 969 ... 970 ); 971 972 /** 973 Function to determine if a given filename represents a directory. 974 975 If DirName is NULL, then ASSERT. 976 977 @param[in] DirName Path to directory to test. 978 979 @retval EFI_SUCCESS The Path represents a directory. 980 @retval EFI_NOT_FOUND The Path does not represent a directory. 981 @retval other The path failed to open. 982 **/ 983 EFI_STATUS 984 EFIAPI 985 ShellIsDirectory( 986 IN CONST CHAR16 *DirName 987 ); 988 989 /** 990 Function to determine if a given filename represents a file. 991 992 This will search the CWD only. 993 994 If Name is NULL, then ASSERT. 995 996 @param[in] Name Path to file to test. 997 998 @retval EFI_SUCCESS The Path represents a file. 999 @retval EFI_NOT_FOUND The Path does not represent a file. 1000 @retval other The path failed to open. 1001 **/ 1002 EFI_STATUS 1003 EFIAPI 1004 ShellIsFile( 1005 IN CONST CHAR16 *Name 1006 ); 1007 1008 /** 1009 Function to determine if a given filename represents a file. 1010 1011 This will search the CWD and then the Path. 1012 1013 If Name is NULL, then ASSERT. 1014 1015 @param[in] Name Path to file to test. 1016 1017 @retval EFI_SUCCESS The Path represents a file. 1018 @retval EFI_NOT_FOUND The Path does not represent a file. 1019 @retval other The path failed to open. 1020 **/ 1021 EFI_STATUS 1022 EFIAPI 1023 ShellIsFileInPath( 1024 IN CONST CHAR16 *Name 1025 ); 1026 1027 /** 1028 Function to determine whether a string is decimal or hex representation of a number 1029 and return the number converted from the string. 1030 1031 Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid 1032 result. Use ShellConvertStringToUint64 instead. 1033 1034 @param[in] String String representation of a number. 1035 1036 @return The unsigned integer result of the conversion. 1037 @retval (UINTN)(-1) An error occured. 1038 **/ 1039 UINTN 1040 EFIAPI 1041 ShellStrToUintn( 1042 IN CONST CHAR16 *String 1043 ); 1044 1045 /** 1046 Function return the number converted from a hex representation of a number. 1047 1048 Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid 1049 result. Use ShellConvertStringToUint64 instead. 1050 1051 @param[in] String String representation of a number. 1052 1053 @return The unsigned integer result of the conversion. 1054 @retval (UINTN)(-1) An error occured. 1055 **/ 1056 UINTN 1057 EFIAPI 1058 ShellHexStrToUintn( 1059 IN CONST CHAR16 *String 1060 ); 1061 1062 /** 1063 Safely append with automatic string resizing given length of Destination and 1064 desired length of copy from Source. 1065 1066 Append the first D characters of Source to the end of Destination, where D is 1067 the lesser of Count and the StrLen() of Source. If appending those D characters 1068 will fit within Destination (whose Size is given as CurrentSize) and 1069 still leave room for a NULL terminator, then those characters are appended, 1070 starting at the original terminating NULL of Destination, and a new terminating 1071 NULL is appended. 1072 1073 If appending D characters onto Destination will result in a overflow of the size 1074 given in CurrentSize the string will be grown such that the copy can be performed 1075 and CurrentSize will be updated to the new size. 1076 1077 If Source is NULL, there is nothing to append, so return the current buffer in 1078 Destination. 1079 1080 If Destination is NULL, then ASSERT(). 1081 If Destination's current length (including NULL terminator) is already more than 1082 CurrentSize, then ASSERT(). 1083 1084 @param[in, out] Destination The String to append onto. 1085 @param[in, out] CurrentSize On call, the number of bytes in Destination. On 1086 return, possibly the new size (still in bytes). If NULL, 1087 then allocate whatever is needed. 1088 @param[in] Source The String to append from. 1089 @param[in] Count The maximum number of characters to append. If 0, then 1090 all are appended. 1091 1092 @return The Destination after appending the Source. 1093 **/ 1094 CHAR16* 1095 EFIAPI 1096 StrnCatGrow ( 1097 IN OUT CHAR16 **Destination, 1098 IN OUT UINTN *CurrentSize, 1099 IN CONST CHAR16 *Source, 1100 IN UINTN Count 1101 ); 1102 1103 /** 1104 This is a find and replace function. Upon successful return the NewString is a copy of 1105 SourceString with each instance of FindTarget replaced with ReplaceWith. 1106 1107 If SourceString and NewString overlap the behavior is undefined. 1108 1109 If the string would grow bigger than NewSize it will halt and return error. 1110 1111 @param[in] SourceString The string with source buffer. 1112 @param[in, out] NewString The string with resultant buffer. 1113 @param[in] NewSize The size in bytes of NewString. 1114 @param[in] FindTarget The string to look for. 1115 @param[in] ReplaceWith The string to replace FindTarget with. 1116 @param[in] SkipPreCarrot If TRUE will skip a FindTarget that has a '^' 1117 immediately before it. 1118 @param[in] ParameterReplacing If TRUE will add "" around items with spaces. 1119 1120 @retval EFI_INVALID_PARAMETER SourceString was NULL. 1121 @retval EFI_INVALID_PARAMETER NewString was NULL. 1122 @retval EFI_INVALID_PARAMETER FindTarget was NULL. 1123 @retval EFI_INVALID_PARAMETER ReplaceWith was NULL. 1124 @retval EFI_INVALID_PARAMETER FindTarget had length < 1. 1125 @retval EFI_INVALID_PARAMETER SourceString had length < 1. 1126 @retval EFI_BUFFER_TOO_SMALL NewSize was less than the minimum size to hold 1127 the new string (truncation occurred). 1128 @retval EFI_SUCCESS The string was successfully copied with replacement. 1129 **/ 1130 EFI_STATUS 1131 EFIAPI 1132 ShellCopySearchAndReplace( 1133 IN CHAR16 CONST *SourceString, 1134 IN OUT CHAR16 *NewString, 1135 IN UINTN NewSize, 1136 IN CONST CHAR16 *FindTarget, 1137 IN CONST CHAR16 *ReplaceWith, 1138 IN CONST BOOLEAN SkipPreCarrot, 1139 IN CONST BOOLEAN ParameterReplacing 1140 ); 1141 1142 /** 1143 Check if a Unicode character is a hexadecimal character. 1144 1145 This internal function checks if a Unicode character is a 1146 numeric character. The valid hexadecimal characters are 1147 L'0' to L'9', L'a' to L'f', or L'A' to L'F'. 1148 1149 1150 @param Char The character to check against. 1151 1152 @retval TRUE The Char is a hexadecmial character. 1153 @retval FALSE The Char is not a hexadecmial character. 1154 1155 **/ 1156 BOOLEAN 1157 EFIAPI 1158 ShellIsHexaDecimalDigitCharacter ( 1159 IN CHAR16 Char 1160 ); 1161 1162 /** 1163 Check if a Unicode character is a decimal character. 1164 1165 This internal function checks if a Unicode character is a 1166 decimal character. The valid characters are 1167 L'0' to L'9'. 1168 1169 1170 @param Char The character to check against. 1171 1172 @retval TRUE The Char is a hexadecmial character. 1173 @retval FALSE The Char is not a hexadecmial character. 1174 1175 **/ 1176 BOOLEAN 1177 EFIAPI 1178 ShellIsDecimalDigitCharacter ( 1179 IN CHAR16 Char 1180 ); 1181 1182 /// 1183 /// What type of answer is requested. 1184 /// 1185 typedef enum { 1186 ShellPromptResponseTypeYesNo, 1187 ShellPromptResponseTypeYesNoCancel, 1188 ShellPromptResponseTypeFreeform, 1189 ShellPromptResponseTypeQuitContinue, 1190 ShellPromptResponseTypeYesNoAllCancel, 1191 ShellPromptResponseTypeEnterContinue, 1192 ShellPromptResponseTypeAnyKeyContinue, 1193 ShellPromptResponseTypeMax 1194 } SHELL_PROMPT_REQUEST_TYPE; 1195 1196 /// 1197 /// What answer was given. 1198 /// 1199 typedef enum { 1200 ShellPromptResponseYes, 1201 ShellPromptResponseNo, 1202 ShellPromptResponseCancel, 1203 ShellPromptResponseQuit, 1204 ShellPromptResponseContinue, 1205 ShellPromptResponseAll, 1206 ShellPromptResponseMax 1207 } SHELL_PROMPT_RESPONSE; 1208 1209 /** 1210 Prompt the user and return the resultant answer to the requestor. 1211 1212 This function will display the requested question on the shell prompt and then 1213 wait for an appropriate answer to be input from the console. 1214 1215 If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue 1216 or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE. 1217 1218 If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type 1219 CHAR16*. 1220 1221 In either case *Response must be callee freed if Response was not NULL; 1222 1223 @param Type What type of question is asked. This is used to filter the input 1224 to prevent invalid answers to question. 1225 @param Prompt The pointer to a string prompt used to request input. 1226 @param Response The pointer to Response, which will be populated upon return. 1227 1228 @retval EFI_SUCCESS The operation was successful. 1229 @retval EFI_UNSUPPORTED The operation is not supported as requested. 1230 @retval EFI_INVALID_PARAMETER A parameter was invalid. 1231 @return other The operation failed. 1232 **/ 1233 EFI_STATUS 1234 EFIAPI 1235 ShellPromptForResponse ( 1236 IN SHELL_PROMPT_REQUEST_TYPE Type, 1237 IN CHAR16 *Prompt OPTIONAL, 1238 IN OUT VOID **Response OPTIONAL 1239 ); 1240 1241 /** 1242 Prompt the user and return the resultant answer to the requestor. 1243 1244 This function is the same as ShellPromptForResponse, except that the prompt is 1245 automatically pulled from HII. 1246 1247 @param[in] Type What type of question is asked. This is used to filter the input 1248 to prevent invalid answers to question. 1249 @param[in] HiiFormatStringId The format string Id for getting from Hii. 1250 @param[in] HiiFormatHandle The format string Handle for getting from Hii. 1251 @param[in, out] Response The pointer to Response, which will be populated upon return. 1252 1253 @retval EFI_SUCCESS The operation was sucessful. 1254 @return other The operation failed. 1255 1256 @sa ShellPromptForResponse 1257 **/ 1258 EFI_STATUS 1259 EFIAPI 1260 ShellPromptForResponseHii ( 1261 IN SHELL_PROMPT_REQUEST_TYPE Type, 1262 IN CONST EFI_STRING_ID HiiFormatStringId, 1263 IN CONST EFI_HANDLE HiiFormatHandle, 1264 IN OUT VOID **Response 1265 ); 1266 1267 /** 1268 Function to determin if an entire string is a valid number. 1269 1270 If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE. 1271 1272 @param[in] String The string to evaluate. 1273 @param[in] ForceHex TRUE - always assume hex. 1274 @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going. 1275 1276 @retval TRUE It is all numeric (dec/hex) characters. 1277 @retval FALSE There is a non-numeric character. 1278 **/ 1279 BOOLEAN 1280 EFIAPI 1281 ShellIsHexOrDecimalNumber ( 1282 IN CONST CHAR16 *String, 1283 IN CONST BOOLEAN ForceHex, 1284 IN CONST BOOLEAN StopAtSpace 1285 ); 1286 1287 /** 1288 Function to verify and convert a string to its numerical 64 bit representation. 1289 1290 If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE. 1291 1292 @param[in] String The string to evaluate. 1293 @param[out] Value Upon a successful return the value of the conversion. 1294 @param[in] ForceHex TRUE - always assume hex. 1295 @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to 1296 process the entire String. 1297 1298 @retval EFI_SUCCESS The conversion was successful. 1299 @retval EFI_INVALID_PARAMETER String contained an invalid character. 1300 @retval EFI_NOT_FOUND String was a number, but Value was NULL. 1301 **/ 1302 EFI_STATUS 1303 EFIAPI 1304 ShellConvertStringToUint64( 1305 IN CONST CHAR16 *String, 1306 OUT UINT64 *Value, 1307 IN CONST BOOLEAN ForceHex, 1308 IN CONST BOOLEAN StopAtSpace 1309 ); 1310 1311 /** 1312 Function to determine if a given filename exists. 1313 1314 @param[in] Name Path to test. 1315 1316 @retval EFI_SUCCESS The Path represents a file. 1317 @retval EFI_NOT_FOUND The Path does not represent a file. 1318 @retval other The path failed to open. 1319 **/ 1320 EFI_STATUS 1321 EFIAPI 1322 ShellFileExists( 1323 IN CONST CHAR16 *Name 1324 ); 1325 1326 /** 1327 Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned 1328 buffer. The returned buffer must be callee freed. 1329 1330 If the position upon start is 0, then the Ascii Boolean will be set. This should be 1331 maintained and not changed for all operations with the same file. 1332 1333 @param[in] Handle SHELL_FILE_HANDLE to read from. 1334 @param[in, out] Ascii Boolean value for indicating whether the file is 1335 Ascii (TRUE) or UCS2 (FALSE). 1336 1337 @return The line of text from the file. 1338 1339 @sa ShellFileHandleReadLine 1340 **/ 1341 CHAR16* 1342 EFIAPI 1343 ShellFileHandleReturnLine( 1344 IN SHELL_FILE_HANDLE Handle, 1345 IN OUT BOOLEAN *Ascii 1346 ); 1347 1348 /** 1349 Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE. 1350 1351 If the position upon start is 0, then the Ascii Boolean will be set. This should be 1352 maintained and not changed for all operations with the same file. 1353 1354 @param[in] Handle SHELL_FILE_HANDLE to read from. 1355 @param[in, out] Buffer The pointer to buffer to read into. 1356 @param[in, out] Size The pointer to number of bytes in Buffer. 1357 @param[in] Truncate If the buffer is large enough, this has no effect. 1358 If the buffer is is too small and Truncate is TRUE, 1359 the line will be truncated. 1360 If the buffer is is too small and Truncate is FALSE, 1361 then no read will occur. 1362 1363 @param[in, out] Ascii Boolean value for indicating whether the file is 1364 Ascii (TRUE) or UCS2 (FALSE). 1365 1366 @retval EFI_SUCCESS The operation was successful. The line is stored in 1367 Buffer. 1368 @retval EFI_END_OF_FILE There are no more lines in the file. 1369 @retval EFI_INVALID_PARAMETER Handle was NULL. 1370 @retval EFI_INVALID_PARAMETER Size was NULL. 1371 @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line. 1372 Size was updated to the minimum space required. 1373 **/ 1374 EFI_STATUS 1375 EFIAPI 1376 ShellFileHandleReadLine( 1377 IN SHELL_FILE_HANDLE Handle, 1378 IN OUT CHAR16 *Buffer, 1379 IN OUT UINTN *Size, 1380 IN BOOLEAN Truncate, 1381 IN OUT BOOLEAN *Ascii 1382 ); 1383 1384 /** 1385 Function to delete a file by name 1386 1387 @param[in] FileName Pointer to file name to delete. 1388 1389 @retval EFI_SUCCESS the file was deleted sucessfully 1390 @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not 1391 deleted 1392 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. 1393 @retval EFI_NOT_FOUND The specified file could not be found on the 1394 device or the file system could not be found 1395 on the device. 1396 @retval EFI_NO_MEDIA The device has no medium. 1397 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the 1398 medium is no longer supported. 1399 @retval EFI_DEVICE_ERROR The device reported an error. 1400 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 1401 @retval EFI_WRITE_PROTECTED The file or medium is write protected. 1402 @retval EFI_ACCESS_DENIED The file was opened read only. 1403 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the 1404 file. 1405 @retval other The file failed to open 1406 **/ 1407 EFI_STATUS 1408 EFIAPI 1409 ShellDeleteFileByName( 1410 IN CONST CHAR16 *FileName 1411 ); 1412 1413 /** 1414 Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function. 1415 1416 @param[in] CommandToGetHelpOn Pointer to a string containing the command name of help file to be printed. 1417 @param[in] SectionToGetHelpOn Pointer to the section specifier(s). 1418 @param[in] PrintCommandText If TRUE, prints the command followed by the help content, otherwise prints 1419 the help content only. 1420 @retval EFI_DEVICE_ERROR The help data format was incorrect. 1421 @retval EFI_NOT_FOUND The help data could not be found. 1422 @retval EFI_SUCCESS The operation was successful. 1423 **/ 1424 EFI_STATUS 1425 EFIAPI 1426 ShellPrintHelp ( 1427 IN CONST CHAR16 *CommandToGetHelpOn, 1428 IN CONST CHAR16 *SectionToGetHelpOn, 1429 IN BOOLEAN PrintCommandText 1430 ); 1431 1432 #endif // __SHELL_LIB__ 1433