function portability documentation

[Bruno Haible]

Hi,

Inspired by Paul Eggert's new chapter about "Portable C and C++ Programming",
I went out and collected portability notes and pitfall reminders for over
200 among the 1116 POSIX functions. (Attached.)

You will also notice that a section named "Function Portability" and with the
same purpose exists already under section "Library Functions" of the autoconf
manual, but that it is quite outdated (it speaks about HP-UX 9 and Solaris 9).

I propose to combine these two "Function Portability" sections.

Questions:

1) Where in the autoconf manual should this section go?

I think it should go into the new "Portable C and C++ Programming" chapter,
because the "Existing Tests" chapter deals primarily with tests already
present in autoconf - whereas for most of the known portability problems
we can only give some advice, but not an autoconf test that is perfect for
everyone.

2) Who should maintain this section in the future?

Why does the section currently have only 20 entries, when an up-to-date
list of portability problems has more than 200 entries? I think the answer
is that the autoconf maintainers are busy with autoconf, whereas the people
who write or maintain programs and deal with portability problems on a daily
basis gather on the bug-gnulib mailing list. On this background, I would
propose that the autoconf people "outsource" this manual section to the
gnulib project and include it as-is from the gnulib CVS. (The same way as
config.guess, standards.texi and other files come from elsewhere.)

Bruno


*** autoconf.texi.bak   2006-05-01 23:09:41.000000000 +0200
--- autoconf.texi       2006-05-22 02:34:30.000000000 +0200
***************
*** 486,491 ****
--- 486,492 ----
  * Null Pointers::               Properties of null pointers
  * Buffer Overruns::             Subscript errors and the like
  * Floating Point Portability::  Portable floating-point arithmetic
+ * Function Portability::        Portable use of standard functions
  * Exiting Portably::            Exiting and the exit status
  
  Manual Configuration
***************
*** 14170,14175 ****
--- 14171,14177 ----
  * Null Pointers::               Properties of null pointers
  * Buffer Overruns::             Subscript errors and the like
  * Floating Point Portability::  Portable floating-point arithmetic
+ * Function Portability::        Portable use of standard functions
  * Exiting Portably::            Exiting and the exit status
  @end menu
  
***************
*** 14310,14315 ****
--- 14312,15178 ----
  @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
  Scientist Should Know About Floating-Point Arithmetic}.
  
+ @node Function Portability
+ @section Portability of Standard Functions
+ @cindex functions
+ 
+ Many standard library functions have portability limitations, although
+ they are specified in the
+ @uref{http://www.opengroup.org/susv3, Posix standard}.  In this section,
+ we mention only functions that behave differently than specified; we don't
+ mention functions that are not implemented at all on some platforms, or
+ that are implemented but not declared on some platforms.  Many of the
+ portability problems have a solution in @ref{Gnulib}.
+ 
+ @table @code
+ @item a64l
+ This function was not correctly implemented in glibc versions before 2.2.5.
+ 
+ @item accept
+ Some systems don't have a @code{socklen_t} type; in this case this function's
+ third argument type is @samp{int *}.
+ 
+ @item asctime
+ This function may overflow its internal buffer if an invalid year is passed.
+ 
+ @item asctime_r
+ This function may put more than 26 bytes into the argument buffer if an
+ invalid year is passed.
+ 
+ @item basename
+ 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
+ names in Windows syntax.
+ 
+ @item bcmp
+ This function is marked as ``legacy'' in POSIX.  Better use @code{memcmp}
+ instead.
+ 
+ @item bcopy
+ This function is marked as ``legacy'' in POSIX.  Better use @code{memcpy}
+ or @code{memmove} instead.
+ 
+ @item btowc
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item bzero
+ This function is marked as ``legacy'' in POSIX.  Better use @code{memset}
+ instead.
+ 
+ @item chown
+ When applied to a symbolic link, some implementations don't dereference
+ the symlink, i.e. they behave like @code{lchown}.
+ 
+ @item cproj
+ @itemx cprojf
+ @itemx cprojl
+ The glibc implementation is or was broken.
+ 
+ @item creat
+ On Windows, this function returns a file handle in @code{O_TEXT} mode.  If you
+ need a file handle in @code{O_BINARY} mode, you need to use the function
+ @code{open} instead.
+ 
+ On platforms where @code{off_t} is a 32-bit type, @code{creat} may not work
+ correctly to create files larger than 2 GB.  The fix is to use the
+ @code{AC_SYS_LARGEFILE} macro.
+ 
+ @item ctime
+ This function may overflow its internal buffer if an invalid year is passed.
+ 
+ @item ctime_r
+ 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
+ names in Windows syntax.
+ 
+ @item dlopen
+ If the file name argument is not absolute, the file is searched for.  The
+ search algorithm is system specific.
+ 
+ @item dlsym
+ The visibility of symbols loaded in dependent shared libraries or present
+ in the main executable is system dependent.
+ 
+ @item ecvt
+ This function is marked as ``legacy'' in POSIX.  Better use @code{sprintf}
+ instead.
+ 
+ @item errno
+ On Windows, the socket functions don't set @code{errno}; their error code is
+ available through @code{WSAGetLastError()} instead.
+ 
+ @item fclose
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item fcvt
+ This function is marked as ``legacy'' in POSIX.  Better use @code{sprintf}
+ instead.
+ 
+ @item fdopen
+ @itemx fflush
+ On Windows systems (excluding Cygwin), these functions do not set @code{errno}
+ upon failure.
+ 
+ @item fgetc
+ @itemx fgets
+ On Windows systems (excluding Cygwin), these functions do not set @code{errno}
+ upon failure.
+ 
+ @item fgetwc
+ @itemx fgetws
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item fnmatch
+ This function is broken in some version of Solaris or glibc.
+ 
+ @item fopen
+ 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.
+ 
+ @item fork
+ On some systems, @code{fork} followed by a call of the @code{exec} family
+ (@code{execl}, @code{execlp}, @code{execle}, @code{execv}, @code{execvp},
+ or @code{execve}) is less efficient than @code{vfork} followed by the same
+ call.  @code{vfork} is a variant of @code{fork} that has been introduced to
+ optimize the @code{fork}/@code{exec} pattern.
+ 
+ On Windows systems (excluding Cygwin), this function is not implemented; use
+ @code{spawnvp} instead.
+ 
+ @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.
+ 
+ On Windows, 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
+ On Windows systems (excluding Cygwin), these functions do not set @code{errno}
+ upon failure.
+ 
+ @item fputwc
+ @itemx fputws
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item fread
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item free
+ On old systems, @code{free (NULL)} is not allowed.
+ 
+ @item freopen
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item fscanf
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
+ @code{t}, @code{z} size specifiers.
+ 
+ @item fseek
+ 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
+ use the @code{AC_SYS_LARGEFILE} macro.
+ 
+ On Cygwin, @code{fstat} applied to the file descriptors 0 and 1, returns
+ different @code{st_ino} values, even if standard input and standard output
+ are not redirected and refer to the same terminal.
+ 
+ @item ftime
+ This function is marked as ``legacy'' in POSIX.  Better use 
@code{gettimeofday}
+ or @code{clock_gettime} instead, and use @code{ftime} only as a fallback for
+ portability to Windows systems.
+ 
+ @item fwide
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate 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.
+ 
+ @item fwrite
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item fwscanf
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item gcvt
+ This function is marked as ``legacy'' in POSIX.  Better use @code{sprintf}
+ instead.
+ 
+ @item getaddrinfo
+ On Windows, this function is declared in @code{<ws2tcpip.h>} rather than in
+ @code{<netdb.h>}.
+ 
+ @item getc
+ @itemx getchar
+ On Windows systems (excluding Cygwin), these functions do not set @code{errno}
+ upon failure.
+ 
+ @item getcwd
+ On glibc systems, @code{getcwd (NULL, n)} allocates memory for the result.
+ On other systems, this call is not allowed.
+ 
+ @item getgroups
+ On Ultrix 4.3, @code{getgroups (0, 0)} always fails.  See macro
+ @samp{AC_FUNC_GETGROUPS}.
+ 
+ @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.
+ 
+ @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.
+ 
+ @item getpeername
+ Some systems don't have a @code{socklen_t} type; in this case this function's
+ third argument type is @samp{int *}.
+ 
+ @item getrusage
+ Many systems don't fill in all the fields of @code{struct rusage} with
+ meaningful values.
+ 
+ @item gets
+ This function should never be used, because it can overflow any given buffer.
+ 
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item getsockname
+ Some systems don't have a @code{socklen_t} type; in this case this function's
+ third argument type is @samp{int *}.
+ 
+ @item getsockopt
+ Some systems don't have a @code{socklen_t} type; in this case this function's
+ fifth argument type is @samp{int *}.
+ 
+ Many socket options are not available on all systems.
+ 
+ BeOS has the @code{setsockopt} function, but not the @code{getsockopt}
+ function.
+ 
+ @item gettimeofday
+ On some systems, @code{gettimeofday} clobbers the buffer in which
+ @code{localtime} returns its result.
+ 
+ @item getwc
+ @itemx getwchar
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item getwd
+ The size of the buffer required for this function is not a compile-time
+ constant. Also, the function truncates a result that would be larger than
+ the minimum buffer size. For these reasons, this function is marked as
+ ``legacy'' in POSIX.  Better use the @code{getcwd} function instead.
+ 
+ @item glob
+ Some systems may store additional flags in the @code{gl_flags} field.
+ 
+ @item gmtime_r
+ Some systems define a function of this name that is incompatible to POSIX.
+ 
+ @item iconv
+ 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.
+ 
+ @item iconv_open
+ The set of supported encodings and conversions is system dependent.
+ 
+ @item index
+ This function is marked as ``legacy'' in POSIX.  Better use @code{strchr}
+ instead.
+ 
+ @item inet_addr
+ On some old systems, this function returns a @samp{struct in_addr} rather
+ than a scalar type such as @samp{unsigned int} or @samp{unsigned long}.
+ 
+ @item ioctl
+ Most @code{ioctl} requests are platform and hardware specific.
+ 
+ @item isatty
+ On Windows, @code{isatty} also returns true for character devices such as
+ "NUL".
+ 
+ @item iswalnum
+ @itemx iswalpha
+ @itemx iswblank
+ @itemx iswcntrl
+ @itemx iswctype
+ @itemx iswdigit
+ @itemx iswgraph
+ @itemx iswlower
+ @itemx iswprint
+ @itemx iswpunct
+ @itemx iswspace
+ @itemx iswupper
+ @itemx iswxdigit
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item l64a
+ This function was not correctly implemented in glibc versions before 2.2.5.
+ 
+ @item localtime_r
+ Some systems define a function of this name that is incompatible to POSIX.
+ 
+ @item longjmp
+ The effects of this call are system and compiler optimization dependent,
+ since it restores the contents of register-allocated variables but not
+ the contents of stack-allocated variables.
+ 
+ When longjumping out of a signal handler that was being executed on an
+ alternate stack (installed through @code{sigaltstack}), on FreeBSD, NetBSD,
+ OpenBSD, you need to clear the @code{SS_ONSTACK} flag in the @code{stack_t}
+ structure managed by the kernel.
+ 
+ @item lseek
+ POSIX does not specify which file descriptors support seeking and which don't.
+ In practice, regular files and block devices support seeking, and ttys, pipes,
+ and most character devices don't support it.
+ 
+ On platforms where @code{off_t} is a 32-bit type, @code{lseek} does not work
+ correctly with files larger than 2 GB.  The fix is to use the
+ @code{AC_SYS_LARGEFILE} macro.
+ 
+ @item lstat
+ 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.
+ 
+ @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.
+ 
+ @item mkdir
+ When the argument ends in a slash, the function call fails on some systems.
+ 
+ On Windows systems (excluding Cygwin), this function is called @code{_mkdir}
+ and takes only one argument.  The fix is to define a macro like this:
+ @smallexample
+ #define mkdir ((int (*)()) _mkdir)
+ @end smallexample
+ 
+ @item mkstemp
+ On some systems (HP-UX 10.20, SunOS 4.1.4, Solaris 2.5.1), mkstemp has a silly
+ 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'
+ umask to 077.  This is a security risk.
+ 
+ @item mktemp
+ This function is not appropriate for creating temporary files.  (It has
+ security risks.)  Therefore it is marked as ``legacy'' in POSIX.  Better use
+ @code{mkstemp} instead.
+ 
+ @item mktime
+ Some implementations of @code{mktime} may go into an endless loop.
+ 
+ @item mmap
+ To get anonymous memory, on some systems, you can use the flags
+ @code{MAP_ANONYMOUS | MAP_PRIVATE} and @code{-1} instead of a file descriptor;
+ on others you have to use a read-only file descriptor of @file{/dev/zero}.
+ 
+ On HP-UX, passing a non-NULL first argument, as a hint for the address (even
+ without @code{MAP_FIXED}, often causes @code{mmap} to fail.  Better pass NULL
+ in this case.
+ 
+ On HP-UX, @code{MAP_FIXED} basically never works.  On other systems, it 
depends
+ on the circumstances whether memory can be returned at a given address.
+ 
+ @item mprotect
+ On AIX, it is not possible to use @code{mprotect} on memory regions allocated
+ with @code{malloc}.
+ 
+ @item msync
+ On NetBSD, @code{msync} takes only two arguments.
+ 
+ @item nanosleep
+ 
+ @item nice
+ In glibc before glibc 2.2.4, @code{nice} returned 0 upon success.
+ 
+ @item nl_langinfo
+ Some older versions of glibc had @code{nl_langinfo} but not the @code{CODESET}
+ macro.
+ 
+ On Cygwin, which doesn't have locales, @code{nl_langinfo(CODESET)} always
+ returns @code{"US-ASCII"}.
+ 
+ @item open
+ On Windows, this function returns a file handle in @code{O_TEXT} mode by
+ default; this means that it translates '\n' to CR/LF by default.  Use the
+ @code{O_BINARY} flag if you need reliable binary I/O.
+ 
+ On platforms where @code{off_t} is a 32-bit type, @code{open} may not work
+ correctly with files larger than 2 GB.  The fix is to use the
+ @code{AC_SYS_LARGEFILE} macro.
+ 
+ @item poll
+ On MacOS X 10.4.0 and AIX 5.3, this function doesn't work on special files
+ 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.
+ 
+ On Windows, 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.
+ 
+ @item putc
+ @itemx putchar
+ @itemx puts
+ On Windows systems (excluding Cygwin), these functions do not set @code{errno}
+ upon failure.
+ 
+ @item putwc
+ @itemx putwchar
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate 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}.
+ 
+ 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.
+ 
+ @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.
+ 
+ @item recvfrom
+ Some systems don't have a @code{socklen_t} type; in this case this function's
+ sixth argument type is @samp{int *}.
+ 
+ @item regcomp
+ @itemx regexec
+ Many regular expression implementations have bugs.
+ 
+ @item rename
+ This function does not work on SunOS 4.1 when the source file name ends in a
+ slash.
+ 
+ @item rewind
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item rindex
+ This function is marked as ``legacy'' in POSIX.  Better use @code{strrchr}
+ instead.
+ 
+ @item rmdir
+ When @code{rmdir} fails because the specified directory is not empty, the
+ @code{errno} value is system dependent.
+ 
+ @item scanf
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
+ @code{t}, @code{z} size specifiers.
+ 
+ @item select
+ When you call @code{select} with a timeout, some implementations modify the
+ timeout parameter so that upon return from the function, it contains the
+ amount of time not slept.  Other implementations leave the timeout parameter
+ unmodified.
+ 
+ On Windows systems (excluding Cygwin) and on BeOS, @code{select} can only be
+ 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.
+ 
+ @item setcontext
+ The effects of this call are system and compiler optimization dependent,
+ 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
+ first argument contains a @samp{=} character.
+ 
+ @item setjmp
+ POSIX does not specify whether @code{setjmp} saves the signal mask in the
+ @code{jmp_buf}.  It does on BSD systems, and on glibc systems when
+ @code{_BSD_SOURCE} is defined; in this case @code{setjmp} behaves like
+ @code{sigsetjmp}, and functions @code{_setjmp} and @code{_longjmp} are
+ available that don't save or restore the signal mask.  On System V systems,
+ and on glibc systems by default, @code{setjmp} doesn't save the signal mask.
+ 
+ @item setlocale
+ On Cygwin, which doesn't have locales, @code{setlocale(LC_ALL,NULL)} always
+ returns @code{"C"}.
+ 
+ @item setsockopt
+ Many socket options are not available on all systems.
+ 
+ @item setvbuf
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ 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.
+ 
+ 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
+ systems, it is not needed.
+ 
+ @item shmget
+ On many systems (not Linux), SHMMAX is so small that it is unusable for
+ reasonable applications, and/or @code{shmget} requires superuser privileges.
+ 
+ @item sigaction
+ The symbolic value @code{SIG_IGN} for the @code{SIGCHLD} signal is equivalent
+ to a signal handler
+ @smallexample
+ void handle_child (int sigchld)
+ @{
+   while (waitpid (-1, NULL, WNOHANG) > 0)
+     ;
+ @}
+ @end smallexample
+ 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.
+ 
+ @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.  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
+ @code{signal}.
+ 
+ @item sigtimedwait
+ Linux implements the meaning of NULL timeout by doing what @code{sigwaitinfo}
+ 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.
+ 
+ @item sleep
+ According to POSIX, the @code{sleep} function may interfere with the program's
+ use of the @code{SIGALRM} signal.  On Linux, it doesn't; on other platforms,
+ 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.
+ 
+ On Windows, 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
+ in calls to @code{read}, @code{write}, and @code{close}; you have to use
+ @code{recv}, @code{send}, @code{closesocket} in these cases instead.
+ 
+ @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.
+ 
+ On Windows, 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}
+ upon failure.
+ 
+ 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
+ use the @code{AC_SYS_LARGEFILE} macro.
+ 
+ Cygwin's @code{stat} function sometimes sets errno to EACCES when ENOENT would
+ be more appropriate.
+ 
+ @item strcasecmp
+ @itemx strcasestr
+ As of 2006, no system is known that implements these functions correctly in
+ multibyte locales.
+ 
+ @item strerror_r
+ glibc has an incompatible version of this function.  The POSIX compliant code
+ @smallexample
+ char *s = (strerror_r (err, buf, buflen) == 0 ? buf : NULL);
+ @end smallexample
+ is essentially equivalent to this code using the glibc function:
+ @smallexample
+ char *s = strerror_r (err, buf, buflen);
+ @end smallexample
+ 
+ @item strstr
+ As of 2006, no system is known that implements this function correctly in
+ multibyte locales.
+ 
+ @item swprintf
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ On Windows, this function does not take a buffer size as second argument.
+ 
+ @item system
+ On Windows systems (excluding Cygwin), the command processor used by the
+ @code{system} function is @file{cmd.exe}, not @file{/bin/sh}.  Accordingly,
+ 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.
+ 
+ @item tcflush
+ On some systems, @code{tcflush} of @code{TCIFLUSH} on a non-tty fails with
+ errno set to EINVAL rather than 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.
+ 
+ @item tempnam
+ This function is not appropriate for creating temporary files.  (It has
+ security risks.)  Better use @code{mkstemp} instead.
+ 
+ @item tmpnam
+ This function is not appropriate for creating temporary files.  (It has
+ security risks.)  Better use @code{mkstemp} instead.
+ 
+ @item towctrans
+ @itemx towlower
+ @itemx towupper
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item ungetc
+ On Windows systems (excluding Cygwin), this function does not set @code{errno}
+ upon failure.
+ 
+ @item ungetwc
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item unlink
+ Removing an open file is unportable: 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.
+ 
+ @item usleep
+ According to POSIX, the @code{usleep} function may interfere with the 
program's
+ use of the @code{SIGALRM} signal.  On Linux, it doesn't; on other platforms,
+ it may.
+ 
+ @item utime
+ On some systems, @code{utime (file, NULL)} fails to set the file's timestamp
+ to the current time.
+ 
+ @item utimes
+ This function is marked as ``legacy'' in POSIX.  Better use @code{utime}
+ instead.
+ 
+ @item va_arg
+ The second argument of @code{va_arg} must be a type that is invariant under
+ the ``default argument promotions'' (ISO C 99 6.5.2.2 paragraph 6).  This
+ means that the following are not valid here:
+ @table @asis
+ @item @samp{float}
+ Use @samp{double} instead.
+ @item @samp{bool}
+ Use @samp{int} instead.
+ @item Integer types smaller than @samp{int}.
+ Use @samp{int} or @samp{unsigned int} instead.
+ @end table
+ 
+ This is a portability problem because you don't know the width of some
+ abstract types like @code{uid_t}, @code{gid_t}, @code{mode_t}.  So, instead of
+ @smallexample
+ mode = va_arg (ap, mode_t);
+ @end smallexample
+ you have to write
+ @smallexample
+ mode = (sizeof (mode_t) < sizeof (int)
+         ? va_arg (ap, int)
+         : va_arg (ap, mode_t));
+ @end smallexample
+ 
+ @item va_copy
+ Some platforms don't provide this macro.  You can use __va_copy where
+ 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.
+ 
+ On Windows, 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}
+ upon failure.
+ 
+ On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
+ @code{t}, @code{z} size specifiers.
+ 
+ @item vprintf
+ @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.
+ 
+ On Windows, these functions don't support the @code{'} flag and the @code{hh},
+ @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
+ 
+ @item vscanf
+ @item vsscanf
+ On Windows systems (excluding Cygwin), these functions do not set @code{errno}
+ upon failure.
+ 
+ On Windows, these functions don't support the @code{hh}, @code{ll}, @code{j},
+ @code{t}, @code{z} size specifiers.
+ 
+ @item vswprintf
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ On Windows, this function does not take a buffer size as second argument.
+ 
+ @item waitid
+ As of 2005, no system is known on which @code{waitid} with flag @code{WNOWAIT}
+ works correctly.
+ 
+ @item wcrtomb
+ @itemx wcscat
+ @itemx wcschr
+ @itemx wcscmp
+ @itemx wcscoll
+ @itemx wcscpy
+ @itemx wcscspn
+ @itemx wcsftime
+ @itemx wcslen
+ @itemx wcsncat
+ @itemx wcsncmp
+ @itemx wcsncpy
+ @itemx wcspbrk
+ @itemx wcsrchr
+ @itemx wcsrtombs
+ @itemx wcsspn
+ @itemx wcsstr
+ @itemx wcstod
+ @itemx wcstof
+ @itemx wcstoimax
+ @itemx wcstok
+ @itemx wcstol
+ @itemx wcstold
+ @itemx wcstoll
+ @itemx wcstombs
+ @itemx wcstoul
+ @itemx wcstoull
+ @itemx wcstoumax
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @item wcswcs
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ This function is marked as ``legacy'' in POSIX.  Better use @code{wcsstr}
+ instead.
+ 
+ @item wcswidth
+ @itemx wcsxfrm
+ @itemx wctob
+ @itemx wctomb
+ @itemx wctrans
+ @itemx wctype
+ @itemx wcwidth
+ @itemx wmemchr
+ @itemx wmemcmp
+ @itemx wmemcpy
+ @itemx wmemmove
+ @itemx wmemset
+ @itemx wprintf
+ @itemx wscanf
+ On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
+ accomodate all Unicode characters.
+ 
+ @end table
+ 
  @node Exiting Portably
  @section Exiting Portably
  @cindex exiting portably