@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,
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
@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}
@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
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
@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.
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
@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
@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}
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
@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}
@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}
@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
@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
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.
@item isatty
On Windows, @code{isatty} also returns true for character devices such as
-"NUL".
+@file{NUL}.
@item iswalnum
@itemx iswalpha
@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.
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.
@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
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
@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
@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
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,
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
@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
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
@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
@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
@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}
@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
@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.
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
@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}
@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.
@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}
@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
@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.
@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.
@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
projects / gnulib.git / blobdiff