StdLib: Clarify and improve comments.
authorDaryl McDaniel <edk2-lists@mc2research.org>
Wed, 6 Jan 2016 00:31:42 +0000 (00:31 +0000)
committerdarylm503 <darylm503@Edk2>
Wed, 6 Jan 2016 00:31:42 +0000 (00:31 +0000)
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
StdLib/LibC/Locale/multibyte_Utf8.c
StdLib/LibC/Uefi/SysCalls.c
StdLibPrivateInternalFiles/Include/kfile.h

index 671a5c0..7588606 100644 (file)
@@ -2,6 +2,7 @@
     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
@@ -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
-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
@@ -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
-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
@@ -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
-int     tcdrain     (int);\r
+int     tcdrain     (int fd);\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
-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
@@ -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
-int     tcflush     (int, int);\r
+int     tcflush     (int fd, int QueueSelector);\r
 \r
 //int     tcsendbreak (int, int);\r
 //pid_t   tcgetsid    (int);\r
index ffe3dee..55f4802 100644 (file)
@@ -1,4 +1,5 @@
 /** @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
@@ -16,7 +17,7 @@
 #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
@@ -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
-  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
@@ -89,7 +90,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
       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
@@ -116,7 +117,7 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
             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
@@ -158,12 +159,12 @@ ProcessOneByte(unsigned char ch, mbstate_t *ps)
             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
-    else {                // Invalid surrogate character\r
+    else {                // Invalid surrogate byte\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
-    @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
@@ -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
-              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
index a2b627b..faa73ed 100644 (file)
@@ -1,6 +1,7 @@
 /** @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
@@ -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
-    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
-      else {\r
+        else {\r
           retval = Fp->f_ops->fo_close( Fp);\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
@@ -671,58 +672,58 @@ open(
 \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
-  // 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
-  // Get an available fd\r
+      // Get an available fd\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
-      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
-      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
-        ++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
+          ++filp->RefCount;\r
+          FILE_SET_MATURE(filp);\r
+        }\r
+      }\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
@@ -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
-    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
-    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
-    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
@@ -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
+        // (Terminal device or the slave side of a pseudo-tty)\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
index 6312895..67bff56 100644 (file)
@@ -102,7 +102,13 @@ struct __filedes {
 \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
+\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
-/*  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