Add copyright notices to long-enough files that lack them, since

[gnulib.git] / doc / functions.texi

@node Function Portability
@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,
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 work 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
accommodate 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 work 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
accommodate 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 @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
(@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 @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.

@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
accommodate 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 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
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
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
accommodate 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
accommodate 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 @code{EINVAL}, instead of returning a truncated host name.

@item getopt
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
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
accommodate 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 into 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
@file{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
accommodate 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
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
accommodate 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
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
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 @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.

@item pthread_create
On Linux/glibc systems before the advent of NPTL, signals could only be
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
@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
accommodate all Unicode characters.

@item readlink
When @code{readlink} is called on a directory: In the case of NFS mounted
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 @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.

@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 @code{errno} to @code{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 @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
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 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.  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
behavior.  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
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
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 @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.

@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 @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.

@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 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 @code{errno} to @code{EACCES} when
@code{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
accommodate 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 @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 @code{EINVAL} rather than @code{ENOTTY}.

On some systems, @code{tcflush} of @code{TCOFLUSH} on a non-tty fails with
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
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
accommodate 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
accommodate all Unicode characters.

@item unlink
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.

@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 @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.

@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 @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.

@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
accommodate 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
accommodate all Unicode characters.

@item wcswcs
On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
accommodate 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
accommodate all Unicode characters.

@end table