X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Ffunctions.texi;h=f89a7f83a0c903ebc9033f2a8a1f63e1cdcfc863;hb=69d25acfd85067031a54285fb933d2e3ccfb0055;hp=9d5e01bd338455ec0495d7ef5bd3116e6bc679d3;hpb=a8db7c04fbdbd590dbdc815938a900f8c5b54c0a;p=gnulib.git

diff --git a/doc/functions.texi b/doc/functions.texi
index 9d5e01bd3..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,
@@ -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
@@ -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.
@@ -143,8 +152,9 @@ 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}
@@ -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}
@@ -237,7 +247,7 @@ If the given buffer is too small for the host name, some implementations
 fail with @code{EINVAL}, instead of returning a truncated host name.
 
 @item getopt
-The default behaviour of the glibc implementation of @code{getopt} allows
+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
@@ -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
@@ -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.
@@ -366,12 +376,15 @@ 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
@@ -449,8 +466,9 @@ 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
@@ -467,17 +485,17 @@ 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 @code{ENOENT} or @code{EIO} instead of
+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 @code{ENXIO} instead of @code{EINVAL}.  Cygwin may set
-errno to @code{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;
@@ -525,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 @code{EBADF}.
+may fail, setting @code{errno} to @code{EBADF}.
 
 @item setcontext
 The effects of this call are system and compiler optimization dependent,
@@ -533,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
@@ -557,8 +575,8 @@ upon failure.
 
 @item shmat
 Attempts to @code{shmat} into a previously malloc-ed region fail on SunOS 4,
-with errno set to @code{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
@@ -581,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
@@ -618,8 +636,9 @@ 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
@@ -632,8 +651,9 @@ 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}
@@ -647,7 +667,7 @@ 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 @code{EACCES} when
+Cygwin's @code{stat} function sometimes sets @code{errno} to @code{EACCES} when
 @code{ENOENT} would be more appropriate.
 
 @item strcasecmp
@@ -671,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.
 
@@ -682,7 +702,7 @@ 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
+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}.
 
@@ -706,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}
@@ -714,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.
@@ -770,8 +790,9 @@ 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}
@@ -788,8 +809,9 @@ 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
@@ -801,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.
 
@@ -838,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.
@@ -862,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