ShellPkg/Application/Shell/ShellManParser.c

   1 /** @file
   2   Provides interface to shell MAN file parser.
   3
   4   Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>
   5   Copyright 2015 Dell Inc.
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "Shell.h"
  17
  18 /**
  19   Convert a Unicode character to upper case only if
  20   it maps to a valid small-case ASCII character.
  21
  22   This internal function only deal with Unicode character
  23   which maps to a valid small-case ASCII character, i.e.
  24   L'a' to L'z'. For other Unicode character, the input character
  25   is returned directly.
  26
  27   @param  Char  The character to convert.
  28
  29   @retval LowerCharacter   If the Char is with range L'a' to L'z'.
  30   @retval Unchanged        Otherwise.
  31
  32 **/
  33 CHAR16
  34 EFIAPI
  35 InternalShellCharToUpper (
  36   IN CHAR16  Char
  37   );
  38
  39 /**
  40   Verifies that the filename has .MAN on the end.
  41
  42   allocates a new buffer and copies the name (appending .MAN if necessary)
  43
  44   ASSERT if ManFileName is NULL
  45
  46   @param[in] ManFileName            original filename
  47
  48   @return the new filename with .man as the extension.
  49 **/
  50 CHAR16 *
  51 EFIAPI
  52 GetManFileName(
  53   IN CONST CHAR16 *ManFileName
  54   )
  55 {
  56   CHAR16 *Buffer;
  57   if (ManFileName == NULL) {
  58     return (NULL);
  59   }
  60   //
  61   // Fix the file name
  62   //
  63   if (StrnCmp(ManFileName+StrLen(ManFileName)-4, L".man", 4)==0) {
  64     Buffer = AllocateCopyPool(StrSize(ManFileName), ManFileName);
  65   } else {
  66     Buffer = AllocateZeroPool(StrSize(ManFileName) + 4*sizeof(CHAR16));
  67     if (Buffer != NULL) {
  68       StrnCpyS( Buffer,
  69                 (StrSize(ManFileName) + 4*sizeof(CHAR16))/sizeof(CHAR16),
  70                 ManFileName,
  71                 StrLen(ManFileName)
  72                 );
  73       StrnCatS( Buffer,
  74                 (StrSize(ManFileName) + 4*sizeof(CHAR16))/sizeof(CHAR16),
  75                 L".man",
  76                 4
  77                 );
  78     }
  79   }
  80   return (Buffer);
  81 }
  82
  83 /**
  84   Search the path environment variable for possible locations and test for
  85   which one contains a man file with the name specified.  If a valid file is found
  86   stop searching and return the (opened) SHELL_FILE_HANDLE for that file.
  87
  88   @param[in] FileName           Name of the file to find and open.
  89   @param[out] Handle            Pointer to the handle of the found file.  The
  90                                 value of this is undefined for return values
  91                                 except EFI_SUCCESS.
  92
  93   @retval EFI_SUCCESS           The file was found.  Handle is a valid SHELL_FILE_HANDLE
  94   @retval EFI_INVALID_PARAMETER A parameter had an invalid value.
  95   @retval EFI_NOT_FOUND         The file was not found.
  96 **/
  97 EFI_STATUS
  98 EFIAPI
  99 SearchPathForFile(
 100   IN CONST CHAR16             *FileName,
 101   OUT SHELL_FILE_HANDLE       *Handle
 102   )
 103 {
 104   CHAR16          *FullFileName;
 105   EFI_STATUS      Status;
 106
 107   if ( FileName     == NULL
 108     || Handle       == NULL
 109     || StrLen(FileName) == 0
 110    ){
 111     return (EFI_INVALID_PARAMETER);
 112   }
 113
 114   FullFileName = ShellFindFilePath(FileName);
 115   if (FullFileName == NULL) {
 116     return (EFI_NOT_FOUND);
 117   }
 118
 119   //
 120   // now open that file
 121   //
 122   Status = EfiShellOpenFileByName(FullFileName, Handle, EFI_FILE_MODE_READ);
 123   FreePool(FullFileName);
 124
 125   return (Status);
 126 }
 127
 128 /**
 129   parses through Buffer (which is MAN file formatted) and returns the
 130   detailed help for any sub section specified in the comma seperated list of
 131   sections provided.  If the end of the file or a .TH section is found then
 132   return.
 133
 134   Upon a sucessful return the caller is responsible to free the memory in *HelpText
 135
 136   @param[in] Buffer             Buffer to read from
 137   @param[in] Sections           name of command's sub sections to find
 138   @param[in] HelpText           pointer to pointer to string where text goes.
 139   @param[in] HelpSize           pointer to size of allocated HelpText (may be updated)
 140
 141   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 142   @retval EFI_SUCCESS           the section was found and its description sotred in
 143                                 an alloceted buffer.
 144 **/
 145 EFI_STATUS
 146 EFIAPI
 147 ManBufferFindSections(
 148   IN CONST CHAR16 *Buffer,
 149   IN CONST CHAR16 *Sections,
 150   IN CHAR16       **HelpText,
 151   IN UINTN        *HelpSize
 152   )
 153 {
 154   EFI_STATUS          Status;
 155   CONST CHAR16        *CurrentLocation;
 156   BOOLEAN             CurrentlyReading;
 157   CHAR16              *SectionName;
 158   UINTN               SectionLen;
 159   BOOLEAN             Found;
 160   CHAR16              *TempString;
 161   CHAR16              *TempString2;
 162
 163   if ( Buffer     == NULL
 164     || HelpText   == NULL
 165     || HelpSize   == NULL
 166    ){
 167     return (EFI_INVALID_PARAMETER);
 168   }
 169
 170   Status            = EFI_SUCCESS;
 171   CurrentlyReading  = FALSE;
 172   Found             = FALSE;
 173
 174   for (CurrentLocation = Buffer,TempString = NULL
 175     ;  CurrentLocation != NULL && *CurrentLocation != CHAR_NULL
 176     ;  CurrentLocation=StrStr(CurrentLocation, L"\r\n"),TempString = NULL
 177    ){
 178     while(CurrentLocation[0] == L'\r' || CurrentLocation[0] == L'\n') {
 179       CurrentLocation++;
 180     }
 181     if (CurrentLocation[0] == L'#') {
 182       //
 183       // Skip comment lines
 184       //
 185       continue;
 186     }
 187     if (StrnCmp(CurrentLocation, L".TH", 3) == 0) {
 188       //
 189       // we hit the end of this commands section so stop.
 190       //
 191       break;
 192     }
 193     if (StrnCmp(CurrentLocation, L".SH ", 4) == 0) {
 194       if (Sections == NULL) {
 195         CurrentlyReading = TRUE;
 196         continue;
 197       } else if (CurrentlyReading) {
 198         CurrentlyReading = FALSE;
 199       }
 200       CurrentLocation += 4;
 201       //
 202       // is this a section we want to read in?
 203       //
 204       if (StrLen(CurrentLocation)!=0) {
 205         TempString2 = StrStr(CurrentLocation, L" ");
 206         TempString2 = MIN(TempString2, StrStr(CurrentLocation, L"\r"));
 207         TempString2 = MIN(TempString2, StrStr(CurrentLocation, L"\n"));
 208         ASSERT(TempString == NULL);
 209         TempString = StrnCatGrow(&TempString, NULL, CurrentLocation, TempString2==NULL?0:TempString2 - CurrentLocation);
 210         if (TempString == NULL) {
 211           Status = EFI_OUT_OF_RESOURCES;
 212           break;
 213         }
 214         SectionName = TempString;
 215         SectionLen = StrLen(SectionName);
 216         SectionName = StrStr(Sections, SectionName);
 217         if (SectionName == NULL) {
 218           continue;
 219         }
 220         if (*(SectionName + SectionLen) == CHAR_NULL || *(SectionName + SectionLen) == L',') {
 221           CurrentlyReading = TRUE;
 222         }
 223       }
 224     } else if (CurrentlyReading) {
 225       Found = TRUE;
 226       if (StrLen(CurrentLocation)!=0) {
 227         TempString2 = StrStr(CurrentLocation, L"\r");
 228         TempString2 = MIN(TempString2, StrStr(CurrentLocation, L"\n"));
 229         ASSERT(TempString == NULL);
 230         TempString = StrnCatGrow(&TempString, NULL, CurrentLocation, TempString2==NULL?0:TempString2 - CurrentLocation);
 231         if (TempString == NULL) {
 232           Status = EFI_OUT_OF_RESOURCES;
 233           break;
 234         }
 235         //
 236         // copy and save the current line.
 237         //
 238         ASSERT((*HelpText == NULL && *HelpSize == 0) || (*HelpText != NULL));
 239         StrnCatGrow (HelpText, HelpSize, TempString, 0);
 240         if (HelpText == NULL) {
 241           Status = EFI_OUT_OF_RESOURCES;
 242           break;
 243         }
 244         StrnCatGrow (HelpText, HelpSize, L"\r\n", 0);
 245         if (HelpText == NULL) {
 246           Status = EFI_OUT_OF_RESOURCES;
 247           break;
 248         }
 249       }
 250     }
 251     SHELL_FREE_NON_NULL(TempString);
 252   }
 253   if (!Found && !EFI_ERROR(Status)) {
 254     return (EFI_NOT_FOUND);
 255   }
 256   return (Status);
 257 }
 258
 259 /**
 260   parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
 261   detailed help for any sub section specified in the comma seperated list of
 262   sections provided.  If the end of the file or a .TH section is found then
 263   return.
 264
 265   Upon a sucessful return the caller is responsible to free the memory in *HelpText
 266
 267   @param[in] Handle             FileHandle to read from
 268   @param[in] Sections           name of command's sub sections to find
 269   @param[out] HelpText          pointer to pointer to string where text goes.
 270   @param[out] HelpSize          pointer to size of allocated HelpText (may be updated)
 271   @param[in] Ascii              TRUE if the file is ASCII, FALSE otherwise.
 272
 273   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 274   @retval EFI_SUCCESS           the section was found and its description sotred in
 275                                 an alloceted buffer.
 276 **/
 277 EFI_STATUS
 278 EFIAPI
 279 ManFileFindSections(
 280   IN SHELL_FILE_HANDLE  Handle,
 281   IN CONST CHAR16       *Sections,
 282   OUT CHAR16            **HelpText,
 283   OUT UINTN             *HelpSize,
 284   IN BOOLEAN            Ascii
 285   )
 286 {
 287   EFI_STATUS          Status;
 288   CHAR16              *ReadLine;
 289   UINTN               Size;
 290   BOOLEAN             CurrentlyReading;
 291   CHAR16              *SectionName;
 292   UINTN               SectionLen;
 293   BOOLEAN             Found;
 294
 295   if ( Handle     == NULL
 296     || HelpText   == NULL
 297     || HelpSize   == NULL
 298    ){
 299     return (EFI_INVALID_PARAMETER);
 300   }
 301
 302   Status            = EFI_SUCCESS;
 303   CurrentlyReading  = FALSE;
 304   Size              = 1024;
 305   Found             = FALSE;
 306
 307   ReadLine          = AllocateZeroPool(Size);
 308   if (ReadLine == NULL) {
 309     return (EFI_OUT_OF_RESOURCES);
 310   }
 311
 312   for (;!ShellFileHandleEof(Handle);Size = 1024) {
 313     Status = ShellFileHandleReadLine(Handle, ReadLine, &Size, TRUE, &Ascii);
 314     if (ReadLine[0] == L'#') {
 315       //
 316       // Skip comment lines
 317       //
 318       continue;
 319     }
 320     //
 321     // ignore too small of buffer...
 322     //
 323     if (Status == EFI_BUFFER_TOO_SMALL) {
 324       Status = EFI_SUCCESS;
 325     }
 326     if (EFI_ERROR(Status)) {
 327       break;
 328     } else if (StrnCmp(ReadLine, L".TH", 3) == 0) {
 329       //
 330       // we hit the end of this commands section so stop.
 331       //
 332       break;
 333     } else if (StrnCmp(ReadLine, L".SH", 3) == 0) {
 334       if (Sections == NULL) {
 335         CurrentlyReading = TRUE;
 336         continue;
 337       }
 338       //
 339       // we found a section
 340       //
 341       if (CurrentlyReading) {
 342         CurrentlyReading = FALSE;
 343       }
 344       //
 345       // is this a section we want to read in?
 346       //
 347       for ( SectionName = ReadLine + 3
 348           ; *SectionName == L' '
 349           ; SectionName++);
 350       SectionLen = StrLen(SectionName);
 351       SectionName = StrStr(Sections, SectionName);
 352       if (SectionName == NULL) {
 353         continue;
 354       }
 355       if (*(SectionName + SectionLen) == CHAR_NULL || *(SectionName + SectionLen) == L',') {
 356         CurrentlyReading = TRUE;
 357       }
 358     } else if (CurrentlyReading) {
 359       Found = TRUE;
 360       //
 361       // copy and save the current line.
 362       //
 363       ASSERT((*HelpText == NULL && *HelpSize == 0) || (*HelpText != NULL));
 364       StrnCatGrow (HelpText, HelpSize, ReadLine, 0);
 365       StrnCatGrow (HelpText, HelpSize, L"\r\n", 0);
 366     }
 367   }
 368   FreePool(ReadLine);
 369   if (!Found && !EFI_ERROR(Status)) {
 370     return (EFI_NOT_FOUND);
 371   }
 372   return (Status);
 373 }
 374
 375 /**
 376   parses through the MAN file formatted Buffer and returns the
 377   "Brief Description" for the .TH section as specified by Command.  If the
 378   command section is not found return EFI_NOT_FOUND.
 379
 380   Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
 381
 382   @param[in] Handle             Buffer to read from
 383   @param[in] Command            name of command's section to find
 384   @param[in] BriefDesc          pointer to pointer to string where description goes.
 385   @param[in] BriefSize          pointer to size of allocated BriefDesc
 386
 387   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 388   @retval EFI_SUCCESS           the section was found and its description sotred in
 389                                 an alloceted buffer.
 390 **/
 391 EFI_STATUS
 392 EFIAPI
 393 ManBufferFindTitleSection(
 394   IN CHAR16         **Buffer,
 395   IN CONST CHAR16   *Command,
 396   IN CHAR16         **BriefDesc,
 397   IN UINTN          *BriefSize
 398   )
 399 {
 400   EFI_STATUS    Status;
 401   CHAR16        *TitleString;
 402   CHAR16        *TitleEnd;
 403   CHAR16        *CurrentLocation;
 404   UINTN         TitleLength;
 405   CONST CHAR16  StartString[] = L".TH ";
 406   CONST CHAR16  EndString[]   = L" 0 ";
 407
 408   if ( Buffer     == NULL
 409     || Command    == NULL
 410     || (BriefDesc != NULL && BriefSize == NULL)
 411    ){
 412     return (EFI_INVALID_PARAMETER);
 413   }
 414
 415   Status    = EFI_SUCCESS;
 416
 417   //
 418   // more characters for StartString and EndString
 419   //
 420   TitleLength = StrSize(Command) + (StrLen(StartString) + StrLen(EndString)) * sizeof(CHAR16);
 421   TitleString = AllocateZeroPool(TitleLength);
 422   if (TitleString == NULL) {
 423     return (EFI_OUT_OF_RESOURCES);
 424   }
 425   StrCpyS(TitleString, TitleLength/sizeof(CHAR16), StartString);
 426   StrCatS(TitleString, TitleLength/sizeof(CHAR16), Command);
 427   StrCatS(TitleString, TitleLength/sizeof(CHAR16), EndString);
 428
 429   CurrentLocation = StrStr(*Buffer, TitleString);
 430   if (CurrentLocation == NULL){
 431     Status = EFI_NOT_FOUND;
 432   } else {
 433     //
 434     // we found it so copy out the rest of the line into BriefDesc
 435     // After skipping any spaces or zeroes
 436     //
 437     for (CurrentLocation += StrLen(TitleString)
 438       ;  *CurrentLocation == L' ' || *CurrentLocation == L'0' || *CurrentLocation == L'1' || *CurrentLocation == L'\"'
 439       ;  CurrentLocation++);
 440
 441     TitleEnd = StrStr(CurrentLocation, L"\"");
 442     if (TitleEnd == NULL) {
 443       Status = EFI_DEVICE_ERROR;
 444     } else {
 445       if (BriefDesc != NULL) {
 446         *BriefSize = StrSize(TitleEnd);
 447         *BriefDesc = AllocateZeroPool(*BriefSize);
 448         if (*BriefDesc == NULL) {
 449           Status = EFI_OUT_OF_RESOURCES;
 450         } else {
 451           StrnCpyS(*BriefDesc, (*BriefSize)/sizeof(CHAR16), CurrentLocation, TitleEnd-CurrentLocation);
 452         }
 453       }
 454
 455       for (CurrentLocation = TitleEnd
 456         ;  *CurrentLocation != L'\n'
 457         ;  CurrentLocation++);
 458       for (
 459         ;  *CurrentLocation == L' ' || *CurrentLocation == L'\n' || *CurrentLocation == L'\r'
 460         ;  CurrentLocation++);
 461       *Buffer = CurrentLocation;
 462     }
 463   }
 464
 465   FreePool(TitleString);
 466   return (Status);
 467 }
 468
 469 /**
 470   Parses a line from a MAN file to see if it is the Title Header. If it is, then
 471   if the "Brief Description" is desired, allocate a buffer for it and return a
 472   copy. Upon a sucessful return the caller is responsible to free the memory in
 473   *BriefDesc
 474
 475   Uses a simple state machine that allows "unlimited" whitespace before and after the
 476   ".TH", compares Command and the MAN file commnd name without respect to case, and
 477   allows "unlimited" whitespace and '0' and '1' characters before the Short Description.
 478   The PCRE regex describing this functionality is: ^\s*\.TH\s+(\S)\s[\s01]*(.*)$
 479   where group 1 is the Command Name and group 2 is the Short Description.
 480
 481   @param[in] Command             name of command whose MAN file we think Line came from
 482   @param[in] Line                Pointer to a line from the MAN file
 483   @param[out] BriefDesc          pointer to pointer to string where description goes.
 484   @param[out] BriefSize          pointer to size of allocated BriefDesc
 485   @param[out] Found              TRUE if the Title Header was found and it belongs to Command
 486
 487   @retval TRUE   Line contained the Title Header
 488   @retval FALSE  Line did not contain the Title Header
 489 **/
 490 BOOLEAN
 491 IsTitleHeader(
 492   IN CONST CHAR16       *Command,
 493   IN CHAR16             *Line,
 494   OUT CHAR16            **BriefDesc OPTIONAL,
 495   OUT UINTN             *BriefSize OPTIONAL,
 496   OUT BOOLEAN           *Found
 497   )
 498 {
 499   // The states of a simple state machine used to recognize a title header line
 500   // and to extract the Short Description, if desired.
 501   typedef enum {
 502     LookForThMacro, LookForCommandName, CompareCommands, GetBriefDescription, Final
 503   } STATEVALUES;
 504
 505   STATEVALUES  State;
 506   UINTN        CommandIndex; // Indexes Command as we compare its chars to the MAN file.
 507   BOOLEAN      ReturnValue;  // TRUE if this the Title Header line of *some* MAN file.
 508   BOOLEAN      ReturnFound;  // TRUE if this the Title Header line of *the desired* MAN file.
 509
 510   ReturnValue = FALSE;
 511   ReturnFound = FALSE;
 512   CommandIndex = 0;
 513   State = LookForThMacro;
 514
 515   do {
 516
 517     if (*Line == L'\0') {
 518       break;
 519     }
 520
 521     switch (State) {
 522
 523       // Handle "^\s*.TH\s"
 524       // Go to state LookForCommandName if the title header macro is present; otherwise,
 525       // eat white space. If we see something other than white space, this is not a
 526       // title header line.
 527       case LookForThMacro:
 528         if (StrnCmp (L".TH ", Line, 4) == 0 || StrnCmp (L".TH\t", Line, 4) == 0) {
 529           Line += 4;
 530           State = LookForCommandName;
 531         }
 532         else if (*Line == L' ' || *Line == L'\t') {
 533           Line++;
 534         }
 535         else {
 536           State = Final;
 537         }
 538       break;
 539
 540       // Handle "\s*"
 541       // Eat any "extra" whitespace after the title header macro (we have already seen
 542       // at least one white space character). Go to state CompareCommands when a
 543       // non-white space is seen.
 544       case LookForCommandName:
 545         if (*Line == L' ' || *Line == L'\t') {
 546           Line++;
 547         }
 548         else {
 549           ReturnValue = TRUE;  // This is *some* command's title header line.
 550           State = CompareCommands;
 551           // Do not increment Line; it points to the first character of the command
 552           // name on the title header line.
 553         }
 554       break;
 555
 556       // Handle "(\S)\s"
 557       // Compare Command to the title header command name, ignoring case. When we
 558       // reach the end of the command (i.e. we see white space), the next state
 559       // depends on whether the caller wants a copy of the Brief Description.
 560       case CompareCommands:
 561         if (*Line == L' ' || *Line == L'\t') {
 562           ReturnFound = TRUE;  // This is the desired command's title header line.
 563           State = (BriefDesc == NULL) ? Final : GetBriefDescription;
 564         }
 565         else if (InternalShellCharToUpper (*Line) != InternalShellCharToUpper (*(Command + CommandIndex++))) {
 566           State = Final;
 567         }
 568         Line++;
 569       break;
 570
 571       // Handle "[\s01]*(.*)$"
 572       // Skip whitespace, '0', and '1' characters, if any, prior to the brief description.
 573       // Return the description to the caller.
 574       case GetBriefDescription:
 575         if (*Line != L' ' && *Line != L'\t' && *Line != L'0' && *Line != L'1') {
 576           *BriefSize = StrSize(Line);
 577           *BriefDesc = AllocateZeroPool(*BriefSize);
 578           if (*BriefDesc != NULL) {
 579             StrCpyS(*BriefDesc, (*BriefSize)/sizeof(CHAR16), Line);
 580           }
 581           State = Final;
 582         }
 583         Line++;
 584       break;
 585
 586       default:
 587        break;
 588     }
 589
 590   } while (State < Final);
 591
 592   *Found = ReturnFound;
 593   return ReturnValue;
 594 }
 595
 596 /**
 597   parses through the MAN file specified by SHELL_FILE_HANDLE and returns the
 598   "Brief Description" for the .TH section as specified by Command.  If the
 599   command section is not found return EFI_NOT_FOUND.
 600
 601   Upon a sucessful return the caller is responsible to free the memory in *BriefDesc
 602
 603   @param[in] Handle              FileHandle to read from
 604   @param[in] Command             name of command's section to find as entered on the
 605                                  command line (may be a relative or absolute path or
 606                                  be in any case: upper, lower, or mixed in numerous ways!).
 607   @param[out] BriefDesc          pointer to pointer to string where description goes.
 608   @param[out] BriefSize          pointer to size of allocated BriefDesc
 609   @param[in, out] Ascii          TRUE if the file is ASCII, FALSE otherwise, will be
 610                                  set if the file handle is at the 0 position.
 611
 612   @retval EFI_OUT_OF_RESOURCES  a memory allocation failed.
 613   @retval EFI_SUCCESS           the section was found and its description stored in
 614                                 an allocated buffer if requested.
 615 **/
 616 EFI_STATUS
 617 EFIAPI
 618 ManFileFindTitleSection(
 619   IN SHELL_FILE_HANDLE  Handle,
 620   IN CONST CHAR16       *Command,
 621   OUT CHAR16            **BriefDesc OPTIONAL,
 622   OUT UINTN             *BriefSize OPTIONAL,
 623   IN OUT BOOLEAN        *Ascii
 624   )
 625 {
 626   EFI_STATUS  Status;
 627   CHAR16      *ReadLine;
 628   UINTN       Size;
 629   BOOLEAN     Found;
 630   UINTN       Start;
 631
 632   if ( Handle     == NULL
 633     || Command    == NULL
 634     || (BriefDesc != NULL && BriefSize == NULL)
 635    ){
 636     return (EFI_INVALID_PARAMETER);
 637   }
 638
 639   Status    = EFI_SUCCESS;
 640   Size      = 1024;
 641   Found     = FALSE;
 642
 643   ReadLine  = AllocateZeroPool(Size);
 644   if (ReadLine == NULL) {
 645     return (EFI_OUT_OF_RESOURCES);
 646   }
 647
 648   //
 649   // Do not pass any leading path information that may be present to IsTitleHeader().
 650   //
 651   Start = StrLen(Command);
 652   while ((Start != 0)
 653          && (*(Command + Start - 1) != L'\\')
 654          && (*(Command + Start - 1) != L'/')
 655          && (*(Command + Start - 1) != L':')) {
 656     --Start;
 657   }
 658
 659   for (;!ShellFileHandleEof(Handle);Size = 1024) {
 660    Status = ShellFileHandleReadLine(Handle, ReadLine, &Size, TRUE, Ascii);
 661     //
 662     // ignore too small of buffer...
 663     //
 664     if (EFI_ERROR(Status) && Status != EFI_BUFFER_TOO_SMALL) {
 665       break;
 666     }
 667
 668     Status = EFI_NOT_FOUND;
 669     if (IsTitleHeader (Command+Start, ReadLine, BriefDesc, BriefSize, &Found)) {
 670       Status = Found ? EFI_SUCCESS : EFI_NOT_FOUND;
 671       break;
 672     }
 673   }
 674
 675   FreePool(ReadLine);
 676   return (Status);
 677 }
 678
 679 /**
 680   This function returns the help information for the specified command. The help text
 681   will be parsed from a UEFI Shell manual page. (see UEFI Shell 2.0 Appendix B)
 682
 683   If Sections is specified, then each section name listed will be compared in a casesensitive
 684   manner, to the section names described in Appendix B. If the section exists,
 685   it will be appended to the returned help text. If the section does not exist, no
 686   information will be returned. If Sections is NULL, then all help text information
 687   available will be returned.
 688
 689   if BriefDesc is NULL, then the breif description will not be savedd seperatly,
 690   but placed first in the main HelpText.
 691
 692   @param[in] ManFileName        Points to the NULL-terminated UEFI Shell MAN file name.
 693   @param[in] Command            Points to the NULL-terminated UEFI Shell command name.
 694   @param[in] Sections           Points to the NULL-terminated comma-delimited
 695                                 section names to return. If NULL, then all
 696                                 sections will be returned.
 697   @param[out] BriefDesc         On return, points to a callee-allocated buffer
 698                                 containing brief description text.
 699   @param[out] HelpText          On return, points to a callee-allocated buffer
 700                                 containing all specified help text.
 701
 702   @retval EFI_SUCCESS           The help text was returned.
 703   @retval EFI_OUT_OF_RESOURCES  The necessary buffer could not be allocated to hold the
 704                                 returned help text.
 705   @retval EFI_INVALID_PARAMETER HelpText is NULL.
 706   @retval EFI_INVALID_PARAMETER ManFileName is invalid.
 707   @retval EFI_NOT_FOUND         There is no help text available for Command.
 708 **/
 709 EFI_STATUS
 710 EFIAPI
 711 ProcessManFile(
 712   IN CONST CHAR16 *ManFileName,
 713   IN CONST CHAR16 *Command,
 714   IN CONST CHAR16 *Sections OPTIONAL,
 715   OUT CHAR16      **BriefDesc OPTIONAL,
 716   OUT CHAR16      **HelpText
 717   )
 718 {
 719   CHAR16            *TempString;
 720   SHELL_FILE_HANDLE FileHandle;
 721   EFI_STATUS        Status;
 722   UINTN             HelpSize;
 723   UINTN             BriefSize;
 724   BOOLEAN           Ascii;
 725   CHAR16            *TempString2;
 726   EFI_DEVICE_PATH_PROTOCOL  *FileDevPath;
 727   EFI_DEVICE_PATH_PROTOCOL  *DevPath;
 728
 729   if ( ManFileName == NULL
 730     || Command     == NULL
 731     || HelpText    == NULL
 732    ){
 733     return (EFI_INVALID_PARAMETER);
 734   }
 735
 736   HelpSize    = 0;
 737   BriefSize   = 0;
 738   TempString  = NULL;
 739   Ascii       = FALSE;
 740   //
 741   // See if it's in HII first
 742   //
 743   TempString = ShellCommandGetCommandHelp(Command);
 744   if (TempString != NULL) {
 745     TempString2 = TempString;
 746     Status = ManBufferFindTitleSection(&TempString2, Command, BriefDesc, &BriefSize);
 747     if (!EFI_ERROR(Status) && HelpText != NULL){
 748       Status = ManBufferFindSections(TempString2, Sections, HelpText, &HelpSize);
 749     }
 750   } else {
 751     FileHandle    = NULL;
 752     TempString  = GetManFileName(ManFileName);
 753     if (TempString == NULL) {
 754       return (EFI_INVALID_PARAMETER);
 755     }
 756
 757     Status = SearchPathForFile(TempString, &FileHandle);
 758     if (EFI_ERROR(Status)) {
 759       FileDevPath = FileDevicePath(NULL, TempString);
 760       DevPath = AppendDevicePath (ShellInfoObject.ImageDevPath, FileDevPath);
 761       Status = InternalOpenFileDevicePath(DevPath, &FileHandle, EFI_FILE_MODE_READ, 0);
 762       FreePool(FileDevPath);
 763       FreePool(DevPath);
 764     }
 765
 766     if (!EFI_ERROR(Status)) {
 767       HelpSize  = 0;
 768       BriefSize = 0;
 769       Status = ManFileFindTitleSection(FileHandle, Command, BriefDesc, &BriefSize, &Ascii);
 770       if (!EFI_ERROR(Status) && HelpText != NULL){
 771         Status = ManFileFindSections(FileHandle, Sections, HelpText, &HelpSize, Ascii);
 772       }
 773       ShellInfoObject.NewEfiShellProtocol->CloseFile(FileHandle);
 774     } else {
 775       *HelpText = NULL;
 776     }
 777   }
 778   if (TempString != NULL) {
 779     FreePool(TempString);
 780   }
 781
 782   return (Status);
 783 }