]> git.proxmox.com Git - mirror_edk2.git/blobdiff - StdLib/LibC/Uefi/SysCalls.c
StdLib: Clarify and improve comments.
[mirror_edk2.git] / StdLib / LibC / Uefi / SysCalls.c
index a2b627bd121ac9ccfb47d1a996b1eb84814d638f..faa73ed7a4eed19715f34b45deecc71ac6a341d1 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