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

diff --git a/StdLib/Include/sys/termios.h b/StdLib/Include/sys/termios.h
index 671a5c06c067ebda7b903bae0840748be4d1608d..75886065b7744c3b1d9f9dcfbf54e394d22e2956 100644 (file)
--- a/StdLib/Include/sys/termios.h
+++ b/StdLib/Include/sys/termios.h
@@ -2,6 +2,7 @@
     Macros and declarations for terminal oriented ioctls and\r
     I/O discipline.\r
 \r
     Macros and declarations for terminal oriented ioctls and\r
     I/O discipline.\r
 \r

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

     Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved.<BR>\r
     This program and the accompanying materials are licensed and made available under\r
     the terms and conditions of the BSD License that accompanies this distribution.\r
     Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved.<BR>\r
     This program and the accompanying materials are licensed and made available under\r
     the terms and conditions of the BSD License that accompanies this distribution.\r


@@ -288,7 +289,7 @@ int     cfsetospeed (struct termios *, speed_t);
                     * EBADF - The fd argument is not a valid file descriptor.\r
                     * ENOTTY - The file associated with fd is not an interactive IO device.\r
 **/\r
                     * EBADF - The fd argument is not a valid file descriptor.\r
                     * ENOTTY - The file associated with fd is not an interactive IO device.\r
 **/\r

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

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


@@ -314,7 +315,7 @@ int     tcgetattr   (int, struct termios *);
                     * EBADF - The fd argument is not a valid file descriptor.\r
                     * ENOTTY - The file associated with fd is not an interactive IO device.\r
 **/\r
                     * EBADF - The fd argument is not a valid file descriptor.\r
                     * ENOTTY - The file associated with fd is not an interactive IO device.\r
 **/\r

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

 \r
 /** Transmit pending output.\r
 \r
 \r
 /** Transmit pending output.\r
 \r


@@ -328,7 +329,7 @@ int     tcsetattr   (int, int, const struct termios *);
                     * EINTR - A signal interrupted tcdrain().\r
                     * ENOTSUP - This function is not supported.\r
 **/\r
                     * EINTR - A signal interrupted tcdrain().\r
                     * ENOTSUP - This function is not supported.\r
 **/\r

-int     tcdrain     (int);\r
+int     tcdrain     (int fd);\r

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


@@ -353,7 +354,7 @@ int     tcdrain     (int);
                     * EINVAL - The Action argument is not a supported value.\r
                     * ENOTSUP - This function is not supported.\r
 **/\r
                     * EINVAL - The Action argument is not a supported value.\r
                     * ENOTSUP - This function is not supported.\r
 **/\r

-int     tcflow      (int, int);\r
+int     tcflow      (int fd, int Action);\r

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


@@ -375,7 +376,7 @@ int     tcflow      (int, int);
                     * EINVAL - The QueueSelector argument is not a supported value.\r
                     * ENOTSUP - This function is not supported.\r
 **/\r
                     * EINVAL - The QueueSelector argument is not a supported value.\r
                     * ENOTSUP - This function is not supported.\r
 **/\r

-int     tcflush     (int, int);\r
+int     tcflush     (int fd, int QueueSelector);\r

 \r
 //int     tcsendbreak (int, int);\r
 //pid_t   tcgetsid    (int);\r
 \r
 //int     tcsendbreak (int, int);\r
 //pid_t   tcgetsid    (int);\r

diff --git a/StdLib/LibC/Locale/multibyte_Utf8.c b/StdLib/LibC/Locale/multibyte_Utf8.c
index ffe3dee231ca203b9e448a827b77f82ae75c4761..55f4802b16c2b13374ab70fe717a7a3f31321194 100644 (file)
--- a/StdLib/LibC/Locale/multibyte_Utf8.c
+++ b/StdLib/LibC/Locale/multibyte_Utf8.c
@@ -1,4 +1,5 @@
 /** @file\r
 /** @file\r

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

   Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>\r
   This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r
   Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>\r
   This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r


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

-typedef      int      ch_UCS4;\r
+typedef int      ch_UCS4;\r

 \r
 static  mbstate_t     LocalConvState = {0};\r
 \r
 \r
 static  mbstate_t     LocalConvState = {0};\r
 \r


@@ -79,7 +80,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
     // We are in an invalid state\r
     ps->A = 0;    // Initial State\r
   }\r
     // We are in an invalid state\r
     ps->A = 0;    // Initial State\r
   }\r

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

   Mask = utf8_code_length[ch];\r
 \r
   if(ps->A == 0) {    // Initial State.  First byte of sequence.\r
   Mask = utf8_code_length[ch];\r
 \r
   if(ps->A == 0) {    // Initial State.  First byte of sequence.\r


@@ -89,7 +90,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
       case 0:                       // State 0, Code 0\r
         errno = EILSEQ;\r
         RetVal = -1;\r
       case 0:                       // State 0, Code 0\r
         errno = EILSEQ;\r
         RetVal = -1;\r

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

         break;\r
       case 1:                       // State 0, Code 1\r
         // ASCII-7 Character\r
         break;\r
       case 1:                       // State 0, Code 1\r
         // ASCII-7 Character\r


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

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

             ps->A = 2;\r
             RetVal = -2;\r
           }\r
             ps->A = 2;\r
             RetVal = -2;\r
           }\r


@@ -158,12 +159,12 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
             errno = EILSEQ;\r
             ps->A = 0;\r
             RetVal = -1;\r
             errno = EILSEQ;\r
             ps->A = 0;\r
             RetVal = -1;\r

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

           }\r
           break;\r
       }\r
     }\r
           }\r
           break;\r
       }\r
     }\r

-    else {                // Invalid surrogate character\r
+    else {                // Invalid surrogate byte\r

       errno = EILSEQ;\r
       ps->A = 0;          // Next is State-0\r
       RetVal = -1;\r
       errno = EILSEQ;\r
       ps->A = 0;          // Next is State-0\r
       RetVal = -1;\r


@@ -287,7 +288,8 @@ OneWcToMcLen(const wchar_t InCh)
 \r
     @param[in]    Src       Pointer to a wide character string.\r
     @param[in]    Limit     Maximum number of bytes the converted string may occupy.\r
 \r
     @param[in]    Src       Pointer to a wide character string.\r
     @param[in]    Limit     Maximum number of bytes the converted string may occupy.\r

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

 \r
     @return     The number of bytes required to convert Src to MBCS,\r
                 not including the terminating NUL.  If NumChar is not NULL, the number\r
 \r
     @return     The number of bytes required to convert Src to MBCS,\r
                 not including the terminating NUL.  If NumChar is not NULL, the number\r


@@ -961,8 +963,8 @@ wcsrtombs(
     @return   If a wide character is encountered that does not correspond to a\r
               valid multibyte character, the wcstombs function returns\r
               (size_t)(-1). Otherwise, the wcstombs function returns the number\r
     @return   If a wide character is encountered that does not correspond to a\r
               valid multibyte character, the wcstombs function returns\r
               (size_t)(-1). Otherwise, the wcstombs function returns the number\r

-              of bytes modified, not including a terminating null character,\r
-              if any.\r
+              of bytes in the resulting multibyte character sequence,\r
+              not including the terminating null character (if any).\r

 \r
     Declared in: stdlib.h\r
 **/\r
 \r
     Declared in: stdlib.h\r
 **/\r

diff --git a/StdLib/LibC/Uefi/SysCalls.c b/StdLib/LibC/Uefi/SysCalls.c
index a2b627bd121ac9ccfb47d1a996b1eb84814d638f..faa73ed7a4eed19715f34b45deecc71ac6a341d1 100644 (file)
--- a/StdLib/LibC/Uefi/SysCalls.c
+++ b/StdLib/LibC/Uefi/SysCalls.c
@@ -1,6 +1,7 @@
 /** @file\r
   EFI versions of NetBSD system calls.\r
 \r
 /** @file\r
   EFI versions of NetBSD system calls.\r
 \r

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

   Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>\r
   This program and the accompanying materials are licensed and made available under\r
   the terms and conditions of the BSD License that accompanies this distribution.\r
   Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>\r
   This program and the accompanying materials are licensed and made available under\r
   the terms and conditions of the BSD License that accompanies this distribution.\r


@@ -192,18 +193,18 @@ _closeX  (int fd, int NewState)
     Fp = &gMD->fdarray[fd];\r
     // Check if there are other users of this FileHandle\r
     if(Fp->RefCount == 1) { // There should be no other users\r
     Fp = &gMD->fdarray[fd];\r
     // Check if there are other users of this FileHandle\r
     if(Fp->RefCount == 1) { // There should be no other users\r

-    if(! IsDupFd(fd)) {\r
-      // Only do the close if no one else is using the FileHandle\r
-      if(Fp->f_iflags & FIF_DELCLOSE) {\r
-        /* Handle files marked "Delete on Close". */\r
-        if(Fp->f_ops->fo_delete != NULL) {\r
-          retval = Fp->f_ops->fo_delete(Fp);\r
+      if(! IsDupFd(fd)) {\r
+        // Only do the close if no one else is using the FileHandle\r
+        if(Fp->f_iflags & FIF_DELCLOSE) {\r
+          /* Handle files marked "Delete on Close". */\r
+          if(Fp->f_ops->fo_delete != NULL) {\r
+            retval = Fp->f_ops->fo_delete(Fp);\r
+          }\r

         }\r
         }\r

-      }\r
-      else {\r
+        else {\r

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

+        }\r

       }\r
       }\r

-    }\r

       Fp->f_iflags = NewState;    // Close this FD or reserve it\r
       Fp->RefCount = 0;           // No one using this FD\r
     }\r
       Fp->f_iflags = NewState;    // Close this FD or reserve it\r
       Fp->RefCount = 0;           // No one using this FD\r
     }\r


@@ -671,58 +672,58 @@ open(
 \r
   Status = ParsePath(path, &NewPath, &Node, &Instance, &MPath);\r
   if(Status == RETURN_SUCCESS) {\r
 \r
   Status = ParsePath(path, &NewPath, &Node, &Instance, &MPath);\r
   if(Status == RETURN_SUCCESS) {\r

-    if((Node == NULL)               ||\r
-       (Node->InstanceList == NULL))\r
+    if ((Node == NULL)               ||\r
+        (Node->InstanceList == NULL))\r

     {\r
       errno   = EPERM;\r
     }\r
     else {\r
     {\r
       errno   = EPERM;\r
     }\r
     else {\r

-  // Could add a test to see if the file name begins with a period.\r
-  // If it does, then add the HIDDEN flag to Attributes.\r
+      // Could add a test to see if the file name begins with a period.\r
+      // If it does, then add the HIDDEN flag to Attributes.\r

 \r
 \r

-  // Get an available fd\r
+      // Get an available fd\r

       fd = FindFreeFD( VALID_CLOSED );\r
 \r
       fd = FindFreeFD( VALID_CLOSED );\r
 \r

-  if( fd < 0 ) {\r
-    // All available FDs are in use\r
-    errno = EMFILE;\r
-  }\r
+      if( fd < 0 ) {\r
+        // All available FDs are in use\r
+        errno = EMFILE;\r
+      }\r

       else {\r
       else {\r

-      filp = &gMD->fdarray[fd];\r
-      // Save the flags and mode in the File Descriptor\r
-      filp->Oflags = oflags;\r
-      filp->Omode = mode;\r
+        filp = &gMD->fdarray[fd];\r
+        // Save the flags and mode in the File Descriptor\r
+        filp->Oflags = oflags;\r
+        filp->Omode = mode;\r

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

-      if(doresult < 0) {\r
-        filp->f_iflags = 0;   // Release this FD\r
-        fd = -1;              // Indicate an error\r
-      }\r
-      else {\r
-        // Build our final f_iflags value\r
-        OpenMode  = ( mode & S_ACC_READ )  ? S_ACC_READ : 0;\r
-        OpenMode |= ( mode & S_ACC_WRITE ) ? S_ACC_WRITE : 0;\r
-\r
-        filp->f_iflags |= OpenMode;\r
-\r
-        if((oflags & O_TTY_INIT) && (filp->f_iflags & _S_ITTY) && (filp->devdata != NULL)) {\r
-          // Initialize the device's termios flags to a "sane" value\r
-          Termio = &((cIIO *)filp->devdata)->Termio;\r
-          Termio->c_iflag = ICRNL | IGNSPEC;\r
-          Termio->c_oflag = OPOST | ONLCR | OXTABS | ONOEOT | ONOCR | ONLRET | OCTRL;\r
-          Termio->c_lflag = ECHO | ECHOE | ECHONL | ICANON;\r
-          Termio->c_cc[VERASE]  = 0x08;   // ^H Backspace\r
-          Termio->c_cc[VKILL]   = 0x15;   // ^U\r
-          Termio->c_cc[VINTR]   = 0x03;   // ^C Interrupt character\r
+        if(doresult < 0) {\r
+          filp->f_iflags = 0;   // Release this FD\r
+          fd = -1;              // Indicate an error\r

         }\r
         }\r

-        ++filp->RefCount;\r
-        FILE_SET_MATURE(filp);\r
-      }\r
+        else {\r
+          // Build our final f_iflags value\r
+          OpenMode  = ( mode & S_ACC_READ )  ? S_ACC_READ : 0;\r
+          OpenMode |= ( mode & S_ACC_WRITE ) ? S_ACC_WRITE : 0;\r
+\r
+          filp->f_iflags |= OpenMode;\r
+\r
+          if((oflags & O_TTY_INIT) && (filp->f_iflags & _S_ITTY) && (filp->devdata != NULL)) {\r
+            // Initialize the device's termios flags to a "sane" value\r
+            Termio = &((cIIO *)filp->devdata)->Termio;\r
+            Termio->c_iflag = ICRNL | IGNSPEC;\r
+            Termio->c_oflag = OPOST | ONLCR | OXTABS | ONOEOT | ONOCR | ONLRET | OCTRL;\r
+            Termio->c_lflag = ECHO | ECHOE | ECHONL | ICANON;\r
+            Termio->c_cc[VERASE]  = 0x08;   // ^H Backspace\r
+            Termio->c_cc[VKILL]   = 0x15;   // ^U\r
+            Termio->c_cc[VINTR]   = 0x03;   // ^C Interrupt character\r

           }\r
           }\r

+          ++filp->RefCount;\r
+          FILE_SET_MATURE(filp);\r
+        }\r
+      }\r

     }\r
     free(NewPath);\r
     }\r
     free(NewPath);\r

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

 \r
   // return the fd of our now open file\r
   return fd;\r
 \r
   // return the fd of our now open file\r
   return fd;\r


@@ -1211,21 +1212,30 @@ read   (int fildes, void *buf, size_t nbyte)
 \r
     This function writes the specified number of bytes to the file at the current\r
     file position. The current file position is advanced the actual number of bytes\r
 \r
     This function writes the specified number of bytes to the file at the current\r
     file position. The current file position is advanced the actual number of bytes\r

-    written, which is returned in BufferSize. Partial writes only occur when there\r
-    has been a data error during the write attempt (such as "volume space full").\r
-    The file is automatically grown to hold the data if required. Direct writes to\r
-    opened directories are not supported.\r
+    written. Partial writes only occur when there has been a data error during\r
+    the write attempt (such as "volume space full").  The file is automatically\r
+    grown to hold the data if required.\r
+\r
+    Direct writes to opened directories are not supported.\r

 \r
     If fildes refers to a terminal device, isatty() returns TRUE, a partial write\r
     will occur if a NULL or EOF character is encountered before n characters have\r
 \r
     If fildes refers to a terminal device, isatty() returns TRUE, a partial write\r
     will occur if a NULL or EOF character is encountered before n characters have\r

-    been written.  Characters inserted due to line-end translations will not be\r
-    counted.  Unconvertable characters are translated into the UEFI character\r
-    BLOCKELEMENT_LIGHT_SHADE.\r
+    been written.  Characters inserted due to line-end translations or TAB\r
+    expansion will not be counted.  Unconvertable characters are translated into\r
+    the UEFI character BLOCKELEMENT_LIGHT_SHADE.\r

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

-    to contain a single-byte character stream which is then translated to wide\r
-    characters using the mbtowc() functions.  The resulting wide character stream\r
-    is what is actually sent to the UEFI console.\r
+    to contain a byte-oriented multi-byte character stream which is then\r
+    translated to wide characters using the mbtowc() functions.  The resulting\r
+    wide character stream is what is actually sent to the UEFI console.\r
+\r
+    Although both text and binary wide-oriented streams are conceptually\r
+    sequences of wide characters, the external file associated with a\r
+    wide-oriented stream is a sequence of multibyte characters,\r
+    generalized as follows:\r
+      - Multibyte encodings within files may contain embedded null bytes\r
+        (unlike multibyte encodings valid for use internal to the program).\r
+      - A file need not begin nor end in the initial shift state.\r

 \r
     @param[in]  fd      Descriptor of file to be written to.\r
     @param[in]  buf     Pointer to data to write to the file.\r
 \r
     @param[in]  fd      Descriptor of file to be written to.\r
     @param[in]  buf     Pointer to data to write to the file.\r


@@ -1250,10 +1260,11 @@ write  (int fd, const void *buf, size_t nbyte)
       IIO = filp->devdata;\r
       if(isatty(fd) && (IIO != NULL)) {\r
         // Output to an Interactive I/O device\r
       IIO = filp->devdata;\r
       if(isatty(fd) && (IIO != NULL)) {\r
         // Output to an Interactive I/O device\r

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

         BufSize = IIO->Write(filp, buf, nbyte);\r
       }\r
       else {\r
         BufSize = IIO->Write(filp, buf, nbyte);\r
       }\r
       else {\r

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

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

diff --git a/StdLibPrivateInternalFiles/Include/kfile.h b/StdLibPrivateInternalFiles/Include/kfile.h
index 6312895c40449b23cd8d5497353954716cf77567..67bff56cc67483b6e7eaa1b2ba50b728942bf3d3 100644 (file)
--- a/StdLibPrivateInternalFiles/Include/kfile.h
+++ b/StdLibPrivateInternalFiles/Include/kfile.h
@@ -102,7 +102,13 @@ struct __filedes {
 \r
 struct fileops {\r
   /* These functions must always be implemented. */\r
 \r
 struct fileops {\r
   /* These functions must always be implemented. */\r

+\r
+  /** Perform device specific operations for closing the device.\r
+      It is the responsibility of this function to flush or discard\r
+      buffer contents.\r
+  **/\r

   int     (EFIAPI *fo_close)    (struct __filedes *filp);\r
   int     (EFIAPI *fo_close)    (struct __filedes *filp);\r

+\r

   ssize_t (EFIAPI *fo_read)     (struct __filedes *filp, off_t *Offset, size_t Len, void *Buf);\r
   ssize_t (EFIAPI *fo_write)    (struct __filedes *filp, off_t *Offset, size_t Len, const void *Buf);\r
 \r
   ssize_t (EFIAPI *fo_read)     (struct __filedes *filp, off_t *Offset, size_t Len, void *Buf);\r
   ssize_t (EFIAPI *fo_write)    (struct __filedes *filp, off_t *Offset, size_t Len, const void *Buf);\r
 \r


@@ -123,7 +129,7 @@ struct fileops {
   off_t   (EFIAPI *fo_lseek)    (struct __filedes *filp, off_t, int);\r
 };\r
 \r
   off_t   (EFIAPI *fo_lseek)    (struct __filedes *filp, off_t, int);\r
 };\r
 \r

-/*  A generic instance structure which is valid for\r
+/*  A generic instance structure which is valid\r

     for all device instance structures.\r
 \r
     All device instance structures MUST be a multiple of 8-bytes in length.\r
     for all device instance structures.\r
 \r
     All device instance structures MUST be a multiple of 8-bytes in length.\r