StdLib: Clarify and improve comments.

Indentation has been corrected in all of the files.

LibC/Locale/multibyte_Utf8.c
LibC/Uefi/SysCalls.c
  Clarify and improve comments.

Include/sys/termios.h
  Add parameter names to function prototypes as referenced in the comments.

StdLibPrivateInternalFiles\Include\kfile.h
  Add comment for the fo_close fileop.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Daryl McDaniel <edk2-lists@mc2research.org>
Reviewed-by: Erik Bjorge <erik.c.bjorge@intel.com>


git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@19588 6f19259b-4bc3-4df7-8a09-765794883524

3 files changed, 86 insertions, 72 deletions

diff --git a/StdLib/Include/sys/termios.h b/StdLib/Include/sys/termios.h
index 671a5c06c0..75886065b7 100644
--- a/StdLib/Include/sys/termios.h
+++ b/StdLib/Include/sys/termios.h
@@ -2,6 +2,7 @@
     Macros and declarations for terminal oriented ioctls and

     I/O discipline.

 

+    Copyright (c) 2016, Daryl McDaniel. All rights reserved.<BR>

     Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved.<BR>

     This program and the accompanying materials are licensed and made available under

     the terms and conditions of the BSD License that accompanies this distribution.

@@ -288,7 +289,7 @@ int     cfsetospeed (struct termios *, speed_t);
                     * EBADF - The fd argument is not a valid file descriptor.

                     * ENOTTY - The file associated with fd is not an interactive IO device.

 **/

-int     tcgetattr   (int, struct termios *);

+int     tcgetattr   (int fd, struct termios *pTermios);

 

 /** Set the parameters associated with an interactive IO device.

 

@@ -314,7 +315,7 @@ int     tcgetattr   (int, struct termios *);
                     * EBADF - The fd argument is not a valid file descriptor.

                     * ENOTTY - The file associated with fd is not an interactive IO device.

 **/

-int     tcsetattr   (int, int, const struct termios *);

+int     tcsetattr   (int fd, int OptAct, const struct termios *pTermios);

 

 /** Transmit pending output.

 

@@ -328,7 +329,7 @@ int     tcsetattr   (int, int, const struct termios *);
                     * EINTR - A signal interrupted tcdrain().

                     * ENOTSUP - This function is not supported.

 **/

-int     tcdrain     (int);

+int     tcdrain     (int fd);

 

 /** Suspend or restart the transmission or reception of data.

 

@@ -353,7 +354,7 @@ int     tcdrain     (int);
                     * EINVAL - The Action argument is not a supported value.

                     * ENOTSUP - This function is not supported.

 **/

-int     tcflow      (int, int);

+int     tcflow      (int fd, int Action);

 

 /** Discard non-transmitted output data, non-read input data, or both.

 

@@ -375,7 +376,7 @@ int     tcflow      (int, int);
                     * EINVAL - The QueueSelector argument is not a supported value.

                     * ENOTSUP - This function is not supported.

 **/

-int     tcflush     (int, int);

+int     tcflush     (int fd, int QueueSelector);

 

 //int     tcsendbreak (int, int);

 //pid_t   tcgetsid    (int);

diff --git a/StdLib/LibC/Locale/multibyte_Utf8.c b/StdLib/LibC/Locale/multibyte_Utf8.c
index ffe3dee231..55f4802b16 100644
--- a/StdLib/LibC/Locale/multibyte_Utf8.c
+++ b/StdLib/LibC/Locale/multibyte_Utf8.c
@@ -1,4 +1,5 @@
 /** @file

+  Copyright (c) 2016, Daryl McDaniel. All rights reserved.<BR>

   Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials

   are licensed and made available under the terms and conditions of the BSD License

@@ -16,7 +17,7 @@
 #include  <sys/types.h>

 #include  <limits.h>

 

-typedef      int      ch_UCS4;

+typedef int      ch_UCS4;

 

 static  mbstate_t     LocalConvState = {0};

 

@@ -79,7 +80,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
     // We are in an invalid state

     ps->A = 0;    // Initial State

   }

-  ps->C[ps->A] = ch;  // Save the current character

+  ps->C[ps->A] = ch;  // Save the current byte

   Mask = utf8_code_length[ch];

 

   if(ps->A == 0) {    // Initial State.  First byte of sequence.

@@ -89,7 +90,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
       case 0:                       // State 0, Code 0

         errno = EILSEQ;

         RetVal = -1;

-        ps->E = 1;        // Consume this character

+        ps->E = 1;        // Consume this byte

         break;

       case 1:                       // State 0, Code 1

         // ASCII-7 Character

@@ -116,7 +117,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
             ps->A = 0;      // Next state is State-0

             RetVal = 2;

           }

-          else {    // This isn't the last character, get more.  State 1, Code 3 or 4

+          else {    // This isn't the last byte, get more.  State 1, Code 3 or 4

             ps->A = 2;

             RetVal = -2;

           }

@@ -158,12 +159,12 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
             errno = EILSEQ;

             ps->A = 0;

             RetVal = -1;

-            ps->E = 4;      // Can't happen, but consume this character anyway

+            ps->E = 4;      // Can't happen, but consume this byte anyway

           }

           break;

       }

     }

-    else {                // Invalid surrogate character

+    else {                // Invalid surrogate byte

       errno = EILSEQ;

       ps->A = 0;          // Next is State-0

       RetVal = -1;

@@ -287,7 +288,8 @@ OneWcToMcLen(const wchar_t InCh)
 

     @param[in]    Src       Pointer to a wide character string.

     @param[in]    Limit     Maximum number of bytes the converted string may occupy.

-    @param[out]   NumChar   Pointer to where to store the number of wide characters, or NULL.

+    @param[out]   NumChar   Pointer to where to store the number of wide characters

+                            consumed, or NULL.

 

     @return     The number of bytes required to convert Src to MBCS,

                 not including the terminating NUL.  If NumChar is not NULL, the number

@@ -961,8 +963,8 @@ wcsrtombs(
     @return   If a wide character is encountered that does not correspond to a

               valid multibyte character, the wcstombs function returns

               (size_t)(-1). Otherwise, the wcstombs function returns the number

-              of bytes modified, not including a terminating null character,

-              if any.

+              of bytes in the resulting multibyte character sequence,

+              not including the terminating null character (if any).

 

     Declared in: stdlib.h

 **/

diff --git a/StdLib/LibC/Uefi/SysCalls.c b/StdLib/LibC/Uefi/SysCalls.c
index a2b627bd12..faa73ed7a4 100644
--- a/StdLib/LibC/Uefi/SysCalls.c
+++ b/StdLib/LibC/Uefi/SysCalls.c
@@ -1,6 +1,7 @@
 /** @file

   EFI versions of NetBSD system calls.

 

+  Copyright (c) 2016, Daryl McDaniel. All rights reserved.<BR>

   Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

@@ -192,18 +193,18 @@ _closeX  (int fd, int NewState)
     Fp = &gMD->fdarray[fd];

     // Check if there are other users of this FileHandle

     if(Fp->RefCount == 1) { // There should be no other users

-    if(! IsDupFd(fd)) {

-      // Only do the close if no one else is using the FileHandle

-      if(Fp->f_iflags & FIF_DELCLOSE) {

-        /* Handle files marked "Delete on Close". */

-        if(Fp->f_ops->fo_delete != NULL) {

-          retval = Fp->f_ops->fo_delete(Fp);

+      if(! IsDupFd(fd)) {

+        // Only do the close if no one else is using the FileHandle

+        if(Fp->f_iflags & FIF_DELCLOSE) {

+          /* Handle files marked "Delete on Close". */

+          if(Fp->f_ops->fo_delete != NULL) {

+            retval = Fp->f_ops->fo_delete(Fp);

+          }

         }

-      }

-      else {

+        else {

           retval = Fp->f_ops->fo_close( Fp);

+        }

       }

-    }

       Fp->f_iflags = NewState;    // Close this FD or reserve it

       Fp->RefCount = 0;           // No one using this FD

     }

@@ -671,58 +672,58 @@ open(
 

   Status = ParsePath(path, &NewPath, &Node, &Instance, &MPath);

   if(Status == RETURN_SUCCESS) {

-    if((Node == NULL)               ||

-       (Node->InstanceList == NULL))

+    if ((Node == NULL)               ||

+        (Node->InstanceList == NULL))

     {

       errno   = EPERM;

     }

     else {

-  // Could add a test to see if the file name begins with a period.

-  // If it does, then add the HIDDEN flag to Attributes.

+      // Could add a test to see if the file name begins with a period.

+      // If it does, then add the HIDDEN flag to Attributes.

 

-  // Get an available fd

+      // Get an available fd

       fd = FindFreeFD( VALID_CLOSED );

 

-  if( fd < 0 ) {

-    // All available FDs are in use

-    errno = EMFILE;

-  }

+      if( fd < 0 ) {

+        // All available FDs are in use

+        errno = EMFILE;

+      }

       else {

-      filp = &gMD->fdarray[fd];

-      // Save the flags and mode in the File Descriptor

-      filp->Oflags = oflags;

-      filp->Omode = mode;

+        filp = &gMD->fdarray[fd];

+        // Save the flags and mode in the File Descriptor

+        filp->Oflags = oflags;

+        filp->Omode = mode;

 

         doresult = Node->OpenFunc(Node, filp, Instance, NewPath, MPath);

-      if(doresult < 0) {

-        filp->f_iflags = 0;   // Release this FD

-        fd = -1;              // Indicate an error

-      }

-      else {

-        // Build our final f_iflags value

-        OpenMode  = ( mode & S_ACC_READ )  ? S_ACC_READ : 0;

-        OpenMode |= ( mode & S_ACC_WRITE ) ? S_ACC_WRITE : 0;

-

-        filp->f_iflags |= OpenMode;

-

-        if((oflags & O_TTY_INIT) && (filp->f_iflags & _S_ITTY) && (filp->devdata != NULL)) {

-          // Initialize the device's termios flags to a "sane" value

-          Termio = &((cIIO *)filp->devdata)->Termio;

-          Termio->c_iflag = ICRNL | IGNSPEC;

-          Termio->c_oflag = OPOST | ONLCR | OXTABS | ONOEOT | ONOCR | ONLRET | OCTRL;

-          Termio->c_lflag = ECHO | ECHOE | ECHONL | ICANON;

-          Termio->c_cc[VERASE]  = 0x08;   // ^H Backspace

-          Termio->c_cc[VKILL]   = 0x15;   // ^U

-          Termio->c_cc[VINTR]   = 0x03;   // ^C Interrupt character

+        if(doresult < 0) {

+          filp->f_iflags = 0;   // Release this FD

+          fd = -1;              // Indicate an error

         }

-        ++filp->RefCount;

-        FILE_SET_MATURE(filp);

-      }

+        else {

+          // Build our final f_iflags value

+          OpenMode  = ( mode & S_ACC_READ )  ? S_ACC_READ : 0;

+          OpenMode |= ( mode & S_ACC_WRITE ) ? S_ACC_WRITE : 0;

+

+          filp->f_iflags |= OpenMode;

+

+          if((oflags & O_TTY_INIT) && (filp->f_iflags & _S_ITTY) && (filp->devdata != NULL)) {

+            // Initialize the device's termios flags to a "sane" value

+            Termio = &((cIIO *)filp->devdata)->Termio;

+            Termio->c_iflag = ICRNL | IGNSPEC;

+            Termio->c_oflag = OPOST | ONLCR | OXTABS | ONOEOT | ONOCR | ONLRET | OCTRL;

+            Termio->c_lflag = ECHO | ECHOE | ECHONL | ICANON;

+            Termio->c_cc[VERASE]  = 0x08;   // ^H Backspace

+            Termio->c_cc[VKILL]   = 0x15;   // ^U

+            Termio->c_cc[VINTR]   = 0x03;   // ^C Interrupt character

           }

+          ++filp->RefCount;

+          FILE_SET_MATURE(filp);

+        }

+      }

     }

     free(NewPath);

-        }

-    free(MPath);    // We don't need this any more.

+  }

+  free(MPath);    // We don't need this any more.

 

   // return the fd of our now open file

   return fd;

@@ -1211,21 +1212,30 @@ read   (int fildes, void *buf, size_t nbyte)
 

     This function writes the specified number of bytes to the file at the current

     file position. The current file position is advanced the actual number of bytes

-    written, which is returned in BufferSize. Partial writes only occur when there

-    has been a data error during the write attempt (such as "volume space full").

-    The file is automatically grown to hold the data if required. Direct writes to

-    opened directories are not supported.

+    written. Partial writes only occur when there has been a data error during

+    the write attempt (such as "volume space full").  The file is automatically

+    grown to hold the data if required.

+

+    Direct writes to opened directories are not supported.

 

     If fildes refers to a terminal device, isatty() returns TRUE, a partial write

     will occur if a NULL or EOF character is encountered before n characters have

-    been written.  Characters inserted due to line-end translations will not be

-    counted.  Unconvertable characters are translated into the UEFI character

-    BLOCKELEMENT_LIGHT_SHADE.

+    been written.  Characters inserted due to line-end translations or TAB

+    expansion will not be counted.  Unconvertable characters are translated into

+    the UEFI character BLOCKELEMENT_LIGHT_SHADE.

 

     Since the UEFI console device works on wide characters, the buffer is assumed

-    to contain a single-byte character stream which is then translated to wide

-    characters using the mbtowc() functions.  The resulting wide character stream

-    is what is actually sent to the UEFI console.

+    to contain a byte-oriented multi-byte character stream which is then

+    translated to wide characters using the mbtowc() functions.  The resulting

+    wide character stream is what is actually sent to the UEFI console.

+

+    Although both text and binary wide-oriented streams are conceptually

+    sequences of wide characters, the external file associated with a

+    wide-oriented stream is a sequence of multibyte characters,

+    generalized as follows:

+      - Multibyte encodings within files may contain embedded null bytes

+        (unlike multibyte encodings valid for use internal to the program).

+      - A file need not begin nor end in the initial shift state.

 

     @param[in]  fd      Descriptor of file to be written to.

     @param[in]  buf     Pointer to data to write to the file.

@@ -1250,10 +1260,11 @@ write  (int fd, const void *buf, size_t nbyte)
       IIO = filp->devdata;

       if(isatty(fd) && (IIO != NULL)) {

         // Output to an Interactive I/O device

+        // (Terminal device or the slave side of a pseudo-tty)

         BufSize = IIO->Write(filp, buf, nbyte);

       }

       else {

-        // Output to a file, socket, pipe, etc.

+        // Output to a regular file, socket, pipe, etc.

         BufSize = filp->f_ops->fo_write(filp, &filp->f_offset, nbyte, buf);

       }

     }