@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,
@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
@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.
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}
@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}
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
@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
@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.
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
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
@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;
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,
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 @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
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
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
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}
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
@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
+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}.
@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.
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}
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