X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Ffunctions.texi;h=f89a7f83a0c903ebc9033f2a8a1f63e1cdcfc863;hb=ea27c6baf761ef00f1f357b1dbf11782bb7deae2;hp=81dac481602c474c11f41030b58dc01f6497b0bf;hpb=ac10d74e23bda88473d5b8c0b9b68d47939645e3;p=gnulib.git

diff --git a/doc/functions.texi b/doc/functions.texi
index 81dac4816..f89a7f83a 100644
--- a/doc/functions.texi
+++ b/doc/functions.texi
@@ -2,6 +2,15 @@
 @section Portability of Standard Functions
 @cindex functions
 
+@c Copyright (C) 2006 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.2 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+@c Texts.  A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
 Many standard library functions have portability limitations, although
 they are specified in the
 @uref{http://www.opengroup.org/susv3, Posix standard}.  In this section,
@@ -29,7 +38,7 @@ invalid year is passed.
 glibc has two different functions @code{basename}: the POSIX version and
 the GNU version.
 
-@code{basename} assumes file names in POSIX syntax; it does not with file
+@code{basename} assumes file names in POSIX syntax; it does not work with file
 names in Windows syntax.
 
 @item bcmp
@@ -42,7 +51,7 @@ or @code{memmove} instead.
 
 @item btowc
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item bzero
 This function is marked as ``legacy'' in POSIX.  Better use @code{memset}
@@ -50,7 +59,7 @@ instead.
 
 @item chown
 When applied to a symbolic link, some implementations don't dereference
-the symlink, i.e. they behave like @code{lchown}.
+the symlink, i.e.@: they behave like @code{lchown}.
 
 @item cproj
 @itemx cprojf
@@ -74,7 +83,7 @@ This function may put more than 26 bytes into the argument buffer if an
 invalid year is passed.
 
 @item dirname
-@code{dirname} assumes file names in POSIX syntax; it does not with file
+@code{dirname} assumes file names in POSIX syntax; it does not work with file
 names in Windows syntax.
 
 @item dlopen
@@ -114,7 +123,7 @@ upon failure.
 @item fgetwc
 @itemx fgetws
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item fnmatch
 This function is broken in some version of Solaris or glibc.
@@ -123,9 +132,9 @@ This function is broken in some version of Solaris or glibc.
 On Windows systems (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 
-On Windows, this function returns a file stream in "text" mode by default;
-this means that it translates '\n' to CR/LF by default.  Use the "b" flag
-if you need reliable binary I/O.
+On Windows, this function returns a file stream in ``text'' mode by default;
+this means that it translates @code{'\n'} to CR/LF by default.  Use the
+@code{"b"} flag if you need reliable binary I/O.
 
 @item fork
 On some systems, @code{fork} followed by a call of the @code{exec} family
@@ -139,12 +148,13 @@ On Windows systems (excluding Cygwin), this function is not implemented; use
 
 @item fprintf
 On NetBSD and Windows, this function doesn't support format directives that
-access arguments in an arbitrary order, such as "%2$s".  The fix is to include
-@file{<libintl.h>} from GNU gettext; it redefines this function so that it is
-POSIX compliant.
+access arguments in an arbitrary order, such as @code{"%2$s"}.  The fix is to
+include @file{<libintl.h>} from GNU gettext; it redefines this function so that
+it is POSIX compliant.
 
-On Windows, this function doesn't support the @code{'} flag and the @code{hh},
-@code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+On Windows systems (excluding Cygwin), this function doesn't support
+the @code{'} flag and the @code{hh}, @code{ll}, @code{j}, @code{t},
+@code{z} size specifiers.
 
 @item fputc
 @itemx fputs
@@ -154,7 +164,7 @@ upon failure.
 @item fputwc
 @itemx fputws
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item fread
 On Windows systems (excluding Cygwin), this function does not set @code{errno}
@@ -179,8 +189,8 @@ On Windows systems (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 
 @item fstat
-On platforms where @code{off_t} is a 32-bit type, @code{stat} may not report
-correctly the size of files or block devices larger than 2 GB.  The fix is to
+On platforms where @code{off_t} is a 32-bit type, @code{stat} may not correctly
+report the size of files or block devices larger than 2 GB.  The fix is to
 use the @code{AC_SYS_LARGEFILE} macro.
 
 On Cygwin, @code{fstat} applied to the file descriptors 0 and 1, returns
@@ -194,14 +204,14 @@ portability to Windows systems.
 
 @item fwide
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @code{fwide} is not guaranteed to be able to change a file stream's mode
 to a different mode than the current one.
 
 @item fwprintf
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item fwrite
 On Windows systems (excluding Cygwin), this function does not set @code{errno}
@@ -209,7 +219,7 @@ upon failure.
 
 @item fwscanf
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item gcvt
 This function is marked as ``legacy'' in POSIX.  Better use @code{sprintf}
@@ -234,14 +244,14 @@ On Ultrix 4.3, @code{getgroups (0, 0)} always fails.  See macro
 
 @item gethostname
 If the given buffer is too small for the host name, some implementations
-fail with EINVAL, instead of returning a truncated host name.
+fail with @code{EINVAL}, instead of returning a truncated host name.
 
 @item getopt
-The glibc implementation of @code{getopt} by default allows mixing option and
-non-option arguments on the command line in any order.  Other implementations,
-such as the one in Cygwin, enfore strict POSIX compliance: they require that
-the option arguments precede the non-option arguments.  This is something to
-watch out in your program's testsuite.
+The default behavior of the glibc implementation of @code{getopt} allows
+mixing option and non-option arguments on the command line in any order.
+Other implementations, such as the one in Cygwin, enforce strict POSIX
+compliance: they require that the option arguments precede the non-option
+arguments.  This is something to watch out in your program's testsuite.
 
 @item getpeername
 Some systems don't have a @code{socklen_t} type; in this case this function's
@@ -277,7 +287,7 @@ On some systems, @code{gettimeofday} clobbers the buffer in which
 @item getwc
 @itemx getwchar
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item getwd
 The size of the buffer required for this function is not a compile-time
@@ -297,7 +307,7 @@ This function was not correctly implemented in glibc versions before 2.2.
 When @code{iconv} encounters an input character that is valid but that can
 not be converted to the output character set, glibc's and GNU libiconv's
 @code{iconv} stop the conversion.  Some other implementations put an
-implementation-defined character in the output buffer.
+implementation-defined character into the output buffer.
 
 @item iconv_open
 The set of supported encodings and conversions is system dependent.
@@ -315,7 +325,7 @@ Most @code{ioctl} requests are platform and hardware specific.
 
 @item isatty
 On Windows, @code{isatty} also returns true for character devices such as
-"NUL".
+@file{NUL}.
 
 @item iswalnum
 @itemx iswalpha
@@ -331,7 +341,7 @@ On Windows, @code{isatty} also returns true for character devices such as
 @itemx iswupper
 @itemx iswxdigit
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item l64a
 This function was not correctly implemented in glibc versions before 2.2.5.
@@ -362,16 +372,19 @@ correctly with files larger than 2 GB.  The fix is to use the
 When the argument ends in a slash, some systems don't dereference the
 argument.
 
-On platforms where @code{off_t} is a 32-bit type, @code{lstat} may not report
-correctly the size of files or block devices larger than 2 GB.  The fix is to
-use the @code{AC_SYS_LARGEFILE} macro.
+On platforms where @code{off_t} is a 32-bit type, @code{lstat} may not
+correctly report the size of files or block devices larger than 2 GB.  The fix
+is to use the @code{AC_SYS_LARGEFILE} macro.
+
+On Windows systems (excluding Cygwin), symlinks are not supported, so
+@code{lstat} does not exist.  The fix is to define lstat to use stat.
 
 @item mbrtowc
 @itemx mbsrtowcs
 @itemx mbstowcs
 @itemx mbtowc
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item mkdir
 When the argument ends in a slash, the function call fails on some systems.
@@ -381,6 +394,10 @@ and takes only one argument.  The fix is to define a macro like this:
 @smallexample
 #define mkdir ((int (*)()) _mkdir)
 @end smallexample
+or
+@smallexample
+#define mkdir(path,mode) _mkdir (path)
+@end smallexample
 
 @item mkstemp
 On some systems (HP-UX 10.20, SunOS 4.1.4, Solaris 2.5.1), mkstemp has a silly
@@ -388,7 +405,7 @@ limit that it can create no more than 26 files from a given template.  On
 OSF/1 4.0f, it can create only 32 files per process.
 
 On systems other than glibc 2.0.7 or newer, @code{mkstemp} can create a
-world or group writable or readable file, if you haven't set the process'
+world or group writable or readable file, if you haven't set the process
 umask to 077.  This is a security risk.
 
 @item mktemp
@@ -445,16 +462,19 @@ like @file{/dev/null} and ttys like @file{/dev/tty}.
 
 @item printf
 On NetBSD and Windows, this function doesn't support format directives that
-access arguments in an arbitrary order, such as "%2$s".  The fix is to include
-@file{<libintl.h>} from GNU gettext; it redefines this function so that it is
-POSIX compliant.
+access arguments in an arbitrary order, such as @code{"%2$s"}.  The fix is to
+include @file{<libintl.h>} from GNU gettext; it redefines this function so that
+it is POSIX compliant.
 
-On Windows, this function doesn't support the @code{'} flag and the @code{hh},
-@code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+On Windows systems (excluding Cygwin), this function doesn't support
+the @code{'} flag and the @code{hh}, @code{ll}, @code{j}, @code{t},
+@code{z} size specifiers.
 
 @item pthread_create
 On Linux/glibc systems before the advent of NPTL, signals could only be
-executed in one particular thread, not by any thread of the process.
+sent to one particular thread.  In POSIX, signals are sent to the entire
+process and executed by any thread of the process that happens to have the
+particular signal currently unblocked.
 
 @item putc
 @itemx putchar
@@ -465,20 +485,21 @@ upon failure.
 @item putwc
 @itemx putwchar
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item readlink
 When @code{readlink} is called on a directory: In the case of NFS mounted
-directories, Cygwin sets errno to ENOENT or EIO instead of EINVAL.  To avoid
-this problem, check for a directory before calling @code{readlink}.
+directories, Cygwin sets @code{errno} to @code{ENOENT} or @code{EIO} instead of
+@code{EINVAL}.  To avoid this problem, check for a directory before calling
+@code{readlink}.
 
 When @code{readlink} is called on a file that is not a symbolic link:
-Irix may set errno to ENXIO instead of EINVAL.  Cygwin may set errno to
-EACCES instead of EINVAL.
+Irix may set @code{errno} to @code{ENXIO} instead of @code{EINVAL}.  Cygwin
+may set errno to @code{EACCES} instead of {EINVAL}.
 
 @item realpath
 This function does not allow to determine the required size of output buffer;
-PATH_MAX - if it is defined - is nothing more than a guess.
+PATH_MAX --- if it is defined --- is nothing more than a guess.
 
 @item recvfrom
 Some systems don't have a @code{socklen_t} type; in this case this function's
@@ -522,7 +543,7 @@ called on descriptors created by the @code{socket} function, not on regular
 file descriptors.
 
 On Linux, when some file descriptor refers to a regular file, @code{select}
-may fail, setting errno to EBADF.
+may fail, setting @code{errno} to @code{EBADF}.
 
 @item setcontext
 The effects of this call are system and compiler optimization dependent,
@@ -530,7 +551,7 @@ since it restores the contents of register-allocated variables but not
 the contents of stack-allocated variables.
 
 @item setenv
-In some versions of glibc (e.g. 2.3.3), @code{setenv} doesn't fail if the
+In some versions of glibc (e.g.@: 2.3.3), @code{setenv} doesn't fail if the
 first argument contains a @samp{=} character.
 
 @item setjmp
@@ -554,7 +575,8 @@ upon failure.
 
 @item shmat
 Attempts to @code{shmat} into a previously malloc-ed region fail on SunOS 4,
-with errno set to EINVAL, even if there is an @code{munmap} call in between.
+with @code{errno} set to @code{EINVAL}, even if there is an @code{munmap} call
+in between.
 
 On Linux, the flag @code{SHM_REMAP} is needed in order to force @code{shmat}
 to replace existing memory mappings in the specify address range.  On other
@@ -577,20 +599,20 @@ void handle_child (int sigchld)
 except that @code{SIG_IGN} for @code{SIGCHLD} has the effect that the children
 execution times are not accounted in the @code{times} function.
 On some systems (BSD? SystemV? Linux?), you need to use the @code{sigaction}
-flag @code{SA_NOCLDWAIT} in order to obtain this behaviour.
+flag @code{SA_NOCLDWAIT} in order to obtain this behavior.
 
 @item sigaltstack
 @code{sigaltstack} doesn't work on HP-UX 11/IA-64 and OpenBSD 3.6/Sparc64.
 
 @item signal
 On System V systems, when the signal is triggered, the kernel uninstalls the
-handler (i.e. resets the signal's action to SIG_DFL) before invoking the
+handler (i.e.@: resets the signal's action to SIG_DFL) before invoking the
 handler.  This opens the door to race conditions: undesired things happen
 if the signal is triggered twice and the signal handler was not quick enough
 reinstalling itself as a handler.  On BSD systems and glibc systems, on the
 other hand, when the signal is triggered, the kernel blocks the signal
 before invoking the handler.  This is saner, but POSIX still allows either
-behaviour.  To avoid this problem, use @code{sigaction} instead of
+behavior.  To avoid this problem, use @code{sigaction} instead of
 @code{signal}.
 
 @item sigtimedwait
@@ -599,7 +621,9 @@ does; other systems may not do the same.
 
 @item sigwait
 On Linux/glibc systems before the advent of NPTL, signals could only be
-executed in one particular thread, not by any thread of the process.
+sent to one particular thread.  In POSIX, signals are sent to the entire
+process and executed by any thread of the process that happens to have the
+particular signal currently unblocked.
 
 @item sleep
 According to POSIX, the @code{sleep} function may interfere with the program's
@@ -608,12 +632,13 @@ it may.
 
 @item snprintf
 On NetBSD and Windows, this function doesn't support format directives that
-access arguments in an arbitrary order, such as "%2$s".  The fix is to include
-@file{<libintl.h>} from GNU gettext; it redefines this function so that it is
-is POSIX compliant.
+access arguments in an arbitrary order, such as @code{"%2$s"}.  The fix is to
+include @file{<libintl.h>} from GNU gettext; it redefines this function so that
+it is POSIX compliant.
 
-On Windows, this function doesn't support the @code{'} flag and the @code{hh},
-@code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+On Windows systems (excluding Cygwin), this function doesn't support
+the @code{'} flag and the @code{hh}, @code{ll}, @code{j}, @code{t},
+@code{z} size specifiers.
 
 @item socket
 On BeOS, the descriptors returned by the @code{socket} function can not be used
@@ -622,12 +647,13 @@ in calls to @code{read}, @code{write}, and @code{close}; you have to use
 
 @item sprintf
 On NetBSD and Windows, this function doesn't support format directives that
-access arguments in an arbitrary order, such as "%2$s".  The fix is to include
-@file{<libintl.h>} from GNU gettext; it redefines this function so that it is
-is POSIX compliant.
+access arguments in an arbitrary order, such as @code{"%2$s"}.  The fix is to
+include @file{<libintl.h>} from GNU gettext; it redefines this function so that
+it is POSIX compliant.
 
-On Windows, this function doesn't support the @code{'} flag and the @code{hh},
-@code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+On Windows systems (excluding Cygwin), this function doesn't support
+the @code{'} flag and the @code{hh}, @code{ll}, @code{j}, @code{t},
+@code{z} size specifiers.
 
 @item sscanf
 On Windows systems (excluding Cygwin), this function does not set @code{errno}
@@ -637,12 +663,12 @@ On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
 @code{t}, @code{z} size specifiers.
 
 @item stat
-On platforms where @code{off_t} is a 32-bit type, @code{stat} may not report
-correctly the size of files or block devices larger than 2 GB.  The fix is to
+On platforms where @code{off_t} is a 32-bit type, @code{stat} may not correctly
+report the size of files or block devices larger than 2 GB.  The fix is to
 use the @code{AC_SYS_LARGEFILE} macro.
 
-Cygwin's @code{stat} function sometimes sets errno to EACCES when ENOENT would
-be more appropriate.
+Cygwin's @code{stat} function sometimes sets @code{errno} to @code{EACCES} when
+@code{ENOENT} would be more appropriate.
 
 @item strcasecmp
 @itemx strcasestr
@@ -665,7 +691,7 @@ multibyte locales.
 
 @item swprintf
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 On Windows, this function does not take a buffer size as second argument.
 
@@ -676,16 +702,17 @@ the rules for quoting shell arguments containing spaces, quote or other special
 characters are different.
 
 @item tcdrain
-On some systems, @code{tcdrain} on a non-tty fails with errno set to EINVAL
-or, on MacOS X, also EOPNOTSUPP or ENODEV, rather than ENOTTY.
+On some systems, @code{tcdrain} on a non-tty fails with @code{errno} set to
+@code{EINVAL} or, on MacOS X, also @code{EOPNOTSUPP} or @code{ENODEV}, rather
+than @code{ENOTTY}.
 
 @item tcflush
 On some systems, @code{tcflush} of @code{TCIFLUSH} on a non-tty fails with
-errno set to EINVAL rather than ENOTTY.
+errno set to @code{EINVAL} rather than @code{ENOTTY}.
 
 On some systems, @code{tcflush} of @code{TCOFLUSH} on a non-tty fails with
-errno set to EINVAL or, on IRIX, also ENOSYS, or, on MacOS X, also EOPNOTSUPP
-or ENODEV, rather than ENOTTY.
+errno set to @code{EINVAL} or, on IRIX, also @code{ENOSYS}, or, on MacOS X,
+also @code{EOPNOTSUPP} or @code{ENODEV}, rather than @code{ENOTTY}.
 
 @item tempnam
 This function is not appropriate for creating temporary files.  (It has
@@ -699,7 +726,7 @@ security risks.)  Better use @code{mkstemp} instead.
 @itemx towlower
 @itemx towupper
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item ungetc
 On Windows systems (excluding Cygwin), this function does not set @code{errno}
@@ -707,10 +734,10 @@ upon failure.
 
 @item ungetwc
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item unlink
-Removing an open file is unportable: On Unix this allows the programs that
+Removing an open file is non-portable: On Unix this allows the programs that
 have the file already open to continue working with it; the file's storage
 is only freed when the no process has the file open any more.  On Windows,
 the attempt to remove an open file fails.
@@ -759,12 +786,13 @@ available instead, or otherwise an assignment or @code{memcpy} call.
 
 @item vfprintf
 On NetBSD and Windows, this function doesn't support format directives that
-access arguments in an arbitrary order, such as "%2$s".  The fix is to include
-@file{<libintl.h>} from GNU gettext; it redefines this function so that it is
-POSIX compliant.
+access arguments in an arbitrary order, such as @code{"%2$s"}.  The fix is to
+include @file{<libintl.h>} from GNU gettext; it redefines this function so that
+it is POSIX compliant.
 
-On Windows, this function doesn't support the @code{'} flag and the @code{hh},
-@code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+On Windows systems (excluding Cygwin), this function doesn't support
+the @code{'} flag and the @code{hh}, @code{ll}, @code{j}, @code{t},
+@code{z} size specifiers.
 
 @item vfscanf
 On Windows systems (excluding Cygwin), this function does not set @code{errno}
@@ -777,12 +805,13 @@ On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
 @itemx vsnprintf
 @itemx vsprintf
 On NetBSD and Windows, these functions don't support format directives that
-access arguments in an arbitrary order, such as "%2$s".  The fix is to include
-@file{<libintl.h>} from GNU gettext; it redefines these functions so that they
-are POSIX compliant.
+access arguments in an arbitrary order, such as @code{"%2$s"}.  The fix is to
+include @file{<libintl.h>} from GNU gettext; it redefines these functions so
+that they are POSIX compliant.
 
-On Windows, these functions don't support the @code{'} flag and the @code{hh},
-@code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+On Windows systems (excluding Cygwin), this function doesn't support
+the @code{'} flag and the @code{hh}, @code{ll}, @code{j}, @code{t},
+@code{z} size specifiers.
 
 @item vscanf
 @item vsscanf
@@ -794,7 +823,7 @@ On Windows, these functions don't support the @code{hh}, @code{ll}, @code{j},
 
 @item vswprintf
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 On Windows, this function does not take a buffer size as second argument.
 
@@ -831,11 +860,11 @@ works correctly.
 @itemx wcstoull
 @itemx wcstoumax
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @item wcswcs
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 This function is marked as ``legacy'' in POSIX.  Better use @code{wcsstr}
 instead.
@@ -855,6 +884,6 @@ instead.
 @itemx wprintf
 @itemx wscanf
 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
-accomodate all Unicode characters.
+accommodate all Unicode characters.
 
 @end table