2 Provides interface to shell MAN file parser.
4 Copyright (c) 2009 - 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.
18 Verifies that the filename has .MAN on the end.
20 allocates a new buffer and copies the name (appending .MAN if necessary)
22 ASSERT if ManFileName is NULL
24 @param[in] ManFileName original filename
26 @return the new filename with .man as the extension.
31 IN CONST CHAR16
*ManFileName
35 if (ManFileName
== NULL
) {
41 if (StrnCmp(ManFileName
+StrLen(ManFileName
)-4, L
".man", 4)==0) {
42 Buffer
= AllocateZeroPool(StrSize(ManFileName
));
44 StrCpy(Buffer
, ManFileName
);
47 Buffer
= AllocateZeroPool(StrSize(ManFileName
) + 4*sizeof(CHAR16
));
49 StrCpy(Buffer
, ManFileName
);
50 StrCat(Buffer
, L
".man");
57 Search the path environment variable for possible locations and test for
58 which one contains a man file with the name specified. If a valid file is found
59 stop searching and return the (opened) SHELL_FILE_HANDLE for that file.
61 @param[in] FileName Name of the file to find and open.
62 @param[out] Handle Pointer to the handle of the found file. The
63 value of this is undefined for return values
66 @retval EFI_SUCCESS The file was found. Handle is a valid SHELL_FILE_HANDLE
67 @retval EFI_INVALID_PARAMETER A parameter had an invalid value.
68 @retval EFI_NOT_FOUND The file was not found.
73 IN CONST CHAR16
*FileName
,
74 OUT SHELL_FILE_HANDLE
*Handle
82 || StrLen(FileName
) == 0
84 return (EFI_INVALID_PARAMETER
);
87 FullFileName
= ShellFindFilePath(FileName
);
88 if (FullFileName
== NULL
) {
89 return (EFI_NOT_FOUND
);
95 Status
= EfiShellOpenFileByName(FullFileName
, Handle
, EFI_FILE_MODE_READ
);
96 FreePool(FullFileName
);
102 parses through Buffer (which is MAN file formatted) and returns the
103 detailed help for any sub section specified in the comma seperated list of
104 sections provided. If the end of the file or a .TH section is found then
107 Upon a sucessful return the caller is responsible to free the memory in *HelpText
109 @param[in] Buffer Buffer to read from
110 @param[in] Sections name of command's sub sections to find
111 @param[in] HelpText pointer to pointer to string where text goes.
112 @param[in] HelpSize pointer to size of allocated HelpText (may be updated)
114 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
115 @retval EFI_SUCCESS the section was found and its description sotred in
120 ManBufferFindSections(
121 IN CONST CHAR16
*Buffer
,
122 IN CONST CHAR16
*Sections
,
123 IN CHAR16
**HelpText
,
128 CONST CHAR16
*CurrentLocation
;
129 BOOLEAN CurrentlyReading
;
140 return (EFI_INVALID_PARAMETER
);
143 Status
= EFI_SUCCESS
;
144 CurrentlyReading
= FALSE
;
147 for (CurrentLocation
= Buffer
,TempString
= NULL
148 ; CurrentLocation
!= NULL
&& *CurrentLocation
!= CHAR_NULL
149 ; CurrentLocation
=StrStr(CurrentLocation
, L
"\r\n"),TempString
= NULL
151 while(CurrentLocation
[0] == L
'\r' || CurrentLocation
[0] == L
'\n') {
154 if (CurrentLocation
[0] == L
'#') {
156 // Skip comment lines
160 if (StrnCmp(CurrentLocation
, L
".TH", 3) == 0) {
162 // we hit the end of this commands section so stop.
166 if (StrnCmp(CurrentLocation
, L
".SH ", 4) == 0) {
167 if (Sections
== NULL
) {
168 CurrentlyReading
= TRUE
;
170 } else if (CurrentlyReading
) {
171 CurrentlyReading
= FALSE
;
173 CurrentLocation
+= 4;
175 // is this a section we want to read in?
177 if (StrLen(CurrentLocation
)!=0) {
178 TempString2
= StrStr(CurrentLocation
, L
" ");
179 TempString2
= MIN(TempString2
, StrStr(CurrentLocation
, L
"\r"));
180 TempString2
= MIN(TempString2
, StrStr(CurrentLocation
, L
"\n"));
181 ASSERT(TempString
== NULL
);
182 TempString
= StrnCatGrow(&TempString
, NULL
, CurrentLocation
, TempString2
==NULL
?0:TempString2
- CurrentLocation
);
183 SectionName
= TempString
;
184 SectionLen
= StrLen(SectionName
);
185 SectionName
= StrStr(Sections
, SectionName
);
186 if (SectionName
== NULL
) {
189 if (*(SectionName
+ SectionLen
) == CHAR_NULL
|| *(SectionName
+ SectionLen
) == L
',') {
190 CurrentlyReading
= TRUE
;
193 } else if (CurrentlyReading
) {
195 if (StrLen(CurrentLocation
)!=0) {
196 TempString2
= StrStr(CurrentLocation
, L
"\r");
197 TempString2
= MIN(TempString2
, StrStr(CurrentLocation
, L
"\n"));
198 ASSERT(TempString
== NULL
);
199 TempString
= StrnCatGrow(&TempString
, NULL
, CurrentLocation
, TempString2
==NULL
?0:TempString2
- CurrentLocation
);
201 // copy and save the current line.
203 ASSERT((*HelpText
== NULL
&& *HelpSize
== 0) || (*HelpText
!= NULL
));
204 StrnCatGrow (HelpText
, HelpSize
, TempString
, 0);
205 StrnCatGrow (HelpText
, HelpSize
, L
"\r\n", 0);
208 SHELL_FREE_NON_NULL(TempString
);
210 if (!Found
&& !EFI_ERROR(Status
)) {
211 return (EFI_NOT_FOUND
);
217 parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
218 detailed help for any sub section specified in the comma seperated list of
219 sections provided. If the end of the file or a .TH section is found then
222 Upon a sucessful return the caller is responsible to free the memory in *HelpText
224 @param[in] Handle FileHandle to read from
225 @param[in] Sections name of command's sub sections to find
226 @param[out] HelpText pointer to pointer to string where text goes.
227 @param[out] HelpSize pointer to size of allocated HelpText (may be updated)
228 @param[in] Ascii TRUE if the file is ASCII, FALSE otherwise.
230 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
231 @retval EFI_SUCCESS the section was found and its description sotred in
237 IN SHELL_FILE_HANDLE Handle
,
238 IN CONST CHAR16
*Sections
,
239 OUT CHAR16
**HelpText
,
247 BOOLEAN CurrentlyReading
;
256 return (EFI_INVALID_PARAMETER
);
259 Status
= EFI_SUCCESS
;
260 CurrentlyReading
= FALSE
;
264 ReadLine
= AllocateZeroPool(Size
);
265 if (ReadLine
== NULL
) {
266 return (EFI_OUT_OF_RESOURCES
);
269 for (;!ShellFileHandleEof(Handle
);Size
= 1024) {
270 Status
= ShellFileHandleReadLine(Handle
, ReadLine
, &Size
, TRUE
, &Ascii
);
271 if (ReadLine
[0] == L
'#') {
273 // Skip comment lines
278 // ignore too small of buffer...
280 if (Status
== EFI_BUFFER_TOO_SMALL
) {
281 Status
= EFI_SUCCESS
;
283 if (EFI_ERROR(Status
)) {
285 } else if (StrnCmp(ReadLine
, L
".TH", 3) == 0) {
287 // we hit the end of this commands section so stop.
290 } else if (StrnCmp(ReadLine
, L
".SH", 3) == 0) {
291 if (Sections
== NULL
) {
292 CurrentlyReading
= TRUE
;
296 // we found a section
298 if (CurrentlyReading
) {
299 CurrentlyReading
= FALSE
;
302 // is this a section we want to read in?
304 for ( SectionName
= ReadLine
+ 3
305 ; *SectionName
== L
' '
307 SectionLen
= StrLen(SectionName
);
308 SectionName
= StrStr(Sections
, SectionName
);
309 if (SectionName
== NULL
) {
312 if (*(SectionName
+ SectionLen
) == CHAR_NULL
|| *(SectionName
+ SectionLen
) == L
',') {
313 CurrentlyReading
= TRUE
;
315 } else if (CurrentlyReading
) {
318 // copy and save the current line.
320 ASSERT((*HelpText
== NULL
&& *HelpSize
== 0) || (*HelpText
!= NULL
));
321 StrnCatGrow (HelpText
, HelpSize
, ReadLine
, 0);
322 StrnCatGrow (HelpText
, HelpSize
, L
"\r\n", 0);
326 if (!Found
&& !EFI_ERROR(Status
)) {
327 return (EFI_NOT_FOUND
);
333 parses through the MAN file formatted Buffer and returns the
334 "Brief Description" for the .TH section as specified by Command. If the
335 command section is not found return EFI_NOT_FOUND.
337 Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
339 @param[in] Handle Buffer to read from
340 @param[in] Command name of command's section to find
341 @param[in] BriefDesc pointer to pointer to string where description goes.
342 @param[in] BriefSize pointer to size of allocated BriefDesc
344 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
345 @retval EFI_SUCCESS the section was found and its description sotred in
350 ManBufferFindTitleSection(
352 IN CONST CHAR16
*Command
,
353 IN CHAR16
**BriefDesc
,
360 CHAR16
*CurrentLocation
;
364 || (BriefDesc
!= NULL
&& BriefSize
== NULL
)
366 return (EFI_INVALID_PARAMETER
);
369 Status
= EFI_SUCCESS
;
371 TitleString
= AllocateZeroPool((7*sizeof(CHAR16
)) + StrSize(Command
));
372 if (TitleString
== NULL
) {
373 return (EFI_OUT_OF_RESOURCES
);
375 StrCpy(TitleString
, L
".TH ");
376 StrCat(TitleString
, Command
);
377 StrCat(TitleString
, L
" 0 ");
379 CurrentLocation
= StrStr(*Buffer
, TitleString
);
380 if (CurrentLocation
== NULL
){
381 Status
= EFI_NOT_FOUND
;
384 // we found it so copy out the rest of the line into BriefDesc
385 // After skipping any spaces or zeroes
387 for (CurrentLocation
+= StrLen(TitleString
)
388 ; *CurrentLocation
== L
' ' || *CurrentLocation
== L
'0' || *CurrentLocation
== L
'1' || *CurrentLocation
== L
'\"'
389 ; CurrentLocation
++);
391 TitleEnd
= StrStr(CurrentLocation
, L
"\"");
392 if (TitleEnd
== NULL
) {
393 Status
= EFI_DEVICE_ERROR
;
395 if (BriefDesc
!= NULL
) {
396 *BriefSize
= StrSize(TitleEnd
);
397 *BriefDesc
= AllocateZeroPool(*BriefSize
);
398 if (*BriefDesc
== NULL
) {
399 Status
= EFI_OUT_OF_RESOURCES
;
401 StrnCpy(*BriefDesc
, CurrentLocation
, TitleEnd
-CurrentLocation
);
405 for (CurrentLocation
= TitleEnd
406 ; *CurrentLocation
!= L
'\n'
407 ; CurrentLocation
++);
409 ; *CurrentLocation
== L
' ' || *CurrentLocation
== L
'\n' || *CurrentLocation
== L
'\r'
410 ; CurrentLocation
++);
411 *Buffer
= CurrentLocation
;
415 FreePool(TitleString
);
420 parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
421 "Brief Description" for the .TH section as specified by Command. if the
422 command section is not found return EFI_NOT_FOUND.
424 Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
426 @param[in] Handle FileHandle to read from
427 @param[in] Command name of command's section to find
428 @param[out] BriefDesc pointer to pointer to string where description goes.
429 @param[out] BriefSize pointer to size of allocated BriefDesc
430 @param[in, out] Ascii TRUE if the file is ASCII, FALSE otherwise, will be
431 set if the file handle is at the 0 position.
433 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
434 @retval EFI_SUCCESS the section was found and its description sotred in
439 ManFileFindTitleSection(
440 IN SHELL_FILE_HANDLE Handle
,
441 IN CONST CHAR16
*Command
,
442 OUT CHAR16
**BriefDesc OPTIONAL
,
443 OUT UINTN
*BriefSize OPTIONAL
,
444 IN OUT BOOLEAN
*Ascii
457 || (BriefDesc
!= NULL
&& BriefSize
== NULL
)
459 return (EFI_INVALID_PARAMETER
);
462 Status
= EFI_SUCCESS
;
466 ReadLine
= AllocateZeroPool(Size
);
467 if (ReadLine
== NULL
) {
468 return (EFI_OUT_OF_RESOURCES
);
471 TitleString
= AllocateZeroPool((4*sizeof(CHAR16
)) + StrSize(Command
));
472 if (TitleString
== NULL
) {
474 return (EFI_OUT_OF_RESOURCES
);
476 StrCpy(TitleString
, L
".TH ");
477 StrCat(TitleString
, Command
);
478 TitleLen
= StrLen(TitleString
);
479 for (;!ShellFileHandleEof(Handle
);Size
= 1024) {
480 Status
= ShellFileHandleReadLine(Handle
, ReadLine
, &Size
, TRUE
, Ascii
);
481 if (ReadLine
[0] == L
'#') {
483 // Skip comment lines
488 // ignore too small of buffer...
490 if (Status
== EFI_BUFFER_TOO_SMALL
) {
491 Status
= EFI_SUCCESS
;
493 if (EFI_ERROR(Status
)) {
496 if (StrnCmp(ReadLine
, TitleString
, TitleLen
) == 0) {
499 // we found it so copy out the rest of the line into BriefDesc
500 // After skipping any spaces or zeroes
502 for ( TitleEnd
= ReadLine
+TitleLen
503 ; *TitleEnd
== L
' ' || *TitleEnd
== L
'0' || *TitleEnd
== L
'1'
505 if (BriefDesc
!= NULL
) {
506 *BriefSize
= StrSize(TitleEnd
);
507 *BriefDesc
= AllocateZeroPool(*BriefSize
);
508 if (*BriefDesc
== NULL
) {
509 Status
= EFI_OUT_OF_RESOURCES
;
512 StrCpy(*BriefDesc
, TitleEnd
);
518 FreePool(TitleString
);
519 if (!Found
&& !EFI_ERROR(Status
)) {
520 return (EFI_NOT_FOUND
);
526 This function returns the help information for the specified command. The help text
527 will be parsed from a UEFI Shell manual page. (see UEFI Shell 2.0 Appendix B)
529 If Sections is specified, then each section name listed will be compared in a casesensitive
530 manner, to the section names described in Appendix B. If the section exists,
531 it will be appended to the returned help text. If the section does not exist, no
532 information will be returned. If Sections is NULL, then all help text information
533 available will be returned.
535 if BriefDesc is NULL, then the breif description will not be savedd seperatly,
536 but placed first in the main HelpText.
538 @param[in] ManFileName Points to the NULL-terminated UEFI Shell MAN file name.
539 @param[in] Command Points to the NULL-terminated UEFI Shell command name.
540 @param[in] Sections Points to the NULL-terminated comma-delimited
541 section names to return. If NULL, then all
542 sections will be returned.
543 @param[out] BriefDesc On return, points to a callee-allocated buffer
544 containing brief description text.
545 @param[out] HelpText On return, points to a callee-allocated buffer
546 containing all specified help text.
548 @retval EFI_SUCCESS The help text was returned.
549 @retval EFI_OUT_OF_RESOURCES The necessary buffer could not be allocated to hold the
551 @retval EFI_INVALID_PARAMETER HelpText is NULL.
552 @retval EFI_INVALID_PARAMETER ManFileName is invalid.
553 @retval EFI_NOT_FOUND There is no help text available for Command.
558 IN CONST CHAR16
*ManFileName
,
559 IN CONST CHAR16
*Command
,
560 IN CONST CHAR16
*Sections OPTIONAL
,
561 OUT CHAR16
**BriefDesc OPTIONAL
,
562 OUT CHAR16
**HelpText
566 SHELL_FILE_HANDLE FileHandle
;
572 EFI_DEVICE_PATH_PROTOCOL
*FileDevPath
;
573 EFI_DEVICE_PATH_PROTOCOL
*DevPath
;
575 if ( ManFileName
== NULL
579 return (EFI_INVALID_PARAMETER
);
586 // See if it's in HII first
588 TempString
= ShellCommandGetCommandHelp(Command
);
589 if (TempString
!= NULL
) {
590 TempString2
= TempString
;
591 Status
= ManBufferFindTitleSection(&TempString2
, Command
, BriefDesc
, &BriefSize
);
592 if (!EFI_ERROR(Status
) && HelpText
!= NULL
){
593 Status
= ManBufferFindSections(TempString2
, Sections
, HelpText
, &HelpSize
);
597 TempString
= GetManFileName(ManFileName
);
598 if (TempString
== NULL
) {
599 return (EFI_INVALID_PARAMETER
);
602 Status
= SearchPathForFile(TempString
, &FileHandle
);
603 if (EFI_ERROR(Status
)) {
604 FileDevPath
= FileDevicePath(NULL
, TempString
);
605 DevPath
= AppendDevicePath (ShellInfoObject
.ImageDevPath
, FileDevPath
);
606 Status
= InternalOpenFileDevicePath(DevPath
, &FileHandle
, EFI_FILE_MODE_READ
, 0);
607 FreePool(FileDevPath
);
611 if (!EFI_ERROR(Status
)) {
614 Status
= ManFileFindTitleSection(FileHandle
, Command
, BriefDesc
, &BriefSize
, &Ascii
);
615 if (!EFI_ERROR(Status
) && HelpText
!= NULL
){
616 Status
= ManFileFindSections(FileHandle
, Sections
, HelpText
, &HelpSize
, Ascii
);
618 ShellInfoObject
.NewEfiShellProtocol
->CloseFile(FileHandle
);
623 if (TempString
!= NULL
) {
624 FreePool(TempString
);