summaryrefslogtreecommitdiff
path: root/StdLib
diff options
context:
space:
mode:
authorDaryl McDaniel <edk2-lists@mc2research.org>2016-01-06 00:31:42 +0000
committerdarylm503 <darylm503@Edk2>2016-01-06 00:31:42 +0000
commit450ea6d5b69cffd2b6c2154fdbeec5bf60c8c858 (patch)
treec25268572cb9f92728bd822d4d2b58a79830bf38 /StdLib
parent4e8f2b290e92891b4248cc680d6751b73331d545 (diff)
downloadedk2-platforms-450ea6d5b69cffd2b6c2154fdbeec5bf60c8c858.tar.xz
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
Diffstat (limited to 'StdLib')
-rw-r--r--StdLib/Include/sys/termios.h11
-rw-r--r--StdLib/LibC/Locale/multibyte_Utf8.c20
-rw-r--r--StdLib/LibC/Uefi/SysCalls.c127
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);
}
}