2 Provides interface to shell functionality for shell commands and applications.
4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #include "UefiShellLib.h"
16 #include <ShellBase.h>
17 #include <Library/SortLib.h>
19 #define FIND_XXXXX_FILE_BUFFER_SIZE (SIZE_OF_EFI_FILE_INFO + MAX_FILE_NAME_LEN)
24 SHELL_PARAM_ITEM EmptyParamList
[] = {
27 SHELL_PARAM_ITEM SfoParamList
[] = {
31 EFI_SHELL_ENVIRONMENT2
*mEfiShellEnvironment2
;
32 EFI_SHELL_INTERFACE
*mEfiShellInterface
;
33 EFI_SHELL_PROTOCOL
*gEfiShellProtocol
;
34 EFI_SHELL_PARAMETERS_PROTOCOL
*gEfiShellParametersProtocol
;
35 EFI_HANDLE mEfiShellEnvironment2Handle
;
36 FILE_HANDLE_FUNCTION_MAP FileFunctionMap
;
39 Check if a Unicode character is a hexadecimal character.
41 This internal function checks if a Unicode character is a
42 numeric character. The valid hexadecimal characters are
43 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
45 @param Char The character to check against.
47 @retval TRUE If the Char is a hexadecmial character.
48 @retval FALSE If the Char is not a hexadecmial character.
53 ShellIsHexaDecimalDigitCharacter (
57 return (BOOLEAN
) ((Char
>= L
'0' && Char
<= L
'9') || (Char
>= L
'A' && Char
<= L
'F') || (Char
>= L
'a' && Char
<= L
'f'));
61 Check if a Unicode character is a decimal character.
63 This internal function checks if a Unicode character is a
64 decimal character. The valid characters are
68 @param Char The character to check against.
70 @retval TRUE If the Char is a hexadecmial character.
71 @retval FALSE If the Char is not a hexadecmial character.
76 ShellIsDecimalDigitCharacter (
80 return (BOOLEAN
) (Char
>= L
'0' && Char
<= L
'9');
84 Helper function to find ShellEnvironment2 for constructor.
86 @param[in] ImageHandle A copy of the calling image's handle.
88 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
93 IN EFI_HANDLE ImageHandle
103 Status
= gBS
->OpenProtocol(ImageHandle
,
104 &gEfiShellEnvironment2Guid
,
105 (VOID
**)&mEfiShellEnvironment2
,
108 EFI_OPEN_PROTOCOL_GET_PROTOCOL
111 // look for the mEfiShellEnvironment2 protocol at a higher level
113 if (EFI_ERROR (Status
) || !(CompareGuid (&mEfiShellEnvironment2
->SESGuid
, &gEfiShellEnvironment2ExtGuid
))){
115 // figure out how big of a buffer we need.
117 Status
= gBS
->LocateHandle (ByProtocol
,
118 &gEfiShellEnvironment2Guid
,
119 NULL
, // ignored for ByProtocol
124 // maybe it's not there???
126 if (Status
== EFI_BUFFER_TOO_SMALL
) {
127 Buffer
= (EFI_HANDLE
*)AllocateZeroPool(BufferSize
);
128 if (Buffer
== NULL
) {
129 return (EFI_OUT_OF_RESOURCES
);
131 Status
= gBS
->LocateHandle (ByProtocol
,
132 &gEfiShellEnvironment2Guid
,
133 NULL
, // ignored for ByProtocol
138 if (!EFI_ERROR (Status
) && Buffer
!= NULL
) {
140 // now parse the list of returned handles
142 Status
= EFI_NOT_FOUND
;
143 for (HandleIndex
= 0; HandleIndex
< (BufferSize
/sizeof(Buffer
[0])); HandleIndex
++) {
144 Status
= gBS
->OpenProtocol(Buffer
[HandleIndex
],
145 &gEfiShellEnvironment2Guid
,
146 (VOID
**)&mEfiShellEnvironment2
,
149 EFI_OPEN_PROTOCOL_GET_PROTOCOL
151 if (CompareGuid (&mEfiShellEnvironment2
->SESGuid
, &gEfiShellEnvironment2ExtGuid
)) {
152 mEfiShellEnvironment2Handle
= Buffer
[HandleIndex
];
153 Status
= EFI_SUCCESS
;
159 if (Buffer
!= NULL
) {
166 Function to do most of the work of the constructor. Allows for calling
167 multiple times without complete re-initialization.
169 @param[in] ImageHandle A copy of the ImageHandle.
170 @param[in] SystemTable A pointer to the SystemTable for the application.
172 @retval EFI_SUCCESS The operationw as successful.
176 ShellLibConstructorWorker (
177 IN EFI_HANDLE ImageHandle
,
178 IN EFI_SYSTEM_TABLE
*SystemTable
184 // UEFI 2.0 shell interfaces (used preferentially)
186 Status
= gBS
->OpenProtocol(
188 &gEfiShellProtocolGuid
,
189 (VOID
**)&gEfiShellProtocol
,
192 EFI_OPEN_PROTOCOL_GET_PROTOCOL
194 if (EFI_ERROR(Status
)) {
196 // Search for the shell protocol
198 Status
= gBS
->LocateProtocol(
199 &gEfiShellProtocolGuid
,
201 (VOID
**)&gEfiShellProtocol
203 if (EFI_ERROR(Status
)) {
204 gEfiShellProtocol
= NULL
;
207 Status
= gBS
->OpenProtocol(
209 &gEfiShellParametersProtocolGuid
,
210 (VOID
**)&gEfiShellParametersProtocol
,
213 EFI_OPEN_PROTOCOL_GET_PROTOCOL
215 if (EFI_ERROR(Status
)) {
216 gEfiShellParametersProtocol
= NULL
;
219 if (gEfiShellParametersProtocol
== NULL
|| gEfiShellProtocol
== NULL
) {
221 // Moved to seperate function due to complexity
223 Status
= ShellFindSE2(ImageHandle
);
225 if (EFI_ERROR(Status
)) {
226 DEBUG((DEBUG_ERROR
, "Status: 0x%08x\r\n", Status
));
227 mEfiShellEnvironment2
= NULL
;
229 Status
= gBS
->OpenProtocol(ImageHandle
,
230 &gEfiShellInterfaceGuid
,
231 (VOID
**)&mEfiShellInterface
,
234 EFI_OPEN_PROTOCOL_GET_PROTOCOL
236 if (EFI_ERROR(Status
)) {
237 mEfiShellInterface
= NULL
;
242 // only success getting 2 of either the old or new, but no 1/2 and 1/2
244 if ((mEfiShellEnvironment2
!= NULL
&& mEfiShellInterface
!= NULL
) ||
245 (gEfiShellProtocol
!= NULL
&& gEfiShellParametersProtocol
!= NULL
) ) {
246 if (gEfiShellProtocol
!= NULL
) {
247 FileFunctionMap
.GetFileInfo
= gEfiShellProtocol
->GetFileInfo
;
248 FileFunctionMap
.SetFileInfo
= gEfiShellProtocol
->SetFileInfo
;
249 FileFunctionMap
.ReadFile
= gEfiShellProtocol
->ReadFile
;
250 FileFunctionMap
.WriteFile
= gEfiShellProtocol
->WriteFile
;
251 FileFunctionMap
.CloseFile
= gEfiShellProtocol
->CloseFile
;
252 FileFunctionMap
.DeleteFile
= gEfiShellProtocol
->DeleteFile
;
253 FileFunctionMap
.GetFilePosition
= gEfiShellProtocol
->GetFilePosition
;
254 FileFunctionMap
.SetFilePosition
= gEfiShellProtocol
->SetFilePosition
;
255 FileFunctionMap
.FlushFile
= gEfiShellProtocol
->FlushFile
;
256 FileFunctionMap
.GetFileSize
= gEfiShellProtocol
->GetFileSize
;
258 FileFunctionMap
.GetFileInfo
= (EFI_SHELL_GET_FILE_INFO
)FileHandleGetInfo
;
259 FileFunctionMap
.SetFileInfo
= (EFI_SHELL_SET_FILE_INFO
)FileHandleSetInfo
;
260 FileFunctionMap
.ReadFile
= (EFI_SHELL_READ_FILE
)FileHandleRead
;
261 FileFunctionMap
.WriteFile
= (EFI_SHELL_WRITE_FILE
)FileHandleWrite
;
262 FileFunctionMap
.CloseFile
= (EFI_SHELL_CLOSE_FILE
)FileHandleClose
;
263 FileFunctionMap
.DeleteFile
= (EFI_SHELL_DELETE_FILE
)FileHandleDelete
;
264 FileFunctionMap
.GetFilePosition
= (EFI_SHELL_GET_FILE_POSITION
)FileHandleGetPosition
;
265 FileFunctionMap
.SetFilePosition
= (EFI_SHELL_SET_FILE_POSITION
)FileHandleSetPosition
;
266 FileFunctionMap
.FlushFile
= (EFI_SHELL_FLUSH_FILE
)FileHandleFlush
;
267 FileFunctionMap
.GetFileSize
= (EFI_SHELL_GET_FILE_SIZE
)FileHandleGetSize
;
269 return (EFI_SUCCESS
);
271 return (EFI_NOT_FOUND
);
274 Constructor for the Shell library.
276 Initialize the library and determine if the underlying is a UEFI Shell 2.0 or an EFI shell.
278 @param ImageHandle the image handle of the process
279 @param SystemTable the EFI System Table pointer
281 @retval EFI_SUCCESS the initialization was complete sucessfully
282 @return others an error ocurred during initialization
286 ShellLibConstructor (
287 IN EFI_HANDLE ImageHandle
,
288 IN EFI_SYSTEM_TABLE
*SystemTable
291 mEfiShellEnvironment2
= NULL
;
292 gEfiShellProtocol
= NULL
;
293 gEfiShellParametersProtocol
= NULL
;
294 mEfiShellInterface
= NULL
;
295 mEfiShellEnvironment2Handle
= NULL
;
298 // verify that auto initialize is not set false
300 if (PcdGetBool(PcdShellLibAutoInitialize
) == 0) {
301 return (EFI_SUCCESS
);
304 return (ShellLibConstructorWorker(ImageHandle
, SystemTable
));
308 Destructor for the library. free any resources.
310 @param[in] ImageHandle A copy of the ImageHandle.
311 @param[in] SystemTable A pointer to the SystemTable for the application.
313 @retval EFI_SUCCESS The operation was successful.
314 @return An error from the CloseProtocol function.
319 IN EFI_HANDLE ImageHandle
,
320 IN EFI_SYSTEM_TABLE
*SystemTable
323 if (mEfiShellEnvironment2
!= NULL
) {
324 gBS
->CloseProtocol(mEfiShellEnvironment2Handle
==NULL
?ImageHandle
:mEfiShellEnvironment2Handle
,
325 &gEfiShellEnvironment2Guid
,
328 mEfiShellEnvironment2
= NULL
;
330 if (mEfiShellInterface
!= NULL
) {
331 gBS
->CloseProtocol(ImageHandle
,
332 &gEfiShellInterfaceGuid
,
335 mEfiShellInterface
= NULL
;
337 if (gEfiShellProtocol
!= NULL
) {
338 gBS
->CloseProtocol(ImageHandle
,
339 &gEfiShellProtocolGuid
,
342 gEfiShellProtocol
= NULL
;
344 if (gEfiShellParametersProtocol
!= NULL
) {
345 gBS
->CloseProtocol(ImageHandle
,
346 &gEfiShellParametersProtocolGuid
,
349 gEfiShellParametersProtocol
= NULL
;
351 mEfiShellEnvironment2Handle
= NULL
;
353 return (EFI_SUCCESS
);
357 This function causes the shell library to initialize itself. If the shell library
358 is already initialized it will de-initialize all the current protocol poitners and
359 re-populate them again.
361 When the library is used with PcdShellLibAutoInitialize set to true this function
362 will return EFI_SUCCESS and perform no actions.
364 This function is intended for internal access for shell commands only.
366 @retval EFI_SUCCESS the initialization was complete sucessfully
375 // if auto initialize is not false then skip
377 if (PcdGetBool(PcdShellLibAutoInitialize
) != 0) {
378 return (EFI_SUCCESS
);
382 // deinit the current stuff
384 ASSERT_EFI_ERROR(ShellLibDestructor(gImageHandle
, gST
));
387 // init the new stuff
389 return (ShellLibConstructorWorker(gImageHandle
, gST
));
393 This function will retrieve the information about the file for the handle
394 specified and store it in allocated pool memory.
396 This function allocates a buffer to store the file's information. It is the
397 caller's responsibility to free the buffer
399 @param FileHandle The file handle of the file for which information is
402 @retval NULL information could not be retrieved.
404 @return the information about the file
409 IN SHELL_FILE_HANDLE FileHandle
412 return (FileFunctionMap
.GetFileInfo(FileHandle
));
416 This function sets the information about the file for the opened handle
419 @param[in] FileHandle The file handle of the file for which information
422 @param[in] FileInfo The information to set.
424 @retval EFI_SUCCESS The information was set.
425 @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid.
426 @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
427 @retval EFI_NO_MEDIA The device has no medium.
428 @retval EFI_DEVICE_ERROR The device reported an error.
429 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
430 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
431 @retval EFI_ACCESS_DENIED The file was opened read only.
432 @retval EFI_VOLUME_FULL The volume is full.
437 IN SHELL_FILE_HANDLE FileHandle
,
438 IN EFI_FILE_INFO
*FileInfo
441 return (FileFunctionMap
.SetFileInfo(FileHandle
, FileInfo
));
445 This function will open a file or directory referenced by DevicePath.
447 This function opens a file with the open mode according to the file path. The
448 Attributes is valid only for EFI_FILE_MODE_CREATE.
450 @param FilePath on input the device path to the file. On output
451 the remaining device path.
452 @param DeviceHandle pointer to the system device handle.
453 @param FileHandle pointer to the file handle.
454 @param OpenMode the mode to open the file with.
455 @param Attributes the file's file attributes.
457 @retval EFI_SUCCESS The information was set.
458 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
459 @retval EFI_UNSUPPORTED Could not open the file path.
460 @retval EFI_NOT_FOUND The specified file could not be found on the
461 device or the file system could not be found on
463 @retval EFI_NO_MEDIA The device has no medium.
464 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
465 medium is no longer supported.
466 @retval EFI_DEVICE_ERROR The device reported an error.
467 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
468 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
469 @retval EFI_ACCESS_DENIED The file was opened read only.
470 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
472 @retval EFI_VOLUME_FULL The volume is full.
476 ShellOpenFileByDevicePath(
477 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
478 OUT EFI_HANDLE
*DeviceHandle
,
479 OUT SHELL_FILE_HANDLE
*FileHandle
,
486 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*EfiSimpleFileSystemProtocol
;
487 EFI_FILE_PROTOCOL
*Handle1
;
488 EFI_FILE_PROTOCOL
*Handle2
;
490 if (FilePath
== NULL
|| FileHandle
== NULL
|| DeviceHandle
== NULL
) {
491 return (EFI_INVALID_PARAMETER
);
495 // which shell interface should we use
497 if (gEfiShellProtocol
!= NULL
) {
499 // use UEFI Shell 2.0 method.
501 FileName
= gEfiShellProtocol
->GetFilePathFromDevicePath(*FilePath
);
502 if (FileName
== NULL
) {
503 return (EFI_INVALID_PARAMETER
);
505 Status
= ShellOpenFileByName(FileName
, FileHandle
, OpenMode
, Attributes
);
512 // use old shell method.
514 Status
= gBS
->LocateDevicePath (&gEfiSimpleFileSystemProtocolGuid
,
517 if (EFI_ERROR (Status
)) {
520 Status
= gBS
->OpenProtocol(*DeviceHandle
,
521 &gEfiSimpleFileSystemProtocolGuid
,
522 (VOID
**)&EfiSimpleFileSystemProtocol
,
525 EFI_OPEN_PROTOCOL_GET_PROTOCOL
);
526 if (EFI_ERROR (Status
)) {
529 Status
= EfiSimpleFileSystemProtocol
->OpenVolume(EfiSimpleFileSystemProtocol
, &Handle1
);
530 if (EFI_ERROR (Status
)) {
536 // go down directories one node at a time.
538 while (!IsDevicePathEnd (*FilePath
)) {
540 // For file system access each node should be a file path component
542 if (DevicePathType (*FilePath
) != MEDIA_DEVICE_PATH
||
543 DevicePathSubType (*FilePath
) != MEDIA_FILEPATH_DP
546 return (EFI_INVALID_PARAMETER
);
549 // Open this file path node
555 // Try to test opening an existing file
557 Status
= Handle2
->Open (
560 ((FILEPATH_DEVICE_PATH
*)*FilePath
)->PathName
,
561 OpenMode
&~EFI_FILE_MODE_CREATE
,
566 // see if the error was that it needs to be created
568 if ((EFI_ERROR (Status
)) && (OpenMode
!= (OpenMode
&~EFI_FILE_MODE_CREATE
))) {
569 Status
= Handle2
->Open (
572 ((FILEPATH_DEVICE_PATH
*)*FilePath
)->PathName
,
578 // Close the last node
580 Handle2
->Close (Handle2
);
582 if (EFI_ERROR(Status
)) {
589 *FilePath
= NextDevicePathNode (*FilePath
);
593 // This is a weak spot since if the undefined SHELL_FILE_HANDLE format changes this must change also!
595 *FileHandle
= (VOID
*)Handle1
;
596 return (EFI_SUCCESS
);
600 This function will open a file or directory referenced by filename.
602 If return is EFI_SUCCESS, the Filehandle is the opened file's handle;
603 otherwise, the Filehandle is NULL. The Attributes is valid only for
604 EFI_FILE_MODE_CREATE.
606 if FileName is NULL then ASSERT()
608 @param FileName pointer to file name
609 @param FileHandle pointer to the file handle.
610 @param OpenMode the mode to open the file with.
611 @param Attributes the file's file attributes.
613 @retval EFI_SUCCESS The information was set.
614 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
615 @retval EFI_UNSUPPORTED Could not open the file path.
616 @retval EFI_NOT_FOUND The specified file could not be found on the
617 device or the file system could not be found
619 @retval EFI_NO_MEDIA The device has no medium.
620 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
621 medium is no longer supported.
622 @retval EFI_DEVICE_ERROR The device reported an error.
623 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
624 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
625 @retval EFI_ACCESS_DENIED The file was opened read only.
626 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
628 @retval EFI_VOLUME_FULL The volume is full.
633 IN CONST CHAR16
*FileName
,
634 OUT SHELL_FILE_HANDLE
*FileHandle
,
639 EFI_HANDLE DeviceHandle
;
640 EFI_DEVICE_PATH_PROTOCOL
*FilePath
;
642 EFI_FILE_INFO
*FileInfo
;
645 // ASSERT if FileName is NULL
647 ASSERT(FileName
!= NULL
);
649 if (FileName
== NULL
) {
650 return (EFI_INVALID_PARAMETER
);
653 if (gEfiShellProtocol
!= NULL
) {
654 if ((OpenMode
& EFI_FILE_MODE_CREATE
) == EFI_FILE_MODE_CREATE
&& (Attributes
& EFI_FILE_DIRECTORY
) == EFI_FILE_DIRECTORY
) {
655 return ShellCreateDirectory(FileName
, FileHandle
);
658 // Use UEFI Shell 2.0 method
660 Status
= gEfiShellProtocol
->OpenFileByName(FileName
,
663 if (StrCmp(FileName
, L
"NUL") != 0 && !EFI_ERROR(Status
) && ((OpenMode
& EFI_FILE_MODE_CREATE
) != 0)){
664 FileInfo
= FileFunctionMap
.GetFileInfo(*FileHandle
);
665 ASSERT(FileInfo
!= NULL
);
666 FileInfo
->Attribute
= Attributes
;
667 Status
= FileFunctionMap
.SetFileInfo(*FileHandle
, FileInfo
);
673 // Using EFI Shell version
674 // this means convert name to path and call that function
675 // since this will use EFI method again that will open it.
677 ASSERT(mEfiShellEnvironment2
!= NULL
);
678 FilePath
= mEfiShellEnvironment2
->NameToPath ((CHAR16
*)FileName
);
679 if (FilePath
!= NULL
) {
680 return (ShellOpenFileByDevicePath(&FilePath
,
686 return (EFI_DEVICE_ERROR
);
689 This function create a directory
691 If return is EFI_SUCCESS, the Filehandle is the opened directory's handle;
692 otherwise, the Filehandle is NULL. If the directory already existed, this
693 function opens the existing directory.
695 @param DirectoryName pointer to directory name
696 @param FileHandle pointer to the file handle.
698 @retval EFI_SUCCESS The information was set.
699 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
700 @retval EFI_UNSUPPORTED Could not open the file path.
701 @retval EFI_NOT_FOUND The specified file could not be found on the
702 device or the file system could not be found
704 @retval EFI_NO_MEDIA The device has no medium.
705 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
706 medium is no longer supported.
707 @retval EFI_DEVICE_ERROR The device reported an error.
708 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
709 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
710 @retval EFI_ACCESS_DENIED The file was opened read only.
711 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
713 @retval EFI_VOLUME_FULL The volume is full.
714 @sa ShellOpenFileByName
718 ShellCreateDirectory(
719 IN CONST CHAR16
*DirectoryName
,
720 OUT SHELL_FILE_HANDLE
*FileHandle
723 if (gEfiShellProtocol
!= NULL
) {
725 // Use UEFI Shell 2.0 method
727 return (gEfiShellProtocol
->CreateFile(DirectoryName
,
732 return (ShellOpenFileByName(DirectoryName
,
734 EFI_FILE_MODE_READ
| EFI_FILE_MODE_WRITE
| EFI_FILE_MODE_CREATE
,
741 This function reads information from an opened file.
743 If FileHandle is not a directory, the function reads the requested number of
744 bytes from the file at the file's current position and returns them in Buffer.
745 If the read goes beyond the end of the file, the read length is truncated to the
746 end of the file. The file's current position is increased by the number of bytes
747 returned. If FileHandle is a directory, the function reads the directory entry
748 at the file's current position and returns the entry in Buffer. If the Buffer
749 is not large enough to hold the current directory entry, then
750 EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated.
751 BufferSize is set to be the size of the buffer needed to read the entry. On
752 success, the current position is updated to the next directory entry. If there
753 are no more directory entries, the read returns a zero-length buffer.
754 EFI_FILE_INFO is the structure returned as the directory entry.
756 @param FileHandle the opened file handle
757 @param BufferSize on input the size of buffer in bytes. on return
758 the number of bytes written.
759 @param Buffer the buffer to put read data into.
761 @retval EFI_SUCCESS Data was read.
762 @retval EFI_NO_MEDIA The device has no media.
763 @retval EFI_DEVICE_ERROR The device reported an error.
764 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
765 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required
772 IN SHELL_FILE_HANDLE FileHandle
,
773 IN OUT UINTN
*BufferSize
,
777 return (FileFunctionMap
.ReadFile(FileHandle
, BufferSize
, Buffer
));
782 Write data to a file.
784 This function writes the specified number of bytes to the file at the current
785 file position. The current file position is advanced the actual number of bytes
786 written, which is returned in BufferSize. Partial writes only occur when there
787 has been a data error during the write attempt (such as "volume space full").
788 The file is automatically grown to hold the data if required. Direct writes to
789 opened directories are not supported.
791 @param FileHandle The opened file for writing
792 @param BufferSize on input the number of bytes in Buffer. On output
793 the number of bytes written.
794 @param Buffer the buffer containing data to write is stored.
796 @retval EFI_SUCCESS Data was written.
797 @retval EFI_UNSUPPORTED Writes to an open directory are not supported.
798 @retval EFI_NO_MEDIA The device has no media.
799 @retval EFI_DEVICE_ERROR The device reported an error.
800 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
801 @retval EFI_WRITE_PROTECTED The device is write-protected.
802 @retval EFI_ACCESS_DENIED The file was open for read only.
803 @retval EFI_VOLUME_FULL The volume is full.
808 IN SHELL_FILE_HANDLE FileHandle
,
809 IN OUT UINTN
*BufferSize
,
813 return (FileFunctionMap
.WriteFile(FileHandle
, BufferSize
, Buffer
));
817 Close an open file handle.
819 This function closes a specified file handle. All "dirty" cached file data is
820 flushed to the device, and the file is closed. In all cases the handle is
823 @param FileHandle the file handle to close.
825 @retval EFI_SUCCESS the file handle was closed sucessfully.
830 IN SHELL_FILE_HANDLE
*FileHandle
833 return (FileFunctionMap
.CloseFile(*FileHandle
));
837 Delete a file and close the handle
839 This function closes and deletes a file. In all cases the file handle is closed.
840 If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is
841 returned, but the handle is still closed.
843 @param FileHandle the file handle to delete
845 @retval EFI_SUCCESS the file was closed sucessfully
846 @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
848 @retval INVALID_PARAMETER One of the parameters has an invalid value.
853 IN SHELL_FILE_HANDLE
*FileHandle
856 return (FileFunctionMap
.DeleteFile(*FileHandle
));
860 Set the current position in a file.
862 This function sets the current file position for the handle to the position
863 supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only
864 absolute positioning is supported, and seeking past the end of the file is
865 allowed (a subsequent write would grow the file). Seeking to position
866 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.
867 If FileHandle is a directory, the only position that may be set is zero. This
868 has the effect of starting the read process of the directory entries over.
870 @param FileHandle The file handle on which the position is being set
871 @param Position Byte position from begining of file
873 @retval EFI_SUCCESS Operation completed sucessfully.
874 @retval EFI_UNSUPPORTED the seek request for non-zero is not valid on
876 @retval INVALID_PARAMETER One of the parameters has an invalid value.
880 ShellSetFilePosition (
881 IN SHELL_FILE_HANDLE FileHandle
,
885 return (FileFunctionMap
.SetFilePosition(FileHandle
, Position
));
889 Gets a file's current position
891 This function retrieves the current file position for the file handle. For
892 directories, the current file position has no meaning outside of the file
893 system driver and as such the operation is not supported. An error is returned
894 if FileHandle is a directory.
896 @param FileHandle The open file handle on which to get the position.
897 @param Position Byte position from begining of file.
899 @retval EFI_SUCCESS the operation completed sucessfully.
900 @retval INVALID_PARAMETER One of the parameters has an invalid value.
901 @retval EFI_UNSUPPORTED the request is not valid on directories.
905 ShellGetFilePosition (
906 IN SHELL_FILE_HANDLE FileHandle
,
910 return (FileFunctionMap
.GetFilePosition(FileHandle
, Position
));
913 Flushes data on a file
915 This function flushes all modified data associated with a file to a device.
917 @param FileHandle The file handle on which to flush data
919 @retval EFI_SUCCESS The data was flushed.
920 @retval EFI_NO_MEDIA The device has no media.
921 @retval EFI_DEVICE_ERROR The device reported an error.
922 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
923 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
924 @retval EFI_ACCESS_DENIED The file was opened for read only.
929 IN SHELL_FILE_HANDLE FileHandle
932 return (FileFunctionMap
.FlushFile(FileHandle
));
935 /** Retrieve first entry from a directory.
937 This function takes an open directory handle and gets information from the
938 first entry in the directory. A buffer is allocated to contain
939 the information and a pointer to the buffer is returned in *Buffer. The
940 caller can use ShellFindNextFile() to get subsequent directory entries.
942 The buffer will be freed by ShellFindNextFile() when the last directory
943 entry is read. Otherwise, the caller must free the buffer, using FreePool,
944 when finished with it.
946 @param[in] DirHandle The file handle of the directory to search.
947 @param[out] Buffer The pointer to the buffer for the file's information.
949 @retval EFI_SUCCESS Found the first file.
950 @retval EFI_NOT_FOUND Cannot find the directory.
951 @retval EFI_NO_MEDIA The device has no media.
952 @retval EFI_DEVICE_ERROR The device reported an error.
953 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
954 @return Others status of ShellGetFileInfo, ShellSetFilePosition,
960 IN SHELL_FILE_HANDLE DirHandle
,
961 OUT EFI_FILE_INFO
**Buffer
965 // pass to file handle lib
967 return (FileHandleFindFirstFile(DirHandle
, Buffer
));
969 /** Retrieve next entries from a directory.
971 To use this function, the caller must first call the ShellFindFirstFile()
972 function to get the first directory entry. Subsequent directory entries are
973 retrieved by using the ShellFindNextFile() function. This function can
974 be called several times to get each entry from the directory. If the call of
975 ShellFindNextFile() retrieved the last directory entry, the next call of
976 this function will set *NoFile to TRUE and free the buffer.
978 @param[in] DirHandle The file handle of the directory.
979 @param[out] Buffer The pointer to buffer for file's information.
980 @param[out] NoFile The pointer to boolean when last file is found.
982 @retval EFI_SUCCESS Found the next file, or reached last file
983 @retval EFI_NO_MEDIA The device has no media.
984 @retval EFI_DEVICE_ERROR The device reported an error.
985 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
990 IN SHELL_FILE_HANDLE DirHandle
,
991 OUT EFI_FILE_INFO
*Buffer
,
996 // pass to file handle lib
998 return (FileHandleFindNextFile(DirHandle
, Buffer
, NoFile
));
1001 Retrieve the size of a file.
1003 if FileHandle is NULL then ASSERT()
1004 if Size is NULL then ASSERT()
1006 This function extracts the file size info from the FileHandle's EFI_FILE_INFO
1009 @param FileHandle file handle from which size is retrieved
1010 @param Size pointer to size
1012 @retval EFI_SUCCESS operation was completed sucessfully
1013 @retval EFI_DEVICE_ERROR cannot access the file
1018 IN SHELL_FILE_HANDLE FileHandle
,
1022 return (FileFunctionMap
.GetFileSize(FileHandle
, Size
));
1025 Retrieves the status of the break execution flag
1027 this function is useful to check whether the application is being asked to halt by the shell.
1029 @retval TRUE the execution break is enabled
1030 @retval FALSE the execution break is not enabled
1034 ShellGetExecutionBreakFlag(
1039 // Check for UEFI Shell 2.0 protocols
1041 if (gEfiShellProtocol
!= NULL
) {
1044 // We are using UEFI Shell 2.0; see if the event has been triggered
1046 if (gBS
->CheckEvent(gEfiShellProtocol
->ExecutionBreak
) != EFI_SUCCESS
) {
1053 // using EFI Shell; call the function to check
1055 if (mEfiShellEnvironment2
!= NULL
) {
1056 return (mEfiShellEnvironment2
->GetExecutionBreak());
1062 return the value of an environment variable
1064 this function gets the value of the environment variable set by the
1065 ShellSetEnvironmentVariable function
1067 @param EnvKey The key name of the environment variable.
1069 @retval NULL the named environment variable does not exist.
1070 @return != NULL pointer to the value of the environment variable
1074 ShellGetEnvironmentVariable (
1075 IN CONST CHAR16
*EnvKey
1079 // Check for UEFI Shell 2.0 protocols
1081 if (gEfiShellProtocol
!= NULL
) {
1082 return (gEfiShellProtocol
->GetEnv(EnvKey
));
1086 // Check for EFI shell
1088 if (mEfiShellEnvironment2
!= NULL
) {
1089 return (mEfiShellEnvironment2
->GetEnv((CHAR16
*)EnvKey
));
1095 set the value of an environment variable
1097 This function changes the current value of the specified environment variable. If the
1098 environment variable exists and the Value is an empty string, then the environment
1099 variable is deleted. If the environment variable exists and the Value is not an empty
1100 string, then the value of the environment variable is changed. If the environment
1101 variable does not exist and the Value is an empty string, there is no action. If the
1102 environment variable does not exist and the Value is a non-empty string, then the
1103 environment variable is created and assigned the specified value.
1105 This is not supported pre-UEFI Shell 2.0.
1107 @param EnvKey The key name of the environment variable.
1108 @param EnvVal The Value of the environment variable
1109 @param Volatile Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).
1111 @retval EFI_SUCCESS the operation was completed sucessfully
1112 @retval EFI_UNSUPPORTED This operation is not allowed in pre UEFI 2.0 Shell environments
1116 ShellSetEnvironmentVariable (
1117 IN CONST CHAR16
*EnvKey
,
1118 IN CONST CHAR16
*EnvVal
,
1123 // Check for UEFI Shell 2.0 protocols
1125 if (gEfiShellProtocol
!= NULL
) {
1126 return (gEfiShellProtocol
->SetEnv(EnvKey
, EnvVal
, Volatile
));
1130 // This feature does not exist under EFI shell
1132 return (EFI_UNSUPPORTED
);
1136 Cause the shell to parse and execute a command line.
1138 This function creates a nested instance of the shell and executes the specified
1139 command (CommandLine) with the specified environment (Environment). Upon return,
1140 the status code returned by the specified command is placed in StatusCode.
1141 If Environment is NULL, then the current environment is used and all changes made
1142 by the commands executed will be reflected in the current environment. If the
1143 Environment is non-NULL, then the changes made will be discarded.
1144 The CommandLine is executed from the current working directory on the current
1147 The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0
1148 environment. The values pointed to by the parameters will be unchanged by the
1149 ShellExecute() function. The Output parameter has no effect in a
1150 UEFI Shell 2.0 environment.
1152 @param[in] ParentHandle The parent image starting the operation.
1153 @param[in] CommandLine The pointer to a NULL terminated command line.
1154 @param[in] Output True to display debug output. False to hide it.
1155 @param[in] EnvironmentVariables Optional pointer to array of environment variables
1156 in the form "x=y". If NULL, the current set is used.
1157 @param[out] Status The status of the run command line.
1159 @retval EFI_SUCCESS The operation completed sucessfully. Status
1160 contains the status code returned.
1161 @retval EFI_INVALID_PARAMETER A parameter contains an invalid value.
1162 @retval EFI_OUT_OF_RESOURCES Out of resources.
1163 @retval EFI_UNSUPPORTED The operation is not allowed.
1168 IN EFI_HANDLE
*ParentHandle
,
1169 IN CHAR16
*CommandLine OPTIONAL
,
1170 IN BOOLEAN Output OPTIONAL
,
1171 IN CHAR16
**EnvironmentVariables OPTIONAL
,
1172 OUT EFI_STATUS
*Status OPTIONAL
1176 // Check for UEFI Shell 2.0 protocols
1178 if (gEfiShellProtocol
!= NULL
) {
1180 // Call UEFI Shell 2.0 version (not using Output parameter)
1182 return (gEfiShellProtocol
->Execute(ParentHandle
,
1184 EnvironmentVariables
,
1189 // Check for EFI shell
1191 if (mEfiShellEnvironment2
!= NULL
) {
1193 // Call EFI Shell version (not using EnvironmentVariables or Status parameters)
1194 // Due to oddity in the EFI shell we want to dereference the ParentHandle here
1196 return (mEfiShellEnvironment2
->Execute(*ParentHandle
,
1201 return (EFI_UNSUPPORTED
);
1204 Retreives the current directory path
1206 If the DeviceName is NULL, it returns the current device's current directory
1207 name. If the DeviceName is not NULL, it returns the current directory name
1210 @param DeviceName the name of the drive to get directory on
1212 @retval NULL the directory does not exist
1213 @return != NULL the directory
1217 ShellGetCurrentDir (
1218 IN CHAR16
* CONST DeviceName OPTIONAL
1222 // Check for UEFI Shell 2.0 protocols
1224 if (gEfiShellProtocol
!= NULL
) {
1225 return (gEfiShellProtocol
->GetCurDir(DeviceName
));
1229 // Check for EFI shell
1231 if (mEfiShellEnvironment2
!= NULL
) {
1232 return (mEfiShellEnvironment2
->CurDir(DeviceName
));
1238 sets (enabled or disabled) the page break mode
1240 when page break mode is enabled the screen will stop scrolling
1241 and wait for operator input before scrolling a subsequent screen.
1243 @param CurrentState TRUE to enable and FALSE to disable
1247 ShellSetPageBreakMode (
1248 IN BOOLEAN CurrentState
1252 // check for enabling
1254 if (CurrentState
!= 0x00) {
1256 // check for UEFI Shell 2.0
1258 if (gEfiShellProtocol
!= NULL
) {
1260 // Enable with UEFI 2.0 Shell
1262 gEfiShellProtocol
->EnablePageBreak();
1266 // Check for EFI shell
1268 if (mEfiShellEnvironment2
!= NULL
) {
1270 // Enable with EFI Shell
1272 mEfiShellEnvironment2
->EnablePageBreak (DEFAULT_INIT_ROW
, DEFAULT_AUTO_LF
);
1278 // check for UEFI Shell 2.0
1280 if (gEfiShellProtocol
!= NULL
) {
1282 // Disable with UEFI 2.0 Shell
1284 gEfiShellProtocol
->DisablePageBreak();
1288 // Check for EFI shell
1290 if (mEfiShellEnvironment2
!= NULL
) {
1292 // Disable with EFI Shell
1294 mEfiShellEnvironment2
->DisablePageBreak ();
1302 /// version of EFI_SHELL_FILE_INFO struct, except has no CONST pointers.
1303 /// This allows for the struct to be populated.
1310 SHELL_FILE_HANDLE Handle
;
1311 EFI_FILE_INFO
*Info
;
1312 } EFI_SHELL_FILE_INFO_NO_CONST
;
1315 Converts a EFI shell list of structures to the coresponding UEFI Shell 2.0 type of list.
1317 if OldStyleFileList is NULL then ASSERT()
1319 this function will convert a SHELL_FILE_ARG based list into a callee allocated
1320 EFI_SHELL_FILE_INFO based list. it is up to the caller to free the memory via
1321 the ShellCloseFileMetaArg function.
1323 @param[in] FileList the EFI shell list type
1324 @param[in, out] ListHead the list to add to
1326 @retval the resultant head of the double linked new format list;
1330 InternalShellConvertFileListType (
1331 IN LIST_ENTRY
*FileList
,
1332 IN OUT LIST_ENTRY
*ListHead
1335 SHELL_FILE_ARG
*OldInfo
;
1337 EFI_SHELL_FILE_INFO_NO_CONST
*NewInfo
;
1342 ASSERT(FileList
!= NULL
);
1343 ASSERT(ListHead
!= NULL
);
1346 // enumerate through each member of the old list and copy
1348 for (Link
= FileList
->ForwardLink
; Link
!= FileList
; Link
= Link
->ForwardLink
) {
1349 OldInfo
= CR (Link
, SHELL_FILE_ARG
, Link
, SHELL_FILE_ARG_SIGNATURE
);
1350 ASSERT(OldInfo
!= NULL
);
1353 // Skip ones that failed to open...
1355 if (OldInfo
->Status
!= EFI_SUCCESS
) {
1360 // make sure the old list was valid
1362 ASSERT(OldInfo
->Info
!= NULL
);
1363 ASSERT(OldInfo
->FullName
!= NULL
);
1364 ASSERT(OldInfo
->FileName
!= NULL
);
1367 // allocate a new EFI_SHELL_FILE_INFO object
1369 NewInfo
= AllocateZeroPool(sizeof(EFI_SHELL_FILE_INFO
));
1370 if (NewInfo
== NULL
) {
1371 ShellCloseFileMetaArg((EFI_SHELL_FILE_INFO
**)(&ListHead
));
1377 // copy the simple items
1379 NewInfo
->Handle
= OldInfo
->Handle
;
1380 NewInfo
->Status
= OldInfo
->Status
;
1382 // old shell checks for 0 not NULL
1383 OldInfo
->Handle
= 0;
1386 // allocate new space to copy strings and structure
1388 NewInfo
->FullName
= AllocateZeroPool(StrSize(OldInfo
->FullName
));
1389 NewInfo
->FileName
= AllocateZeroPool(StrSize(OldInfo
->FileName
));
1390 NewInfo
->Info
= AllocateZeroPool((UINTN
)OldInfo
->Info
->Size
);
1393 // make sure all the memory allocations were sucessful
1395 if (NULL
== NewInfo
->FullName
|| NewInfo
->FileName
== NULL
|| NewInfo
->Info
== NULL
) {
1396 ShellCloseFileMetaArg((EFI_SHELL_FILE_INFO
**)(&ListHead
));
1402 // Copt the strings and structure
1404 StrCpy(NewInfo
->FullName
, OldInfo
->FullName
);
1405 StrCpy(NewInfo
->FileName
, OldInfo
->FileName
);
1406 gBS
->CopyMem (NewInfo
->Info
, OldInfo
->Info
, (UINTN
)OldInfo
->Info
->Size
);
1409 // add that to the list
1411 InsertTailList(ListHead
, &NewInfo
->Link
);
1416 Opens a group of files based on a path.
1418 This function uses the Arg to open all the matching files. Each matched
1419 file has a SHELL_FILE_ARG structure to record the file information. These
1420 structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG
1421 structures from ListHead to access each file. This function supports wildcards
1422 and will process '?' and '*' as such. the list must be freed with a call to
1423 ShellCloseFileMetaArg().
1425 If you are NOT appending to an existing list *ListHead must be NULL. If
1426 *ListHead is NULL then it must be callee freed.
1428 @param Arg pointer to path string
1429 @param OpenMode mode to open files with
1430 @param ListHead head of linked list of results
1432 @retval EFI_SUCCESS the operation was sucessful and the list head
1433 contains the list of opened files
1434 @return != EFI_SUCCESS the operation failed
1436 @sa InternalShellConvertFileListType
1440 ShellOpenFileMetaArg (
1443 IN OUT EFI_SHELL_FILE_INFO
**ListHead
1447 LIST_ENTRY mOldStyleFileList
;
1450 // ASSERT that Arg and ListHead are not NULL
1452 ASSERT(Arg
!= NULL
);
1453 ASSERT(ListHead
!= NULL
);
1456 // Check for UEFI Shell 2.0 protocols
1458 if (gEfiShellProtocol
!= NULL
) {
1459 if (*ListHead
== NULL
) {
1460 *ListHead
= (EFI_SHELL_FILE_INFO
*)AllocateZeroPool(sizeof(EFI_SHELL_FILE_INFO
));
1461 if (*ListHead
== NULL
) {
1462 return (EFI_OUT_OF_RESOURCES
);
1464 InitializeListHead(&((*ListHead
)->Link
));
1466 Status
= gEfiShellProtocol
->OpenFileList(Arg
,
1469 if (EFI_ERROR(Status
)) {
1470 gEfiShellProtocol
->RemoveDupInFileList(ListHead
);
1472 Status
= gEfiShellProtocol
->RemoveDupInFileList(ListHead
);
1474 if (*ListHead
!= NULL
&& IsListEmpty(&(*ListHead
)->Link
)) {
1475 FreePool(*ListHead
);
1477 return (EFI_NOT_FOUND
);
1483 // Check for EFI shell
1485 if (mEfiShellEnvironment2
!= NULL
) {
1487 // make sure the list head is initialized
1489 InitializeListHead(&mOldStyleFileList
);
1492 // Get the EFI Shell list of files
1494 Status
= mEfiShellEnvironment2
->FileMetaArg(Arg
, &mOldStyleFileList
);
1495 if (EFI_ERROR(Status
)) {
1500 if (*ListHead
== NULL
) {
1501 *ListHead
= (EFI_SHELL_FILE_INFO
*)AllocateZeroPool(sizeof(EFI_SHELL_FILE_INFO
));
1502 if (*ListHead
== NULL
) {
1503 return (EFI_OUT_OF_RESOURCES
);
1505 InitializeListHead(&((*ListHead
)->Link
));
1509 // Convert that to equivalent of UEFI Shell 2.0 structure
1511 InternalShellConvertFileListType(&mOldStyleFileList
, &(*ListHead
)->Link
);
1514 // Free the EFI Shell version that was converted.
1516 mEfiShellEnvironment2
->FreeFileList(&mOldStyleFileList
);
1518 if ((*ListHead
)->Link
.ForwardLink
== (*ListHead
)->Link
.BackLink
&& (*ListHead
)->Link
.BackLink
== &((*ListHead
)->Link
)) {
1519 FreePool(*ListHead
);
1521 Status
= EFI_NOT_FOUND
;
1526 return (EFI_UNSUPPORTED
);
1529 Free the linked list returned from ShellOpenFileMetaArg.
1531 if ListHead is NULL then ASSERT().
1533 @param ListHead the pointer to free.
1535 @retval EFI_SUCCESS the operation was sucessful.
1539 ShellCloseFileMetaArg (
1540 IN OUT EFI_SHELL_FILE_INFO
**ListHead
1546 // ASSERT that ListHead is not NULL
1548 ASSERT(ListHead
!= NULL
);
1551 // Check for UEFI Shell 2.0 protocols
1553 if (gEfiShellProtocol
!= NULL
) {
1554 return (gEfiShellProtocol
->FreeFileList(ListHead
));
1555 } else if (mEfiShellEnvironment2
!= NULL
) {
1557 // Since this is EFI Shell version we need to free our internally made copy
1560 for ( Node
= GetFirstNode(&(*ListHead
)->Link
)
1561 ; *ListHead
!= NULL
&& !IsListEmpty(&(*ListHead
)->Link
)
1562 ; Node
= GetFirstNode(&(*ListHead
)->Link
)) {
1563 RemoveEntryList(Node
);
1564 ((EFI_FILE_PROTOCOL
*)((EFI_SHELL_FILE_INFO_NO_CONST
*)Node
)->Handle
)->Close(((EFI_SHELL_FILE_INFO_NO_CONST
*)Node
)->Handle
);
1565 FreePool(((EFI_SHELL_FILE_INFO_NO_CONST
*)Node
)->FullName
);
1566 FreePool(((EFI_SHELL_FILE_INFO_NO_CONST
*)Node
)->FileName
);
1567 FreePool(((EFI_SHELL_FILE_INFO_NO_CONST
*)Node
)->Info
);
1568 FreePool((EFI_SHELL_FILE_INFO_NO_CONST
*)Node
);
1573 return (EFI_UNSUPPORTED
);
1577 Find a file by searching the CWD and then the path.
1579 If FileName is NULL then ASSERT.
1581 If the return value is not NULL then the memory must be caller freed.
1583 @param FileName Filename string.
1585 @retval NULL the file was not found
1586 @return !NULL the full path to the file.
1591 IN CONST CHAR16
*FileName
1595 SHELL_FILE_HANDLE Handle
;
1599 CONST CHAR16
*Walker
;
1606 // First make sure its not an absolute path.
1608 Status
= ShellOpenFileByName(FileName
, &Handle
, EFI_FILE_MODE_READ
, 0);
1609 if (!EFI_ERROR(Status
)){
1610 if (FileHandleIsDirectory(Handle
) != EFI_SUCCESS
) {
1611 ASSERT(RetVal
== NULL
);
1612 RetVal
= StrnCatGrow(&RetVal
, NULL
, FileName
, 0);
1613 ShellCloseFile(&Handle
);
1616 ShellCloseFile(&Handle
);
1620 Path
= ShellGetEnvironmentVariable(L
"cwd");
1622 Size
= StrSize(Path
);
1623 Size
+= StrSize(FileName
);
1624 TestPath
= AllocateZeroPool(Size
);
1625 if (TestPath
== NULL
) {
1628 StrCpy(TestPath
, Path
);
1629 StrCat(TestPath
, FileName
);
1630 Status
= ShellOpenFileByName(TestPath
, &Handle
, EFI_FILE_MODE_READ
, 0);
1631 if (!EFI_ERROR(Status
)){
1632 if (FileHandleIsDirectory(Handle
) != EFI_SUCCESS
) {
1633 ASSERT(RetVal
== NULL
);
1634 RetVal
= StrnCatGrow(&RetVal
, NULL
, TestPath
, 0);
1635 ShellCloseFile(&Handle
);
1639 ShellCloseFile(&Handle
);
1644 Path
= ShellGetEnvironmentVariable(L
"path");
1646 Size
= StrSize(Path
)+sizeof(CHAR16
);
1647 Size
+= StrSize(FileName
);
1648 TestPath
= AllocateZeroPool(Size
);
1649 if (TestPath
== NULL
) {
1652 Walker
= (CHAR16
*)Path
;
1654 CopyMem(TestPath
, Walker
, StrSize(Walker
));
1655 if (TestPath
!= NULL
) {
1656 TempChar
= StrStr(TestPath
, L
";");
1657 if (TempChar
!= NULL
) {
1658 *TempChar
= CHAR_NULL
;
1660 if (TestPath
[StrLen(TestPath
)-1] != L
'\\') {
1661 StrCat(TestPath
, L
"\\");
1663 if (FileName
[0] == L
'\\') {
1666 StrCat(TestPath
, FileName
);
1667 if (StrStr(Walker
, L
";") != NULL
) {
1668 Walker
= StrStr(Walker
, L
";") + 1;
1672 Status
= ShellOpenFileByName(TestPath
, &Handle
, EFI_FILE_MODE_READ
, 0);
1673 if (!EFI_ERROR(Status
)){
1674 if (FileHandleIsDirectory(Handle
) != EFI_SUCCESS
) {
1675 ASSERT(RetVal
== NULL
);
1676 RetVal
= StrnCatGrow(&RetVal
, NULL
, TestPath
, 0);
1677 ShellCloseFile(&Handle
);
1680 ShellCloseFile(&Handle
);
1684 } while (Walker
!= NULL
&& Walker
[0] != CHAR_NULL
);
1691 Find a file by searching the CWD and then the path with a variable set of file
1692 extensions. If the file is not found it will append each extension in the list
1693 in the order provided and return the first one that is successful.
1695 If FileName is NULL, then ASSERT.
1696 If FileExtension is NULL, then behavior is identical to ShellFindFilePath.
1698 If the return value is not NULL then the memory must be caller freed.
1700 @param[in] FileName Filename string.
1701 @param[in] FileExtension Semi-colon delimeted list of possible extensions.
1703 @retval NULL The file was not found.
1704 @retval !NULL The path to the file.
1708 ShellFindFilePathEx (
1709 IN CONST CHAR16
*FileName
,
1710 IN CONST CHAR16
*FileExtension
1715 CONST CHAR16
*ExtensionWalker
;
1720 ASSERT(FileName
!= NULL
);
1721 if (FileExtension
== NULL
) {
1722 return (ShellFindFilePath(FileName
));
1724 RetVal
= ShellFindFilePath(FileName
);
1725 if (RetVal
!= NULL
) {
1728 Size
= StrSize(FileName
);
1729 Size
+= StrSize(FileExtension
);
1730 TestPath
= AllocateZeroPool(Size
);
1731 if (TestPath
== NULL
) {
1734 for (ExtensionWalker
= FileExtension
, TempChar2
= (CHAR16
*)FileExtension
; TempChar2
!= NULL
; ExtensionWalker
= TempChar2
+ 1){
1735 StrCpy(TestPath
, FileName
);
1736 if (ExtensionWalker
!= NULL
) {
1737 StrCat(TestPath
, ExtensionWalker
);
1739 TempChar
= StrStr(TestPath
, L
";");
1740 if (TempChar
!= NULL
) {
1741 *TempChar
= CHAR_NULL
;
1743 RetVal
= ShellFindFilePath(TestPath
);
1744 if (RetVal
!= NULL
) {
1747 ASSERT(ExtensionWalker
!= NULL
);
1748 TempChar2
= StrStr(ExtensionWalker
, L
";");
1757 SHELL_PARAM_TYPE Type
;
1759 UINTN OriginalPosition
;
1760 } SHELL_PARAM_PACKAGE
;
1763 Checks the list of valid arguments and returns TRUE if the item was found. If the
1764 return value is TRUE then the type parameter is set also.
1766 if CheckList is NULL then ASSERT();
1767 if Name is NULL then ASSERT();
1768 if Type is NULL then ASSERT();
1770 @param Name pointer to Name of parameter found
1771 @param CheckList List to check against
1772 @param Type pointer to type of parameter if it was found
1774 @retval TRUE the Parameter was found. Type is valid.
1775 @retval FALSE the Parameter was not found. Type is not valid.
1779 InternalIsOnCheckList (
1780 IN CONST CHAR16
*Name
,
1781 IN CONST SHELL_PARAM_ITEM
*CheckList
,
1782 OUT SHELL_PARAM_TYPE
*Type
1785 SHELL_PARAM_ITEM
*TempListItem
;
1789 // ASSERT that all 3 pointer parameters aren't NULL
1791 ASSERT(CheckList
!= NULL
);
1792 ASSERT(Type
!= NULL
);
1793 ASSERT(Name
!= NULL
);
1796 // question mark and page break mode are always supported
1798 if ((StrCmp(Name
, L
"-?") == 0) ||
1799 (StrCmp(Name
, L
"-b") == 0)
1806 // Enumerate through the list
1808 for (TempListItem
= (SHELL_PARAM_ITEM
*)CheckList
; TempListItem
->Name
!= NULL
; TempListItem
++) {
1810 // If the Type is TypeStart only check the first characters of the passed in param
1811 // If it matches set the type and return TRUE
1813 if (TempListItem
->Type
== TypeStart
) {
1814 if (StrnCmp(Name
, TempListItem
->Name
, StrLen(TempListItem
->Name
)) == 0) {
1815 *Type
= TempListItem
->Type
;
1819 TempString
= StrnCatGrow(&TempString
, NULL
, Name
, StrLen(TempListItem
->Name
));
1820 if (TempString
!= NULL
) {
1821 if (StringNoCaseCompare(&TempString
, &TempListItem
->Name
) == 0) {
1822 *Type
= TempListItem
->Type
;
1823 FreePool(TempString
);
1826 FreePool(TempString
);
1828 } else if (StringNoCaseCompare(&Name
, &TempListItem
->Name
) == 0) {
1829 *Type
= TempListItem
->Type
;
1837 Checks the string for indicators of "flag" status. this is a leading '/', '-', or '+'
1839 @param[in] Name pointer to Name of parameter found
1840 @param[in] AlwaysAllowNumbers TRUE to allow numbers, FALSE to not.
1842 @retval TRUE the Parameter is a flag.
1843 @retval FALSE the Parameter not a flag.
1848 IN CONST CHAR16
*Name
,
1849 IN BOOLEAN AlwaysAllowNumbers
1853 // ASSERT that Name isn't NULL
1855 ASSERT(Name
!= NULL
);
1858 // If we accept numbers then dont return TRUE. (they will be values)
1860 if (((Name
[0] == L
'-' || Name
[0] == L
'+') && ShellIsHexaDecimalDigitCharacter(Name
[1])) && AlwaysAllowNumbers
) {
1865 // If the Name has a /, +, or - as the first character return TRUE
1867 if ((Name
[0] == L
'/') ||
1868 (Name
[0] == L
'-') ||
1877 Checks the command line arguments passed against the list of valid ones.
1879 If no initialization is required, then return RETURN_SUCCESS.
1881 @param[in] CheckList pointer to list of parameters to check
1882 @param[out] CheckPackage pointer to pointer to list checked values
1883 @param[out] ProblemParam optional pointer to pointer to unicode string for
1884 the paramater that caused failure. If used then the
1885 caller is responsible for freeing the memory.
1886 @param[in] AutoPageBreak will automatically set PageBreakEnabled for "b" parameter
1887 @param[in] Argv pointer to array of parameters
1888 @param[in] Argc Count of parameters in Argv
1889 @param[in] AlwaysAllowNumbers TRUE to allow numbers always, FALSE otherwise.
1891 @retval EFI_SUCCESS The operation completed sucessfully.
1892 @retval EFI_OUT_OF_RESOURCES A memory allocation failed
1893 @retval EFI_INVALID_PARAMETER A parameter was invalid
1894 @retval EFI_VOLUME_CORRUPTED the command line was corrupt. an argument was
1895 duplicated. the duplicated command line argument
1896 was returned in ProblemParam if provided.
1897 @retval EFI_NOT_FOUND a argument required a value that was missing.
1898 the invalid command line argument was returned in
1899 ProblemParam if provided.
1903 InternalCommandLineParse (
1904 IN CONST SHELL_PARAM_ITEM
*CheckList
,
1905 OUT LIST_ENTRY
**CheckPackage
,
1906 OUT CHAR16
**ProblemParam OPTIONAL
,
1907 IN BOOLEAN AutoPageBreak
,
1908 IN CONST CHAR16
**Argv
,
1910 IN BOOLEAN AlwaysAllowNumbers
1914 SHELL_PARAM_TYPE CurrentItemType
;
1915 SHELL_PARAM_PACKAGE
*CurrentItemPackage
;
1919 CONST CHAR16
*TempPointer
;
1921 CurrentItemPackage
= NULL
;
1927 // If there is only 1 item we dont need to do anything
1930 *CheckPackage
= NULL
;
1931 return (EFI_SUCCESS
);
1937 ASSERT(CheckList
!= NULL
);
1938 ASSERT(Argv
!= NULL
);
1941 // initialize the linked list
1943 *CheckPackage
= (LIST_ENTRY
*)AllocateZeroPool(sizeof(LIST_ENTRY
));
1944 if (*CheckPackage
== NULL
) {
1945 return (EFI_OUT_OF_RESOURCES
);
1948 InitializeListHead(*CheckPackage
);
1951 // loop through each of the arguments
1953 for (LoopCounter
= 0 ; LoopCounter
< Argc
; ++LoopCounter
) {
1954 if (Argv
[LoopCounter
] == NULL
) {
1956 // do nothing for NULL argv
1958 } else if (InternalIsOnCheckList(Argv
[LoopCounter
], CheckList
, &CurrentItemType
)) {
1960 // We might have leftover if last parameter didnt have optional value
1962 if (GetItemValue
!= 0) {
1964 InsertHeadList(*CheckPackage
, &CurrentItemPackage
->Link
);
1969 CurrentItemPackage
= AllocateZeroPool(sizeof(SHELL_PARAM_PACKAGE
));
1970 if (CurrentItemPackage
== NULL
) {
1971 ShellCommandLineFreeVarList(*CheckPackage
);
1972 *CheckPackage
= NULL
;
1973 return (EFI_OUT_OF_RESOURCES
);
1975 CurrentItemPackage
->Name
= AllocateZeroPool(StrSize(Argv
[LoopCounter
]));
1976 if (CurrentItemPackage
->Name
== NULL
) {
1977 ShellCommandLineFreeVarList(*CheckPackage
);
1978 *CheckPackage
= NULL
;
1979 return (EFI_OUT_OF_RESOURCES
);
1981 StrCpy(CurrentItemPackage
->Name
, Argv
[LoopCounter
]);
1982 CurrentItemPackage
->Type
= CurrentItemType
;
1983 CurrentItemPackage
->OriginalPosition
= (UINTN
)(-1);
1984 CurrentItemPackage
->Value
= NULL
;
1987 // Does this flag require a value
1989 switch (CurrentItemPackage
->Type
) {
1991 // possibly trigger the next loop(s) to populate the value of this item
1997 case TypeDoubleValue
:
2002 GetItemValue
= (UINTN
)(-1);
2007 // this item has no value expected; we are done
2009 InsertHeadList(*CheckPackage
, &CurrentItemPackage
->Link
);
2010 ASSERT(GetItemValue
== 0);
2013 } else if (GetItemValue
!= 0 && !InternalIsFlag(Argv
[LoopCounter
], AlwaysAllowNumbers
)) {
2014 ASSERT(CurrentItemPackage
!= NULL
);
2016 // get the item VALUE for a previous flag
2018 CurrentItemPackage
->Value
= ReallocatePool(ValueSize
, ValueSize
+ StrSize(Argv
[LoopCounter
]) + sizeof(CHAR16
), CurrentItemPackage
->Value
);
2019 ASSERT(CurrentItemPackage
->Value
!= NULL
);
2020 if (ValueSize
== 0) {
2021 StrCpy(CurrentItemPackage
->Value
, Argv
[LoopCounter
]);
2023 StrCat(CurrentItemPackage
->Value
, L
" ");
2024 StrCat(CurrentItemPackage
->Value
, Argv
[LoopCounter
]);
2026 ValueSize
+= StrSize(Argv
[LoopCounter
]) + sizeof(CHAR16
);
2028 if (GetItemValue
== 0) {
2029 InsertHeadList(*CheckPackage
, &CurrentItemPackage
->Link
);
2031 } else if (!InternalIsFlag(Argv
[LoopCounter
], AlwaysAllowNumbers
) ){ //|| ProblemParam == NULL) {
2033 // add this one as a non-flag
2036 TempPointer
= Argv
[LoopCounter
];
2037 if ((*TempPointer
== L
'^' && *(TempPointer
+1) == L
'-')
2038 || (*TempPointer
== L
'^' && *(TempPointer
+1) == L
'/')
2039 || (*TempPointer
== L
'^' && *(TempPointer
+1) == L
'+')
2043 CurrentItemPackage
= AllocateZeroPool(sizeof(SHELL_PARAM_PACKAGE
));
2044 if (CurrentItemPackage
== NULL
) {
2045 ShellCommandLineFreeVarList(*CheckPackage
);
2046 *CheckPackage
= NULL
;
2047 return (EFI_OUT_OF_RESOURCES
);
2049 CurrentItemPackage
->Name
= NULL
;
2050 CurrentItemPackage
->Type
= TypePosition
;
2051 CurrentItemPackage
->Value
= AllocateZeroPool(StrSize(TempPointer
));
2052 if (CurrentItemPackage
->Value
== NULL
) {
2053 ShellCommandLineFreeVarList(*CheckPackage
);
2054 *CheckPackage
= NULL
;
2055 return (EFI_OUT_OF_RESOURCES
);
2057 StrCpy(CurrentItemPackage
->Value
, TempPointer
);
2058 CurrentItemPackage
->OriginalPosition
= Count
++;
2059 InsertHeadList(*CheckPackage
, &CurrentItemPackage
->Link
);
2062 // this was a non-recognised flag... error!
2064 if (ProblemParam
!= NULL
) {
2065 *ProblemParam
= AllocateZeroPool(StrSize(Argv
[LoopCounter
]));
2066 if (*ProblemParam
!= NULL
) {
2067 StrCpy(*ProblemParam
, Argv
[LoopCounter
]);
2070 ShellCommandLineFreeVarList(*CheckPackage
);
2071 *CheckPackage
= NULL
;
2072 return (EFI_VOLUME_CORRUPTED
);
2075 if (GetItemValue
!= 0) {
2077 InsertHeadList(*CheckPackage
, &CurrentItemPackage
->Link
);
2080 // support for AutoPageBreak
2082 if (AutoPageBreak
&& ShellCommandLineGetFlag(*CheckPackage
, L
"-b")) {
2083 ShellSetPageBreakMode(TRUE
);
2085 return (EFI_SUCCESS
);
2089 Checks the command line arguments passed against the list of valid ones.
2090 Optionally removes NULL values first.
2092 If no initialization is required, then return RETURN_SUCCESS.
2094 @param[in] CheckList The pointer to list of parameters to check.
2095 @param[out] CheckPackage The package of checked values.
2096 @param[out] ProblemParam Optional pointer to pointer to unicode string for
2097 the paramater that caused failure.
2098 @param[in] AutoPageBreak Will automatically set PageBreakEnabled.
2099 @param[in] AlwaysAllowNumbers Will never fail for number based flags.
2101 @retval EFI_SUCCESS The operation completed sucessfully.
2102 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
2103 @retval EFI_INVALID_PARAMETER A parameter was invalid.
2104 @retval EFI_VOLUME_CORRUPTED The command line was corrupt.
2105 @retval EFI_DEVICE_ERROR The commands contained 2 opposing arguments. One
2106 of the command line arguments was returned in
2107 ProblemParam if provided.
2108 @retval EFI_NOT_FOUND A argument required a value that was missing.
2109 The invalid command line argument was returned in
2110 ProblemParam if provided.
2114 ShellCommandLineParseEx (
2115 IN CONST SHELL_PARAM_ITEM
*CheckList
,
2116 OUT LIST_ENTRY
**CheckPackage
,
2117 OUT CHAR16
**ProblemParam OPTIONAL
,
2118 IN BOOLEAN AutoPageBreak
,
2119 IN BOOLEAN AlwaysAllowNumbers
2123 // ASSERT that CheckList and CheckPackage aren't NULL
2125 ASSERT(CheckList
!= NULL
);
2126 ASSERT(CheckPackage
!= NULL
);
2129 // Check for UEFI Shell 2.0 protocols
2131 if (gEfiShellParametersProtocol
!= NULL
) {
2132 return (InternalCommandLineParse(CheckList
,
2136 (CONST CHAR16
**) gEfiShellParametersProtocol
->Argv
,
2137 gEfiShellParametersProtocol
->Argc
,
2138 AlwaysAllowNumbers
));
2142 // ASSERT That EFI Shell is not required
2144 ASSERT (mEfiShellInterface
!= NULL
);
2145 return (InternalCommandLineParse(CheckList
,
2149 (CONST CHAR16
**) mEfiShellInterface
->Argv
,
2150 mEfiShellInterface
->Argc
,
2151 AlwaysAllowNumbers
));
2155 Frees shell variable list that was returned from ShellCommandLineParse.
2157 This function will free all the memory that was used for the CheckPackage
2158 list of postprocessed shell arguments.
2160 this function has no return value.
2162 if CheckPackage is NULL, then return
2164 @param CheckPackage the list to de-allocate
2168 ShellCommandLineFreeVarList (
2169 IN LIST_ENTRY
*CheckPackage
2175 // check for CheckPackage == NULL
2177 if (CheckPackage
== NULL
) {
2182 // for each node in the list
2184 for ( Node
= GetFirstNode(CheckPackage
)
2185 ; !IsListEmpty(CheckPackage
)
2186 ; Node
= GetFirstNode(CheckPackage
)
2189 // Remove it from the list
2191 RemoveEntryList(Node
);
2194 // if it has a name free the name
2196 if (((SHELL_PARAM_PACKAGE
*)Node
)->Name
!= NULL
) {
2197 FreePool(((SHELL_PARAM_PACKAGE
*)Node
)->Name
);
2201 // if it has a value free the value
2203 if (((SHELL_PARAM_PACKAGE
*)Node
)->Value
!= NULL
) {
2204 FreePool(((SHELL_PARAM_PACKAGE
*)Node
)->Value
);
2208 // free the node structure
2210 FreePool((SHELL_PARAM_PACKAGE
*)Node
);
2213 // free the list head node
2215 FreePool(CheckPackage
);
2218 Checks for presence of a flag parameter
2220 flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key
2222 if CheckPackage is NULL then return FALSE.
2223 if KeyString is NULL then ASSERT()
2225 @param CheckPackage The package of parsed command line arguments
2226 @param KeyString the Key of the command line argument to check for
2228 @retval TRUE the flag is on the command line
2229 @retval FALSE the flag is not on the command line
2233 ShellCommandLineGetFlag (
2234 IN CONST LIST_ENTRY
* CONST CheckPackage
,
2235 IN CONST CHAR16
* CONST KeyString
2242 // return FALSE for no package or KeyString is NULL
2244 if (CheckPackage
== NULL
|| KeyString
== NULL
) {
2249 // enumerate through the list of parametrs
2251 for ( Node
= GetFirstNode(CheckPackage
)
2252 ; !IsNull (CheckPackage
, Node
)
2253 ; Node
= GetNextNode(CheckPackage
, Node
)
2256 // If the Name matches, return TRUE (and there may be NULL name)
2258 if (((SHELL_PARAM_PACKAGE
*)Node
)->Name
!= NULL
) {
2260 // If Type is TypeStart then only compare the begining of the strings
2262 if (((SHELL_PARAM_PACKAGE
*)Node
)->Type
== TypeStart
) {
2263 if (StrnCmp(KeyString
, ((SHELL_PARAM_PACKAGE
*)Node
)->Name
, StrLen(KeyString
)) == 0) {
2267 TempString
= StrnCatGrow(&TempString
, NULL
, KeyString
, StrLen(((SHELL_PARAM_PACKAGE
*)Node
)->Name
));
2268 if (TempString
!= NULL
) {
2269 if (StringNoCaseCompare(&KeyString
, &((SHELL_PARAM_PACKAGE
*)Node
)->Name
) == 0) {
2270 FreePool(TempString
);
2273 FreePool(TempString
);
2275 } else if (StringNoCaseCompare(&KeyString
, &((SHELL_PARAM_PACKAGE
*)Node
)->Name
) == 0) {
2283 Returns value from command line argument.
2285 Value parameters are in the form of "-<Key> value" or "/<Key> value".
2287 If CheckPackage is NULL, then return NULL.
2289 @param[in] CheckPackage The package of parsed command line arguments.
2290 @param[in] KeyString The Key of the command line argument to check for.
2292 @retval NULL The flag is not on the command line.
2293 @retval !=NULL The pointer to unicode string of the value.
2297 ShellCommandLineGetValue (
2298 IN CONST LIST_ENTRY
*CheckPackage
,
2299 IN CHAR16
*KeyString
2306 // return NULL for no package or KeyString is NULL
2308 if (CheckPackage
== NULL
|| KeyString
== NULL
) {
2313 // enumerate through the list of parametrs
2315 for ( Node
= GetFirstNode(CheckPackage
)
2316 ; !IsNull (CheckPackage
, Node
)
2317 ; Node
= GetNextNode(CheckPackage
, Node
)
2320 // If the Name matches, return TRUE (and there may be NULL name)
2322 if (((SHELL_PARAM_PACKAGE
*)Node
)->Name
!= NULL
) {
2324 // If Type is TypeStart then only compare the begining of the strings
2326 if (((SHELL_PARAM_PACKAGE
*)Node
)->Type
== TypeStart
) {
2327 if (StrnCmp(KeyString
, ((SHELL_PARAM_PACKAGE
*)Node
)->Name
, StrLen(KeyString
)) == 0) {
2328 return (((SHELL_PARAM_PACKAGE
*)Node
)->Name
+ StrLen(KeyString
));
2331 TempString
= StrnCatGrow(&TempString
, NULL
, KeyString
, StrLen(((SHELL_PARAM_PACKAGE
*)Node
)->Name
));
2332 if (TempString
!= NULL
) {
2333 if (StringNoCaseCompare(&KeyString
, &((SHELL_PARAM_PACKAGE
*)Node
)->Name
) == 0) {
2334 FreePool(TempString
);
2335 return (((SHELL_PARAM_PACKAGE
*)Node
)->Name
+ StrLen(KeyString
));
2337 FreePool(TempString
);
2339 } else if (StringNoCaseCompare(&KeyString
, &((SHELL_PARAM_PACKAGE
*)Node
)->Name
) == 0) {
2340 return (((SHELL_PARAM_PACKAGE
*)Node
)->Value
);
2348 Returns raw value from command line argument.
2350 Raw value parameters are in the form of "value" in a specific position in the list.
2352 If CheckPackage is NULL, then return NULL.
2354 @param[in] CheckPackage The package of parsed command line arguments.
2355 @param[in] Position The position of the value.
2357 @retval NULL The flag is not on the command line.
2358 @retval !=NULL The pointer to unicode string of the value.
2362 ShellCommandLineGetRawValue (
2363 IN CONST LIST_ENTRY
* CONST CheckPackage
,
2370 // check for CheckPackage == NULL
2372 if (CheckPackage
== NULL
) {
2377 // enumerate through the list of parametrs
2379 for ( Node
= GetFirstNode(CheckPackage
)
2380 ; !IsNull (CheckPackage
, Node
)
2381 ; Node
= GetNextNode(CheckPackage
, Node
)
2384 // If the position matches, return the value
2386 if (((SHELL_PARAM_PACKAGE
*)Node
)->OriginalPosition
== Position
) {
2387 return (((SHELL_PARAM_PACKAGE
*)Node
)->Value
);
2394 returns the number of command line value parameters that were parsed.
2396 this will not include flags.
2398 @param[in] CheckPackage The package of parsed command line arguments.
2400 @retval (UINTN)-1 No parsing has ocurred
2401 @return other The number of value parameters found
2405 ShellCommandLineGetCount(
2406 IN CONST LIST_ENTRY
*CheckPackage
2412 if (CheckPackage
== NULL
) {
2415 for ( Node1
= GetFirstNode(CheckPackage
), Count
= 0
2416 ; !IsNull (CheckPackage
, Node1
)
2417 ; Node1
= GetNextNode(CheckPackage
, Node1
)
2419 if (((SHELL_PARAM_PACKAGE
*)Node1
)->Name
== NULL
) {
2427 Determins if a parameter is duplicated.
2429 If Param is not NULL then it will point to a callee allocated string buffer
2430 with the parameter value if a duplicate is found.
2432 If CheckPackage is NULL, then ASSERT.
2434 @param[in] CheckPackage The package of parsed command line arguments.
2435 @param[out] Param Upon finding one, a pointer to the duplicated parameter.
2437 @retval EFI_SUCCESS No parameters were duplicated.
2438 @retval EFI_DEVICE_ERROR A duplicate was found.
2442 ShellCommandLineCheckDuplicate (
2443 IN CONST LIST_ENTRY
*CheckPackage
,
2450 ASSERT(CheckPackage
!= NULL
);
2452 for ( Node1
= GetFirstNode(CheckPackage
)
2453 ; !IsNull (CheckPackage
, Node1
)
2454 ; Node1
= GetNextNode(CheckPackage
, Node1
)
2456 for ( Node2
= GetNextNode(CheckPackage
, Node1
)
2457 ; !IsNull (CheckPackage
, Node2
)
2458 ; Node2
= GetNextNode(CheckPackage
, Node2
)
2460 if ((((SHELL_PARAM_PACKAGE
*)Node1
)->Name
!= NULL
) && (((SHELL_PARAM_PACKAGE
*)Node2
)->Name
!= NULL
) && StrCmp(((SHELL_PARAM_PACKAGE
*)Node1
)->Name
, ((SHELL_PARAM_PACKAGE
*)Node2
)->Name
) == 0) {
2461 if (Param
!= NULL
) {
2463 *Param
= StrnCatGrow(Param
, NULL
, ((SHELL_PARAM_PACKAGE
*)Node1
)->Name
, 0);
2465 return (EFI_DEVICE_ERROR
);
2469 return (EFI_SUCCESS
);
2473 This is a find and replace function. Upon successful return the NewString is a copy of
2474 SourceString with each instance of FindTarget replaced with ReplaceWith.
2476 If SourceString and NewString overlap the behavior is undefined.
2478 If the string would grow bigger than NewSize it will halt and return error.
2480 @param[in] SourceString The string with source buffer.
2481 @param[in, out] NewString The string with resultant buffer.
2482 @param[in] NewSize The size in bytes of NewString.
2483 @param[in] FindTarget The string to look for.
2484 @param[in] ReplaceWith The string to replace FindTarget with.
2485 @param[in] SkipPreCarrot If TRUE will skip a FindTarget that has a '^'
2486 immediately before it.
2487 @param[in] ParameterReplacing If TRUE will add "" around items with spaces.
2489 @retval EFI_INVALID_PARAMETER SourceString was NULL.
2490 @retval EFI_INVALID_PARAMETER NewString was NULL.
2491 @retval EFI_INVALID_PARAMETER FindTarget was NULL.
2492 @retval EFI_INVALID_PARAMETER ReplaceWith was NULL.
2493 @retval EFI_INVALID_PARAMETER FindTarget had length < 1.
2494 @retval EFI_INVALID_PARAMETER SourceString had length < 1.
2495 @retval EFI_BUFFER_TOO_SMALL NewSize was less than the minimum size to hold
2496 the new string (truncation occurred).
2497 @retval EFI_SUCCESS The string was successfully copied with replacement.
2501 ShellCopySearchAndReplace(
2502 IN CHAR16 CONST
*SourceString
,
2503 IN OUT CHAR16
*NewString
,
2505 IN CONST CHAR16
*FindTarget
,
2506 IN CONST CHAR16
*ReplaceWith
,
2507 IN CONST BOOLEAN SkipPreCarrot
,
2508 IN CONST BOOLEAN ParameterReplacing
2514 if ( (SourceString
== NULL
)
2515 || (NewString
== NULL
)
2516 || (FindTarget
== NULL
)
2517 || (ReplaceWith
== NULL
)
2518 || (StrLen(FindTarget
) < 1)
2519 || (StrLen(SourceString
) < 1)
2521 return (EFI_INVALID_PARAMETER
);
2524 if (StrStr(ReplaceWith
, L
" ") == NULL
|| !ParameterReplacing
) {
2525 Replace
= StrnCatGrow(&Replace
, NULL
, ReplaceWith
, 0);
2527 Replace
= AllocateZeroPool(StrSize(ReplaceWith
) + 2*sizeof(CHAR16
));
2528 if (Replace
!= NULL
) {
2529 UnicodeSPrint(Replace
, StrSize(ReplaceWith
) + 2*sizeof(CHAR16
), L
"\"%s\"", ReplaceWith
);
2532 if (Replace
== NULL
) {
2533 return (EFI_OUT_OF_RESOURCES
);
2535 NewString
= SetMem16(NewString
, NewSize
, CHAR_NULL
);
2536 while (*SourceString
!= CHAR_NULL
) {
2538 // if we find the FindTarget and either Skip == FALSE or Skip and we
2539 // dont have a carrot do a replace...
2541 if (StrnCmp(SourceString
, FindTarget
, StrLen(FindTarget
)) == 0
2542 && ((SkipPreCarrot
&& *(SourceString
-1) != L
'^') || !SkipPreCarrot
)
2544 SourceString
+= StrLen(FindTarget
);
2545 Size
= StrSize(NewString
);
2546 if ((Size
+ (StrLen(Replace
)*sizeof(CHAR16
))) > NewSize
) {
2548 return (EFI_BUFFER_TOO_SMALL
);
2550 StrCat(NewString
, Replace
);
2552 Size
= StrSize(NewString
);
2553 if (Size
+ sizeof(CHAR16
) > NewSize
) {
2555 return (EFI_BUFFER_TOO_SMALL
);
2557 StrnCat(NewString
, SourceString
, 1);
2562 return (EFI_SUCCESS
);
2566 Internal worker function to output a string.
2568 This function will output a string to the correct StdOut.
2570 @param[in] String The string to print out.
2572 @retval EFI_SUCCESS The operation was sucessful.
2573 @retval !EFI_SUCCESS The operation failed.
2578 IN CONST CHAR16
*String
2582 Size
= StrSize(String
) - sizeof(CHAR16
);
2584 return (EFI_SUCCESS
);
2586 if (gEfiShellParametersProtocol
!= NULL
) {
2587 return (gEfiShellProtocol
->WriteFile(gEfiShellParametersProtocol
->StdOut
, &Size
, (VOID
*)String
));
2589 if (mEfiShellInterface
!= NULL
) {
2590 if (mEfiShellInterface
->RedirArgc
== 0) {
2592 // Divide in half for old shell. Must be string length not size.
2594 Size
/=2; // Divide in half only when no redirection.
2596 return (mEfiShellInterface
->StdOut
->Write(mEfiShellInterface
->StdOut
, &Size
, (VOID
*)String
));
2599 return (EFI_UNSUPPORTED
);
2603 Print at a specific location on the screen.
2605 This function will move the cursor to a given screen location and print the specified string
2607 If -1 is specified for either the Row or Col the current screen location for BOTH
2610 if either Row or Col is out of range for the current console, then ASSERT
2611 if Format is NULL, then ASSERT
2613 In addition to the standard %-based flags as supported by UefiLib Print() this supports
2614 the following additional flags:
2615 %N - Set output attribute to normal
2616 %H - Set output attribute to highlight
2617 %E - Set output attribute to error
2618 %B - Set output attribute to blue color
2619 %V - Set output attribute to green color
2621 Note: The background color is controlled by the shell command cls.
2623 @param[in] Col the column to print at
2624 @param[in] Row the row to print at
2625 @param[in] Format the format string
2626 @param[in] Marker the marker for the variable argument list
2628 @return EFI_SUCCESS The operation was successful.
2629 @return EFI_DEVICE_ERROR The console device reported an error.
2633 InternalShellPrintWorker(
2634 IN INT32 Col OPTIONAL
,
2635 IN INT32 Row OPTIONAL
,
2636 IN CONST CHAR16
*Format
,
2641 CHAR16
*ResumeLocation
;
2642 CHAR16
*FormatWalker
;
2643 UINTN OriginalAttribute
;
2644 CHAR16
*mPostReplaceFormat
;
2645 CHAR16
*mPostReplaceFormat2
;
2647 mPostReplaceFormat
= AllocateZeroPool (PcdGet16 (PcdShellPrintBufferSize
));
2648 mPostReplaceFormat2
= AllocateZeroPool (PcdGet16 (PcdShellPrintBufferSize
));
2650 if (mPostReplaceFormat
== NULL
|| mPostReplaceFormat2
== NULL
) {
2651 SHELL_FREE_NON_NULL(mPostReplaceFormat
);
2652 SHELL_FREE_NON_NULL(mPostReplaceFormat2
);
2653 return (EFI_OUT_OF_RESOURCES
);
2656 Status
= EFI_SUCCESS
;
2657 OriginalAttribute
= gST
->ConOut
->Mode
->Attribute
;
2660 // Back and forth each time fixing up 1 of our flags...
2662 Status
= ShellCopySearchAndReplace(Format
, mPostReplaceFormat
, PcdGet16 (PcdShellPrintBufferSize
), L
"%N", L
"%%N", FALSE
, FALSE
);
2663 ASSERT_EFI_ERROR(Status
);
2664 Status
= ShellCopySearchAndReplace(mPostReplaceFormat
, mPostReplaceFormat2
, PcdGet16 (PcdShellPrintBufferSize
), L
"%E", L
"%%E", FALSE
, FALSE
);
2665 ASSERT_EFI_ERROR(Status
);
2666 Status
= ShellCopySearchAndReplace(mPostReplaceFormat2
, mPostReplaceFormat
, PcdGet16 (PcdShellPrintBufferSize
), L
"%H", L
"%%H", FALSE
, FALSE
);
2667 ASSERT_EFI_ERROR(Status
);
2668 Status
= ShellCopySearchAndReplace(mPostReplaceFormat
, mPostReplaceFormat2
, PcdGet16 (PcdShellPrintBufferSize
), L
"%B", L
"%%B", FALSE
, FALSE
);
2669 ASSERT_EFI_ERROR(Status
);
2670 Status
= ShellCopySearchAndReplace(mPostReplaceFormat2
, mPostReplaceFormat
, PcdGet16 (PcdShellPrintBufferSize
), L
"%V", L
"%%V", FALSE
, FALSE
);
2671 ASSERT_EFI_ERROR(Status
);
2674 // Use the last buffer from replacing to print from...
2676 UnicodeVSPrint (mPostReplaceFormat2
, PcdGet16 (PcdShellPrintBufferSize
), mPostReplaceFormat
, Marker
);
2678 if (Col
!= -1 && Row
!= -1) {
2679 Status
= gST
->ConOut
->SetCursorPosition(gST
->ConOut
, Col
, Row
);
2682 FormatWalker
= mPostReplaceFormat2
;
2683 while (*FormatWalker
!= CHAR_NULL
) {
2685 // Find the next attribute change request
2687 ResumeLocation
= StrStr(FormatWalker
, L
"%");
2688 if (ResumeLocation
!= NULL
) {
2689 *ResumeLocation
= CHAR_NULL
;
2692 // print the current FormatWalker string
2694 if (StrLen(FormatWalker
)>0) {
2695 Status
= InternalPrintTo(FormatWalker
);
2696 if (EFI_ERROR(Status
)) {
2702 // update the attribute
2704 if (ResumeLocation
!= NULL
) {
2705 if (*(ResumeLocation
-1) == L
'^') {
2707 // Print a simple '%' symbol
2709 Status
= InternalPrintTo(L
"%");
2710 ResumeLocation
= ResumeLocation
- 1;
2712 switch (*(ResumeLocation
+1)) {
2714 gST
->ConOut
->SetAttribute(gST
->ConOut
, OriginalAttribute
);
2717 gST
->ConOut
->SetAttribute(gST
->ConOut
, EFI_TEXT_ATTR(EFI_YELLOW
, ((OriginalAttribute
&(BIT4
|BIT5
|BIT6
))>>4)));
2720 gST
->ConOut
->SetAttribute(gST
->ConOut
, EFI_TEXT_ATTR(EFI_WHITE
, ((OriginalAttribute
&(BIT4
|BIT5
|BIT6
))>>4)));
2723 gST
->ConOut
->SetAttribute(gST
->ConOut
, EFI_TEXT_ATTR(EFI_BLUE
, ((OriginalAttribute
&(BIT4
|BIT5
|BIT6
))>>4)));
2726 gST
->ConOut
->SetAttribute(gST
->ConOut
, EFI_TEXT_ATTR(EFI_GREEN
, ((OriginalAttribute
&(BIT4
|BIT5
|BIT6
))>>4)));
2730 // Print a simple '%' symbol
2732 Status
= InternalPrintTo(L
"%");
2733 if (EFI_ERROR(Status
)) {
2736 ResumeLocation
= ResumeLocation
- 1;
2742 // reset to normal now...
2748 // update FormatWalker to Resume + 2 (skip the % and the indicator)
2750 FormatWalker
= ResumeLocation
+ 2;
2753 gST
->ConOut
->SetAttribute(gST
->ConOut
, OriginalAttribute
);
2755 SHELL_FREE_NON_NULL(mPostReplaceFormat
);
2756 SHELL_FREE_NON_NULL(mPostReplaceFormat2
);
2761 Print at a specific location on the screen.
2763 This function will move the cursor to a given screen location and print the specified string.
2765 If -1 is specified for either the Row or Col the current screen location for BOTH
2768 If either Row or Col is out of range for the current console, then ASSERT.
2769 If Format is NULL, then ASSERT.
2771 In addition to the standard %-based flags as supported by UefiLib Print() this supports
2772 the following additional flags:
2773 %N - Set output attribute to normal
2774 %H - Set output attribute to highlight
2775 %E - Set output attribute to error
2776 %B - Set output attribute to blue color
2777 %V - Set output attribute to green color
2779 Note: The background color is controlled by the shell command cls.
2781 @param[in] Col the column to print at
2782 @param[in] Row the row to print at
2783 @param[in] Format the format string
2784 @param[in] ... The variable argument list.
2786 @return EFI_SUCCESS The printing was successful.
2787 @return EFI_DEVICE_ERROR The console device reported an error.
2792 IN INT32 Col OPTIONAL
,
2793 IN INT32 Row OPTIONAL
,
2794 IN CONST CHAR16
*Format
,
2800 if (Format
== NULL
) {
2801 return (EFI_INVALID_PARAMETER
);
2803 VA_START (Marker
, Format
);
2804 RetVal
= InternalShellPrintWorker(Col
, Row
, Format
, Marker
);
2810 Print at a specific location on the screen.
2812 This function will move the cursor to a given screen location and print the specified string.
2814 If -1 is specified for either the Row or Col the current screen location for BOTH
2817 If either Row or Col is out of range for the current console, then ASSERT.
2818 If Format is NULL, then ASSERT.
2820 In addition to the standard %-based flags as supported by UefiLib Print() this supports
2821 the following additional flags:
2822 %N - Set output attribute to normal.
2823 %H - Set output attribute to highlight.
2824 %E - Set output attribute to error.
2825 %B - Set output attribute to blue color.
2826 %V - Set output attribute to green color.
2828 Note: The background color is controlled by the shell command cls.
2830 @param[in] Col The column to print at.
2831 @param[in] Row The row to print at.
2832 @param[in] Language The language of the string to retrieve. If this parameter
2833 is NULL, then the current platform language is used.
2834 @param[in] HiiFormatStringId The format string Id for getting from Hii.
2835 @param[in] HiiFormatHandle The format string Handle for getting from Hii.
2836 @param[in] ... The variable argument list.
2838 @return EFI_SUCCESS The printing was successful.
2839 @return EFI_DEVICE_ERROR The console device reported an error.
2844 IN INT32 Col OPTIONAL
,
2845 IN INT32 Row OPTIONAL
,
2846 IN CONST CHAR8
*Language OPTIONAL
,
2847 IN CONST EFI_STRING_ID HiiFormatStringId
,
2848 IN CONST EFI_HANDLE HiiFormatHandle
,
2853 CHAR16
*HiiFormatString
;
2856 VA_START (Marker
, HiiFormatHandle
);
2857 HiiFormatString
= HiiGetString(HiiFormatHandle
, HiiFormatStringId
, Language
);
2858 ASSERT(HiiFormatString
!= NULL
);
2860 RetVal
= InternalShellPrintWorker(Col
, Row
, HiiFormatString
, Marker
);
2862 SHELL_FREE_NON_NULL(HiiFormatString
);
2869 Function to determine if a given filename represents a file or a directory.
2871 @param[in] DirName Path to directory to test.
2873 @retval EFI_SUCCESS The Path represents a directory
2874 @retval EFI_NOT_FOUND The Path does not represent a directory
2875 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
2876 @return The path failed to open
2881 IN CONST CHAR16
*DirName
2885 SHELL_FILE_HANDLE Handle
;
2886 CHAR16
*TempLocation
;
2887 CHAR16
*TempLocation2
;
2889 ASSERT(DirName
!= NULL
);
2892 TempLocation
= NULL
;
2894 Status
= ShellOpenFileByName(DirName
, &Handle
, EFI_FILE_MODE_READ
, 0);
2895 if (EFI_ERROR(Status
)) {
2897 // try good logic first.
2899 if (gEfiShellProtocol
!= NULL
) {
2900 TempLocation
= StrnCatGrow(&TempLocation
, NULL
, DirName
, 0);
2901 if (TempLocation
== NULL
) {
2902 ShellCloseFile(&Handle
);
2903 return (EFI_OUT_OF_RESOURCES
);
2905 TempLocation2
= StrStr(TempLocation
, L
":");
2906 if (TempLocation2
!= NULL
&& StrLen(StrStr(TempLocation
, L
":")) == 2) {
2907 *(TempLocation2
+1) = CHAR_NULL
;
2909 if (gEfiShellProtocol
->GetDevicePathFromMap(TempLocation
) != NULL
) {
2910 FreePool(TempLocation
);
2911 return (EFI_SUCCESS
);
2913 FreePool(TempLocation
);
2916 // probably a map name?!?!!?
2918 TempLocation
= StrStr(DirName
, L
"\\");
2919 if (TempLocation
!= NULL
&& *(TempLocation
+1) == CHAR_NULL
) {
2920 return (EFI_SUCCESS
);
2926 if (FileHandleIsDirectory(Handle
) == EFI_SUCCESS
) {
2927 ShellCloseFile(&Handle
);
2928 return (EFI_SUCCESS
);
2930 ShellCloseFile(&Handle
);
2931 return (EFI_NOT_FOUND
);
2935 Function to determine if a given filename represents a file.
2937 @param[in] Name Path to file to test.
2939 @retval EFI_SUCCESS The Path represents a file.
2940 @retval EFI_NOT_FOUND The Path does not represent a file.
2941 @retval other The path failed to open.
2946 IN CONST CHAR16
*Name
2950 SHELL_FILE_HANDLE Handle
;
2952 ASSERT(Name
!= NULL
);
2956 Status
= ShellOpenFileByName(Name
, &Handle
, EFI_FILE_MODE_READ
, 0);
2957 if (EFI_ERROR(Status
)) {
2961 if (FileHandleIsDirectory(Handle
) != EFI_SUCCESS
) {
2962 ShellCloseFile(&Handle
);
2963 return (EFI_SUCCESS
);
2965 ShellCloseFile(&Handle
);
2966 return (EFI_NOT_FOUND
);
2970 Function to determine if a given filename represents a file.
2972 This will search the CWD and then the Path.
2974 If Name is NULL, then ASSERT.
2976 @param[in] Name Path to file to test.
2978 @retval EFI_SUCCESS The Path represents a file.
2979 @retval EFI_NOT_FOUND The Path does not represent a file.
2980 @retval other The path failed to open.
2985 IN CONST CHAR16
*Name
2991 if (!EFI_ERROR(ShellIsFile(Name
))) {
2992 return (EFI_SUCCESS
);
2995 NewName
= ShellFindFilePath(Name
);
2996 if (NewName
== NULL
) {
2997 return (EFI_NOT_FOUND
);
2999 Status
= ShellIsFile(NewName
);
3005 Function to determine whether a string is decimal or hex representation of a number
3006 and return the number converted from the string.
3008 @param[in] String String representation of a number
3011 @retval (UINTN)(-1) An error ocurred.
3016 IN CONST CHAR16
*String
3024 if (!InternalShellIsHexOrDecimalNumber(String
, Hex
, TRUE
)) {
3028 if (!EFI_ERROR(ShellConvertStringToUint64(String
, &RetVal
, Hex
, TRUE
))) {
3029 return ((UINTN
)RetVal
);
3031 return ((UINTN
)(-1));
3035 Safely append with automatic string resizing given length of Destination and
3036 desired length of copy from Source.
3038 append the first D characters of Source to the end of Destination, where D is
3039 the lesser of Count and the StrLen() of Source. If appending those D characters
3040 will fit within Destination (whose Size is given as CurrentSize) and
3041 still leave room for a NULL terminator, then those characters are appended,
3042 starting at the original terminating NULL of Destination, and a new terminating
3045 If appending D characters onto Destination will result in a overflow of the size
3046 given in CurrentSize the string will be grown such that the copy can be performed
3047 and CurrentSize will be updated to the new size.
3049 If Source is NULL, there is nothing to append, just return the current buffer in
3052 if Destination is NULL, then ASSERT()
3053 if Destination's current length (including NULL terminator) is already more then
3054 CurrentSize, then ASSERT()
3056 @param[in, out] Destination The String to append onto
3057 @param[in, out] CurrentSize on call the number of bytes in Destination. On
3058 return possibly the new size (still in bytes). if NULL
3059 then allocate whatever is needed.
3060 @param[in] Source The String to append from
3061 @param[in] Count Maximum number of characters to append. if 0 then
3064 @return Destination return the resultant string.
3069 IN OUT CHAR16
**Destination
,
3070 IN OUT UINTN
*CurrentSize
,
3071 IN CONST CHAR16
*Source
,
3075 UINTN DestinationStartSize
;
3081 ASSERT(Destination
!= NULL
);
3084 // If there's nothing to do then just return Destination
3086 if (Source
== NULL
) {
3087 return (*Destination
);
3091 // allow for un-initialized pointers, based on size being 0
3093 if (CurrentSize
!= NULL
&& *CurrentSize
== 0) {
3094 *Destination
= NULL
;
3098 // allow for NULL pointers address as Destination
3100 if (*Destination
!= NULL
) {
3101 ASSERT(CurrentSize
!= 0);
3102 DestinationStartSize
= StrSize(*Destination
);
3103 ASSERT(DestinationStartSize
<= *CurrentSize
);
3105 DestinationStartSize
= 0;
3106 // ASSERT(*CurrentSize == 0);
3110 // Append all of Source?
3113 Count
= StrLen(Source
);
3117 // Test and grow if required
3119 if (CurrentSize
!= NULL
) {
3120 NewSize
= *CurrentSize
;
3121 while (NewSize
< (DestinationStartSize
+ (Count
*sizeof(CHAR16
)))) {
3122 NewSize
+= 2 * Count
* sizeof(CHAR16
);
3124 *Destination
= ReallocatePool(*CurrentSize
, NewSize
, *Destination
);
3125 *CurrentSize
= NewSize
;
3127 *Destination
= AllocateZeroPool((Count
+1)*sizeof(CHAR16
));
3131 // Now use standard StrnCat on a big enough buffer
3133 if (*Destination
== NULL
) {
3136 return StrnCat(*Destination
, Source
, Count
);
3140 Prompt the user and return the resultant answer to the requestor.
3142 This function will display the requested question on the shell prompt and then
3143 wait for an apropriate answer to be input from the console.
3145 if the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue
3146 or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.
3148 if the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type
3151 In either case *Response must be callee freed if Response was not NULL;
3153 @param Type What type of question is asked. This is used to filter the input
3154 to prevent invalid answers to question.
3155 @param Prompt Pointer to string prompt to use to request input.
3156 @param Response Pointer to Response which will be populated upon return.
3158 @retval EFI_SUCCESS The operation was sucessful.
3159 @retval EFI_UNSUPPORTED The operation is not supported as requested.
3160 @retval EFI_INVALID_PARAMETER A parameter was invalid.
3161 @return other The operation failed.
3165 ShellPromptForResponse (
3166 IN SHELL_PROMPT_REQUEST_TYPE Type
,
3167 IN CHAR16
*Prompt OPTIONAL
,
3168 IN OUT VOID
**Response OPTIONAL
3174 SHELL_PROMPT_RESPONSE
*Resp
;
3178 Status
= EFI_UNSUPPORTED
;
3182 if (Type
!= ShellPromptResponseTypeFreeform
) {
3183 Resp
= (SHELL_PROMPT_RESPONSE
*)AllocateZeroPool(sizeof(SHELL_PROMPT_RESPONSE
));
3185 return (EFI_OUT_OF_RESOURCES
);
3190 case ShellPromptResponseTypeQuitContinue
:
3191 if (Prompt
!= NULL
) {
3192 ShellPrintEx(-1, -1, L
"%s", Prompt
);
3195 // wait for valid response
3197 gBS
->WaitForEvent (1, &gST
->ConIn
->WaitForKey
, &EventIndex
);
3198 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3199 ASSERT_EFI_ERROR(Status
);
3200 ShellPrintEx(-1, -1, L
"%c", Key
.UnicodeChar
);
3201 if (Key
.UnicodeChar
== L
'Q' || Key
.UnicodeChar
==L
'q') {
3202 *Resp
= ShellPromptResponseQuit
;
3204 *Resp
= ShellPromptResponseContinue
;
3207 case ShellPromptResponseTypeYesNoCancel
:
3208 if (Prompt
!= NULL
) {
3209 ShellPrintEx(-1, -1, L
"%s", Prompt
);
3212 // wait for valid response
3214 *Resp
= ShellPromptResponseMax
;
3215 while (*Resp
== ShellPromptResponseMax
) {
3216 gBS
->WaitForEvent (1, &gST
->ConIn
->WaitForKey
, &EventIndex
);
3217 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3218 ASSERT_EFI_ERROR(Status
);
3219 ShellPrintEx(-1, -1, L
"%c", Key
.UnicodeChar
);
3220 switch (Key
.UnicodeChar
) {
3223 *Resp
= ShellPromptResponseYes
;
3227 *Resp
= ShellPromptResponseNo
;
3231 *Resp
= ShellPromptResponseCancel
;
3235 break; case ShellPromptResponseTypeYesNoAllCancel
:
3236 if (Prompt
!= NULL
) {
3237 ShellPrintEx(-1, -1, L
"%s", Prompt
);
3240 // wait for valid response
3242 *Resp
= ShellPromptResponseMax
;
3243 while (*Resp
== ShellPromptResponseMax
) {
3244 gBS
->WaitForEvent (1, &gST
->ConIn
->WaitForKey
, &EventIndex
);
3245 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3246 ASSERT_EFI_ERROR(Status
);
3247 ShellPrintEx(-1, -1, L
"%c", Key
.UnicodeChar
);
3248 switch (Key
.UnicodeChar
) {
3251 *Resp
= ShellPromptResponseYes
;
3255 *Resp
= ShellPromptResponseNo
;
3259 *Resp
= ShellPromptResponseAll
;
3263 *Resp
= ShellPromptResponseCancel
;
3268 case ShellPromptResponseTypeEnterContinue
:
3269 case ShellPromptResponseTypeAnyKeyContinue
:
3270 if (Prompt
!= NULL
) {
3271 ShellPrintEx(-1, -1, L
"%s", Prompt
);
3274 // wait for valid response
3276 *Resp
= ShellPromptResponseMax
;
3277 while (*Resp
== ShellPromptResponseMax
) {
3278 gBS
->WaitForEvent (1, &gST
->ConIn
->WaitForKey
, &EventIndex
);
3279 if (Type
== ShellPromptResponseTypeEnterContinue
) {
3280 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3281 ASSERT_EFI_ERROR(Status
);
3282 ShellPrintEx(-1, -1, L
"%c", Key
.UnicodeChar
);
3283 if (Key
.UnicodeChar
== CHAR_CARRIAGE_RETURN
) {
3284 *Resp
= ShellPromptResponseContinue
;
3288 if (Type
== ShellPromptResponseTypeAnyKeyContinue
) {
3289 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3290 ASSERT_EFI_ERROR(Status
);
3291 *Resp
= ShellPromptResponseContinue
;
3296 case ShellPromptResponseTypeYesNo
:
3297 if (Prompt
!= NULL
) {
3298 ShellPrintEx(-1, -1, L
"%s", Prompt
);
3301 // wait for valid response
3303 *Resp
= ShellPromptResponseMax
;
3304 while (*Resp
== ShellPromptResponseMax
) {
3305 gBS
->WaitForEvent (1, &gST
->ConIn
->WaitForKey
, &EventIndex
);
3306 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3307 ASSERT_EFI_ERROR(Status
);
3308 ShellPrintEx(-1, -1, L
"%c", Key
.UnicodeChar
);
3309 switch (Key
.UnicodeChar
) {
3312 *Resp
= ShellPromptResponseYes
;
3316 *Resp
= ShellPromptResponseNo
;
3321 case ShellPromptResponseTypeFreeform
:
3322 if (Prompt
!= NULL
) {
3323 ShellPrintEx(-1, -1, L
"%s", Prompt
);
3326 gBS
->WaitForEvent (1, &gST
->ConIn
->WaitForKey
, &EventIndex
);
3327 Status
= gST
->ConIn
->ReadKeyStroke (gST
->ConIn
, &Key
);
3328 ASSERT_EFI_ERROR(Status
);
3329 ShellPrintEx(-1, -1, L
"%c", Key
.UnicodeChar
);
3330 if (Key
.UnicodeChar
== CHAR_CARRIAGE_RETURN
) {
3333 ASSERT((Buffer
== NULL
&& Size
== 0) || (Buffer
!= NULL
));
3334 StrnCatGrow(&Buffer
, &Size
, &Key
.UnicodeChar
, 1);
3338 // This is the location to add new prompt types.
3344 if (Response
!= NULL
) {
3347 } else if (Buffer
!= NULL
) {
3354 if (Buffer
!= NULL
) {
3359 ShellPrintEx(-1, -1, L
"\r\n");
3364 Prompt the user and return the resultant answer to the requestor.
3366 This function is the same as ShellPromptForResponse, except that the prompt is
3367 automatically pulled from HII.
3369 @param Type What type of question is asked. This is used to filter the input
3370 to prevent invalid answers to question.
3371 @param[in] HiiFormatStringId The format string Id for getting from Hii.
3372 @param[in] HiiFormatHandle The format string Handle for getting from Hii.
3373 @param Response Pointer to Response which will be populated upon return.
3375 @retval EFI_SUCCESS the operation was sucessful.
3376 @return other the operation failed.
3378 @sa ShellPromptForResponse
3382 ShellPromptForResponseHii (
3383 IN SHELL_PROMPT_REQUEST_TYPE Type
,
3384 IN CONST EFI_STRING_ID HiiFormatStringId
,
3385 IN CONST EFI_HANDLE HiiFormatHandle
,
3386 IN OUT VOID
**Response
3392 Prompt
= HiiGetString(HiiFormatHandle
, HiiFormatStringId
, NULL
);
3393 Status
= ShellPromptForResponse(Type
, Prompt
, Response
);
3399 Function to determin if an entire string is a valid number.
3401 If Hex it must be preceeded with a 0x or has ForceHex, set TRUE.
3403 @param[in] String The string to evaluate.
3404 @param[in] ForceHex TRUE - always assume hex.
3405 @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going.
3407 @retval TRUE It is all numeric (dec/hex) characters.
3408 @retval FALSE There is a non-numeric character.
3412 InternalShellIsHexOrDecimalNumber (
3413 IN CONST CHAR16
*String
,
3414 IN CONST BOOLEAN ForceHex
,
3415 IN CONST BOOLEAN StopAtSpace
3421 // chop off a single negative sign
3423 if (String
!= NULL
&& *String
== L
'-') {
3427 if (String
== NULL
) {
3432 // chop leading zeroes
3434 while(String
!= NULL
&& *String
== L
'0'){
3438 // allow '0x' or '0X', but not 'x' or 'X'
3440 if (String
!= NULL
&& (*String
== L
'x' || *String
== L
'X')) {
3441 if (*(String
-1) != L
'0') {
3443 // we got an x without a preceeding 0
3449 } else if (ForceHex
) {
3456 // loop through the remaining characters and use the lib function
3458 for ( ; String
!= NULL
&& *String
!= CHAR_NULL
&& !(StopAtSpace
&& *String
== L
' ') ; String
++){
3460 if (!ShellIsHexaDecimalDigitCharacter(*String
)) {
3464 if (!ShellIsDecimalDigitCharacter(*String
)) {
3474 Function to determine if a given filename exists.
3476 @param[in] Name Path to test.
3478 @retval EFI_SUCCESS The Path represents a file.
3479 @retval EFI_NOT_FOUND The Path does not represent a file.
3480 @retval other The path failed to open.
3485 IN CONST CHAR16
*Name
3489 EFI_SHELL_FILE_INFO
*List
;
3491 ASSERT(Name
!= NULL
);
3494 Status
= ShellOpenFileMetaArg((CHAR16
*)Name
, EFI_FILE_MODE_READ
, &List
);
3495 if (EFI_ERROR(Status
)) {
3499 ShellCloseFileMetaArg(&List
);
3501 return (EFI_SUCCESS
);
3505 Convert a Unicode character to upper case only if
3506 it maps to a valid small-case ASCII character.
3508 This internal function only deal with Unicode character
3509 which maps to a valid small-case ASCII character, i.e.
3510 L'a' to L'z'. For other Unicode character, the input character
3511 is returned directly.
3513 @param Char The character to convert.
3515 @retval LowerCharacter If the Char is with range L'a' to L'z'.
3516 @retval Unchanged Otherwise.
3521 InternalShellCharToUpper (
3525 if (Char
>= L
'a' && Char
<= L
'z') {
3526 return (CHAR16
) (Char
- (L
'a' - L
'A'));
3533 Convert a Unicode character to numerical value.
3535 This internal function only deal with Unicode character
3536 which maps to a valid hexadecimal ASII character, i.e.
3537 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
3538 Unicode character, the value returned does not make sense.
3540 @param Char The character to convert.
3542 @return The numerical value converted.
3547 InternalShellHexCharToUintn (
3551 if (ShellIsDecimalDigitCharacter (Char
)) {
3555 return (UINTN
) (10 + InternalShellCharToUpper (Char
) - L
'A');
3559 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
3561 This function returns a value of type UINTN by interpreting the contents
3562 of the Unicode string specified by String as a hexadecimal number.
3563 The format of the input Unicode string String is:
3565 [spaces][zeros][x][hexadecimal digits].
3567 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
3568 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
3569 If "x" appears in the input string, it must be prefixed with at least one 0.
3570 The function will ignore the pad space, which includes spaces or tab characters,
3571 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
3572 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
3573 first valid hexadecimal digit. Then, the function stops at the first character that is
3574 a not a valid hexadecimal character or NULL, whichever one comes first.
3576 If String has only pad spaces, then zero is returned.
3577 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
3578 then zero is returned.
3580 @param[in] String A pointer to a Null-terminated Unicode string.
3581 @param[out] Value Upon a successful return the value of the conversion.
3582 @param[in] StopAtSpace FALSE to skip spaces.
3584 @retval EFI_SUCCESS The conversion was successful.
3585 @retval EFI_INVALID_PARAMETER A parameter was NULL or invalid.
3586 @retval EFI_DEVICE_ERROR An overflow occured.
3590 InternalShellStrHexToUint64 (
3591 IN CONST CHAR16
*String
,
3593 IN CONST BOOLEAN StopAtSpace
3598 if (String
== NULL
|| StrSize(String
) == 0 || Value
== NULL
) {
3599 return (EFI_INVALID_PARAMETER
);
3603 // Ignore the pad spaces (space or tab)
3605 while ((*String
== L
' ') || (*String
== L
'\t')) {
3610 // Ignore leading Zeros after the spaces
3612 while (*String
== L
'0') {
3616 if (InternalShellCharToUpper (*String
) == L
'X') {
3617 if (*(String
- 1) != L
'0') {
3629 // Skip spaces if requested
3631 while (StopAtSpace
&& *String
== L
' ') {
3635 while (ShellIsHexaDecimalDigitCharacter (*String
)) {
3637 // If the Hex Number represented by String overflows according
3638 // to the range defined by UINTN, then ASSERT().
3640 if (!(Result
<= (RShiftU64((((UINT64
) ~0) - InternalShellHexCharToUintn (*String
)), 4)))) {
3641 // if (!(Result <= ((((UINT64) ~0) - InternalShellHexCharToUintn (*String)) >> 4))) {
3642 return (EFI_DEVICE_ERROR
);
3645 Result
= (LShiftU64(Result
, 4));
3646 Result
+= InternalShellHexCharToUintn (*String
);
3650 // Skip spaces if requested
3652 while (StopAtSpace
&& *String
== L
' ') {
3658 return (EFI_SUCCESS
);
3662 Convert a Null-terminated Unicode decimal string to a value of
3665 This function returns a value of type UINT64 by interpreting the contents
3666 of the Unicode string specified by String as a decimal number. The format
3667 of the input Unicode string String is:
3669 [spaces] [decimal digits].
3671 The valid decimal digit character is in the range [0-9]. The
3672 function will ignore the pad space, which includes spaces or
3673 tab characters, before [decimal digits]. The running zero in the
3674 beginning of [decimal digits] will be ignored. Then, the function
3675 stops at the first character that is a not a valid decimal character
3676 or a Null-terminator, whichever one comes first.
3678 If String has only pad spaces, then 0 is returned.
3679 If String has no pad spaces or valid decimal digits,
3682 @param[in] String A pointer to a Null-terminated Unicode string.
3683 @param[out] Value Upon a successful return the value of the conversion.
3684 @param[in] StopAtSpace FALSE to skip spaces.
3686 @retval EFI_SUCCESS The conversion was successful.
3687 @retval EFI_INVALID_PARAMETER A parameter was NULL or invalid.
3688 @retval EFI_DEVICE_ERROR An overflow occured.
3692 InternalShellStrDecimalToUint64 (
3693 IN CONST CHAR16
*String
,
3695 IN CONST BOOLEAN StopAtSpace
3700 if (String
== NULL
|| StrSize (String
) == 0 || Value
== NULL
) {
3701 return (EFI_INVALID_PARAMETER
);
3705 // Ignore the pad spaces (space or tab)
3707 while ((*String
== L
' ') || (*String
== L
'\t')) {
3712 // Ignore leading Zeros after the spaces
3714 while (*String
== L
'0') {
3721 // Skip spaces if requested
3723 while (StopAtSpace
&& *String
== L
' ') {
3726 while (ShellIsDecimalDigitCharacter (*String
)) {
3728 // If the number represented by String overflows according
3729 // to the range defined by UINT64, then ASSERT().
3732 if (!(Result
<= (DivU64x32((((UINT64
) ~0) - (*String
- L
'0')),10)))) {
3733 return (EFI_DEVICE_ERROR
);
3736 Result
= MultU64x32(Result
, 10) + (*String
- L
'0');
3740 // Stop at spaces if requested
3742 if (StopAtSpace
&& *String
== L
' ') {
3749 return (EFI_SUCCESS
);
3753 Function to verify and convert a string to its numerical value.
3755 If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
3757 @param[in] String The string to evaluate.
3758 @param[out] Value Upon a successful return the value of the conversion.
3759 @param[in] ForceHex TRUE - always assume hex.
3760 @param[in] StopAtSpace FALSE to skip spaces.
3762 @retval EFI_SUCCESS The conversion was successful.
3763 @retval EFI_INVALID_PARAMETER String contained an invalid character.
3764 @retval EFI_NOT_FOUND String was a number, but Value was NULL.
3768 ShellConvertStringToUint64(
3769 IN CONST CHAR16
*String
,
3771 IN CONST BOOLEAN ForceHex
,
3772 IN CONST BOOLEAN StopAtSpace
3776 CONST CHAR16
*Walker
;
3782 if (!InternalShellIsHexOrDecimalNumber(String
, Hex
, StopAtSpace
)) {
3785 if (!InternalShellIsHexOrDecimalNumber(String
, Hex
, StopAtSpace
)) {
3786 return (EFI_INVALID_PARAMETER
);
3789 return (EFI_INVALID_PARAMETER
);
3794 // Chop off leading spaces
3796 for (Walker
= String
; Walker
!= NULL
&& *Walker
!= CHAR_NULL
&& *Walker
== L
' '; Walker
++);
3799 // make sure we have something left that is numeric.
3801 if (Walker
== NULL
|| *Walker
== CHAR_NULL
|| !InternalShellIsHexOrDecimalNumber(Walker
, Hex
, StopAtSpace
)) {
3802 return (EFI_INVALID_PARAMETER
);
3806 // do the conversion.
3808 if (Hex
|| StrnCmp(Walker
, L
"0x", 2) == 0 || StrnCmp(Walker
, L
"0X", 2) == 0){
3809 Status
= InternalShellStrHexToUint64(Walker
, &RetVal
, StopAtSpace
);
3811 Status
= InternalShellStrDecimalToUint64(Walker
, &RetVal
, StopAtSpace
);
3814 if (Value
== NULL
&& !EFI_ERROR(Status
)) {
3815 return (EFI_NOT_FOUND
);
3818 if (Value
!= NULL
) {
3826 Function to determin if an entire string is a valid number.
3828 If Hex it must be preceeded with a 0x or has ForceHex, set TRUE.
3830 @param[in] String The string to evaluate.
3831 @param[in] ForceHex TRUE - always assume hex.
3832 @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going.
3834 @retval TRUE It is all numeric (dec/hex) characters.
3835 @retval FALSE There is a non-numeric character.
3839 ShellIsHexOrDecimalNumber (
3840 IN CONST CHAR16
*String
,
3841 IN CONST BOOLEAN ForceHex
,
3842 IN CONST BOOLEAN StopAtSpace
3845 if (ShellConvertStringToUint64(String
, NULL
, ForceHex
, StopAtSpace
) == EFI_NOT_FOUND
) {
3852 Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
3853 buffer. The returned buffer must be callee freed.
3855 If the position upon start is 0, then the Ascii Boolean will be set. This should be
3856 maintained and not changed for all operations with the same file.
3858 @param[in] Handle SHELL_FILE_HANDLE to read from.
3859 @param[in, out] Ascii Boolean value for indicating whether the file is
3860 Ascii (TRUE) or UCS2 (FALSE).
3862 @return The line of text from the file.
3863 @retval NULL There was not enough memory available.
3865 @sa ShellFileHandleReadLine
3869 ShellFileHandleReturnLine(
3870 IN SHELL_FILE_HANDLE Handle
,
3871 IN OUT BOOLEAN
*Ascii
3881 Status
= ShellFileHandleReadLine(Handle
, RetVal
, &Size
, FALSE
, Ascii
);
3882 if (Status
== EFI_BUFFER_TOO_SMALL
) {
3883 RetVal
= AllocateZeroPool(Size
);
3884 if (RetVal
== NULL
) {
3887 Status
= ShellFileHandleReadLine(Handle
, RetVal
, &Size
, FALSE
, Ascii
);
3890 if (EFI_ERROR(Status
) && (RetVal
!= NULL
)) {
3898 Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
3900 If the position upon start is 0, then the Ascii Boolean will be set. This should be
3901 maintained and not changed for all operations with the same file.
3903 @param[in] Handle SHELL_FILE_HANDLE to read from.
3904 @param[in, out] Buffer The pointer to buffer to read into.
3905 @param[in, out] Size The pointer to number of bytes in Buffer.
3906 @param[in] Truncate If the buffer is large enough, this has no effect.
3907 If the buffer is is too small and Truncate is TRUE,
3908 the line will be truncated.
3909 If the buffer is is too small and Truncate is FALSE,
3910 then no read will occur.
3912 @param[in, out] Ascii Boolean value for indicating whether the file is
3913 Ascii (TRUE) or UCS2 (FALSE).
3915 @retval EFI_SUCCESS The operation was successful. The line is stored in
3917 @retval EFI_INVALID_PARAMETER Handle was NULL.
3918 @retval EFI_INVALID_PARAMETER Size was NULL.
3919 @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line.
3920 Size was updated to the minimum space required.
3924 ShellFileHandleReadLine(
3925 IN SHELL_FILE_HANDLE Handle
,
3926 IN OUT CHAR16
*Buffer
,
3928 IN BOOLEAN Truncate
,
3929 IN OUT BOOLEAN
*Ascii
3936 UINT64 OriginalFilePosition
;
3942 return (EFI_INVALID_PARAMETER
);
3944 if (Buffer
== NULL
) {
3947 *Buffer
= CHAR_NULL
;
3949 gEfiShellProtocol
->GetFilePosition(Handle
, &OriginalFilePosition
);
3950 if (OriginalFilePosition
== 0) {
3951 CharSize
= sizeof(CHAR16
);
3952 Status
= gEfiShellProtocol
->ReadFile(Handle
, &CharSize
, &CharBuffer
);
3953 ASSERT_EFI_ERROR(Status
);
3954 if (CharBuffer
== gUnicodeFileTag
) {
3958 gEfiShellProtocol
->SetFilePosition(Handle
, OriginalFilePosition
);
3962 for (CountSoFar
= 0;;CountSoFar
++){
3965 CharSize
= sizeof(CHAR8
);
3967 CharSize
= sizeof(CHAR16
);
3969 Status
= gEfiShellProtocol
->ReadFile(Handle
, &CharSize
, &CharBuffer
);
3970 if ( EFI_ERROR(Status
)
3972 || (CharBuffer
== L
'\n' && !(*Ascii
))
3973 || (CharBuffer
== '\n' && *Ascii
)
3978 // if we have space save it...
3980 if ((CountSoFar
+1)*sizeof(CHAR16
) < *Size
){
3981 ASSERT(Buffer
!= NULL
);
3982 ((CHAR16
*)Buffer
)[CountSoFar
] = CharBuffer
;
3983 ((CHAR16
*)Buffer
)[CountSoFar
+1] = CHAR_NULL
;
3988 // if we ran out of space tell when...
3990 if ((CountSoFar
+1)*sizeof(CHAR16
) > *Size
){
3991 *Size
= (CountSoFar
+1)*sizeof(CHAR16
);
3993 gEfiShellProtocol
->SetFilePosition(Handle
, OriginalFilePosition
);
3995 DEBUG((DEBUG_WARN
, "The line was truncated in ShellFileHandleReadLine"));
3997 return (EFI_BUFFER_TOO_SMALL
);
3999 while(Buffer
[StrLen(Buffer
)-1] == L
'\r') {
4000 Buffer
[StrLen(Buffer
)-1] = CHAR_NULL
;