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

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);

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
@@ -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,
+              of bytes in the resulting multibyte character sequence,
-              if any.
+              not including the terminating null character (if any).
 
     Declared in: stdlib.h
 **/

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.
@@ -671,7 +672,7 @@ open(
 
   Status = ParsePath(path, &NewPath, &Node, &Instance, &MPath);
   if(Status == RETURN_SUCCESS) {
-    if((Node == NULL)               ||
+    if ((Node == NULL)               ||
         (Node->InstanceList == NULL))
     {
       errno   = EPERM;
@@ -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
+    written. Partial writes only occur when there has been a data error during
-    has been a data error during the write attempt (such as "volume space full").
+    the write attempt (such as "volume space full").  The file is automatically
-    The file is automatically grown to hold the data if required. Direct writes to
+    grown to hold the data if required.
-    opened directories are not supported.
+
+    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
+    been written.  Characters inserted due to line-end translations or TAB
-    counted.  Unconvertable characters are translated into the UEFI character
+    expansion will not be counted.  Unconvertable characters are translated into
-    BLOCKELEMENT_LIGHT_SHADE.
+    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
+    to contain a byte-oriented multi-byte character stream which is then
-    characters using the mbtowc() functions.  The resulting wide character stream
+    translated to wide characters using the mbtowc() functions.  The resulting
-    is what is actually sent to the UEFI console.
+    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);
       }
     }

StdLibPrivateInternalFiles/Include/kfile.h

@@ -102,7 +102,13 @@ struct __filedes {
 
 struct fileops {
   /* These functions must always be implemented. */
+
+  /** Perform device specific operations for closing the device.
+      It is the responsibility of this function to flush or discard
+      buffer contents.
+  **/
   int     (EFIAPI *fo_close)    (struct __filedes *filp);
+
   ssize_t (EFIAPI *fo_read)     (struct __filedes *filp, off_t *Offset, size_t Len, void *Buf);
   ssize_t (EFIAPI *fo_write)    (struct __filedes *filp, off_t *Offset, size_t Len, const void *Buf);
 
@@ -123,7 +129,7 @@ struct fileops {
   off_t   (EFIAPI *fo_lseek)    (struct __filedes *filp, off_t, int);
 };
 
-/*  A generic instance structure which is valid for
+/*  A generic instance structure which is valid
     for all device instance structures.
 
     All device instance structures MUST be a multiple of 8-bytes in length.