1 @node Function Portability
2 @section Portability of Standard Functions
5 Many standard library functions have portability limitations, although
6 they are specified in the
7 @uref{http://www.opengroup.org/susv3, Posix standard}. In this section,
8 we mention only functions that behave differently than specified; we don't
9 mention functions that are not implemented at all on some platforms, or
10 that are implemented but not declared on some platforms. Many of the
11 portability problems have a solution in @ref{Gnulib}.
15 This function was not correctly implemented in glibc versions before 2.2.5.
18 Some systems don't have a @code{socklen_t} type; in this case this function's
19 third argument type is @samp{int *}.
22 This function may overflow its internal buffer if an invalid year is passed.
25 This function may put more than 26 bytes into the argument buffer if an
26 invalid year is passed.
29 glibc has two different functions @code{basename}: the POSIX version and
32 @code{basename} assumes file names in POSIX syntax; it does not work with file
33 names in Windows syntax.
36 This function is marked as ``legacy'' in POSIX. Better use @code{memcmp}
40 This function is marked as ``legacy'' in POSIX. Better use @code{memcpy}
41 or @code{memmove} instead.
44 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
45 accomodate all Unicode characters.
48 This function is marked as ``legacy'' in POSIX. Better use @code{memset}
52 When applied to a symbolic link, some implementations don't dereference
53 the symlink, i.e. they behave like @code{lchown}.
58 The glibc implementation is or was broken.
61 On Windows, this function returns a file handle in @code{O_TEXT} mode. If you
62 need a file handle in @code{O_BINARY} mode, you need to use the function
65 On platforms where @code{off_t} is a 32-bit type, @code{creat} may not work
66 correctly to create files larger than 2 GB. The fix is to use the
67 @code{AC_SYS_LARGEFILE} macro.
70 This function may overflow its internal buffer if an invalid year is passed.
73 This function may put more than 26 bytes into the argument buffer if an
74 invalid year is passed.
77 @code{dirname} assumes file names in POSIX syntax; it does not work with file
78 names in Windows syntax.
81 If the file name argument is not absolute, the file is searched for. The
82 search algorithm is system specific.
85 The visibility of symbols loaded in dependent shared libraries or present
86 in the main executable is system dependent.
89 This function is marked as ``legacy'' in POSIX. Better use @code{sprintf}
93 On Windows, the socket functions don't set @code{errno}; their error code is
94 available through @code{WSAGetLastError()} instead.
97 On Windows systems (excluding Cygwin), this function does not set @code{errno}
101 This function is marked as ``legacy'' in POSIX. Better use @code{sprintf}
106 On Windows systems (excluding Cygwin), these functions do not set @code{errno}
111 On Windows systems (excluding Cygwin), these functions do not set @code{errno}
116 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
117 accomodate all Unicode characters.
120 This function is broken in some version of Solaris or glibc.
123 On Windows systems (excluding Cygwin), this function does not set @code{errno}
126 On Windows, this function returns a file stream in ``text'' mode by default;
127 this means that it translates @code{'\n'} to CR/LF by default. Use the
128 @code{"b"} flag if you need reliable binary I/O.
131 On some systems, @code{fork} followed by a call of the @code{exec} family
132 (@code{execl}, @code{execlp}, @code{execle}, @code{execv}, @code{execvp},
133 or @code{execve}) is less efficient than @code{vfork} followed by the same
134 call. @code{vfork} is a variant of @code{fork} that has been introduced to
135 optimize the @code{fork}/@code{exec} pattern.
137 On Windows systems (excluding Cygwin), this function is not implemented; use
138 @code{spawnvp} instead.
141 On NetBSD and Windows, this function doesn't support format directives that
142 access arguments in an arbitrary order, such as @code{"%2$s"}. The fix is to
143 include @file{<libintl.h>} from GNU gettext; it redefines this function so that
144 it is POSIX compliant.
146 On Windows, this function doesn't support the @code{'} flag and the @code{hh},
147 @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
151 On Windows systems (excluding Cygwin), these functions do not set @code{errno}
156 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
157 accomodate all Unicode characters.
160 On Windows systems (excluding Cygwin), this function does not set @code{errno}
164 On old systems, @code{free (NULL)} is not allowed.
167 On Windows systems (excluding Cygwin), this function does not set @code{errno}
171 On Windows systems (excluding Cygwin), this function does not set @code{errno}
174 On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
175 @code{t}, @code{z} size specifiers.
178 On Windows systems (excluding Cygwin), this function does not set @code{errno}
182 On platforms where @code{off_t} is a 32-bit type, @code{stat} may not correctly
183 report the size of files or block devices larger than 2 GB. The fix is to
184 use the @code{AC_SYS_LARGEFILE} macro.
186 On Cygwin, @code{fstat} applied to the file descriptors 0 and 1, returns
187 different @code{st_ino} values, even if standard input and standard output
188 are not redirected and refer to the same terminal.
191 This function is marked as ``legacy'' in POSIX. Better use @code{gettimeofday}
192 or @code{clock_gettime} instead, and use @code{ftime} only as a fallback for
193 portability to Windows systems.
196 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
197 accomodate all Unicode characters.
199 @code{fwide} is not guaranteed to be able to change a file stream's mode
200 to a different mode than the current one.
203 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
204 accomodate all Unicode characters.
207 On Windows systems (excluding Cygwin), this function does not set @code{errno}
211 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
212 accomodate all Unicode characters.
215 This function is marked as ``legacy'' in POSIX. Better use @code{sprintf}
219 On Windows, this function is declared in @code{<ws2tcpip.h>} rather than in
224 On Windows systems (excluding Cygwin), these functions do not set @code{errno}
228 On glibc systems, @code{getcwd (NULL, n)} allocates memory for the result.
229 On other systems, this call is not allowed.
232 On Ultrix 4.3, @code{getgroups (0, 0)} always fails. See macro
233 @samp{AC_FUNC_GETGROUPS}.
236 If the given buffer is too small for the host name, some implementations
237 fail with @code{EINVAL}, instead of returning a truncated host name.
240 The default behaviour of the glibc implementation of @code{getopt} allows
241 mixing option and non-option arguments on the command line in any order.
242 Other implementations, such as the one in Cygwin, enforce strict POSIX
243 compliance: they require that the option arguments precede the non-option
244 arguments. This is something to watch out in your program's testsuite.
247 Some systems don't have a @code{socklen_t} type; in this case this function's
248 third argument type is @samp{int *}.
251 Many systems don't fill in all the fields of @code{struct rusage} with
255 This function should never be used, because it can overflow any given buffer.
257 On Windows systems (excluding Cygwin), this function does not set @code{errno}
261 Some systems don't have a @code{socklen_t} type; in this case this function's
262 third argument type is @samp{int *}.
265 Some systems don't have a @code{socklen_t} type; in this case this function's
266 fifth argument type is @samp{int *}.
268 Many socket options are not available on all systems.
270 BeOS has the @code{setsockopt} function, but not the @code{getsockopt}
274 On some systems, @code{gettimeofday} clobbers the buffer in which
275 @code{localtime} returns its result.
279 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
280 accomodate all Unicode characters.
283 The size of the buffer required for this function is not a compile-time
284 constant. Also, the function truncates a result that would be larger than
285 the minimum buffer size. For these reasons, this function is marked as
286 ``legacy'' in POSIX. Better use the @code{getcwd} function instead.
289 Some systems may store additional flags in the @code{gl_flags} field.
292 Some systems define a function of this name that is incompatible to POSIX.
295 This function was not correctly implemented in glibc versions before 2.2.
297 When @code{iconv} encounters an input character that is valid but that can
298 not be converted to the output character set, glibc's and GNU libiconv's
299 @code{iconv} stop the conversion. Some other implementations put an
300 implementation-defined character into the output buffer.
303 The set of supported encodings and conversions is system dependent.
306 This function is marked as ``legacy'' in POSIX. Better use @code{strchr}
310 On some old systems, this function returns a @samp{struct in_addr} rather
311 than a scalar type such as @samp{unsigned int} or @samp{unsigned long}.
314 Most @code{ioctl} requests are platform and hardware specific.
317 On Windows, @code{isatty} also returns true for character devices such as
333 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
334 accomodate all Unicode characters.
337 This function was not correctly implemented in glibc versions before 2.2.5.
340 Some systems define a function of this name that is incompatible to POSIX.
343 The effects of this call are system and compiler optimization dependent,
344 since it restores the contents of register-allocated variables but not
345 the contents of stack-allocated variables.
347 When longjumping out of a signal handler that was being executed on an
348 alternate stack (installed through @code{sigaltstack}), on FreeBSD, NetBSD,
349 OpenBSD, you need to clear the @code{SS_ONSTACK} flag in the @code{stack_t}
350 structure managed by the kernel.
353 POSIX does not specify which file descriptors support seeking and which don't.
354 In practice, regular files and block devices support seeking, and ttys, pipes,
355 and most character devices don't support it.
357 On platforms where @code{off_t} is a 32-bit type, @code{lseek} does not work
358 correctly with files larger than 2 GB. The fix is to use the
359 @code{AC_SYS_LARGEFILE} macro.
362 When the argument ends in a slash, some systems don't dereference the
365 On platforms where @code{off_t} is a 32-bit type, @code{lstat} may not
366 correctly report the size of files or block devices larger than 2 GB. The fix
367 is to use the @code{AC_SYS_LARGEFILE} macro.
373 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
374 accomodate all Unicode characters.
377 When the argument ends in a slash, the function call fails on some systems.
379 On Windows systems (excluding Cygwin), this function is called @code{_mkdir}
380 and takes only one argument. The fix is to define a macro like this:
382 #define mkdir ((int (*)()) _mkdir)
386 On some systems (HP-UX 10.20, SunOS 4.1.4, Solaris 2.5.1), mkstemp has a silly
387 limit that it can create no more than 26 files from a given template. On
388 OSF/1 4.0f, it can create only 32 files per process.
390 On systems other than glibc 2.0.7 or newer, @code{mkstemp} can create a
391 world or group writable or readable file, if you haven't set the process
392 umask to 077. This is a security risk.
395 This function is not appropriate for creating temporary files. (It has
396 security risks.) Therefore it is marked as ``legacy'' in POSIX. Better use
397 @code{mkstemp} instead.
400 Some implementations of @code{mktime} may go into an endless loop.
403 To get anonymous memory, on some systems, you can use the flags
404 @code{MAP_ANONYMOUS | MAP_PRIVATE} and @code{-1} instead of a file descriptor;
405 on others you have to use a read-only file descriptor of @file{/dev/zero}.
407 On HP-UX, passing a non-NULL first argument, as a hint for the address (even
408 without @code{MAP_FIXED}, often causes @code{mmap} to fail. Better pass NULL
411 On HP-UX, @code{MAP_FIXED} basically never works. On other systems, it depends
412 on the circumstances whether memory can be returned at a given address.
415 On AIX, it is not possible to use @code{mprotect} on memory regions allocated
419 On NetBSD, @code{msync} takes only two arguments.
424 In glibc before glibc 2.2.4, @code{nice} returned 0 upon success.
427 Some older versions of glibc had @code{nl_langinfo} but not the @code{CODESET}
430 On Cygwin, which doesn't have locales, @code{nl_langinfo(CODESET)} always
431 returns @code{"US-ASCII"}.
434 On Windows, this function returns a file handle in @code{O_TEXT} mode by
435 default; this means that it translates '\n' to CR/LF by default. Use the
436 @code{O_BINARY} flag if you need reliable binary I/O.
438 On platforms where @code{off_t} is a 32-bit type, @code{open} may not work
439 correctly with files larger than 2 GB. The fix is to use the
440 @code{AC_SYS_LARGEFILE} macro.
443 On MacOS X 10.4.0 and AIX 5.3, this function doesn't work on special files
444 like @file{/dev/null} and ttys like @file{/dev/tty}.
447 On NetBSD and Windows, this function doesn't support format directives that
448 access arguments in an arbitrary order, such as @code{"%2$s"}. The fix is to
449 include @file{<libintl.h>} from GNU gettext; it redefines this function so that
450 it is POSIX compliant.
452 On Windows, this function doesn't support the @code{'} flag and the @code{hh},
453 @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
456 On Linux/glibc systems before the advent of NPTL, signals could only be
457 sent to one particular thread. In POSIX, signals are sent to the entire
458 process and executed by any thread of the process that happens to have the
459 particular signal currently unblocked.
464 On Windows systems (excluding Cygwin), these functions do not set @code{errno}
469 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
470 accomodate all Unicode characters.
473 When @code{readlink} is called on a directory: In the case of NFS mounted
474 directories, Cygwin sets errno to @code{ENOENT} or @code{EIO} instead of
475 @code{EINVAL}. To avoid this problem, check for a directory before calling
478 When @code{readlink} is called on a file that is not a symbolic link:
479 Irix may set errno to @code{ENXIO} instead of @code{EINVAL}. Cygwin may set
480 errno to @code{EACCES} instead of {EINVAL}.
483 This function does not allow to determine the required size of output buffer;
484 PATH_MAX --- if it is defined --- is nothing more than a guess.
487 Some systems don't have a @code{socklen_t} type; in this case this function's
488 sixth argument type is @samp{int *}.
492 Many regular expression implementations have bugs.
495 This function does not work on SunOS 4.1 when the source file name ends in a
499 On Windows systems (excluding Cygwin), this function does not set @code{errno}
503 This function is marked as ``legacy'' in POSIX. Better use @code{strrchr}
507 When @code{rmdir} fails because the specified directory is not empty, the
508 @code{errno} value is system dependent.
511 On Windows systems (excluding Cygwin), this function does not set @code{errno}
514 On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
515 @code{t}, @code{z} size specifiers.
518 When you call @code{select} with a timeout, some implementations modify the
519 timeout parameter so that upon return from the function, it contains the
520 amount of time not slept. Other implementations leave the timeout parameter
523 On Windows systems (excluding Cygwin) and on BeOS, @code{select} can only be
524 called on descriptors created by the @code{socket} function, not on regular
527 On Linux, when some file descriptor refers to a regular file, @code{select}
528 may fail, setting errno to @code{EBADF}.
531 The effects of this call are system and compiler optimization dependent,
532 since it restores the contents of register-allocated variables but not
533 the contents of stack-allocated variables.
536 In some versions of glibc (e.g. 2.3.3), @code{setenv} doesn't fail if the
537 first argument contains a @samp{=} character.
540 POSIX does not specify whether @code{setjmp} saves the signal mask in the
541 @code{jmp_buf}. It does on BSD systems, and on glibc systems when
542 @code{_BSD_SOURCE} is defined; in this case @code{setjmp} behaves like
543 @code{sigsetjmp}, and functions @code{_setjmp} and @code{_longjmp} are
544 available that don't save or restore the signal mask. On System V systems,
545 and on glibc systems by default, @code{setjmp} doesn't save the signal mask.
548 On Cygwin, which doesn't have locales, @code{setlocale(LC_ALL,NULL)} always
552 Many socket options are not available on all systems.
555 On Windows systems (excluding Cygwin), this function does not set @code{errno}
559 Attempts to @code{shmat} into a previously malloc-ed region fail on SunOS 4,
560 with errno set to @code{EINVAL}, even if there is an @code{munmap} call in
563 On Linux, the flag @code{SHM_REMAP} is needed in order to force @code{shmat}
564 to replace existing memory mappings in the specify address range. On other
565 systems, it is not needed.
568 On many systems (not Linux), SHMMAX is so small that it is unusable for
569 reasonable applications, and/or @code{shmget} requires superuser privileges.
572 The symbolic value @code{SIG_IGN} for the @code{SIGCHLD} signal is equivalent
575 void handle_child (int sigchld)
577 while (waitpid (-1, NULL, WNOHANG) > 0)
581 except that @code{SIG_IGN} for @code{SIGCHLD} has the effect that the children
582 execution times are not accounted in the @code{times} function.
583 On some systems (BSD? SystemV? Linux?), you need to use the @code{sigaction}
584 flag @code{SA_NOCLDWAIT} in order to obtain this behaviour.
587 @code{sigaltstack} doesn't work on HP-UX 11/IA-64 and OpenBSD 3.6/Sparc64.
590 On System V systems, when the signal is triggered, the kernel uninstalls the
591 handler (i.e. resets the signal's action to SIG_DFL) before invoking the
592 handler. This opens the door to race conditions: undesired things happen
593 if the signal is triggered twice and the signal handler was not quick enough
594 reinstalling itself as a handler. On BSD systems and glibc systems, on the
595 other hand, when the signal is triggered, the kernel blocks the signal
596 before invoking the handler. This is saner, but POSIX still allows either
597 behaviour. To avoid this problem, use @code{sigaction} instead of
601 Linux implements the meaning of NULL timeout by doing what @code{sigwaitinfo}
602 does; other systems may not do the same.
605 On Linux/glibc systems before the advent of NPTL, signals could only be
606 sent to one particular thread. In POSIX, signals are sent to the entire
607 process and executed by any thread of the process that happens to have the
608 particular signal currently unblocked.
611 According to POSIX, the @code{sleep} function may interfere with the program's
612 use of the @code{SIGALRM} signal. On Linux, it doesn't; on other platforms,
616 On NetBSD and Windows, this function doesn't support format directives that
617 access arguments in an arbitrary order, such as @code{"%2$s"}. The fix is to
618 include @file{<libintl.h>} from GNU gettext; it redefines this function so that
619 it is POSIX compliant.
621 On Windows, this function doesn't support the @code{'} flag and the @code{hh},
622 @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
625 On BeOS, the descriptors returned by the @code{socket} function can not be used
626 in calls to @code{read}, @code{write}, and @code{close}; you have to use
627 @code{recv}, @code{send}, @code{closesocket} in these cases instead.
630 On NetBSD and Windows, this function doesn't support format directives that
631 access arguments in an arbitrary order, such as @code{"%2$s"}. The fix is to
632 include @file{<libintl.h>} from GNU gettext; it redefines this function so that
633 it is POSIX compliant.
635 On Windows, this function doesn't support the @code{'} flag and the @code{hh},
636 @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
639 On Windows systems (excluding Cygwin), this function does not set @code{errno}
642 On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
643 @code{t}, @code{z} size specifiers.
646 On platforms where @code{off_t} is a 32-bit type, @code{stat} may not correctly
647 report the size of files or block devices larger than 2 GB. The fix is to
648 use the @code{AC_SYS_LARGEFILE} macro.
650 Cygwin's @code{stat} function sometimes sets errno to @code{EACCES} when
651 @code{ENOENT} would be more appropriate.
655 As of 2006, no system is known that implements these functions correctly in
659 glibc has an incompatible version of this function. The POSIX compliant code
661 char *s = (strerror_r (err, buf, buflen) == 0 ? buf : NULL);
663 is essentially equivalent to this code using the glibc function:
665 char *s = strerror_r (err, buf, buflen);
669 As of 2006, no system is known that implements this function correctly in
673 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
674 accomodate all Unicode characters.
676 On Windows, this function does not take a buffer size as second argument.
679 On Windows systems (excluding Cygwin), the command processor used by the
680 @code{system} function is @file{cmd.exe}, not @file{/bin/sh}. Accordingly,
681 the rules for quoting shell arguments containing spaces, quote or other special
682 characters are different.
685 On some systems, @code{tcdrain} on a non-tty fails with errno set to
686 @code{EINVAL} or, on MacOS X, also @code{EOPNOTSUPP} or @code{ENODEV}, rather
690 On some systems, @code{tcflush} of @code{TCIFLUSH} on a non-tty fails with
691 errno set to @code{EINVAL} rather than @code{ENOTTY}.
693 On some systems, @code{tcflush} of @code{TCOFLUSH} on a non-tty fails with
694 errno set to @code{EINVAL} or, on IRIX, also @code{ENOSYS}, or, on MacOS X,
695 also @code{EOPNOTSUPP} or @code{ENODEV}, rather than @code{ENOTTY}.
698 This function is not appropriate for creating temporary files. (It has
699 security risks.) Better use @code{mkstemp} instead.
702 This function is not appropriate for creating temporary files. (It has
703 security risks.) Better use @code{mkstemp} instead.
708 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
709 accomodate all Unicode characters.
712 On Windows systems (excluding Cygwin), this function does not set @code{errno}
716 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
717 accomodate all Unicode characters.
720 Removing an open file is unportable: On Unix this allows the programs that
721 have the file already open to continue working with it; the file's storage
722 is only freed when the no process has the file open any more. On Windows,
723 the attempt to remove an open file fails.
726 According to POSIX, the @code{usleep} function may interfere with the program's
727 use of the @code{SIGALRM} signal. On Linux, it doesn't; on other platforms,
731 On some systems, @code{utime (file, NULL)} fails to set the file's timestamp
735 This function is marked as ``legacy'' in POSIX. Better use @code{utime}
739 The second argument of @code{va_arg} must be a type that is invariant under
740 the ``default argument promotions'' (ISO C 99 6.5.2.2 paragraph 6). This
741 means that the following are not valid here:
744 Use @samp{double} instead.
746 Use @samp{int} instead.
747 @item Integer types smaller than @samp{int}.
748 Use @samp{int} or @samp{unsigned int} instead.
751 This is a portability problem because you don't know the width of some
752 abstract types like @code{uid_t}, @code{gid_t}, @code{mode_t}. So, instead of
754 mode = va_arg (ap, mode_t);
758 mode = (sizeof (mode_t) < sizeof (int)
760 : va_arg (ap, mode_t));
764 Some platforms don't provide this macro. You can use __va_copy where
765 available instead, or otherwise an assignment or @code{memcpy} call.
768 On NetBSD and Windows, this function doesn't support format directives that
769 access arguments in an arbitrary order, such as @code{"%2$s"}. The fix is to
770 include @file{<libintl.h>} from GNU gettext; it redefines this function so that
771 it is POSIX compliant.
773 On Windows, this function doesn't support the @code{'} flag and the @code{hh},
774 @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
777 On Windows systems (excluding Cygwin), this function does not set @code{errno}
780 On Windows, this function doesn't support the @code{hh}, @code{ll}, @code{j},
781 @code{t}, @code{z} size specifiers.
786 On NetBSD and Windows, these functions don't support format directives that
787 access arguments in an arbitrary order, such as @code{"%2$s"}. The fix is to
788 include @file{<libintl.h>} from GNU gettext; it redefines these functions so
789 that they are POSIX compliant.
791 On Windows, these functions don't support the @code{'} flag and the @code{hh},
792 @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.
796 On Windows systems (excluding Cygwin), these functions do not set @code{errno}
799 On Windows, these functions don't support the @code{hh}, @code{ll}, @code{j},
800 @code{t}, @code{z} size specifiers.
803 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
804 accomodate all Unicode characters.
806 On Windows, this function does not take a buffer size as second argument.
809 As of 2005, no system is known on which @code{waitid} with flag @code{WNOWAIT}
840 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
841 accomodate all Unicode characters.
844 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
845 accomodate all Unicode characters.
847 This function is marked as ``legacy'' in POSIX. Better use @code{wcsstr}
864 On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
865 accomodate all Unicode characters.