VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellLib.h@ 107064

Last change on this file since 107064 was 105670, checked in by vboxsync, 6 months ago

Devices/EFI/FirmwareNew: Merge edk2-stable-202405 and make it build on aarch64, bugref:4643
  • Property svn:eol-style set to native
File size: 50.9 KB
Line 
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
30extern EFI_SHELL_PARAMETERS_PROTOCOL *gEfiShellParametersProtocol;
31extern 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**/
61CHAR16 *
62EFIAPI
63FullyQualifyPath (
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**/
81EFI_FILE_INFO *
82EFIAPI
83ShellGetFileInfo (
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**/
106EFI_STATUS
107EFIAPI
108ShellSetFileInfo (
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**/
142EFI_STATUS
143EFIAPI
144ShellOpenFileByDevicePath (
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**/
180EFI_STATUS
181EFIAPI
182ShellOpenFileByName (
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**/
216EFI_STATUS
217EFIAPI
218ShellCreateDirectory (
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**/
252EFI_STATUS
253EFIAPI
254ShellReadFile (
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**/
286EFI_STATUS
287EFIAPI
288ShellWriteFile (
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 successfully.
304 @retval INVALID_PARAMETER One of the parameters has an invalid value.
305**/
306EFI_STATUS
307EFIAPI
308ShellCloseFile (
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 successfully.
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**/
326EFI_STATUS
327EFIAPI
328ShellDeleteFile (
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 beginning of the file.
346
347 @retval EFI_SUCCESS Operation completed successfully.
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**/
352EFI_STATUS
353EFIAPI
354ShellSetFilePosition (
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 beginning of the file.
369
370 @retval EFI_SUCCESS The operation completed successfully.
371 @retval INVALID_PARAMETER One of the parameters has an invalid value.
372 @retval EFI_UNSUPPORTED The request is not valid on directories.
373**/
374EFI_STATUS
375EFIAPI
376ShellGetFilePosition (
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**/
395EFI_STATUS
396EFIAPI
397ShellFlushFile (
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**/
425EFI_STATUS
426EFIAPI
427ShellFindFirstFile (
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**/
452EFI_STATUS
453EFIAPI
454ShellFindNextFile (
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 successfully.
470 @retval EFI_DEVICE_ERROR Cannot access the file.
471**/
472EFI_STATUS
473EFIAPI
474ShellGetFileSize (
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**/
487BOOLEAN
488EFIAPI
489ShellGetExecutionBreakFlag (
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**/
504CONST CHAR16 *
505EFIAPI
506ShellGetEnvironmentVariable (
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 successfully
528 @retval EFI_UNSUPPORTED This operation is not allowed in pre-UEFI 2.0 Shell environments.
529**/
530EFI_STATUS
531EFIAPI
532ShellSetEnvironmentVariable (
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 successfully. 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**/
568EFI_STATUS
569EFIAPI
570ShellExecute (
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**/
592CONST CHAR16 *
593EFIAPI
594ShellGetCurrentDir (
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**/
606VOID
607EFIAPI
608ShellSetPageBreakMode (
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 successful and the list head
630 contains the list of opened files.
631 @retval != EFI_SUCCESS The operation failed.
632
633 @sa InternalShellConvertFileListType
634**/
635EFI_STATUS
636EFIAPI
637ShellOpenFileMetaArg (
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 successful.
649 @retval EFI_INVALID_PARAMETER A parameter was invalid.
650**/
651EFI_STATUS
652EFIAPI
653ShellCloseFileMetaArg (
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**/
669CHAR16 *
670EFIAPI
671ShellFindFilePath (
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**/
691CHAR16 *
692EFIAPI
693ShellFindFilePathEx (
694 IN CONST CHAR16 *FileName,
695 IN CONST CHAR16 *FileExtension
696 );
697
698typedef 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
709typedef struct {
710 CHAR16 *Name;
711 SHELL_PARAM_TYPE Type;
712} SHELL_PARAM_ITEM;
713
714/// Helper structure for no parameters (besides -? and -b)
715extern SHELL_PARAM_ITEM EmptyParamList[];
716
717/// Helper structure for -sfo only (besides -? and -b)
718extern SHELL_PARAM_ITEM SfoParamList[];
719
720/**
721 Checks the command line arguments passed against the list of valid ones.
722 Optionally removes NULL values first.
723
724 If no initialization is required, then return RETURN_SUCCESS.
725
726 @param[in] CheckList The pointer to list of parameters to check.
727 @param[out] CheckPackage The package of checked values.
728 @param[out] ProblemParam Optional pointer to pointer to unicode string for
729 the paramater that caused failure.
730 @param[in] AutoPageBreak Will automatically set PageBreakEnabled.
731 @param[in] AlwaysAllowNumbers Will never fail for number based flags.
732
733 @retval EFI_SUCCESS The operation completed successfully.
734 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
735 @retval EFI_INVALID_PARAMETER A parameter was invalid.
736 @retval EFI_VOLUME_CORRUPTED The command line was corrupt.
737 @retval EFI_DEVICE_ERROR The commands contained 2 opposing arguments. One
738 of the command line arguments was returned in
739 ProblemParam if provided.
740 @retval EFI_NOT_FOUND A argument required a value that was missing.
741 The invalid command line argument was returned in
742 ProblemParam if provided.
743**/
744EFI_STATUS
745EFIAPI
746ShellCommandLineParseEx (
747 IN CONST SHELL_PARAM_ITEM *CheckList,
748 OUT LIST_ENTRY **CheckPackage,
749 OUT CHAR16 **ProblemParam OPTIONAL,
750 IN BOOLEAN AutoPageBreak,
751 IN BOOLEAN AlwaysAllowNumbers
752 );
753
754/// Make it easy to upgrade from older versions of the shell library.
755#define ShellCommandLineParse(CheckList, CheckPackage, ProblemParam, AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)
756
757/**
758 Frees shell variable list that was returned from ShellCommandLineParse.
759
760 This function will free all the memory that was used for the CheckPackage
761 list of postprocessed shell arguments.
762
763 If CheckPackage is NULL, then return.
764
765 @param[in] CheckPackage The list to de-allocate.
766 **/
767VOID
768EFIAPI
769ShellCommandLineFreeVarList (
770 IN LIST_ENTRY *CheckPackage
771 );
772
773/**
774 Checks for presence of a flag parameter.
775
776 Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key.
777
778 If CheckPackage is NULL then return FALSE.
779 If KeyString is NULL then ASSERT().
780
781 @param[in] CheckPackage The package of parsed command line arguments.
782 @param[in] KeyString The Key of the command line argument to check for.
783
784 @retval TRUE The flag is on the command line.
785 @retval FALSE The flag is not on the command line.
786**/
787BOOLEAN
788EFIAPI
789ShellCommandLineGetFlag (
790 IN CONST LIST_ENTRY *CONST CheckPackage,
791 IN CONST CHAR16 *CONST KeyString
792 );
793
794/**
795 Returns value from command line argument.
796
797 Value parameters are in the form of "-<Key> value" or "/<Key> value".
798
799 If CheckPackage is NULL, then return NULL.
800
801 @param[in] CheckPackage The package of parsed command line arguments.
802 @param[in] KeyString The Key of the command line argument to check for.
803
804 @retval NULL The flag is not on the command line.
805 @retval !=NULL The pointer to unicode string of the value.
806**/
807CONST CHAR16 *
808EFIAPI
809ShellCommandLineGetValue (
810 IN CONST LIST_ENTRY *CheckPackage,
811 IN CHAR16 *KeyString
812 );
813
814/**
815 Returns raw value from command line argument.
816
817 Raw value parameters are in the form of "value" in a specific position in the list.
818
819 If CheckPackage is NULL, then return NULL.
820
821 @param[in] CheckPackage The package of parsed command line arguments.
822 @param[in] Position The position of the value.
823
824 @retval NULL The flag is not on the command line.
825 @retval !=NULL The pointer to unicode string of the value.
826**/
827CONST CHAR16 *
828EFIAPI
829ShellCommandLineGetRawValue (
830 IN CONST LIST_ENTRY *CONST CheckPackage,
831 IN UINTN Position
832 );
833
834/**
835 Returns the number of command line value parameters that were parsed.
836
837 This will not include flags.
838
839 @param[in] CheckPackage The package of parsed command line arguments.
840
841 @retval (UINTN)-1 No parsing has occurred.
842 @retval other The number of value parameters found.
843**/
844UINTN
845EFIAPI
846ShellCommandLineGetCount (
847 IN CONST LIST_ENTRY *CheckPackage
848 );
849
850/**
851 Determines if a parameter is duplicated.
852
853 If Param is not NULL, then it will point to a callee-allocated string buffer
854 with the parameter value, if a duplicate is found.
855
856 If CheckPackage is NULL, then ASSERT.
857
858 @param[in] CheckPackage The package of parsed command line arguments.
859 @param[out] Param Upon finding one, a pointer to the duplicated parameter.
860
861 @retval EFI_SUCCESS No parameters were duplicated.
862 @retval EFI_DEVICE_ERROR A duplicate was found.
863 **/
864EFI_STATUS
865EFIAPI
866ShellCommandLineCheckDuplicate (
867 IN CONST LIST_ENTRY *CheckPackage,
868 OUT CHAR16 **Param
869 );
870
871/**
872 This function causes the shell library to initialize itself. If the shell library
873 is already initialized it will de-initialize all the current protocol pointers and
874 re-populate them again.
875
876 When the library is used with PcdShellLibAutoInitialize set to true this function
877 will return EFI_SUCCESS and perform no actions.
878
879 This function is intended for internal access for shell commands only.
880
881 @retval EFI_SUCCESS The initialization was complete successfully.
882
883**/
884EFI_STATUS
885EFIAPI
886ShellInitialize (
887 VOID
888 );
889
890/**
891 Print at a specific location on the screen.
892
893 This function will move the cursor to a given screen location and print the specified string.
894
895 If -1 is specified for either the Row or Col the current screen location for BOTH
896 will be used.
897
898 If either Row or Col is out of range for the current console, then ASSERT.
899 If Format is NULL, then ASSERT.
900
901 In addition to the standard %-based flags as supported by UefiLib Print() this supports
902 the following additional flags:
903 %N - Set output attribute to normal
904 %H - Set output attribute to highlight
905 %E - Set output attribute to error
906 %B - Set output attribute to blue color
907 %V - Set output attribute to green color
908
909 Note: The background color is controlled by the shell command cls.
910
911 @param[in] Col The column to print at.
912 @param[in] Row The row to print at.
913 @param[in] Format The format string.
914 @param[in] ... The variable argument list.
915
916 @return EFI_SUCCESS The printing was successful.
917 @return EFI_DEVICE_ERROR The console device reported an error.
918**/
919EFI_STATUS
920EFIAPI
921ShellPrintEx (
922 IN INT32 Col OPTIONAL,
923 IN INT32 Row OPTIONAL,
924 IN CONST CHAR16 *Format,
925 ...
926 );
927
928/**
929 Print at a specific location on the screen.
930
931 This function will move the cursor to a given screen location and print the specified string.
932
933 If -1 is specified for either the Row or Col the current screen location for BOTH
934 will be used.
935
936 If either Row or Col is out of range for the current console, then ASSERT.
937 If Format is NULL, then ASSERT.
938
939 In addition to the standard %-based flags as supported by UefiLib Print() this supports
940 the following additional flags:
941 %N - Set output attribute to normal.
942 %H - Set output attribute to highlight.
943 %E - Set output attribute to error.
944 %B - Set output attribute to blue color.
945 %V - Set output attribute to green color.
946
947 Note: The background color is controlled by the shell command cls.
948
949 @param[in] Col The column to print at.
950 @param[in] Row The row to print at.
951 @param[in] Language The language of the string to retrieve. If this parameter
952 is NULL, then the current platform language is used.
953 @param[in] HiiFormatStringId The format string Id for getting from Hii.
954 @param[in] HiiFormatHandle The format string Handle for getting from Hii.
955 @param[in] ... The variable argument list.
956
957 @return EFI_SUCCESS The printing was successful.
958 @return EFI_DEVICE_ERROR The console device reported an error.
959**/
960EFI_STATUS
961EFIAPI
962ShellPrintHiiEx (
963 IN INT32 Col OPTIONAL,
964 IN INT32 Row OPTIONAL,
965 IN CONST CHAR8 *Language OPTIONAL,
966 IN CONST EFI_STRING_ID HiiFormatStringId,
967 IN CONST EFI_HII_HANDLE HiiFormatHandle,
968 ...
969 );
970
971/**
972 Function to determine if a given filename represents a directory.
973
974 If DirName is NULL, then ASSERT.
975
976 @param[in] DirName Path to directory to test.
977
978 @retval EFI_SUCCESS The Path represents a directory.
979 @retval EFI_NOT_FOUND The Path does not represent a directory.
980 @retval other The path failed to open.
981**/
982EFI_STATUS
983EFIAPI
984ShellIsDirectory (
985 IN CONST CHAR16 *DirName
986 );
987
988/**
989 Function to determine if a given filename represents a file.
990
991 This will search the CWD only.
992
993 If Name is NULL, then ASSERT.
994
995 @param[in] Name Path to file to test.
996
997 @retval EFI_SUCCESS The Path represents a file.
998 @retval EFI_NOT_FOUND The Path does not represent a file.
999 @retval other The path failed to open.
1000**/
1001EFI_STATUS
1002EFIAPI
1003ShellIsFile (
1004 IN CONST CHAR16 *Name
1005 );
1006
1007/**
1008 Function to determine if a given filename represents a file.
1009
1010 This will search the CWD and then the Path.
1011
1012 If Name is NULL, then ASSERT.
1013
1014 @param[in] Name Path to file to test.
1015
1016 @retval EFI_SUCCESS The Path represents a file.
1017 @retval EFI_NOT_FOUND The Path does not represent a file.
1018 @retval other The path failed to open.
1019**/
1020EFI_STATUS
1021EFIAPI
1022ShellIsFileInPath (
1023 IN CONST CHAR16 *Name
1024 );
1025
1026/**
1027 Function to determine whether a string is decimal or hex representation of a number
1028 and return the number converted from the string.
1029
1030 Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
1031 result. Use ShellConvertStringToUint64 instead.
1032
1033 @param[in] String String representation of a number.
1034
1035 @return The unsigned integer result of the conversion.
1036 @retval (UINTN)(-1) An error occurred.
1037**/
1038UINTN
1039EFIAPI
1040ShellStrToUintn (
1041 IN CONST CHAR16 *String
1042 );
1043
1044/**
1045 Function return the number converted from a hex representation of a number.
1046
1047 Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
1048 result. Use ShellConvertStringToUint64 instead.
1049
1050 @param[in] String String representation of a number.
1051
1052 @return The unsigned integer result of the conversion.
1053 @retval (UINTN)(-1) An error occurred.
1054**/
1055UINTN
1056EFIAPI
1057ShellHexStrToUintn (
1058 IN CONST CHAR16 *String
1059 );
1060
1061/**
1062 Safely append with automatic string resizing given length of Destination and
1063 desired length of copy from Source.
1064
1065 Append the first D characters of Source to the end of Destination, where D is
1066 the lesser of Count and the StrLen() of Source. If appending those D characters
1067 will fit within Destination (whose Size is given as CurrentSize) and
1068 still leave room for a NULL terminator, then those characters are appended,
1069 starting at the original terminating NULL of Destination, and a new terminating
1070 NULL is appended.
1071
1072 If appending D characters onto Destination will result in a overflow of the size
1073 given in CurrentSize the string will be grown such that the copy can be performed
1074 and CurrentSize will be updated to the new size.
1075
1076 If Source is NULL, there is nothing to append, so return the current buffer in
1077 Destination.
1078
1079 If Destination is NULL, then ASSERT().
1080 If Destination's current length (including NULL terminator) is already more than
1081 CurrentSize, then ASSERT().
1082
1083 @param[in, out] Destination The String to append onto.
1084 @param[in, out] CurrentSize On call, the number of bytes in Destination. On
1085 return, possibly the new size (still in bytes). If NULL,
1086 then allocate whatever is needed.
1087 @param[in] Source The String to append from.
1088 @param[in] Count The maximum number of characters to append. If 0, then
1089 all are appended.
1090
1091 @return The Destination after appending the Source.
1092**/
1093CHAR16 *
1094EFIAPI
1095StrnCatGrow (
1096 IN OUT CHAR16 **Destination,
1097 IN OUT UINTN *CurrentSize,
1098 IN CONST CHAR16 *Source,
1099 IN UINTN Count
1100 );
1101
1102/**
1103 This is a find and replace function. Upon successful return the NewString is a copy of
1104 SourceString with each instance of FindTarget replaced with ReplaceWith.
1105
1106 If SourceString and NewString overlap the behavior is undefined.
1107
1108 If the string would grow bigger than NewSize it will halt and return error.
1109
1110 @param[in] SourceString The string with source buffer.
1111 @param[in, out] NewString The string with resultant buffer.
1112 @param[in] NewSize The size in bytes of NewString.
1113 @param[in] FindTarget The string to look for.
1114 @param[in] ReplaceWith The string to replace FindTarget with.
1115 @param[in] SkipPreCarrot If TRUE will skip a FindTarget that has a '^'
1116 immediately before it.
1117 @param[in] ParameterReplacing If TRUE will add "" around items with spaces.
1118
1119 @retval EFI_INVALID_PARAMETER SourceString was NULL.
1120 @retval EFI_INVALID_PARAMETER NewString was NULL.
1121 @retval EFI_INVALID_PARAMETER FindTarget was NULL.
1122 @retval EFI_INVALID_PARAMETER ReplaceWith was NULL.
1123 @retval EFI_INVALID_PARAMETER FindTarget had length < 1.
1124 @retval EFI_INVALID_PARAMETER SourceString had length < 1.
1125 @retval EFI_BUFFER_TOO_SMALL NewSize was less than the minimum size to hold
1126 the new string (truncation occurred).
1127 @retval EFI_SUCCESS The string was successfully copied with replacement.
1128**/
1129EFI_STATUS
1130EFIAPI
1131ShellCopySearchAndReplace (
1132 IN CHAR16 CONST *SourceString,
1133 IN OUT CHAR16 *NewString,
1134 IN UINTN NewSize,
1135 IN CONST CHAR16 *FindTarget,
1136 IN CONST CHAR16 *ReplaceWith,
1137 IN CONST BOOLEAN SkipPreCarrot,
1138 IN CONST BOOLEAN ParameterReplacing
1139 );
1140
1141/**
1142 Check if a Unicode character is a hexadecimal character.
1143
1144 This internal function checks if a Unicode character is a
1145 numeric character. The valid hexadecimal characters are
1146 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
1147
1148
1149 @param Char The character to check against.
1150
1151 @retval TRUE The Char is a hexadecmial character.
1152 @retval FALSE The Char is not a hexadecmial character.
1153
1154**/
1155BOOLEAN
1156EFIAPI
1157ShellIsHexaDecimalDigitCharacter (
1158 IN CHAR16 Char
1159 );
1160
1161/**
1162 Check if a Unicode character is a decimal character.
1163
1164 This internal function checks if a Unicode character is a
1165 decimal character. The valid characters are
1166 L'0' to L'9'.
1167
1168
1169 @param Char The character to check against.
1170
1171 @retval TRUE The Char is a hexadecmial character.
1172 @retval FALSE The Char is not a hexadecmial character.
1173
1174**/
1175BOOLEAN
1176EFIAPI
1177ShellIsDecimalDigitCharacter (
1178 IN CHAR16 Char
1179 );
1180
1181///
1182/// What type of answer is requested.
1183///
1184typedef enum {
1185 ShellPromptResponseTypeYesNo,
1186 ShellPromptResponseTypeYesNoCancel,
1187 ShellPromptResponseTypeFreeform,
1188 ShellPromptResponseTypeQuitContinue,
1189 ShellPromptResponseTypeYesNoAllCancel,
1190 ShellPromptResponseTypeEnterContinue,
1191 ShellPromptResponseTypeAnyKeyContinue,
1192 ShellPromptResponseTypeMax
1193} SHELL_PROMPT_REQUEST_TYPE;
1194
1195///
1196/// What answer was given.
1197///
1198typedef enum {
1199 ShellPromptResponseYes,
1200 ShellPromptResponseNo,
1201 ShellPromptResponseCancel,
1202 ShellPromptResponseQuit,
1203 ShellPromptResponseContinue,
1204 ShellPromptResponseAll,
1205 ShellPromptResponseMax
1206} SHELL_PROMPT_RESPONSE;
1207
1208/**
1209 Prompt the user and return the resultant answer to the requestor.
1210
1211 This function will display the requested question on the shell prompt and then
1212 wait for an appropriate answer to be input from the console.
1213
1214 If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue
1215 or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.
1216
1217 If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type
1218 CHAR16*.
1219
1220 In either case *Response must be callee freed if Response was not NULL;
1221
1222 @param Type What type of question is asked. This is used to filter the input
1223 to prevent invalid answers to question.
1224 @param Prompt The pointer to a string prompt used to request input.
1225 @param Response The pointer to Response, which will be populated upon return.
1226
1227 @retval EFI_SUCCESS The operation was successful.
1228 @retval EFI_UNSUPPORTED The operation is not supported as requested.
1229 @retval EFI_INVALID_PARAMETER A parameter was invalid.
1230 @return other The operation failed.
1231**/
1232EFI_STATUS
1233EFIAPI
1234ShellPromptForResponse (
1235 IN SHELL_PROMPT_REQUEST_TYPE Type,
1236 IN CHAR16 *Prompt OPTIONAL,
1237 IN OUT VOID **Response OPTIONAL
1238 );
1239
1240/**
1241 Prompt the user and return the resultant answer to the requestor.
1242
1243 This function is the same as ShellPromptForResponse, except that the prompt is
1244 automatically pulled from HII.
1245
1246 @param[in] Type What type of question is asked. This is used to filter the input
1247 to prevent invalid answers to question.
1248 @param[in] HiiFormatStringId The format string Id for getting from Hii.
1249 @param[in] HiiFormatHandle The format string Handle for getting from Hii.
1250 @param[in, out] Response The pointer to Response, which will be populated upon return.
1251
1252 @retval EFI_SUCCESS The operation was successful.
1253 @return other The operation failed.
1254
1255 @sa ShellPromptForResponse
1256**/
1257EFI_STATUS
1258EFIAPI
1259ShellPromptForResponseHii (
1260 IN SHELL_PROMPT_REQUEST_TYPE Type,
1261 IN CONST EFI_STRING_ID HiiFormatStringId,
1262 IN CONST EFI_HII_HANDLE HiiFormatHandle,
1263 IN OUT VOID **Response
1264 );
1265
1266/**
1267 Function to determin if an entire string is a valid number.
1268
1269 If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
1270
1271 @param[in] String The string to evaluate.
1272 @param[in] ForceHex TRUE - always assume hex.
1273 @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going.
1274
1275 @retval TRUE It is all numeric (dec/hex) characters.
1276 @retval FALSE There is a non-numeric character.
1277**/
1278BOOLEAN
1279EFIAPI
1280ShellIsHexOrDecimalNumber (
1281 IN CONST CHAR16 *String,
1282 IN CONST BOOLEAN ForceHex,
1283 IN CONST BOOLEAN StopAtSpace
1284 );
1285
1286/**
1287 Function to verify and convert a string to its numerical 64 bit representation.
1288
1289 If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
1290
1291 @param[in] String The string to evaluate.
1292 @param[out] Value Upon a successful return the value of the conversion.
1293 @param[in] ForceHex TRUE - always assume hex.
1294 @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to
1295 process the entire String.
1296
1297 @retval EFI_SUCCESS The conversion was successful.
1298 @retval EFI_INVALID_PARAMETER String contained an invalid character.
1299 @retval EFI_NOT_FOUND String was a number, but Value was NULL.
1300**/
1301EFI_STATUS
1302EFIAPI
1303ShellConvertStringToUint64 (
1304 IN CONST CHAR16 *String,
1305 OUT UINT64 *Value,
1306 IN CONST BOOLEAN ForceHex,
1307 IN CONST BOOLEAN StopAtSpace
1308 );
1309
1310/**
1311 Function to determine if a given filename exists.
1312
1313 @param[in] Name Path to test.
1314
1315 @retval EFI_SUCCESS The Path represents a file.
1316 @retval EFI_NOT_FOUND The Path does not represent a file.
1317 @retval other The path failed to open.
1318**/
1319EFI_STATUS
1320EFIAPI
1321ShellFileExists (
1322 IN CONST CHAR16 *Name
1323 );
1324
1325/**
1326 Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
1327 buffer. The returned buffer must be callee freed.
1328
1329 If the position upon start is 0, then the Ascii Boolean will be set. This should be
1330 maintained and not changed for all operations with the same file.
1331
1332 @param[in] Handle SHELL_FILE_HANDLE to read from.
1333 @param[in, out] Ascii Boolean value for indicating whether the file is
1334 Ascii (TRUE) or UCS2 (FALSE).
1335
1336 @return The line of text from the file.
1337
1338 @sa ShellFileHandleReadLine
1339**/
1340CHAR16 *
1341EFIAPI
1342ShellFileHandleReturnLine (
1343 IN SHELL_FILE_HANDLE Handle,
1344 IN OUT BOOLEAN *Ascii
1345 );
1346
1347/**
1348 Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
1349
1350 If the position upon start is 0, then the Ascii Boolean will be set. This should be
1351 maintained and not changed for all operations with the same file.
1352
1353 @param[in] Handle SHELL_FILE_HANDLE to read from.
1354 @param[in, out] Buffer The pointer to buffer to read into.
1355 @param[in, out] Size The pointer to number of bytes in Buffer.
1356 @param[in] Truncate If the buffer is large enough, this has no effect.
1357 If the buffer is is too small and Truncate is TRUE,
1358 the line will be truncated.
1359 If the buffer is is too small and Truncate is FALSE,
1360 then no read will occur.
1361
1362 @param[in, out] Ascii Boolean value for indicating whether the file is
1363 Ascii (TRUE) or UCS2 (FALSE).
1364
1365 @retval EFI_SUCCESS The operation was successful. The line is stored in
1366 Buffer.
1367 @retval EFI_END_OF_FILE There are no more lines in the file.
1368 @retval EFI_INVALID_PARAMETER Handle was NULL.
1369 @retval EFI_INVALID_PARAMETER Size was NULL.
1370 @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line.
1371 Size was updated to the minimum space required.
1372**/
1373EFI_STATUS
1374EFIAPI
1375ShellFileHandleReadLine (
1376 IN SHELL_FILE_HANDLE Handle,
1377 IN OUT CHAR16 *Buffer,
1378 IN OUT UINTN *Size,
1379 IN BOOLEAN Truncate,
1380 IN OUT BOOLEAN *Ascii
1381 );
1382
1383/**
1384 Function to delete a file by name
1385
1386 @param[in] FileName Pointer to file name to delete.
1387
1388 @retval EFI_SUCCESS the file was deleted successfully
1389 @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
1390 deleted
1391 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1392 @retval EFI_NOT_FOUND The specified file could not be found on the
1393 device or the file system could not be found
1394 on the device.
1395 @retval EFI_NO_MEDIA The device has no medium.
1396 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
1397 medium is no longer supported.
1398 @retval EFI_DEVICE_ERROR The device reported an error.
1399 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
1400 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
1401 @retval EFI_ACCESS_DENIED The file was opened read only.
1402 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
1403 file.
1404 @retval other The file failed to open
1405**/
1406EFI_STATUS
1407EFIAPI
1408ShellDeleteFileByName (
1409 IN CONST CHAR16 *FileName
1410 );
1411
1412/**
1413 Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function.
1414
1415 @param[in] CommandToGetHelpOn Pointer to a string containing the command name of help file to be printed.
1416 @param[in] SectionToGetHelpOn Pointer to the section specifier(s).
1417 @param[in] PrintCommandText If TRUE, prints the command followed by the help content, otherwise prints
1418 the help content only.
1419 @retval EFI_DEVICE_ERROR The help data format was incorrect.
1420 @retval EFI_NOT_FOUND The help data could not be found.
1421 @retval EFI_SUCCESS The operation was successful.
1422**/
1423EFI_STATUS
1424EFIAPI
1425ShellPrintHelp (
1426 IN CONST CHAR16 *CommandToGetHelpOn,
1427 IN CONST CHAR16 *SectionToGetHelpOn,
1428 IN BOOLEAN PrintCommandText
1429 );
1430
1431#endif // __SHELL_LIB__
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette