diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index 5b1713cdd..4af7da050 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -111,13 +111,6 @@ is set appropriately. .TP .B ENOSYS The system call is not supported on this kernel. -.SH "CONFORMING TO" -These calls existed only in Linux 2.5.36 through to 2.5.54. -These calls are specific to Linux on Intel processors, and should not be -used in programs intended to be portable. -Indeed, the system call numbers -are marked for reuse, so programs using these may do something random -on a future kernel. .SH FILES .I /proc/sys/vm/nr_hugepages Number of configured hugetlb pages. @@ -126,6 +119,13 @@ This can be read and written. .I /proc/meminfo Gives info on the number of configured hugetlb pages and on their size in the three variables HugePages_Total, HugePages_Free, Hugepagesize. +.SH "CONFORMING TO" +These calls existed only in Linux 2.5.36 through to 2.5.54. +These calls are specific to Linux on Intel processors, and should not be +used in programs intended to be portable. +Indeed, the system call numbers +are marked for reuse, so programs using these may do something random +on a future kernel. .SH NOTES The system calls are gone. Now the hugetlbfs filesystem can be used instead. diff --git a/man2/fdatasync.2 b/man2/fdatasync.2 index 05837531d..4de7fac83 100644 --- a/man2/fdatasync.2 +++ b/man2/fdatasync.2 @@ -74,6 +74,8 @@ An error occurred during synchronization. .BR EROFS ", " EINVAL .I fd is bound to a special file which does not support synchronization. +.SH "CONFORMING TO" +POSIX.1-2001. .SH AVAILABILITY On POSIX systems on which .BR fdatasync () @@ -85,8 +87,6 @@ i defined in to a value greater than 0. .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. .\" -1: unavailable, 0: ask using sysconf(). .\" glibc defines them to 1. -.SH "CONFORMING TO" -POSIX.1-2001. .SH BUGS .\" FIXME The following is no longer true Currently (Linux 2.2) diff --git a/man2/fork.2 b/man2/fork.2 index d437798f2..4dcb53006 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -177,11 +177,6 @@ capability. failed to allocate the necessary kernel structures because memory is tight. .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. -.SH EXAMPLE -See -.BR pipe (2) -and -.BR wait (2). .SH NOTES .PP Under Linux, @@ -189,6 +184,11 @@ Under Linux, is implemented using copy-on-write pages, so the only penalty that it incurs is the time and memory required to duplicate the parent's page tables, and to create a unique task structure for the child. +.SH EXAMPLE +See +.BR pipe (2) +and +.BR wait (2). .SH "SEE ALSO" .BR clone (2), .BR execve (2), diff --git a/man2/gethostid.2 b/man2/gethostid.2 index 89c68d6b3..43f6f8d2d 100644 --- a/man2/gethostid.2 +++ b/man2/gethostid.2 @@ -56,6 +56,8 @@ argument is stored in the file .BR gethostid () returns the 32-bit identifier for the current host as set by .BR sethostid (2). +.SH FILES +.I /etc/hostid .SH "CONFORMING TO" 4.2BSD; these functions were dropped in 4.4BSD. SVr4 includes @@ -66,8 +68,6 @@ POSIX.1-2001 specifies .BR gethostid () but not .BR sethostid (). -.SH FILES -.I /etc/hostid .SH "SEE ALSO" .BR hostid (1), .BR gethostbyname (3) diff --git a/man2/intro.2 b/man2/intro.2 index bbbcd4591..d8a8cd543 100644 --- a/man2/intro.2 +++ b/man2/intro.2 @@ -83,50 +83,8 @@ These macros create a function called \fIname\fP with the arguments you specify. Once you include the _syscall() in your source file, you call the system call by \fIname\fP. -.SH EXAMPLE -.sp -.nf -#include -#include -#include /* for _syscallX macros/related stuff */ -#include /* for struct sysinfo */ - -_syscall1(int, sysinfo, struct sysinfo *, info); - -/* Note: if you copy directly from the nroff source, remember to -REMOVE the extra backslashes in the printf statement. */ - -int -main(void) -{ - struct sysinfo s_info; - int error; - - error = sysinfo(&s_info); - printf("code error = %d\\n", error); - printf("Uptime = %lds\\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\\n" - "RAM: total %lu / free %lu / shared %lu\\n" - "Memory in buffers = %lu\\nSwap: total %lu / free %lu\\n" - "Number of processes = %d\\n", - s_info.uptime, s_info.loads[0], - s_info.loads[1], s_info.loads[2], - s_info.totalram, s_info.freeram, - s_info.sharedram, s_info.bufferram, - s_info.totalswap, s_info.freeswap, - s_info.procs); - exit(EXIT_SUCCESS); -} -.fi -.SS "Sample Output" -.nf -code error = 0 -uptime = 502034s -Load: 1 min 13376 / 5 min 5504 / 15 min 1152 -RAM: total 15343616 / free 827392 / shared 8237056 -Memory in buffers = 5066752 -Swap: total 27881472 / free 24698880 -Number of processes = 40 -.fi +.SH FILES +.I /usr/include/linux/unistd.h .SH "CONFORMING TO" Certain codes are used to indicate Unix variants and standards to which calls in the section conform. @@ -172,8 +130,50 @@ Some architectures, notably ia64, do not provide the _syscall macros. On these architectures, .BR syscall (2) must be used. -.SH FILES -.I /usr/include/linux/unistd.h +.SH EXAMPLE +.sp +.nf +#include +#include +#include /* for _syscallX macros/related stuff */ +#include /* for struct sysinfo */ + +_syscall1(int, sysinfo, struct sysinfo *, info); + +/* Note: if you copy directly from the nroff source, remember to +REMOVE the extra backslashes in the printf statement. */ + +int +main(void) +{ + struct sysinfo s_info; + int error; + + error = sysinfo(&s_info); + printf("code error = %d\\n", error); + printf("Uptime = %lds\\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\\n" + "RAM: total %lu / free %lu / shared %lu\\n" + "Memory in buffers = %lu\\nSwap: total %lu / free %lu\\n" + "Number of processes = %d\\n", + s_info.uptime, s_info.loads[0], + s_info.loads[1], s_info.loads[2], + s_info.totalram, s_info.freeram, + s_info.sharedram, s_info.bufferram, + s_info.totalswap, s_info.freeswap, + s_info.procs); + exit(EXIT_SUCCESS); +} +.fi +.SS "Sample Output" +.nf +code error = 0 +uptime = 502034s +Load: 1 min 13376 / 5 min 5504 / 15 min 1152 +RAM: total 15343616 / free 827392 / shared 8237056 +Memory in buffers = 5066752 +Swap: total 27881472 / free 24698880 +Number of processes = 40 +.fi .SH "SEE ALSO" .BR syscall (2), .BR errno (3), diff --git a/man2/listxattr.2 b/man2/listxattr.2 index 14ece2108..d73eea00e 100644 --- a/man2/listxattr.2 +++ b/man2/listxattr.2 @@ -91,7 +91,7 @@ An empty buffer of zero can be passed into these calls to return the current size of the list of extended attribute names, which can be used to estimate the size of a buffer which is sufficiently large to hold the list of names. -.SH EXAMPLE +.SS Example The .I list of names is returned as an unordered array of null-terminated character diff --git a/man2/mmap.2 b/man2/mmap.2 index 8f6a9ff2d..ebbcd3052 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -420,6 +420,10 @@ Attempted write into a region mapped as read-only. Attempted access to a portion of the buffer that does not correspond to the file (for example, beyond the end of the file, including the case where another process has truncated the file). +.SH "CONFORMING TO" +SVr4, 4.4BSD, POSIX.1-2001. +.\" SVr4 documents additional error codes ENXIO and ENODEV. +.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. .SH AVAILABILITY On POSIX systems on which .BR mmap (), @@ -433,10 +437,6 @@ is defined in to a value greater than 0. (See also .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. .\" -1: unavailable, 0: ask using sysconf(). .\" glibc defines it to 1. -.SH "CONFORMING TO" -SVr4, 4.4BSD, POSIX.1-2001. -.\" SVr4 documents additional error codes ENXIO and ENODEV. -.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. .SH NOTES It is architecture dependent whether .B PROT_READ diff --git a/man2/mprotect.2 b/man2/mprotect.2 index 232a2aaca..69cf11589 100644 --- a/man2/mprotect.2 +++ b/man2/mprotect.2 @@ -99,6 +99,27 @@ Or: addresses in the range .IR addr + len ] are invalid for the address space of the process, or specify one or more pages that are not mapped. +.SH "CONFORMING TO" +SVr4, POSIX.1-2001. +.\" SVr4 defines an additional error +.\" code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's. +POSIX says that +.BR mprotect () +can be used only on regions of memory obtained from +.BR mmap (2). +.SH NOTES +On Linux it is always legal to call +.BR mprotect () +on any address in a process' address space (except for the +kernel vsyscall area). +In particular it can be used +to change existing code mappings to be writable. + +Whether +.B PROT_EXEC +has any effect different from +.B PROT_READ +is architecture and kernel version dependent. .SH EXAMPLE .nf #include @@ -143,26 +164,5 @@ main(void) exit(EXIT_SUCCESS); } .fi -.SH "CONFORMING TO" -SVr4, POSIX.1-2001. -.\" SVr4 defines an additional error -.\" code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's. -POSIX says that -.BR mprotect () -can be used only on regions of memory obtained from -.BR mmap (2). -.SH NOTES -On Linux it is always legal to call -.BR mprotect () -on any address in a process' address space (except for the -kernel vsyscall area). -In particular it can be used -to change existing code mappings to be writable. - -Whether -.B PROT_EXEC -has any effect different from -.B PROT_READ -is architecture and kernel version dependent. .SH "SEE ALSO" .BR mmap (2) diff --git a/man2/msync.2 b/man2/msync.2 index beaa3b1d4..3014c94ba 100644 --- a/man2/msync.2 +++ b/man2/msync.2 @@ -88,6 +88,12 @@ MS_SYNC and MS_ASYNC are set in .TP .B ENOMEM The indicated memory (or part of it) was not mapped. +.SH "CONFORMING TO" +POSIX.1-2001. + +This call was introduced in Linux 1.3.21, and then used EFAULT instead of +ENOMEM. +In Linux 2.4.19 this was changed to the POSIX value ENOMEM. .SH AVAILABILITY On POSIX systems on which .BR msync () @@ -101,12 +107,6 @@ are defined in to a value greater than 0. .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. .\" -1: unavailable, 0: ask using sysconf(). .\" glibc defines them to 1. -.SH "CONFORMING TO" -POSIX.1-2001. - -This call was introduced in Linux 1.3.21, and then used EFAULT instead of -ENOMEM. -In Linux 2.4.19 this was changed to the POSIX value ENOMEM. .SH "SEE ALSO" .BR mmap (2) .br diff --git a/man2/ptrace.2 b/man2/ptrace.2 index d6f64ee40..f186ad75b 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -322,6 +322,55 @@ Although perhaps not intended, under Linux a traced child can be detached in this way regardless of which method was used to initiate tracing. (\fIaddr\fP is ignored.) +.SH "RETURN VALUE" +On success, PTRACE_PEEK* requests return the requested data, +while other requests return zero. +On error, all requests return \-1, and +.I errno +is set appropriately. +Since the value returned by a successful PTRACE_PEEK* +request may be \-1, the caller must check +.I errno +after such requests to determine whether or not an error occurred. +.SH ERRORS +.TP +.B EBUSY +(i386 only) There was an error with allocating or freeing a debug +register. +.TP +.B EFAULT +There was an attempt to read from or write to an invalid area in +the parent's or child's memory, +probably because the area wasn't mapped or accessible. +Unfortunately, under Linux, different variations of this fault +will return EIO or EFAULT more or less arbitrarily. +.TP +.B EINVAL +An attempt was made to set an invalid option. +.TP +.B EIO +\fIrequest\fP is invalid, or an attempt was made to read from or +write to an invalid area in the parent's or child's memory, +or there was a word-alignment violation, +or an invalid signal was specified during a restart request. +.TP +.B EPERM +The specified process cannot be traced. +This could be because the +parent has insufficient privileges (the required capability is +.BR CAP_SYS_PTRACE ); +non-root processes cannot trace processes that they +cannot send signals to or those running +set-user-ID/set-group-ID programs, for obvious reasons. +Alternatively, the process may already be being traced, or be +.BR init +(PID 1). +.TP +.B ESRCH +The specified process does not exist, or is not currently being traced +by the caller, or is not stopped (for requests that require that). +.SH "CONFORMING TO" +SVr4, 4.3BSD .SH NOTES Although arguments to .BR ptrace () @@ -376,55 +425,6 @@ The proc-based debugging interface present in Solaris 2 implements a superset of .BR ptrace () functionality in a more powerful and uniform way. -.SH "RETURN VALUE" -On success, PTRACE_PEEK* requests return the requested data, -while other requests return zero. -On error, all requests return \-1, and -.I errno -is set appropriately. -Since the value returned by a successful PTRACE_PEEK* -request may be \-1, the caller must check -.I errno -after such requests to determine whether or not an error occurred. -.SH ERRORS -.TP -.B EBUSY -(i386 only) There was an error with allocating or freeing a debug -register. -.TP -.B EFAULT -There was an attempt to read from or write to an invalid area in -the parent's or child's memory, -probably because the area wasn't mapped or accessible. -Unfortunately, under Linux, different variations of this fault -will return EIO or EFAULT more or less arbitrarily. -.TP -.B EINVAL -An attempt was made to set an invalid option. -.TP -.B EIO -\fIrequest\fP is invalid, or an attempt was made to read from or -write to an invalid area in the parent's or child's memory, -or there was a word-alignment violation, -or an invalid signal was specified during a restart request. -.TP -.B EPERM -The specified process cannot be traced. -This could be because the -parent has insufficient privileges (the required capability is -.BR CAP_SYS_PTRACE ); -non-root processes cannot trace processes that they -cannot send signals to or those running -set-user-ID/set-group-ID programs, for obvious reasons. -Alternatively, the process may already be being traced, or be -.BR init -(PID 1). -.TP -.B ESRCH -The specified process does not exist, or is not currently being traced -by the caller, or is not stopped (for requests that require that). -.SH "CONFORMING TO" -SVr4, 4.3BSD .SH BUGS On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a different value than the one for 2.4. diff --git a/man2/select.2 b/man2/select.2 index 6622b99da..02b36a118 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -308,42 +308,6 @@ is invalid. .TP .B ENOMEM unable to allocate memory for internal tables. -.SH EXAMPLE -.nf -#include -#include -#include -#include - -int -main(void) -{ - fd_set rfds; - struct timeval tv; - int retval; - - /* Watch stdin (fd 0) to see when it has input. */ - FD_ZERO(&rfds); - FD_SET(0, &rfds); - - /* Wait up to five seconds. */ - tv.tv_sec = 5; - tv.tv_usec = 0; - - retval = select(1, &rfds, NULL, NULL, &tv); - /* Don't rely on the value of tv now! */ - - if (retval == \-1) - perror("select()"); - else if (retval) - printf("Data is available now.\\n"); - /* FD_ISSET(0, &rfds) will be true. */ - else - printf("No data within five seconds.\\n"); - - exit(EXIT_SUCCESS); -} -.fi .SH VERSIONS .BR pselect () was added to Linux in kernel 2.6.16. @@ -485,6 +449,42 @@ Thus it may be safer to use O_NONBLOCK on sockets that should not block. .\" .\" FIXME select() (and pselect()?) also modify the timeout .\" on an EINTR error return; POSIX.1-2001 doesn't permit this. +.SH EXAMPLE +.nf +#include +#include +#include +#include + +int +main(void) +{ + fd_set rfds; + struct timeval tv; + int retval; + + /* Watch stdin (fd 0) to see when it has input. */ + FD_ZERO(&rfds); + FD_SET(0, &rfds); + + /* Wait up to five seconds. */ + tv.tv_sec = 5; + tv.tv_usec = 0; + + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don't rely on the value of tv now! */ + + if (retval == \-1) + perror("select()"); + else if (retval) + printf("Data is available now.\\n"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\\n"); + + exit(EXIT_SUCCESS); +} +.fi .SH "SEE ALSO" For a tutorial with discussion and examples, see .BR select_tut (2). diff --git a/man2/select_tut.2 b/man2/select_tut.2 index d8c5585a4..bfc6ed034 100644 --- a/man2/select_tut.2 +++ b/man2/select_tut.2 @@ -497,6 +497,55 @@ follows: .fi .PP This is only guaranteed to work on Unix systems, however. +.SH RETURN VALUE +On success, +.BR select () +returns the total number of file descriptors +still present in the file descriptor sets. + +If +.BR select () +timed out, then +the return value will be zero. +The file descriptors set should be all +empty (but may not be on some systems). + +A return value of \-1 indicates an error, with \fIerrno\fP being +set appropriately. +In the case of an error, the returned sets and +the timeout struct contents are undefined and should not be used. +.BR pselect () +however never modifies \fIntimeout\fP. +.SH NOTES +Generally speaking, all operating systems that support sockets, also +support +.BR select (). +Many types of programs become +extremely complicated without the use of +.BR select (). +.BR select () +can be used to solve +many problems in a portable and efficient way that naive programmers try +to solve in a more complicated manner using +threads, forking, IPCs, signals, memory sharing, and so on. +.PP +The +.BR poll (2) +system call has the same functionality as +.BR select (), +and is somewhat more efficient when monitoring sparse +file descriptor sets. +It is nowadays widely available, +but historically was less portable than +.BR select (). +.PP +The Linux-specific +.BR epoll (7) +API provides an interface that is more efficient than +.BR select (2) +and +.BR poll (2) +when monitoring large numbers of file descriptors. .SH EXAMPLE Here is an example that better demonstrates the true utility of .BR select (). @@ -788,55 +837,6 @@ time, although it could easily be extended to do this with a linked list of buffers \(em one for each connection. At the moment, new connections cause the current connection to be dropped. -.SH RETURN VALUE -On success, -.BR select () -returns the total number of file descriptors -still present in the file descriptor sets. - -If -.BR select () -timed out, then -the return value will be zero. -The file descriptors set should be all -empty (but may not be on some systems). - -A return value of \-1 indicates an error, with \fIerrno\fP being -set appropriately. -In the case of an error, the returned sets and -the timeout struct contents are undefined and should not be used. -.BR pselect () -however never modifies \fIntimeout\fP. -.SH NOTES -Generally speaking, all operating systems that support sockets, also -support -.BR select (). -Many types of programs become -extremely complicated without the use of -.BR select (). -.BR select () -can be used to solve -many problems in a portable and efficient way that naive programmers try -to solve in a more complicated manner using -threads, forking, IPCs, signals, memory sharing, and so on. -.PP -The -.BR poll (2) -system call has the same functionality as -.BR select (), -and is somewhat more efficient when monitoring sparse -file descriptor sets. -It is nowadays widely available, -but historically was less portable than -.BR select (). -.PP -The Linux-specific -.BR epoll (7) -API provides an interface that is more efficient than -.BR select (2) -and -.BR poll (2) -when monitoring large numbers of file descriptors. .SH SEE ALSO .BR accept (2), .BR connect (2), diff --git a/man2/sendfile.2 b/man2/sendfile.2 index 7e037ac66..01ee2ccb6 100644 --- a/man2/sendfile.2 +++ b/man2/sendfile.2 @@ -95,22 +95,6 @@ Applications may wish to fall back to in the case where .BR sendfile () fails with EINVAL or ENOSYS. -.SH NOTES -If you plan to use -.BR sendfile () -for sending files to a TCP socket, but need -to send some header data in front of the file contents, you will find -it useful to employ the -.B TCP_CORK -option, described in -.BR tcp (7), -to minimize the number of packets and to tune performance. - -In Linux 2.4 and earlier, -.I out_fd -could refer to a regular file, and -.BR sendfile () -changed the current offset of that file. .SH "RETURN VALUE" If the transfer was successful, the number of bytes written to .I out_fd @@ -156,6 +140,22 @@ Other Unix systems implement .BR sendfile () with different semantics and prototypes. It should not be used in portable programs. +.SH NOTES +If you plan to use +.BR sendfile () +for sending files to a TCP socket, but need +to send some header data in front of the file contents, you will find +it useful to employ the +.B TCP_CORK +option, described in +.BR tcp (7), +to minimize the number of packets and to tune performance. + +In Linux 2.4 and earlier, +.I out_fd +could refer to a regular file, and +.BR sendfile () +changed the current offset of that file. .SH "SEE ALSO" .BR open (2), .BR mmap (2), diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index 882b2f16d..41456e41a 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -130,23 +130,6 @@ The specified size of the new alternate signal stack An attempt was made to change the alternate signal stack while it was active (i.e., the process was already executing on the current alternate signal stack). -.SH EXAMPLE -The following code segment demonstrates the use of -.BR sigaltstack (): - -.RS -.nf -stack_t ss; - -ss.ss_sp = malloc(SIGSTKSZ); -if (ss.ss_sp == NULL) - /* Handle error */; -ss.ss_size = SIGSTKSZ; -ss.ss_flags = 0; -if (sigaltstack(&ss, NULL) == \-1) - /* Handle error */; -.fi -.RE .SH "CONFORMING TO" SUSv2, SVr4, POSIX.1-2001. .SH NOTES @@ -203,6 +186,23 @@ system call. It used a slightly different struct, and had the major disadvantage that the caller had to know the direction of stack growth. +.SH EXAMPLE +The following code segment demonstrates the use of +.BR sigaltstack (): + +.RS +.nf +stack_t ss; + +ss.ss_sp = malloc(SIGSTKSZ); +if (ss.ss_sp == NULL) + /* Handle error */; +ss.ss_size = SIGSTKSZ; +ss.ss_flags = 0; +if (sigaltstack(&ss, NULL) == \-1) + /* Handle error */; +.fi +.RE .SH "SEE ALSO" .BR execve (2), .BR setrlimit (2), diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 index 8464c392e..fb73254b8 100644 --- a/man2/sigreturn.2 +++ b/man2/sigreturn.2 @@ -43,6 +43,10 @@ interrupted by the signal. .SH "RETURN VALUE" .BR sigreturn () never returns. +.SH FILES +/usr/src/linux/arch/i386/kernel/signal.c +.br +/usr/src/linux/arch/alpha/kernel/entry.S .SH "CONFORMING TO" .BR sigreturn () is specific to Linux and should not be used in programs intended to be @@ -57,10 +61,6 @@ be called directly. Better yet, the specific use of the .I __unused argument varies depending on the architecture. -.SH FILES -/usr/src/linux/arch/i386/kernel/signal.c -.br -/usr/src/linux/arch/alpha/kernel/entry.S .SH "SEE ALSO" .BR kill (2), .BR signal (2), diff --git a/man2/stat.2 b/man2/stat.2 index edae16386..7ba2d2120 100644 --- a/man2/stat.2 +++ b/man2/stat.2 @@ -249,29 +249,6 @@ The `sticky' bit (S_ISVTX) on a directory means that a file in that directory can be renamed or deleted only by the owner of the file, by the owner of the directory, and by a privileged process. -.SH NOTES -.SS Linux Notes -Since kernel 2.5.48, the -.I stat -structure supports nanosecond resolution for the three -file timestamp fields. -Glibc exposes the nanosecond component of each field using names either -of the form -.IR st_atim.tv_nsec , -if the _BSD_SOURCE or _SVID_SOURCE feature test macro is defined, -or of the form -.IR st_atimensec , -if neither of these macros is defined. -On file systems that do not support sub-second timestamps, -these nanosecond fields are returned with the value 0. - -For most files under the -.I /proc -directory, -.BR stat () -does not return the file size in the -.I st_size -field; instead the field is returned with the value 0. .SH "RETURN VALUE" On success, zero is returned. On error, \-1 is returned, and @@ -377,6 +354,29 @@ e000 S_IFWHT w% 160000 BSD whiteout (not used for inode) .TE A sticky command appeared in Version 32V AT&T UNIX. +.SH NOTES +.SS Linux Notes +Since kernel 2.5.48, the +.I stat +structure supports nanosecond resolution for the three +file timestamp fields. +Glibc exposes the nanosecond component of each field using names either +of the form +.IR st_atim.tv_nsec , +if the _BSD_SOURCE or _SVID_SOURCE feature test macro is defined, +or of the form +.IR st_atimensec , +if neither of these macros is defined. +On file systems that do not support sub-second timestamps, +these nanosecond fields are returned with the value 0. + +For most files under the +.I /proc +directory, +.BR stat () +does not return the file size in the +.I st_size +field; instead the field is returned with the value 0. .SH "SEE ALSO" .BR access (2), .BR chmod (2), diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index eb78726aa..a4a25baf2 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -78,7 +78,7 @@ after performing any write. Specifying .I flags as 0 is permitted, as a no-op. -.SH NOTES +.SS Some details None of these operations write out the file's metadata. Therefore, unless the application is strictly performing overwrites of already-instantiated disk blocks, diff --git a/man2/sysctl.2 b/man2/sysctl.2 index 0b4d4a04f..51f7ada21 100644 --- a/man2/sysctl.2 +++ b/man2/sysctl.2 @@ -70,39 +70,6 @@ a directory tree under .IR /proc/sys , and if the requested item is found calls some appropriate routine to read or modify the value. -.SH EXAMPLE -.nf -#include -#include -#include - -_syscall1(int, _sysctl, struct __sysctl_args *, args); -int sysctl(int *name, int nlen, void *oldval, size_t *oldlenp, - void *newval, size_t newlen) -{ - struct __sysctl_args args = { name, nlen, oldval, oldlenp, - newval, newlen }; - return _sysctl(&args); -} - -#define SIZE(x) sizeof(x)/sizeof(x[0]) -#define OSNAMESZ 100 - -char osname[OSNAMESZ]; -int osnamelth; -int name[] = { CTL_KERN, KERN_OSTYPE }; - -int -main(void) -{ - osnamelth = sizeof(osname); - if (sysctl(name, SIZE(name), osname, &osnamelth, 0, 0)) - perror("sysctl"); - else - printf("This machine is running %*s\en", osnamelth, osname); - exit(EXIT_SUCCESS); -} -.fi .SH "RETURN VALUE" Upon successful completion, .BR _sysctl () @@ -154,5 +121,38 @@ Not all available objects are properly documented. .PP It is not yet possible to change operating system by writing to .IR /proc/sys/kernel/ostype . +.SH EXAMPLE +.nf +#include +#include +#include + +_syscall1(int, _sysctl, struct __sysctl_args *, args); +int sysctl(int *name, int nlen, void *oldval, size_t *oldlenp, + void *newval, size_t newlen) +{ + struct __sysctl_args args = { name, nlen, oldval, oldlenp, + newval, newlen }; + return _sysctl(&args); +} + +#define SIZE(x) sizeof(x)/sizeof(x[0]) +#define OSNAMESZ 100 + +char osname[OSNAMESZ]; +int osnamelth; +int name[] = { CTL_KERN, KERN_OSTYPE }; + +int +main(void) +{ + osnamelth = sizeof(osname); + if (sysctl(name, SIZE(name), osname, &osnamelth, 0, 0)) + perror("sysctl"); + else + printf("This machine is running %*s\en", osnamelth, osname); + exit(EXIT_SUCCESS); +} +.fi .SH "SEE ALSO" .BR proc (5) diff --git a/man3/INFINITY.3 b/man3/INFINITY.3 index 2d7cb62a7..4abfff72f 100644 --- a/man3/INFINITY.3 +++ b/man3/INFINITY.3 @@ -63,6 +63,8 @@ The macros .BR HUGE_VALL expand to constants of types double, float and long double, respectively, that represent a large positive value, possibly plus infinity. +.SH "CONFORMING TO" +C99 .SH AVAILABILITY On a glibc system, the macro HUGE_VAL is always available. Availability of the NAN macro can be tested using @@ -72,8 +74,6 @@ They will be defined by .I if _ISOC99_SOURCE or _GNU_SOURCE is defined, or __STDC_VERSION__ is defined and has a value not less than 199901L. -.SH "CONFORMING TO" -C99 .SH "SEE ALSO" .BR fpclassify (3), .BR feature_test_macros (7) diff --git a/man3/__setfpucw.3 b/man3/__setfpucw.3 index 3119e8d8b..8d7244416 100644 --- a/man3/__setfpucw.3 +++ b/man3/__setfpucw.3 @@ -15,16 +15,6 @@ transfers to the registers of the fpu (floating point unit) on i386 architecture. This was used to control floating point precision, rounding and floating point exceptions. -.SH EXAMPLE -.BR __setfpucw(0x1372) - -Set fpu control word on i386 architecture to -.br - \- extended precision -.br - \- rounding to nearest -.br - \- exceptions on overflow, zero divide and NaN .SH AVAILABILITY As of glibc 2.1 this function does not exist anymore. There are new functions from C99, with prototypes in @@ -48,6 +38,16 @@ If direct access to the FPU control word is still needed, the _FPU_GETCW and _FPU_SETCW macros from .I /usr/include/fpu_control.h can be used. +.SH EXAMPLE +.BR __setfpucw(0x1372) + +Set fpu control word on i386 architecture to +.br + \- extended precision +.br + \- rounding to nearest +.br + \- exceptions on overflow, zero divide and NaN .SH "SEE ALSO" .BR feclearexcept (3) .br diff --git a/man3/a64l.3 b/man3/a64l.3 index 3058de9be..07ed38f9e 100644 --- a/man3/a64l.3 +++ b/man3/a64l.3 @@ -39,6 +39,8 @@ a-z represent 38-63 .fi .RE So 123 = 59*64^0 + 1*64^1 = "v/". +.SH "CONFORMING TO" +POSIX.1-2001. .SH NOTES The value returned by .BR a64l () @@ -59,8 +61,6 @@ These functions are broken in glibc before 2.2.5 .LP This is not the encoding used by .BR uuencode (1). -.SH "CONFORMING TO" -POSIX.1-2001. .SH "SEE ALSO" .BR uuencode (1), .BR itoa (3), diff --git a/man3/addseverity.3 b/man3/addseverity.3 index 8abd0bb6e..482310a85 100644 --- a/man3/addseverity.3 +++ b/man3/addseverity.3 @@ -45,9 +45,6 @@ Upon error, the return value is .BR MM_NOTOK . Possible errors include: out of memory, attempt to remove a nonexistent or default severity class. -.SH NOTES -New severity classes can also be added by setting the environment variable -.BR SEV_LEVEL . .SH "CONFORMING TO" This function is not specified in the X/Open Portability Guide although the @@ -55,6 +52,9 @@ although the function is. It is available on System V systems. +.SH NOTES +New severity classes can also be added by setting the environment variable +.BR SEV_LEVEL . .SH "SEE ALSO" .BR fmtmsg (3), .BR feature_test_macros (7) diff --git a/man3/adjtime.3 b/man3/adjtime.3 index 82d9ad5ae..57d0136b3 100644 --- a/man3/adjtime.3 +++ b/man3/adjtime.3 @@ -70,6 +70,26 @@ If is not NULL, then the buffer that it points to is used to return the amount of time remaining from any previous adjustment that has not yet been completed. +.SH "RETURN VALUE" +On success, +.BR adjtime () +returns 0. On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The adjustment in +.I delta +is outside the permitted range. +.TP +.B EPERM +The caller does not have sufficient privilege to adjust the time. +Under Linux the +.B CAP_SYS_TIME +capability is required. +.SH CONFORMING TO +4.3BSD, System V. .SH NOTES The adjustment that .BR adjtime () @@ -91,26 +111,6 @@ In the glibc implementation, must be less than or equal to (INT_MAX / 1000000 \- 2) and greater than or equal to (INT_MIN / 1000000 + 2) (respectively 2145 and \-2145 seconds on x86). -.SH "RETURN VALUE" -On success, -.BR adjtime () -returns 0. On failure, \-1 is returned, and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EINVAL -The adjustment in -.I delta -is outside the permitted range. -.TP -.B EPERM -The caller does not have sufficient privilege to adjust the time. -Under Linux the -.B CAP_SYS_TIME -capability is required. -.SH CONFORMING TO -4.3BSD, System V. .SH BUGS Currently, if .I delta diff --git a/man3/aio_read.3 b/man3/aio_read.3 index 81372327d..4ca419a48 100644 --- a/man3/aio_read.3 +++ b/man3/aio_read.3 @@ -99,6 +99,8 @@ This function is not supported. The file is a regular file, we start reading before end-of-file and want at least one byte, but the starting position is past the maximum offset for this file. +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES It is a good idea to zero out the control block before use. This control block must not be changed while the read operation @@ -108,8 +110,6 @@ The buffer area being read into must not be accessed during the operation or undefined results may occur. The memory areas involved must remain valid. -.SH "CONFORMING TO" -POSIX.1-2001 .SH "SEE ALSO" .BR aio_cancel (3), .BR aio_error (3), diff --git a/man3/aio_suspend.3 b/man3/aio_suspend.3 index dd5228906..d05c2eb2a 100644 --- a/man3/aio_suspend.3 +++ b/man3/aio_suspend.3 @@ -67,12 +67,12 @@ had completed. .B EINTR The call was ended by signal. (Possibly the completion signal of one of the operations we were waiting for.) +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES One can achieve polling by using a non-NULL .I timeout that specifies a zero time interval. -.SH "CONFORMING TO" -POSIX.1-2001 .SH "SEE ALSO" .BR aio_cancel (3), .BR aio_error (3), diff --git a/man3/aio_write.3 b/man3/aio_write.3 index 828dfab6c..df794eb52 100644 --- a/man3/aio_write.3 +++ b/man3/aio_write.3 @@ -99,6 +99,8 @@ are invalid. .TP .B ENOSYS This function is not supported. +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES It is a good idea to zero out the control block before use. This control block must not be changed while the write operation @@ -108,8 +110,6 @@ The buffer area being written out must not be accessed during the operation or undefined results may occur. The memory areas involved must remain valid. -.SH "CONFORMING TO" -POSIX.1-2001 .SH "SEE ALSO" .BR aio_cancel (3), .BR aio_error (3), diff --git a/man3/argz_add.3 b/man3/argz_add.3 index 1c67bf16e..3d51b6ee1 100644 --- a/man3/argz_add.3 +++ b/man3/argz_add.3 @@ -203,10 +203,11 @@ all null bytes ('\\0') except the last by All argz functions that do memory allocation have a return type of \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP if an allocation error occurs. -.SH BUGS -Argz vectors without a terminating null byte may lead to Segmentation Faults. .SH CONFORMING TO These functions are a GNU extension. Handle with care. +.SH BUGS +Argz vectors without a terminating null byte may lead to +Segmentation Faults. .SH "SEE ALSO" .BR envz (3) diff --git a/man3/atexit.3 b/man3/atexit.3 index 7e269553d..6e5f0a1a1 100644 --- a/man3/atexit.3 +++ b/man3/atexit.3 @@ -64,6 +64,23 @@ The .BR atexit () function returns the value 0 if successful; otherwise it returns a non-zero value. +.SH "CONFORMING TO" +SVr4, 4.3BSD, C89, C99, POSIX.1-2001. +.SH NOTES +.\" FIXME .SS Linux Notes here, and grammar in this sentence +Since glibc 2.2.3, +.BR atexit () +(and +.BR on_exit (3)) +can be used to within a shared library to establish functions +that are called when the shared library is unloaded. +.PP +Functions registered using +.BR atexit () +(and +.BR on_exit (3)) +are not called if a process terminates abnormally because +of the delivery of a signal. .SH EXAMPLE .nf #include @@ -93,22 +110,6 @@ main(void) return EXIT_SUCCESS; } .fi -.SH NOTES -Since glibc 2.2.3, -.BR atexit () -(and -.BR on_exit (3)) -can be used to within a shared library to establish functions -that are called when the shared library is unloaded. -.PP -Functions registered using -.BR atexit () -(and -.BR on_exit (3)) -are not called if a process terminates abnormally because -of the delivery of a signal. -.SH "CONFORMING TO" -SVr4, 4.3BSD, C89, C99, POSIX.1-2001. .SH "SEE ALSO" .BR _exit (3), .BR exit (3), diff --git a/man3/basename.3 b/man3/basename.3 index 2e1ec7964..84e1e8ecd 100644 --- a/man3/basename.3 +++ b/man3/basename.3 @@ -112,25 +112,14 @@ path dirname basename "." "." "." ".." "." ".." .fi -.SH EXAMPLE -.RS -.nf -char *dirc, *basec, *bname, *dname; -char *path = "/etc/passwd"; - -dirc = strdup(path); -basec = strdup(path); -dname = dirname(dirc); -bname = basename(basec); -printf("dirname=%s, basename=%s\\n", dname, bname); -.fi -.RE .SH "RETURN VALUE" Both .BR dirname () and .BR basename () return pointers to null-terminated strings. +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES There are two different versions of .BR basename () @@ -162,8 +151,19 @@ Before glibc 2.2.1, the glibc version of .BR dirname () did not correctly handle pathnames with trailing '/' characters, and generated a segfault if given a NULL argument. -.SH "CONFORMING TO" -POSIX.1-2001 +.SH EXAMPLE +.RS +.nf +char *dirc, *basec, *bname, *dname; +char *path = "/etc/passwd"; + +dirc = strdup(path); +basec = strdup(path); +dname = dirname(dirc); +bname = basename(basec); +printf("dirname=%s, basename=%s\\n", dname, bname); +.fi +.RE .SH "SEE ALSO" .BR basename (1), .BR dirname (1), diff --git a/man3/bsd_signal.3 b/man3/bsd_signal.3 index 30df1b9ee..072cbb15b 100644 --- a/man3/bsd_signal.3 +++ b/man3/bsd_signal.3 @@ -58,6 +58,8 @@ on error. .SH ERRORS As for .BR signal (2). +.SH "CONFORMING TO" +4.2BSD, POSIX.1-2001. .SH NOTES Use of .BR bsd_signal () @@ -81,8 +83,6 @@ The use of is a GNU extension; this type is only defined if the _GNU_SOURCE feature test macro is defined. -.SH "CONFORMING TO" -4.2BSD, POSIX.1-2001. .SH "SEE ALSO" .BR sigaction (2), .BR signal (2), diff --git a/man3/bsearch.3 b/man3/bsearch.3 index 9742ba56f..d3b24aa78 100644 --- a/man3/bsearch.3 +++ b/man3/bsearch.3 @@ -62,6 +62,8 @@ function returns a pointer to a matching member of the array, or NULL if no match is found. If there are multiple elements that match the key, the element returned is unspecified. +.SH "CONFORMING TO" +SVr4, 4.3BSD, POSIX.1-2001, C89, C99 .SH EXAMPLE The example below first sorts an array of structures using .BR qsort (3), @@ -112,8 +114,6 @@ main(int argc, char **argv) } .fi .\" this example referred to in qsort.3 -.SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001, C89, C99 .SH "SEE ALSO" .BR hsearch (3), .BR lsearch (3), diff --git a/man3/cabs.3 b/man3/cabs.3 index 8141af9a5..564bd1b30 100644 --- a/man3/cabs.3 +++ b/man3/cabs.3 @@ -19,10 +19,10 @@ The .BR cabs () function returns the absolute value of the complex number z. The result is a real number. -.SH NOTES -The function is actually an alias for hypot(a,b) = sqrt(a*a+b*b). .SH "CONFORMING TO" C99 +.SH NOTES +The function is actually an alias for hypot(a,b) = sqrt(a*a+b*b). .SH "SEE ALSO" .BR abs (3), .BR cimag (3), diff --git a/man3/catgets.3 b/man3/catgets.3 index 13dd4ba3e..84fb0cce1 100644 --- a/man3/catgets.3 +++ b/man3/catgets.3 @@ -64,6 +64,8 @@ On failure, .BR catgets () returns the value .IR message . +.SH "CONFORMING TO" +POSIX.1-2001. .SH NOTES These functions are only available in libc.so.4.4.4c and above. The Jan 1987 X/Open Portability Guide specifies a more subtle @@ -77,8 +79,6 @@ the specified message. These two possible error returns seem to be discarded in SUSv2 in favour of always returning .IR message . -.SH "CONFORMING TO" -POSIX.1-2001. .SH "SEE ALSO" .BR catopen (3), .BR setlocale (3) diff --git a/man3/catopen.3 b/man3/catopen.3 index 27898dbb1..ef691c4cf 100644 --- a/man3/catopen.3 +++ b/man3/catopen.3 @@ -134,6 +134,13 @@ is set to The language to use if .I flag is 0. +.SH "CONFORMING TO" +POSIX.1-2001. +.\" In XPG 1987, Vol. 3 it says: +.\" .I "The flag argument of catopen is reserved for future use" +.\" .IR "and should be set to 0" . +It is unclear what the source was for the constants MCLoadBySet +and MCLoadAll (see below). .SH NOTES The above is the POSIX.1-2001 description. The glibc value for NL_CAT_LOCALE is 1. @@ -164,13 +171,6 @@ The default search path varies, but usually looks at a number of places below .I /etc/locale and .IR /usr/lib/locale . -.SH "CONFORMING TO" -POSIX.1-2001. -.\" In XPG 1987, Vol. 3 it says: -.\" .I "The flag argument of catopen is reserved for future use" -.\" .IR "and should be set to 0" . -It is unclear what the source was for the constants MCLoadBySet -and MCLoadAll. .SH "SEE ALSO" .BR catgets (3), .BR setlocale (3) diff --git a/man3/ceil.3 b/man3/ceil.3 index 75ff0e3c5..3a5fd8052 100644 --- a/man3/ceil.3 +++ b/man3/ceil.3 @@ -47,6 +47,11 @@ No errors other than EDOM and ERANGE can occur. If \fIx\fP is NaN, then NaN is returned and .I errno may be set to EDOM. +.SH "CONFORMING TO" +The +.BR ceil () +function conforms to SVr4, POSIX.1-2001, 4.3BSD, C89, C99. +The other functions are from C99. .SH NOTES SUSv2 and POSIX.1-2001 contain text about overflow (which might set .I errno @@ -58,11 +63,6 @@ of the exponent is smaller than the number of mantissa bits. For the IEEE-754 standard 32-bit and 64-bit floating point numbers the maximum value of the exponent is 128 (resp. 1024), and the number of mantissa bits is 24 (resp. 53).) -.SH "CONFORMING TO" -The -.BR ceil () -function conforms to SVr4, POSIX.1-2001, 4.3BSD, C89, C99. -The other functions are from C99. .SH "SEE ALSO" .BR floor (3), .BR lrint (3), diff --git a/man3/cimag.3 b/man3/cimag.3 index 1ee279abb..0c0569b3e 100644 --- a/man3/cimag.3 +++ b/man3/cimag.3 @@ -20,11 +20,11 @@ The function returns the imaginary part of the complex number z. .LP One has z = creal(z) + I * cimag(z). +.SH "CONFORMING TO" +C99 .SH NOTES gcc also supports __imag__. That is a GNU extension. -.SH "CONFORMING TO" -C99 .SH "SEE ALSO" .BR cabs (3), .BR creal (3), diff --git a/man3/clock_getres.3 b/man3/clock_getres.3 index 9c4547eca..2240541c9 100644 --- a/man3/clock_getres.3 +++ b/man3/clock_getres.3 @@ -138,6 +138,23 @@ specified is not supported on this system. .B EPERM .BR clock_settime () does not have permission to set the clock indicated. +.SH "CONFORMING TO" +SUSv2, POSIX.1-2001. +.SH AVAILABILITY +On POSIX systems on which these functions are available, the symbol +.B _POSIX_TIMERS +is defined in to a value greater than 0. +The symbols +.BR _POSIX_MONOTONIC_CLOCK , +.BR _POSIX_CPUTIME , +.B _POSIX_THREAD_CPUTIME +indicate that +.BR CLOCK_MONOTONIC , +.BR CLOCK_PROCESS_CPUTIME_ID , +.B CLOCK_THREAD_CPUTIME_ID +are available. +(See also +.BR sysconf (3).) .SH NOTES Most systems require the program be linked with the librt library to use these functions. @@ -172,23 +189,6 @@ Glibc contains no provisions to deal with these offsets (unlike the Linux Kernel). Typically these offsets are small and therefore the effects may be negligible in most cases. -.SH AVAILABILITY -On POSIX systems on which these functions are available, the symbol -.B _POSIX_TIMERS -is defined in to a value greater than 0. -The symbols -.BR _POSIX_MONOTONIC_CLOCK , -.BR _POSIX_CPUTIME , -.B _POSIX_THREAD_CPUTIME -indicate that -.BR CLOCK_MONOTONIC , -.BR CLOCK_PROCESS_CPUTIME_ID , -.B CLOCK_THREAD_CPUTIME_ID -are available. -(See also -.BR sysconf (3).) -.SH "CONFORMING TO" -SUSv2, POSIX.1-2001. .SH "SEE ALSO" .BR date (1), .BR adjtimex (2), diff --git a/man3/cmsg.3 b/man3/cmsg.3 index 4f17ea669..cc8f3dff6 100644 --- a/man3/cmsg.3 +++ b/man3/cmsg.3 @@ -134,6 +134,27 @@ flag is set in the .I msg_flags member of the .BR msghdr . +.SH "CONFORMING TO" +This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, +the IPv6 advanced API described in RFC\ 2292 and the SUSv2. +.B +CMSG_ALIGN +is a Linux extension. +.SH NOTES +For portability, ancillary data should be accessed only using the macros +described here. +.BR CMSG_ALIGN () +is a Linux extension and should be not used in portable programs. +.PP +In Linux, +.BR CMSG_LEN , +.BR CMSG_DATA , +and +.BR CMSG_ALIGN () +are constant expressions (assuming their argument is constant); +this could be used to declare the size of global +variables. +This may be not portable, however. .SH EXAMPLE This code looks for the .B IP_TTL @@ -192,27 +213,6 @@ msg.msg_controllen = cmsg->cmsg_len; .ta .fi .RE -.SH NOTES -For portability, ancillary data should be accessed only using the macros -described here. -.BR CMSG_ALIGN () -is a Linux extension and should be not used in portable programs. -.PP -In Linux, -.BR CMSG_LEN , -.BR CMSG_DATA , -and -.BR CMSG_ALIGN () -are constant expressions (assuming their argument is constant); -this could be used to declare the size of global -variables. -This may be not portable, however. -.SH "CONFORMING TO" -This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, -the IPv6 advanced API described in RFC\ 2292 and the SUSv2. -.B -CMSG_ALIGN -is a Linux extension. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2) diff --git a/man3/confstr.3 b/man3/confstr.3 index d35547bfa..c0870770f 100644 --- a/man3/confstr.3 +++ b/man3/confstr.3 @@ -118,6 +118,8 @@ is set to If the value of .I name is invalid. +.SH "CONFORMING TO" +POSIX.1-2001 .SH EXAMPLE The following code fragment determines the path where to find the POSIX.2 system utilities: @@ -130,8 +132,6 @@ char *pathbuf; size_t n; n = confstr(_CS_PATH,NULL,(size_t)0); if ((pathbuf = malloc(n)) == NULL) abort(); confstr(_CS_PATH, pathbuf, n); -.SH "CONFORMING TO" -POSIX.1-2001 .SH "SEE ALSO" .BR sh (1), .BR exec (3), diff --git a/man3/copysign.3 b/man3/copysign.3 index 48adc7430..ef3ff7af2 100644 --- a/man3/copysign.3 +++ b/man3/copysign.3 @@ -47,14 +47,14 @@ The functions return a value whose absolute value matches that of \fIx\fP, but whose sign matches that of \fIy\fP. If \fIx\fP is a NaN, then a NaN with the sign of \fIy\fP is returned. +.SH "CONFORMING TO" +C99, 4.3BSD. +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). .SH NOTES On architectures where the floating-point formats are not IEEE 754 compliant, the .BR copysign () functions may treat a negative zero as positive. -.SH "CONFORMING TO" -C99, 4.3BSD. -This function is defined in IEC 559 (and the appendix with -recommended functions in IEEE 754/IEEE 854). .SH "SEE ALSO" .BR signbit (3) diff --git a/man3/creal.3 b/man3/creal.3 index dbc774be6..77cdf7497 100644 --- a/man3/creal.3 +++ b/man3/creal.3 @@ -20,11 +20,11 @@ The function returns the real part of the complex number z. .LP One has z = creal(z) + I * cimag(z). +.SH "CONFORMING TO" +C99 .SH NOTES The gcc supports also __real__. That is a GNU extension. -.SH "CONFORMING TO" -C99 .SH "SEE ALSO" .BR cabs (3), .BR cimag (3), diff --git a/man3/crypt.3 b/man3/crypt.3 index 31d943c79..73559129d 100644 --- a/man3/crypt.3 +++ b/man3/crypt.3 @@ -135,6 +135,8 @@ function was not implemented, probably because of U.S.A. export restrictions. .\" .PP .\" Making encrypted data computed using crypt() publicly available has .\" to be considered insecure for the given reasons. +.SH "CONFORMING TO" +SVr4, 4.3BSD, POSIX.1-2001 .SH NOTES .SS Glibc Notes The glibc2 version of this function has the following additional features. @@ -155,8 +157,6 @@ is significant here (instead of only the first 8 bytes). .LP Programs using this function must be linked with \-lcrypt. -.SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001 .SH "SEE ALSO" .BR login (1), .BR passwd (1), diff --git a/man3/ctime.3 b/man3/ctime.3 index 635166d00..3f33c42c8 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -226,6 +226,15 @@ Each of these functions returns the value described, or NULL (\-1 in case of .BR mktime ()) in case an error was detected. +.SH "CONFORMING TO" +POSIX.1-2001. +C89 and C99 specify +.BR asctime (), +.BR ctime (), +.BR gmtime (), +.BR localtime (), +and +.BR mktime () .SH NOTES The four functions .BR asctime (), @@ -260,15 +269,6 @@ const char *tm_zone; /* Timezone abbreviation */ defined when _BSD_SOURCE was set before including .IR . This is a BSD extension, present in 4.3BSD-Reno. -.SH "CONFORMING TO" -POSIX.1-2001. -C89 and C99 specify -.BR asctime (), -.BR ctime (), -.BR gmtime (), -.BR localtime (), -and -.BR mktime () .SH "SEE ALSO" .BR date (1), .BR gettimeofday (2), diff --git a/man3/daemon.3 b/man3/daemon.3 index 18b7e7950..ab2f9e875 100644 --- a/man3/daemon.3 +++ b/man3/daemon.3 @@ -72,6 +72,12 @@ to any of the errors specified for the .BR fork (2) and .BR setsid (2). +.SH CONFORMING TO +Not in POSIX.1-2001. +A similar function appears on the BSDs. +The +.BR daemon () +function first appeared in 4.4BSD. .SH NOTES The glibc implementation can also return \-1 when .I /dev/null @@ -80,12 +86,6 @@ major and minor numbers. In this case .I errno need not be set. -.SH CONFORMING TO -Not in POSIX.1-2001. -A similar function appears on the BSDs. -The -.BR daemon () -function first appeared in 4.4BSD. .SH "SEE ALSO" .BR fork (2), .BR setsid (2) diff --git a/man3/dirfd.3 b/man3/dirfd.3 index 0141e61fa..e023b095a 100644 --- a/man3/dirfd.3 +++ b/man3/dirfd.3 @@ -46,6 +46,12 @@ It will be automatically closed when is called. .SH ERRORS On error \-1 is returned. +.SH "CONFORMING TO" +This is a BSD extension, present in 4.3BSD-Reno, not in 4.2BSD. +It is present in libc5 (since 5.1.2) and in glibc2. +.\" As at 2006: +This function is under consideration for inclusion in +a future version of POSIX.1. .SH NOTES The prototype for .BR dirfd () @@ -54,12 +60,6 @@ is only available if or .B _SVID_SOURCE is defined. -.SH "CONFORMING TO" -This is a BSD extension, present in 4.3BSD-Reno, not in 4.2BSD. -It is present in libc5 (since 5.1.2) and in glibc2. -.\" As at 2006: -This function is under consideration for inclusion in -a future version of POSIX.1. .SH "SEE ALSO" .BR open (2), .BR closedir (3), diff --git a/man3/div.3 b/man3/div.3 index cdd878d2b..0cca8cfbf 100644 --- a/man3/div.3 +++ b/man3/div.3 @@ -70,12 +70,6 @@ of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP of the same type as the function arguments. .SH "RETURN VALUE" The \fIdiv_t\fP (etc.) structure. -.SH EXAMPLE -After -.nf - div_t q = div(\-5, 3); -.fi -the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. The functions @@ -83,6 +77,12 @@ The functions and .BR imaxdiv () were added in C99. +.SH EXAMPLE +After +.nf + div_t q = div(\-5, 3); +.fi +the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. .SH "SEE ALSO" .BR abs (3), .BR remainder (3) diff --git a/man3/dl_iterate_phdr.3 b/man3/dl_iterate_phdr.3 index 199336b72..f3f383868 100644 --- a/man3/dl_iterate_phdr.3 +++ b/man3/dl_iterate_phdr.3 @@ -140,6 +140,15 @@ in virtual memory using the formula: .nf addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr; .fi +.SH RETURN VALUE +The +.BR dl_iterate_phdr () +function returns whatever value was returned by the last call to +.IR callback . +.SH "CONFORMING TO" +The +.BR dl_iterate_phdr () +function is Linux specific and should be avoided in portable applications. .SH EXAMPLE The following program displays a list of pathnames of the shared objects it has loaded. @@ -174,15 +183,6 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .fi -.SH RETURN VALUE -The -.BR dl_iterate_phdr () -function returns whatever value was returned by the last call to -.IR callback . -.SH "CONFORMING TO" -The -.BR dl_iterate_phdr () -function is Linux specific and should be avoided in portable applications. .SH "SEE ALSO" .BR ldd (1), .BR objdump (1), diff --git a/man3/dlopen.3 b/man3/dlopen.3 index 38f29a2d7..410a29fa4 100644 --- a/man3/dlopen.3 +++ b/man3/dlopen.3 @@ -357,6 +357,37 @@ The function does the same as .BR dlsym () but takes a version string as an additional argument. +.SH "CONFORMING TO" +POSIX.1-2001 describes +.BR dlclose (), +.BR dlerror (), +.BR dlopen (), +and +.BR dlsym (). +.SH NOTES +The symbols RTLD_DEFAULT and RTLD_NEXT are defined by +.I +only when _GNU_SOURCE was defined before including it. +.\" .LP +.\" The string returned by +.\" .BR dlerror () +.\" should not be modified. +.\" Some systems give the prototype as +.\" .sp +.\" .in +5 +.\" .B "const char *dlerror(void);" +.\" .in + +Since glibc 2.2.3, +.BR atexit (3) +can be used to register an exit handler that is automatically +called when a library is unloaded. +.SS History +The dlopen interface standard comes from SunOS. +That system also has +.BR dladdr (), +but not +.BR dlvsym (). .SH EXAMPLE Load the math library, and print the cosine of 2.0: .RS @@ -410,37 +441,6 @@ follows, using bar.c as the example name: .LP gcc \-shared \-nostartfiles \-o bar bar.c .RE -.SH NOTES -The symbols RTLD_DEFAULT and RTLD_NEXT are defined by -.I -only when _GNU_SOURCE was defined before including it. -.\" .LP -.\" The string returned by -.\" .BR dlerror () -.\" should not be modified. -.\" Some systems give the prototype as -.\" .sp -.\" .in +5 -.\" .B "const char *dlerror(void);" -.\" .in - -Since glibc 2.2.3, -.BR atexit (3) -can be used to register an exit handler that is automatically -called when a library is unloaded. -.SS History -The dlopen interface standard comes from SunOS. -That system also has -.BR dladdr (), -but not -.BR dlvsym (). -.SH "CONFORMING TO" -POSIX.1-2001 describes -.BR dlclose (), -.BR dlerror (), -.BR dlopen (), -and -.BR dlsym (). .SH "SEE ALSO" .BR ld (1), .BR ldd (1), diff --git a/man3/dprintf.3 b/man3/dprintf.3 index 83e4e98d7..157403551 100644 --- a/man3/dprintf.3 +++ b/man3/dprintf.3 @@ -45,6 +45,8 @@ and except that they output to a file descriptor .I fd instead of to a given stream. +.SH "CONFORMING TO" +These functions are GNU extensions. .SH NOTES These functions are GNU extensions, not in C or POSIX. Clearly, the names were badly chosen. @@ -68,8 +70,6 @@ intended to be portable. A better name would have been .BR fdprintf (3). -.SH "CONFORMING TO" -These functions are GNU extensions. .SH "SEE ALSO" .BR printf (3), .BR feature_test_macros (7) diff --git a/man3/ecvt.3 b/man3/ecvt.3 index f5555a3c9..fce837c71 100644 --- a/man3/ecvt.3 +++ b/man3/ecvt.3 @@ -78,6 +78,9 @@ The static string is overwritten by each call to .BR ecvt () or .BR fcvt (). +.SH "CONFORMING TO" +SVr2; +marked as LEGACY in POSIX.1-2001. .SH NOTES These functions are obsolete. Instead, @@ -88,9 +91,6 @@ Linux libc4 and libc5 specified the type of as .BR size_t . Not all locales use a point as the radix character (`decimal point'). -.SH "CONFORMING TO" -SVr2; -marked as LEGACY in POSIX.1-2001. .SH "SEE ALSO" .BR ecvt_r (3), .BR gcvt (3), diff --git a/man3/ecvt_r.3 b/man3/ecvt_r.3 index 501c76b19..be943c215 100644 --- a/man3/ecvt_r.3 +++ b/man3/ecvt_r.3 @@ -68,13 +68,13 @@ and .BR qecvt (3). .SH "RETURN VALUE" These functions return 0 on success, and \-1 otherwise. +.SH "CONFORMING TO" +These functions are GNU extensions. .SH NOTES These functions are obsolete. Instead, .BR sprintf (3) is recommended. -.SH "CONFORMING TO" -These functions are GNU extensions. .SH "SEE ALSO" .BR ecvt (3), .BR qecvt (3), diff --git a/man3/encrypt.3 b/man3/encrypt.3 index 0cf48f4f5..7c975e44a 100644 --- a/man3/encrypt.3 +++ b/man3/encrypt.3 @@ -112,6 +112,19 @@ On success, it is unchanged. .BR ENOSYS The function is not provided. (For example because of former USA export restrictions.) +.SH "CONFORMING TO" +The functions +.BR encrypt () +and +.BR setkey () +conform to SVr4, SUSv2, and POSIX.1-2001. +The functions +.BR encrypt_r () +and +.BR setkey_r () +are GNU extensions. +.SH NOTES +In glibc 2.2 these functions use the DES algorithm. .SH EXAMPLE You need to link with libcrypt to compile this example with glibc 2.2. To do useful work the key[] and txt[] arrays must be filled with a @@ -133,19 +146,6 @@ main(void) encrypt(txt, 1); /* decode */ } .fi -.SH NOTES -In glibc 2.2 these functions use the DES algorithm. -.SH "CONFORMING TO" -The functions -.BR encrypt () -and -.BR setkey () -conform to SVr4, SUSv2, and POSIX.1-2001. -The functions -.BR encrypt_r () -and -.BR setkey_r () -are GNU extensions. .SH "SEE ALSO" .BR cbc_crypt (3), .BR crypt (3), diff --git a/man3/envz_add.3 b/man3/envz_add.3 index 80ce4633c..c7cf73905 100644 --- a/man3/envz_add.3 +++ b/man3/envz_add.3 @@ -113,6 +113,9 @@ removes all entries with value NULL. All envz functions that do memory allocation have a return type of \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP if an allocation error occurs. +.SH "CONFORMING TO" +These functions are a GNU extension. +Handle with care. .SH EXAMPLE .sp .nf @@ -135,8 +138,5 @@ main(int argc, char *argv[], char *envp[]) exit(EXIT_SUCCESS); } .fi -.SH "CONFORMING TO" -These functions are a GNU extension. -Handle with care. .SH "SEE ALSO" .BR argz (3) diff --git a/man3/ether_aton.3 b/man3/ether_aton.3 index 083ed039c..7960e8e84 100644 --- a/man3/ether_aton.3 +++ b/man3/ether_aton.3 @@ -118,9 +118,9 @@ struct ether_addr { } .fi .in -0.5i -.SH BUGS -The glibc 2.2.5 implementation of ether_line() is broken. .SH "CONFORMING TO" 4.3BSD, SunOS +.SH BUGS +The glibc 2.2.5 implementation of ether_line() is broken. .SH "SEE ALSO" .BR ethers (5) diff --git a/man3/exec.3 b/man3/exec.3 index 7dad2c7b7..b71609e01 100644 --- a/man3/exec.3 +++ b/man3/exec.3 @@ -161,13 +161,16 @@ The return value is \-1, and the global variable .I errno will be set to indicate the error. -.SH FILES -.I /bin/sh .SH ERRORS All of these functions may fail and set .I errno for any of the errors specified for the library function .BR execve (2). +.SH FILES +.\" FIXME remove this section? +.I /bin/sh +.SH "CONFORMING TO" +POSIX.1-2001. .SH NOTES On some other systems the default path (used when the environment does not contain the variable \fBPATH\fR) has the current working @@ -202,8 +205,6 @@ and upon which they returned. They now return if any error other than the ones described above occurs. -.SH "CONFORMING TO" -POSIX.1-2001. .SH "SEE ALSO" .BR sh (1), .BR execve (2), diff --git a/man3/fclose.3 b/man3/fclose.3 index 876a36566..04aec840c 100644 --- a/man3/fclose.3 +++ b/man3/fclose.3 @@ -85,6 +85,8 @@ for any of the errors specified for the routines .BR write (2) or .BR fflush (3). +.SH "CONFORMING TO" +C89, C99. .SH NOTES Note that .BR fclose () @@ -95,8 +97,6 @@ on disk the kernel buffers must be flushed too, e.g. with .BR sync (2) or .BR fsync (2). -.SH "CONFORMING TO" -C89, C99. .SH "SEE ALSO" .BR close (2), .BR fcloseall (3), diff --git a/man3/fenv.3 b/man3/fenv.3 index 2d5ac479d..03f7772f3 100644 --- a/man3/fenv.3 +++ b/man3/fenv.3 @@ -207,7 +207,13 @@ These functions return zero on success and non-zero if an error occurred. .\" Earlier seven of these functions were listed as returning void. .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E)) .\" of the C99 Standard. +.SH "CONFORMING TO" +IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99. .SH NOTES +.\" FIXME notes of the following form are not consistent across pages +Link with +.BR \-lm . +.PP .SS Glibc Notes If possible, the GNU C Library defines a macro .B FE_NOMASK_ENV @@ -252,10 +258,5 @@ and \-1 otherwise. The .BR fegetexcept () function returns the set of all currently enabled exceptions. -.SH NOTES -Link with -.BR \-lm . -.SH "CONFORMING TO" -IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99. .SH "SEE ALSO" .BR feature_test_macros (7) diff --git a/man3/fflush.3 b/man3/fflush.3 index 419ce8e51..2d401868a 100644 --- a/man3/fflush.3 +++ b/man3/fflush.3 @@ -84,6 +84,8 @@ may also fail and set .I errno for any of the errors specified for the routine .BR write (2). +.SH "CONFORMING TO" +C89, C99. .SH NOTES Note that .BR fflush () @@ -93,8 +95,6 @@ the kernel buffers must be flushed too, e.g. with .BR sync (2) or .BR fsync (2). -.SH "CONFORMING TO" -C89, C99. .SH "SEE ALSO" .BR fsync (2), .BR sync (2), diff --git a/man3/flockfile.3 b/man3/flockfile.3 index cda59aed4..e9fe8cb9b 100644 --- a/man3/flockfile.3 +++ b/man3/flockfile.3 @@ -97,12 +97,12 @@ function returns zero for success (the lock was obtained), and non-zero for failure. .SH ERRORS None. +.SH "CONFORMING TO" +POSIX.1-2001. .SH AVAILABILITY These functions are available when _POSIX_THREAD_SAFE_FUNCTIONS is defined. They are in libc since libc 5.1.1 and in glibc since glibc 2.0. -.SH "CONFORMING TO" -POSIX.1-2001. .SH "SEE ALSO" .BR unlocked_stdio (3) diff --git a/man3/floor.3 b/man3/floor.3 index 9b9fefac2..9d4d0afc4 100644 --- a/man3/floor.3 +++ b/man3/floor.3 @@ -46,6 +46,11 @@ No errors other than EDOM and ERANGE can occur. If \fIx\fP is NaN, then NaN is returned and .I errno may be set to EDOM. +.SH "CONFORMING TO" +The +.BR floor () +function conforms to SVr4, 4.3BSD, C89. +The other functions are from C99. .SH NOTES SUSv2 and POSIX.1-2001 contain text about overflow (which might set .I errno @@ -57,11 +62,6 @@ of the exponent is smaller than the number of mantissa bits. For the IEEE-754 standard 32-bit and 64-bit floating point numbers the maximum value of the exponent is 128 (resp. 1024), and the number of mantissa bits is 24 (resp. 53).) -.SH "CONFORMING TO" -The -.BR floor () -function conforms to SVr4, 4.3BSD, C89. -The other functions are from C99. .SH "SEE ALSO" .BR ceil (3), .BR lrint (3), diff --git a/man3/fmemopen.3 b/man3/fmemopen.3 index 50e6df09d..e004457b0 100644 --- a/man3/fmemopen.3 +++ b/man3/fmemopen.3 @@ -141,6 +141,10 @@ pointer. Otherwise, NULL is returned and the global variable .I errno is set to indicate the error. +.SH "CONFORMING TO" +These functions are GNU extensions. +.\" Jan 06: But they appear to be going up for standardization by +.\" POSIX/PASC/IEEE. .SH "EXAMPLE" The program below uses .BR fmemopen () @@ -193,10 +197,6 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .fi -.SH "CONFORMING TO" -These functions are GNU extensions. -.\" Jan 06: But they appear to be going up for standardization by -.\" POSIX/PASC/IEEE. .SH "SEE ALSO" .BR open (3), .BR feature_test_macros (7) diff --git a/man3/fmtmsg.3 b/man3/fmtmsg.3 index 0623a0b3f..1d99b2623 100644 --- a/man3/fmtmsg.3 +++ b/man3/fmtmsg.3 @@ -143,6 +143,21 @@ Using or the environment variable .B SEV_LEVEL you can add more levels and strings to print. +.SH "RETURN VALUE" +The function can return 4 values: +.TP 12n +.B MM_OK +Everything went smooth. +.TP +.B MM_NOTOK +Complete failure. +.TP +.B MM_NOMSG +Error writing to +.IR stderr . +.TP +.B MM_NOCON +Error writing to the console. .SH ENVIRONMENT The environment variable .B MSGVERB @@ -198,21 +213,6 @@ any of the predefined classes. The printstring is the string printed when a message of this class is processed by .BR fmtmsg (). -.SH "RETURN VALUE" -The function can return 4 values: -.TP 12n -.B MM_OK -Everything went smooth. -.TP -.B MM_NOTOK -Complete failure. -.TP -.B MM_NOMSG -Error writing to -.IR stderr . -.TP -.B MM_NOCON -Error writing to the console. .SH "CONFORMING TO" The functions .BR fmtmsg () diff --git a/man3/fpclassify.3 b/man3/fpclassify.3 index 0cb94ca39..2bf6991c0 100644 --- a/man3/fpclassify.3 +++ b/man3/fpclassify.3 @@ -74,6 +74,8 @@ returns 1 if is positive infinity, and \-1 if .I x is negative infinity. +.SH "CONFORMING TO" +C99 .SH NOTES In glibc 2.01 and earlier, .BR isinf () @@ -81,8 +83,6 @@ returns a non-zero value (actually: 1) if .I x is an infinity (positive or negative). (This is all that C99 requires.) -.SH "CONFORMING TO" -C99 .SH "SEE ALSO" .BR finite (3), .BR INFINITY (3), diff --git a/man3/fseeko.3 b/man3/fseeko.3 index 1ee12b0d2..ac30feabd 100644 --- a/man3/fseeko.3 +++ b/man3/fseeko.3 @@ -70,11 +70,11 @@ is set to indicate the error. .SH ERRORS See the ERRORS in .BR fseek (3). +.SH "CONFORMING TO" +SUSv2, POSIX.1-2001. .SH NOTES These functions are found on System V-like systems. They are not present in libc4, libc5, glibc 2.0 but are available since glibc 2.1. -.SH "CONFORMING TO" -SUSv2, POSIX.1-2001. .SH "SEE ALSO" .BR fseek (3) diff --git a/man3/ftime.3 b/man3/ftime.3 index 46ec2f1dd..9efb008eb 100644 --- a/man3/ftime.3 +++ b/man3/ftime.3 @@ -61,6 +61,8 @@ These days the contents of the \fItimezone\fP and \fIdstflag\fP fields are undefined. .SH "RETURN VALUE" This function always returns 0. +.SH "CONFORMING TO" +4.2BSD, POSIX.1-2001. .SH BUGS This function is obsolete. Don't use it. @@ -80,8 +82,6 @@ glibc 2.1.1 is correct again. .\" The .\" .BR ftime () .\" function appeared in 4.2BSD. -.SH "CONFORMING TO" -4.2BSD, POSIX.1-2001. .SH "SEE ALSO" .BR gettimeofday (2), .BR time (2) diff --git a/man3/fts.3 b/man3/fts.3 index 395e9d73f..66cf2b21f 100644 --- a/man3/fts.3 +++ b/man3/fts.3 @@ -742,14 +742,14 @@ as follows: .It Bq Er EINVAL The options were invalid. .El +.Sh VERSIONS +These functions are available in Linux since glibc2. .Sh "CONFORMING TO" 4.4BSD. The .Nm fts utility is expected to be included in a future .St -p1003.1-88 revision. -.Sh VERSIONS -These functions are available in Linux since glibc2. .Sh SEE ALSO .Xr find 1 , .Xr chdir 2 , diff --git a/man3/ftw.3 b/man3/ftw.3 index be6a22a61..e79084d40 100644 --- a/man3/ftw.3 +++ b/man3/ftw.3 @@ -295,6 +295,8 @@ then the only non-zero value that should be used by \fIfn\fP() to terminate the tree walk is \fBFTW_STOP\fP, and that value is returned as the result of .BR nftw (). +.SH "CONFORMING TO" +POSIX.1-2001, SVr4, SUSv1. .SH NOTES The function .BR nftw () @@ -321,8 +323,6 @@ The function is available since glibc 2.1. \fBFTW_ACTIONRETVAL\fP is glibc specific. -.SH "CONFORMING TO" -POSIX.1-2001, SVr4, SUSv1. .SH EXAMPLE The following program traverses the directory tree under the path named in its first command-line argument, or under the current directory diff --git a/man3/gamma.3 b/man3/gamma.3 index 8eec48f50..6bcca3bbc 100644 --- a/man3/gamma.3 +++ b/man3/gamma.3 @@ -31,6 +31,9 @@ function that is equivalent to and computes the natural logarithm of the Gamma function. (This is for compatibility reasons only. Don't use this function.) +.SH "CONFORMING TO" +4.2BSD. +Compatible with previous mistakes. .SH NOTES .SS History 4.2BSD had a @@ -60,9 +63,6 @@ the "true gamma" function. .\" The FreeBSD man page says about gamma() that it is like lgamma() .\" except that is does not set signgam. .\" Also, that 4.4BSD has a gamma() that computes the true gamma function. -.SH "CONFORMING TO" -4.2BSD. -Compatible with previous mistakes. .SH "SEE ALSO" .BR lgamma (3), .BR signgam (3), diff --git a/man3/gcvt.3 b/man3/gcvt.3 index dfe31c8e8..02e0795bc 100644 --- a/man3/gcvt.3 +++ b/man3/gcvt.3 @@ -42,11 +42,6 @@ terminated ASCII string and stores the result in \fIbuf\fP. It produces \fIndigit\fP significant digits in either .BR printf (3) F format or E format. -.SH NOTES -This function is obsolete. -Instead, -.BR sprintf (3) -is recommended. .SH "RETURN VALUE" The .BR gcvt () @@ -54,6 +49,11 @@ function returns the address of the string pointed to by \fIbuf\fP. .SH "CONFORMING TO" marked as LEGACY in POSIX.1-2001. +.SH NOTES +This function is obsolete. +Instead, +.BR sprintf (3) +is recommended. .SH "SEE ALSO" .BR ecvt (3), .BR fcvt (3), diff --git a/man3/getcwd.3 b/man3/getcwd.3 index 96fb69b8d..b62f05d22 100644 --- a/man3/getcwd.3 +++ b/man3/getcwd.3 @@ -152,6 +152,13 @@ The .IR size argument is less than the length of the working directory name. You need to allocate a bigger array and try again. +.SH "CONFORMING TO" +.BR getcwd () +conforms to POSIX.1-2001. +.BR getwd() +is present in POSIX.1-2001, but marked LEGACY. +.BR get_current_dir_name () +is a GNU extension. .SH NOTES Under Linux, the function .BR getcwd () @@ -171,13 +178,6 @@ directory (".") and calling .BR fchdir (2) to return is usually a faster and more reliable alternative when sufficiently many file descriptors are available, especially on platforms other than Linux. -.SH "CONFORMING TO" -.BR getcwd () -conforms to POSIX.1-2001. -.BR getwd() -is present in POSIX.1-2001, but marked LEGACY. -.BR get_current_dir_name () -is a GNU extension. .SH "SEE ALSO" .BR chdir (2), .BR fchdir (2), diff --git a/man3/getdate.3 b/man3/getdate.3 index b113ff3ef..54245d0b9 100644 --- a/man3/getdate.3 +++ b/man3/getdate.3 @@ -126,6 +126,16 @@ There is no line in the file that matches the input. .TP .B 8 Invalid input specification. +.SH ENVIRONMENT +.TP +.B DATEMSK +File containing format patterns. +.TP +.BR TZ ", " LC_TIME +Variables used by +.BR strptime (3). +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES Since .BR getdate () @@ -157,16 +167,6 @@ so that automatically precisely the same conversions are supported by both. The glibc implementation does not support the .B %Z conversion specification. -.SH ENVIRONMENT -.TP -.B DATEMSK -File containing format patterns. -.TP -.BR TZ ", " LC_TIME -Variables used by -.BR strptime (3). -.SH "CONFORMING TO" -POSIX.1-2001 .SH "SEE ALSO" .BR localtime (3), .BR setlocale (3), diff --git a/man3/getgrent_r.3 b/man3/getgrent_r.3 index a7dcad7dd..e93e1a8ed 100644 --- a/man3/getgrent_r.3 +++ b/man3/getgrent_r.3 @@ -100,6 +100,33 @@ No more entries. .B ERANGE Insufficient buffer space supplied. Try again with larger buffer. +.SH "CONFORMING TO" +These functions are GNU extensions, done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +Other systems use prototype +.sp +.nf +.in +4 +struct group * +getgrent_r(struct group *grp, char *buf, int buflen); +.in +.fi +.sp +or, better, +.sp +.nf +.in +4 +int +getgrent_r(struct group *grp, char *buf, int buflen, + FILE **gr_fp); +.in +.fi +.SH NOTES +The function +.BR getgrent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. .SH EXAMPLE .nf #define _GNU_SOURCE @@ -140,33 +167,6 @@ main(void) .\" printf("getgrent_r: %s", strerror(i)); .\" exit(EXIT_FAILURE); .\" } -.SH "CONFORMING TO" -These functions are GNU extensions, done in a style resembling -the POSIX version of functions like -.BR getpwnam_r (3). -Other systems use prototype -.sp -.nf -.in +4 -struct group * -getgrent_r(struct group *grp, char *buf, int buflen); -.in -.fi -.sp -or, better, -.sp -.nf -.in +4 -int -getgrent_r(struct group *grp, char *buf, int buflen, - FILE **gr_fp); -.in -.fi -.SH NOTES -The function -.BR getgrent_r () -is not really reentrant since it shares the reading position -in the stream with all other threads. .SH "SEE ALSO" .BR fgetgrent (3), .BR getgrent (3), diff --git a/man3/getgrouplist.3 b/man3/getgrouplist.3 index 0778f6016..3837524f1 100644 --- a/man3/getgrouplist.3 +++ b/man3/getgrouplist.3 @@ -37,14 +37,14 @@ is smaller than the total number of groups found, then returns a value of `\-1'. In all cases the actual number of groups is stored in .RI * ngroups . +.SH "VERSIONS" +This function is present since glibc 2.2.4. +.SH "CONFORMING TO" +This function is non-standard; it appears on most BSDs. .SH BUGS The glibc 2.3.2 implementation of this function is broken: it overwrites memory when the actual number of groups is larger than .RI * ngroups . -.SH "CONFORMING TO" -This function is non-standard; it appears on most BSDs. -.SH "VERSIONS" -This function is present since glibc 2.2.4. .SH EXAMPLE .nf /* This crashes with glibc 2.3.2 */ diff --git a/man3/getipnodebyname.3 b/man3/getipnodebyname.3 index a094b2f85..b056863a1 100644 --- a/man3/getipnodebyname.3 +++ b/man3/getipnodebyname.3 @@ -251,14 +251,14 @@ is AF_INET6. This is an array of one or more pointers to network address structures for the network host. The array is terminated by a null pointer. +.SH "CONFORMING TO" +RFC\ 2553. +.\" Not in POSIX.1-2001. .SH NOTES These functions have been present in glibc 2.1.91-95, but were removed again. Several Unix-like systems support them, but all call them deprecated. -.SH "CONFORMING TO" -RFC\ 2553. -.\" Not in POSIX.1-2001. .SH "SEE ALSO" .BR getaddrinfo (3), .BR getnameinfo (3), diff --git a/man3/getline.3 b/man3/getline.3 index 0acf8aeed..acf8be1bd 100644 --- a/man3/getline.3 +++ b/man3/getline.3 @@ -103,6 +103,13 @@ or is NULL, or .I stream is not valid). +.SH "CONFORMING TO" +Both +.BR getline () +and +.BR getdelim () +are GNU extensions. +They are available since libc 4.6.27. .SH "EXAMPLE" .nf #define _GNU_SOURCE @@ -128,13 +135,6 @@ main(void) return EXIT_SUCCESS; } .fi -.SH "CONFORMING TO" -Both -.BR getline () -and -.BR getdelim () -are GNU extensions. -They are available since libc 4.6.27. .SH "SEE ALSO" .BR read (2), .BR fgets (3), diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3 index 16fe87268..02dfd0b5b 100644 --- a/man3/getnameinfo.3 +++ b/man3/getnameinfo.3 @@ -174,6 +174,8 @@ suitable for error reporting. /etc/nsswitch.conf .br /etc/resolv.conf +.SH "CONFORMING TO" +RFC\ 2553, POSIX.1-2001. .SH NOTES In order to assist the programmer in choosing reasonable sizes for the supplied buffers, @@ -223,8 +225,6 @@ reverse address mapping. printf("host=%s\en", hbuf); .fi .RE -.SH "CONFORMING TO" -RFC\ 2553, POSIX.1-2001. .SH "SEE ALSO" .BR getaddrinfo (3), .BR gethostbyaddr (3), diff --git a/man3/getopt.3 b/man3/getopt.3 index 657de8da1..03b35ca1f 100644 --- a/man3/getopt.3 +++ b/man3/getopt.3 @@ -293,6 +293,36 @@ wildcard expansion and so should not be considered as options. This behaviour was removed in .B bash version 2.01, but the support remains in GNU libc. +.SH "CONFORMING TO" +.TP +.BR getopt (): +POSIX.2 and POSIX.1-2001, +provided the environment variable POSIXLY_CORRECT is set. +Otherwise, the elements of \fIargv\fP aren't really const, because we +permute them. +We pretend they're const in the prototype to be +compatible with other systems. +.sp +On some older implementations, +.BR getopt () +was declared in +.IR . +SUSv1 permitted the declaration to appear in either +.I +or +.IR . +POSIX.1-2001 marked the use of +.I +for this purpose as LEGACY. +POSIX.1-2001 does not allow the declaration to appear in +.IR . +.SH BUGS +The POSIX.2 specification of +.BR getopt () +has a technical error described in POSIX.2 Interpretation 150. +The GNU +implementation (and probably all other implementations) implements the +correct behaviour rather than that specified. .SH EXAMPLE The following trivial example program uses .BR getopt () @@ -431,36 +461,6 @@ main(int argc, char **argv) exit(EXIT_SUCCESS); } .fi -.SH BUGS -The POSIX.2 specification of -.BR getopt () -has a technical error described in POSIX.2 Interpretation 150. -The GNU -implementation (and probably all other implementations) implements the -correct behaviour rather than that specified. -.SH "CONFORMING TO" -.TP -.BR getopt (): -POSIX.2 and POSIX.1-2001, -provided the environment variable POSIXLY_CORRECT is set. -Otherwise, the elements of \fIargv\fP aren't really const, because we -permute them. -We pretend they're const in the prototype to be -compatible with other systems. -.sp -On some older implementations, -.BR getopt () -was declared in -.IR . -SUSv1 permitted the declaration to appear in either -.I -or -.IR . -POSIX.1-2001 marked the use of -.I -for this purpose as LEGACY. -POSIX.1-2001 does not allow the declaration to appear in -.IR . .SH "SEE ALSO" .BR getsubopt (3), .BR feature_test_macros (7) diff --git a/man3/getpass.3 b/man3/getpass.3 index ab3ba5711..67183941a 100644 --- a/man3/getpass.3 +++ b/man3/getpass.3 @@ -56,6 +56,15 @@ The function may fail if .TP .B ENXIO The process does not have a controlling terminal. +.SH FILES +.I /dev/tty +.\" .SH HISTORY +.\" A +.\" .BR getpass () +.\" function appeared in Version 7 AT&T UNIX. +.SH "CONFORMING TO" +Present in SUSv2, but marked LEGACY. +Removed in POSIX.1-2001. .SH NOTES For libc4 and libc5, the prompt is not written to .I /dev/tty @@ -92,15 +101,6 @@ and _SC_PASS_MAX, and the function .BR getpass (). Libc4 and libc5 have never supported PASS_MAX or _SC_PASS_MAX. Glibc2 accepts _SC_PASS_MAX and returns BUFSIZ (e.g., 8192). -.SH FILES -.I /dev/tty -.\" .SH HISTORY -.\" A -.\" .BR getpass () -.\" function appeared in Version 7 AT&T UNIX. -.SH "CONFORMING TO" -Present in SUSv2, but marked LEGACY. -Removed in POSIX.1-2001. .SH BUGS The calling process should zero the password as soon as possible to avoid leaving the cleartext password visible in the process's address space. diff --git a/man3/getpwent_r.3 b/man3/getpwent_r.3 index 6f27c34a6..f16e1d7cd 100644 --- a/man3/getpwent_r.3 +++ b/man3/getpwent_r.3 @@ -102,6 +102,33 @@ No more entries. .B ERANGE Insufficient buffer space supplied. Try again with larger buffer. +.SH "CONFORMING TO" +These functions are GNU extensions, done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +Other systems use prototype +.sp +.nf +.in +4 +struct passwd * +getpwent_r(struct passwd *pwd, char *buf, int buflen); +.in +.fi +.sp +or, better, +.sp +.nf +.in +4 +int +getpwent_r(struct passwd *pwd, char *buf, int buflen, + FILE **pw_fp); +.in +.fi +.SH NOTES +The function +.BR getpwent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. .SH EXAMPLE .nf #define _GNU_SOURCE @@ -137,33 +164,6 @@ main(void) .\" printf("getpwent_r: %s", strerror(i)); .\" exit(EXIT_SUCCESS); .\" } -.SH "CONFORMING TO" -These functions are GNU extensions, done in a style resembling -the POSIX version of functions like -.BR getpwnam_r (3). -Other systems use prototype -.sp -.nf -.in +4 -struct passwd * -getpwent_r(struct passwd *pwd, char *buf, int buflen); -.in -.fi -.sp -or, better, -.sp -.nf -.in +4 -int -getpwent_r(struct passwd *pwd, char *buf, int buflen, - FILE **pw_fp); -.in -.fi -.SH NOTES -The function -.BR getpwent_r () -is not really reentrant since it shares the reading position -in the stream with all other threads. .SH "SEE ALSO" .BR fgetpwent (3), .BR getpw (3), diff --git a/man3/getrpcent.3 b/man3/getrpcent.3 index 068407f6a..78af0567c 100644 --- a/man3/getrpcent.3 +++ b/man3/getrpcent.3 @@ -88,11 +88,6 @@ and sequentially search from the beginning of the file until a matching rpc program name or program number is found, or until end-of-file is encountered. -.SH FILES -.PD 0 -.TP 20 -.I /etc/rpc -.PD .SH RETURN VALUE .LP A @@ -100,15 +95,20 @@ A pointer is returned on .SM EOF or error. +.SH FILES +.PD 0 +.TP 20 +.I /etc/rpc +.PD +.SH "CONFORMING TO" +Not in POSIX.1-2001. +Present on the BSDs, Solaris, and many other systems. .SH BUGS .LP All information is contained in a static area so it must be copied if it is to be saved. -.SH "CONFORMING TO" -Not in POSIX.1-2001. -Present on the BSDs, Solaris, and many other systems. .SH "SEE ALSO" .BR rpc (5), .BR rpcinfo (8), diff --git a/man3/getttyent.3 b/man3/getttyent.3 index 3265ab933..efddeb16c 100644 --- a/man3/getttyent.3 +++ b/man3/getttyent.3 @@ -58,13 +58,13 @@ can be #define TTY_ON 0x01 /* enable logins (start ty_getty program) */ #define TTY_SECURE 0x02 /* allow UID 0 to login */ .fi +.SH "CONFORMING TO" +Not in POSIX.1-2001. +Present on the BSDs, and perhaps other systems. .SH NOTES Under Linux the file .IR /etc/ttys , and the functions described above, are not used. -.SH "CONFORMING TO" -Not in POSIX.1-2001. -Present on the BSDs, and perhaps other systems. .SH "SEE ALSO" .BR ttyname (3), .BR ttyslot (3) diff --git a/man3/getumask.3 b/man3/getumask.3 index ae9483d05..ee16af1ec 100644 --- a/man3/getumask.3 +++ b/man3/getumask.3 @@ -51,9 +51,9 @@ except that it is documented to be thread-safe (that is, shares a lock with the .BR umask (2) library call). -.SH NOTES -This function is documented but not implemented yet in glibc 2.2.5. .SH "CONFORMING TO" This is a vapourware GNU extension. +.SH NOTES +This function is documented but not implemented yet in glibc 2.2.5. .SH "SEE ALSO" .BR umask (2) diff --git a/man3/getutent.3 b/man3/getutent.3 index 6f14e969a..6993299e1 100644 --- a/man3/getutent.3 +++ b/man3/getutent.3 @@ -110,6 +110,52 @@ and return a pointer to a \fBstruct utmp\fP on success, and NULL on failure. This \fBstruct utmp\fP is allocated in static storage, and may be overwritten by subsequent calls. +.SH FILES +/var/run/utmp database of currently logged-in users +.br +/var/log/wtmp database of past user logins +.SH "CONFORMING TO" +XPG2, SVr4. +.LP +In XPG2 and SVID 2 the function +.BR pututline () +is documented to return void, and that is what it does on many systems +(AIX, HP-UX, Linux libc5). +HP-UX introduces a new function +.BR _pututline () +with the prototype given above for +.BR pututline () +(also found in Linux libc5). +.LP +All these functions are obsolete now on non-Linux systems. +POSIX.1-2001, following SUSv1, +does not have any of these functions, but instead uses +.sp +.B #include +.sp +.B struct utmpx *getutxent(void); +.br +.B struct utmpx *getutxid(const struct utmpx *); +.br +.B struct utmpx *getutxline(const struct utmpx *); +.br +.B struct utmpx *pututxline(const struct utmpx *); +.br +.B void setutxent(void); +.br +.B void endutxent(void); +.sp +The \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, +with additional fields, and larger versions of the existing fields. +The corresponding files are often +.I /var/*/utmpx +and +.IR /var/*/wtmpx . +.LP +Linux glibc on the other hand does not use \fIutmpx\fP since its +\fIutmp\fP structure is already large enough. +The functions \fIgetutxent\fP +etc. are aliases for \fIgetutent\fP etc. .SH NOTES .SS Glibc Notes The above functions are not thread-safe. @@ -186,52 +232,6 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .fi -.SH FILES -/var/run/utmp database of currently logged-in users -.br -/var/log/wtmp database of past user logins -.SH "CONFORMING TO" -XPG2, SVr4. -.LP -In XPG2 and SVID 2 the function -.BR pututline () -is documented to return void, and that is what it does on many systems -(AIX, HP-UX, Linux libc5). -HP-UX introduces a new function -.BR _pututline () -with the prototype given above for -.BR pututline () -(also found in Linux libc5). -.LP -All these functions are obsolete now on non-Linux systems. -POSIX.1-2001, following SUSv1, -does not have any of these functions, but instead uses -.sp -.B #include -.sp -.B struct utmpx *getutxent(void); -.br -.B struct utmpx *getutxid(const struct utmpx *); -.br -.B struct utmpx *getutxline(const struct utmpx *); -.br -.B struct utmpx *pututxline(const struct utmpx *); -.br -.B void setutxent(void); -.br -.B void endutxent(void); -.sp -The \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, -with additional fields, and larger versions of the existing fields. -The corresponding files are often -.I /var/*/utmpx -and -.IR /var/*/wtmpx . -.LP -Linux glibc on the other hand does not use \fIutmpx\fP since its -\fIutmp\fP structure is already large enough. -The functions \fIgetutxent\fP -etc. are aliases for \fIgetutent\fP etc. .SH "SEE ALSO" .BR utmp (5), .BR feature_test_macros (7) diff --git a/man3/getw.3 b/man3/getw.3 index 6bacf43c2..88f22a4c2 100644 --- a/man3/getw.3 +++ b/man3/getw.3 @@ -51,12 +51,12 @@ returns the word read, and .BR putw () returns 0. On error, they return \fBEOF\fP. +.SH "CONFORMING TO" +SVr4 .SH BUGS The value returned on error is also a legitimate data value. .BR ferror (3) can be used to distinguish between the two cases. -.SH "CONFORMING TO" -SVr4 .SH "SEE ALSO" .BR ferror (3), .BR fread (3), diff --git a/man3/glob.3 b/man3/glob.3 index 1fb0c3129..d55a33fa4 100644 --- a/man3/glob.3 +++ b/man3/glob.3 @@ -201,6 +201,28 @@ for a read error, and .TP .B GLOB_NOMATCH for no found matches. +.SH "CONFORMING TO" +POSIX.2, POSIX.1-2001. +.SH NOTES +The structure elements +.I gl_pathc +and +.I gl_offs +are declared as +.BR size_t +in glibc 2.1, as they should according to POSIX.2, +but are declared as +.I int +in libc4, libc5 and glibc 2.0. +.SH BUGS +The +.BR glob () +function may fail due to failure of underlying function calls, such as +.BR malloc (3) +or +.BR opendir (3). +These will store their error code in +.IR errno . .SH EXAMPLE One example of use is the following code, which simulates typing .sp @@ -219,28 +241,6 @@ globbuf.gl_pathv[0] = "ls"; globbuf.gl_pathv[1] = "\-l"; execvp("ls", &globbuf.gl_pathv[0]); .fi -.SH "CONFORMING TO" -POSIX.2, POSIX.1-2001. -.SH BUGS -The -.BR glob () -function may fail due to failure of underlying function calls, such as -.BR malloc (3) -or -.BR opendir (3). -These will store their error code in -.IR errno . -.SH NOTES -The structure elements -.I gl_pathc -and -.I gl_offs -are declared as -.BR size_t -in glibc 2.1, as they should according to POSIX.2, -but are declared as -.I int -in libc4, libc5 and glibc 2.0. .SH "SEE ALSO" .BR ls (1), .BR sh (1), diff --git a/man3/inet.3 b/man3/inet.3 index 772ac574a..b10814ac4 100644 --- a/man3/inet.3 +++ b/man3/inet.3 @@ -135,6 +135,13 @@ struct in_addr { Note that on the i80x86 the host byte order is Least Significant Byte first (little endian), whereas the network byte order, as used on the Internet, is Most Significant Byte first (big endian). +.SH "CONFORMING TO" +4.3BSD. +.BR inet_addr (), +.BR inet_aton (), +and +.BR inet_ntoa () +are specified in POSIX.1-2001. .SH NOTES When you using numbers-and-dots notation for addresses, be aware that each number will be interpreted as octal @@ -146,13 +153,6 @@ In order to expose the declaration of .BR inet_aton (), one of the feature test macros _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE must be defined. -.SH "CONFORMING TO" -4.3BSD. -.BR inet_addr (), -.BR inet_aton (), -and -.BR inet_ntoa () -are specified in POSIX.1-2001. .SH "SEE ALSO" .BR gethostbyname (3), .BR getnetent (3), diff --git a/man3/infnan.3 b/man3/infnan.3 index 37f6c5b70..a4418ee81 100644 --- a/man3/infnan.3 +++ b/man3/infnan.3 @@ -48,13 +48,6 @@ The value of \fIerror\fP can be ERANGE to represent infinity or anything else to represent NaN. \fIerrno\fP is also set. -.SH NOTES -This obsolete function was provided in -.I libc4 -and -.IR libc5 , -but is not available in -.IR glibc2 . .SH "RETURN VALUE" If \fIerror\fP is ERANGE (Infinity), HUGE_VAL is returned. .PP @@ -70,3 +63,10 @@ The value of \fIerror\fP is "not-a-number" (NaN). The value of \fIerror\fP is positive or negative infinity. .SH "CONFORMING TO" 4.3BSD +.SH NOTES +This obsolete function was provided in +.I libc4 +and +.IR libc5 , +but is not available in +.IR glibc2 . diff --git a/man3/isgreater.3 b/man3/isgreater.3 index 650e222d5..0f26451f7 100644 --- a/man3/isgreater.3 +++ b/man3/isgreater.3 @@ -53,13 +53,13 @@ true if x or y is NaN. .TP isunordered() is true if x or y is NaN and false otherwise. +.SH "CONFORMING TO" +C99 .SH NOTES Not all hardware supports these functions, and where it doesn't, they will be emulated by macros. This will give you a performance penalty. Don't use these functions if NaN is of no concern for you. -.SH "CONFORMING TO" -C99 .SH "SEE ALSO" .BR fpclassify (3), .BR isnan (3) diff --git a/man3/key_setsecret.3 b/man3/key_setsecret.3 index d224025a9..948d211ae 100644 --- a/man3/key_setsecret.3 +++ b/man3/key_setsecret.3 @@ -53,6 +53,8 @@ The function .BR key_secretkey_is_set () can be used to determine whether a key has been set for the effective UID of the calling process. +.SH "RETURN VALUE" +These functions return 1 on success and 0 on failure. .SH NOTES Note that we talk about two types of encryption here. One is asymmetric using a public and secret key. @@ -60,7 +62,5 @@ The other is symmetric, the 64-bit DES. .br The routines were part of the linux/doors-project, abandoned by now. -.SH "RETURN VALUE" -These functions return 1 on success and 0 on failure. .SH "SEE ALSO" .BR crypt (3) diff --git a/man3/login.3 b/man3/login.3 index fb9df8a1f..b88ef0e72 100644 --- a/man3/login.3 +++ b/man3/login.3 @@ -86,6 +86,18 @@ The .BR logout () function returns 1 if the entry was successfully written to the database, or 0 if an error occurred. +.SH FILES +.TP +.I /var/run/utmp +user accounting database, configured through _PATH_UTMP in +.I +.TP +.I /var/log/wtmp +user accounting log file, configured through _PATH_WTMP in +.I +.SH "CONFORMING TO" +Not in POSIX.1-2001. +Present on the BSDs. .SH NOTES These functions are included in libutil, hence you'll need to add .B \-lutil @@ -105,18 +117,6 @@ is defined as an alias for .I ut_user in .IR . -.SH FILES -.TP -.I /var/run/utmp -user accounting database, configured through _PATH_UTMP in -.I -.TP -.I /var/log/wtmp -user accounting log file, configured through _PATH_WTMP in -.I -.SH "CONFORMING TO" -Not in POSIX.1-2001. -Present on the BSDs. .SH "SEE ALSO" .BR getutent (3), .BR utmp (5) diff --git a/man3/makecontext.3 b/man3/makecontext.3 index 25ccfcc2b..f012046cf 100644 --- a/man3/makecontext.3 +++ b/man3/makecontext.3 @@ -92,6 +92,8 @@ sets \fIerrno\fP appropriately. .TP .B ENOMEM Insufficient stack space left. +.SH "CONFORMING TO" +SUSv2, POSIX.1-2001. .SH NOTES The interpretation of \fIucp->uc_stack\fP is just as in .BR sigaltstack (2), @@ -100,8 +102,6 @@ to be used as the stack, regardless of the direction of growth of the stack. Thus, it is not necessary for the user program to worry about this direction. -.SH "CONFORMING TO" -SUSv2, POSIX.1-2001. .SH EXAMPLE .PP The example program below demonstrates the use of diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3 index 8ce32255f..11a8c0c61 100644 --- a/man3/malloc_hook.3 +++ b/man3/malloc_hook.3 @@ -75,6 +75,8 @@ The variable points at a function that is called each time after .BR sbrk (2) was asked for more memory. +.SH "CONFORMING TO" +These functions are GNU extensions. .SH "EXAMPLE" Here is a short example of how to use these variables. .sp @@ -123,8 +125,6 @@ my_malloc_hook(size_t size, const void *caller) return result; } .fi -.SH "CONFORMING TO" -These functions are GNU extensions. .SH "SEE ALSO" .BR mallinfo (3), .BR malloc (3), diff --git a/man3/mempcpy.3 b/man3/mempcpy.3 index 83d6a8175..ca3fd6a47 100644 --- a/man3/mempcpy.3 +++ b/man3/mempcpy.3 @@ -48,6 +48,8 @@ type arguments and copies wide characters. .SH "RETURN VALUE" \fIdest\fP + \fIn\fP . +.SH "CONFORMING TO" +This function is a GNU extension. .SH "EXAMPLE" .nf void * @@ -59,8 +61,6 @@ combine(void *o1, size_t s1, void *o2, size_t s2) return result; } .fi -.SH "CONFORMING TO" -This function is a GNU extension. .SH "SEE ALSO" .BR memccpy (3), .BR memcpy (3), diff --git a/man3/mkdtemp.3 b/man3/mkdtemp.3 index 8df667e1a..b8aa2ba16 100644 --- a/man3/mkdtemp.3 +++ b/man3/mkdtemp.3 @@ -59,12 +59,12 @@ Now \fItemplate\fP is unchanged. Also see .BR mkdir (2) for other possible values for \fIerrno\fP. +.SH VERSIONS +Available since glibc 2.1.91. .SH "CONFORMING TO" This function is present on the BSDs. .\" As at 2006, this function is being considered for a revision of POSIX.1 .\" Also in NetBSD 1.4. -.SH VERSIONS -Available since glibc 2.1.91. .SH "SEE ALSO" .BR mkdir (2), .BR mkstemp (3), diff --git a/man3/mkfifoat.3 b/man3/mkfifoat.3 index 603931964..7c6a5f520 100644 --- a/man3/mkfifoat.3 +++ b/man3/mkfifoat.3 @@ -91,20 +91,20 @@ is not a valid file descriptor. is a relative path and .I dirfd is a file descriptor referring to a file other than a directory. -.SH NOTES -See -.BR openat (2) -for an explanation of the need for -.BR mkfifoat (). -.SH "CONFORMING TO" -This function is non-standard but is proposed -for inclusion in a future revision of POSIX.1. .SH VERSIONS .BR mkfifoat () was added to glibc in version 2.4. It is implemented using .BR mknod (2), available on Linux since kernel 2.6.16. +.SH "CONFORMING TO" +This function is non-standard but is proposed +for inclusion in a future revision of POSIX.1. +.SH NOTES +See +.BR openat (2) +for an explanation of the need for +.BR mkfifoat (). .SH "SEE ALSO" .BR openat (2), .BR path_resolution (2), diff --git a/man3/mkstemp.3 b/man3/mkstemp.3 index 87b4a67c8..92a854f1e 100644 --- a/man3/mkstemp.3 +++ b/man3/mkstemp.3 @@ -73,6 +73,8 @@ Now the contents of \fItemplate\fP are undefined. .B EINVAL The last six characters of \fItemplate\fP were not XXXXXX. Now \fItemplate\fP is unchanged. +.SH "CONFORMING TO" +4.3BSD, POSIX.1-2001 .SH NOTES The old behaviour (creating a file with mode 0666) may be a security risk, especially since other Unix flavours use 0600, @@ -87,8 +89,6 @@ The prototype is in .I for libc4, libc5, glibc1; glibc2 follows POSIX.1 and has the prototype in .IR . -.SH "CONFORMING TO" -4.3BSD, POSIX.1-2001 .SH "SEE ALSO" .BR mkdtemp (3), .BR mktemp (3), diff --git a/man3/mq_close.3 b/man3/mq_close.3 index 26d3c4810..a550c1253 100644 --- a/man3/mq_close.3 +++ b/man3/mq_close.3 @@ -39,10 +39,6 @@ to this message queue via .IR mqdes , then this request is removed, and another process can now attach a notification request. -.SH NOTES -All open message queues are automatically closed on process termination, -or upon -.BR execve (2). .SH RETURN VALUE On success .BR mq_close () @@ -57,6 +53,10 @@ The descriptor specified in is invalid. .SH CONFORMING TO POSIX.1-2001. +.SH NOTES +All open message queues are automatically closed on process termination, +or upon +.BR execve (2). .SH "SEE ALSO" .BR mq_getattr (3), .BR mq_notify (3), diff --git a/man3/mtrace.3 b/man3/mtrace.3 index 8ed5e9abb..0316d0629 100644 --- a/man3/mtrace.3 +++ b/man3/mtrace.3 @@ -32,13 +32,13 @@ This file must be writable to the user or .BR mtrace () will do nothing. If the file is not empty it will be truncated. +.SH "CONFORMING TO" +These are GNU extensions. .SH NOTES The output of .BR mtrace () will be ASCII but not in a friendly format. So glibc comes with a perl-script called mtrace to make sense of it. -.SH "CONFORMING TO" -These are GNU extensions. .SH "SEE ALSO" .BR malloc (3), .BR malloc_hook (3) diff --git a/man3/offsetof.3 b/man3/offsetof.3 index 3275a3721..9f9e861da 100644 --- a/man3/offsetof.3 +++ b/man3/offsetof.3 @@ -50,6 +50,8 @@ A compiler error will result if .BR offsetof () returns the offset of the given element within the given type, in units of bytes. +.SH "CONFORMING TO" +C89, C99, POSIX.1-2001. .SH EXAMPLE On a Linux/x86 system, when compiled using the default .BR gcc (1) @@ -88,8 +90,6 @@ main(void) exit(EXIT_SUCCESS); } .fi -.SH "CONFORMING TO" -C89, C99, POSIX.1-2001. .\" .SH SEE ALSO .\" FIXME . When one day readdir_r(3) is documented, it should have .\" a SEE ALSO that refers to this page. diff --git a/man3/opendir.3 b/man3/opendir.3 index 8739862b8..85ba0788d 100644 --- a/man3/opendir.3 +++ b/man3/opendir.3 @@ -69,11 +69,11 @@ Insufficient memory to complete the operation. .TP .B ENOTDIR \fIname\fP is not a directory. +.SH "CONFORMING TO" +SVr4, 4.3BSD, POSIX.1-2001. .SH NOTES The underlying file descriptor of the directory stream can be obtained using .BR dirfd (3). -.SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. .SH "SEE ALSO" .BR open (2), .BR closedir (3), diff --git a/man3/openpty.3 b/man3/openpty.3 index a40785275..26013588c 100644 --- a/man3/openpty.3 +++ b/man3/openpty.3 @@ -145,6 +145,8 @@ will fail if either or .BR fork (2) fails. +.SH "CONFORMING TO" +These are BSD functions, present in libc5 and glibc2. .SH NOTES These functions are included in libutil, hence you'll need to add .B \-lutil @@ -156,8 +158,6 @@ returns file descriptors for a BSD pseudo-terminal pair; since glibc 2.0.92, it first attempts to open a Unix 98 pseudo-terminal pair, and falls back to opening a BSD pseudo-terminal pair if that fails. -.SH "CONFORMING TO" -These are BSD functions, present in libc5 and glibc2. .SH BUGS Nobody knows how much space should be reserved for .IR name . diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 index 5ab1377a7..7b2635137 100644 --- a/man3/posix_memalign.3 +++ b/man3/posix_memalign.3 @@ -91,6 +91,46 @@ parameter was not a power of two, or was not a multiple of .TP .B ENOMEM There was insufficient memory to fulfill the allocation request. +.SH VERSIONS +The functions +.BR memalign () +and +.BR valloc () +have been available in all Linux libc libraries. +The function +.BR posix_memalign () +is available since glibc 2.1.91. +.SH "CONFORMING TO" +The function +.BR valloc () +appeared in 3.0BSD. +It is documented as being obsolete in 4.3BSD, +and as legacy in SUSv2. +It does not appear in POSIX.1-2001. +The function +.BR memalign () +appears in SunOS 4.1.3 but not in 4.4BSD. +The function +.BR posix_memalign () +comes from POSIX.1d. +.SS Headers +Everybody agrees that +.BR posix_memalign () +is declared in . +In order to declare it, glibc needs +_GNU_SOURCE defined, or _XOPEN_SOURCE defined to a value not less than 600. + +On some systems +.BR memalign () +is declared in instead of . + +According to SUSv2, +.BR valloc () +is declared in . +Libc4,5 and glibc declare it in and perhaps also in +(namely, if _GNU_SOURCE is defined, or _BSD_SOURCE is defined, or, +for glibc, if _XOPEN_SOURCE_EXTENDED is defined, or, equivalently, +_XOPEN_SOURCE is defined to a value not less than 500). .SH NOTES On many systems there are alignment restrictions, e.g. on buffers used for direct block device I/O. @@ -141,46 +181,6 @@ GNU libc .BR malloc (3) always returns 8-byte aligned memory addresses, so these routines are only needed if you require larger alignment values. -.SH VERSIONS -The functions -.BR memalign () -and -.BR valloc () -have been available in all Linux libc libraries. -The function -.BR posix_memalign () -is available since glibc 2.1.91. -.SH "CONFORMING TO" -The function -.BR valloc () -appeared in 3.0BSD. -It is documented as being obsolete in 4.3BSD, -and as legacy in SUSv2. -It does not appear in POSIX.1-2001. -The function -.BR memalign () -appears in SunOS 4.1.3 but not in 4.4BSD. -The function -.BR posix_memalign () -comes from POSIX.1d. -.SS Headers -Everybody agrees that -.BR posix_memalign () -is declared in . -In order to declare it, glibc needs -_GNU_SOURCE defined, or _XOPEN_SOURCE defined to a value not less than 600. - -On some systems -.BR memalign () -is declared in instead of . - -According to SUSv2, -.BR valloc () -is declared in . -Libc4,5 and glibc declare it in and perhaps also in -(namely, if _GNU_SOURCE is defined, or _BSD_SOURCE is defined, or, -for glibc, if _XOPEN_SOURCE_EXTENDED is defined, or, equivalently, -_XOPEN_SOURCE is defined to a value not less than 500). .SH "SEE ALSO" .BR brk (2), .BR getpagesize (2), diff --git a/man3/printf.3 b/man3/printf.3 index 31b4c365d..91762f9dc 100644 --- a/man3/printf.3 +++ b/man3/printf.3 @@ -756,6 +756,145 @@ A `%' is written. No argument is converted. The complete conversion specification is `%%'. +.SH "CONFORMING TO" +The +.BR fprintf (), +.BR printf (), +.BR sprintf (), +.BR vprintf (), +.BR vfprintf (), +and +.BR vsprintf () +functions conform to C89 and C99. +The +.BR snprintf () +and +.BR vsnprintf () +functions conform to C99. +.PP +Concerning the return value of +.BR snprintf (), +SUSv2 and C99 contradict each other: when +.BR snprintf () +is called with +.IR size =0 +then SUSv2 stipulates an unspecified return value less than 1, +while C99 allows +.I str +to be NULL in this case, and gives the return value (as always) +as the number of characters that would have been written in case +the output string has been large enough. +.PP +Linux libc4 knows about the five C standard flags. +It knows about the length modifiers h,l,L, and the conversions +cdeEfFgGinopsuxX, where F is a synonym for f. +Additionally, it accepts D,O,U as synonyms for ld,lo,lu. +(This is bad, and caused serious bugs later, when +support for %D disappeared.) +No locale-dependent radix character, +no thousands' separator, no NaN or infinity, no %m$ and *m$. +.PP +Linux libc5 knows about the five C standard flags and the ' flag, +locale, %m$ and *m$. +It knows about the length modifiers h,l,L,Z,q, but accepts L and q +both for long doubles and for long long integers (this is a bug). +It no longer recognizes FDOU, but adds the conversion character +.BR m , +which outputs +.IR strerror(errno) . +.PP +glibc 2.0 adds conversion characters C and S. +.PP +glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A. +.PP +glibc 2.2 adds the conversion character F with C99 semantics, and the +flag character I. +.SH NOTES +The glibc implementation of the functions +.BR snprintf () +and +.BR vsnprintf () +conforms to the C99 standard, i.e., behaves as described above, +since glibc version 2.1. +Until glibc 2.0.6 they would return \-1 +when the output was truncated. +.\" .SH HISTORY +.\" Unix V7 defines the three routines +.\" .BR printf (), +.\" .BR fprintf (), +.\" .BR sprintf (), +.\" and has the flag \-, the width or precision *, the length modifier l, +.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. +.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags +.\" #, + and and no longer mentions D,O,U,X. +.\" 2.11BSD has +.\" .BR vprintf (), +.\" .BR vfprintf (), +.\" .BR vsprintf (), +.\" and warns not to use D,O,U,X. +.\" 4.3BSD Reno has the flag 0, the length modifiers h and L, +.\" and the conversions n, p, E, G, X (with current meaning) +.\" and deprecates D,O,U. +.\" 4.4BSD introduces the functions +.\" .BR snprintf () +.\" and +.\" .BR vsnprintf (), +.\" and the length modifier q. +.\" FreeBSD also has functions +.\" .BR asprintf () +.\" and +.\" .BR vasprintf (), +.\" that allocate a buffer large enough for +.\" .BR sprintf (). +.\" In glibc there are functions +.\" .BR dprintf () +.\" and +.\" .BR vdprintf () +.\" that print to a file descriptor instead of a stream. +.SH BUGS +Because +.BR sprintf () +and +.BR vsprintf () +assume an arbitrarily long string, callers must be careful not to overflow +the actual space; this is often impossible to assure. +Note that the length +of the strings produced is locale-dependent and difficult to predict. +Use +.BR snprintf () +and +.BR vsnprintf () +instead (or +.BR asprintf () +and +.BR vasprintf ). +.PP +Linux libc4.[45] does not have a +.BR snprintf (), +but provides a libbsd that contains an +.BR snprintf () +equivalent to +.BR sprintf (), +i.e., one that ignores the +.I size +argument. +Thus, the use of +.BR snprintf () +with early libc4 leads to serious security problems. +.PP +Code such as +.BI printf( foo ); +often indicates a bug, since +.I foo +may contain a % character. +If +.I foo +comes from untrusted user input, it may contain %n, causing the +.BR printf () +call to write to memory and creating a security hole. +.\" .PP +.\" Some floating point conversions under early libc4 +.\" caused memory leaks. .SH EXAMPLE .br .if \w'\*(Pi'=0 .ds Pi pi @@ -850,145 +989,6 @@ make_message(const char *fmt, ...) } .fi .RE -.SH NOTES -The glibc implementation of the functions -.BR snprintf () -and -.BR vsnprintf () -conforms to the C99 standard, i.e., behaves as described above, -since glibc version 2.1. -Until glibc 2.0.6 they would return \-1 -when the output was truncated. -.SH "CONFORMING TO" -The -.BR fprintf (), -.BR printf (), -.BR sprintf (), -.BR vprintf (), -.BR vfprintf (), -and -.BR vsprintf () -functions conform to C89 and C99. -The -.BR snprintf () -and -.BR vsnprintf () -functions conform to C99. -.PP -Concerning the return value of -.BR snprintf (), -SUSv2 and C99 contradict each other: when -.BR snprintf () -is called with -.IR size =0 -then SUSv2 stipulates an unspecified return value less than 1, -while C99 allows -.I str -to be NULL in this case, and gives the return value (as always) -as the number of characters that would have been written in case -the output string has been large enough. -.PP -Linux libc4 knows about the five C standard flags. -It knows about the length modifiers h,l,L, and the conversions -cdeEfFgGinopsuxX, where F is a synonym for f. -Additionally, it accepts D,O,U as synonyms for ld,lo,lu. -(This is bad, and caused serious bugs later, when -support for %D disappeared.) -No locale-dependent radix character, -no thousands' separator, no NaN or infinity, no %m$ and *m$. -.PP -Linux libc5 knows about the five C standard flags and the ' flag, -locale, %m$ and *m$. -It knows about the length modifiers h,l,L,Z,q, but accepts L and q -both for long doubles and for long long integers (this is a bug). -It no longer recognizes FDOU, but adds the conversion character -.BR m , -which outputs -.IR strerror(errno) . -.PP -glibc 2.0 adds conversion characters C and S. -.PP -glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A. -.PP -glibc 2.2 adds the conversion character F with C99 semantics, and the -flag character I. -.\" .SH HISTORY -.\" Unix V7 defines the three routines -.\" .BR printf (), -.\" .BR fprintf (), -.\" .BR sprintf (), -.\" and has the flag \-, the width or precision *, the length modifier l, -.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. -.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags -.\" #, + and and no longer mentions D,O,U,X. -.\" 2.11BSD has -.\" .BR vprintf (), -.\" .BR vfprintf (), -.\" .BR vsprintf (), -.\" and warns not to use D,O,U,X. -.\" 4.3BSD Reno has the flag 0, the length modifiers h and L, -.\" and the conversions n, p, E, G, X (with current meaning) -.\" and deprecates D,O,U. -.\" 4.4BSD introduces the functions -.\" .BR snprintf () -.\" and -.\" .BR vsnprintf (), -.\" and the length modifier q. -.\" FreeBSD also has functions -.\" .BR asprintf () -.\" and -.\" .BR vasprintf (), -.\" that allocate a buffer large enough for -.\" .BR sprintf (). -.\" In glibc there are functions -.\" .BR dprintf () -.\" and -.\" .BR vdprintf () -.\" that print to a file descriptor instead of a stream. -.SH BUGS -Because -.BR sprintf () -and -.BR vsprintf () -assume an arbitrarily long string, callers must be careful not to overflow -the actual space; this is often impossible to assure. -Note that the length -of the strings produced is locale-dependent and difficult to predict. -Use -.BR snprintf () -and -.BR vsnprintf () -instead (or -.BR asprintf () -and -.BR vasprintf ). -.PP -Linux libc4.[45] does not have a -.BR snprintf (), -but provides a libbsd that contains an -.BR snprintf () -equivalent to -.BR sprintf (), -i.e., one that ignores the -.I size -argument. -Thus, the use of -.BR snprintf () -with early libc4 leads to serious security problems. -.PP -Code such as -.BI printf( foo ); -often indicates a bug, since -.I foo -may contain a % character. -If -.I foo -comes from untrusted user input, it may contain %n, causing the -.BR printf () -call to write to memory and creating a security hole. -.\" .PP -.\" Some floating point conversions under early libc4 -.\" caused memory leaks. .SH "SEE ALSO" .BR printf (1), .BR asprintf (3), diff --git a/man3/profil.3 b/man3/profil.3 index e1b0cd591..64535420c 100644 --- a/man3/profil.3 +++ b/man3/profil.3 @@ -56,6 +56,8 @@ If is NULL, profiling is disabled. .SH "RETURN VALUE" Zero is always returned. +.SH "CONFORMING TO" +Similar to a call in SVr4 (but not POSIX.1-2001). .SH BUGS .BR profil () cannot be used on a program that also uses @@ -64,8 +66,6 @@ itimers. True kernel profiling provides more accurate results. Libc 4.4 contained a kernel patch providing a system call profil. -.SH "CONFORMING TO" -Similar to a call in SVr4 (but not POSIX.1-2001). .SH "SEE ALSO" .BR gprof (1), .BR setitimer (2), diff --git a/man3/program_invocation_name.3 b/man3/program_invocation_name.3 index ce5fae804..d49e7dec1 100644 --- a/man3/program_invocation_name.3 +++ b/man3/program_invocation_name.3 @@ -50,13 +50,13 @@ with all text up to and including the final slash (/), if any, removed. These variables are automatically initialised by the glibc run-time startup code. +.SH "CONFORMING TO" +These variables are GNU extensions, and should not be +used in programs intended to be portable. .SH NOTES The Linux-specific .I /proc/[number]/cmdline file provides access to similar information. -.SH "CONFORMING TO" -These variables are GNU extensions, and should not be -used in programs intended to be portable. .SH SEE ALSO .BR proc (5), .BR feature_test_macros (7) diff --git a/man3/putenv.3 b/man3/putenv.3 index 3635b3166..673edd454 100644 --- a/man3/putenv.3 +++ b/man3/putenv.3 @@ -63,6 +63,8 @@ or non-zero if an error occurs. .TP .B ENOMEM Insufficient space to allocate new environment. +.SH "CONFORMING TO" +SVr4, POSIX.1-2001, 4.3BSD .SH NOTES The .BR putenv () @@ -101,8 +103,6 @@ This has been fixed in glibc 2.1.2. The 4.4BSD version, like glibc 2.0, uses a copy. .LP SUSv2 removes the `const' from the prototype, and so does glibc 2.1.3. -.SH "CONFORMING TO" -SVr4, POSIX.1-2001, 4.3BSD .SH "SEE ALSO" .BR clearenv (3), .BR getenv (3), diff --git a/man3/qecvt.3 b/man3/qecvt.3 index 609b7a0ce..7bb9965e8 100644 --- a/man3/qecvt.3 +++ b/man3/qecvt.3 @@ -55,17 +55,17 @@ See .BR ecvt (3) and .BR gcvt (3). -.SH NOTES -These functions are obsolete. -Instead, -.BR sprintf (3) -is recommended. .SH "CONFORMING TO" SVr4. Not seen in most common Unix implementations, but occurs in SunOS. Not supported by libc4 and libc5. Supported by glibc. +.SH NOTES +These functions are obsolete. +Instead, +.BR sprintf (3) +is recommended. .SH "SEE ALSO" .BR ecvt (3), .BR ecvt_r (3), diff --git a/man3/rand.3 b/man3/rand.3 index ef27552fb..5c1ef04fa 100644 --- a/man3/rand.3 +++ b/man3/rand.3 @@ -96,26 +96,15 @@ between 0 and RAND_MAX. The .BR srand () function returns no value. -.SH EXAMPLE -POSIX.1-2001 gives the following example of an implementation of +.SH "CONFORMING TO" +The functions .BR rand () and -.BR srand (), -possibly useful when one needs the same sequence on two different machines. -.sp -.nf - static unsigned long next = 1; - - /* RAND_MAX assumed to be 32767 */ - int myrand(void) { - next = next * 1103515245 + 12345; - return((unsigned)(next/65536) % 32768); - } - - void mysrand(unsigned seed) { - next = seed; - } -.fi +.BR srand () +conform to SVr4, 4.3BSD, C89, C99, POSIX.1-2001. +The function +.BR rand_r () +is from POSIX.1-2001. .SH NOTES The versions of .BR rand () @@ -169,15 +158,26 @@ in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's .IR "The Art of Computer Programming" , volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: Addison-Wesley Publishing Company, 1981. -.SH "CONFORMING TO" -The functions +.SH EXAMPLE +POSIX.1-2001 gives the following example of an implementation of .BR rand () and -.BR srand () -conform to SVr4, 4.3BSD, C89, C99, POSIX.1-2001. -The function -.BR rand_r () -is from POSIX.1-2001. +.BR srand (), +possibly useful when one needs the same sequence on two different machines. +.sp +.nf + static unsigned long next = 1; + + /* RAND_MAX assumed to be 32767 */ + int myrand(void) { + next = next * 1103515245 + 12345; + return((unsigned)(next/65536) % 32768); + } + + void mysrand(unsigned seed) { + next = seed; + } +.fi .SH "SEE ALSO" .BR drand48 (3), .BR random (3) diff --git a/man3/random.3 b/man3/random.3 index b32050827..2918c67ba 100644 --- a/man3/random.3 +++ b/man3/random.3 @@ -115,14 +115,14 @@ array, or NULL on error. .B EINVAL A state array of less than 8 bytes was specified to .BR initstate (). +.SH "CONFORMING TO" +4.3BSD, POSIX.1-2001. .SH NOTES Current "optimal" values for the size of the state array \fIn\fP are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to the nearest known amount. Using less than 8 bytes will cause an error. -.SH "CONFORMING TO" -4.3BSD, POSIX.1-2001. .SH "SEE ALSO" .BR rand (3), .BR srand (3) diff --git a/man3/realpath.3 b/man3/realpath.3 index 00ccaa331..3c6ff611e 100644 --- a/man3/realpath.3 +++ b/man3/realpath.3 @@ -94,54 +94,6 @@ The named file does not exist. .TP .B ENOTDIR A component of the path prefix is not a directory. -.SH NOTES -The glibc implementation of -.BR realpath () -provides a non-standard extension. -If -.I resolved_path -is specified as NULL, then -.BR realpath () -uses -.BR malloc (3) -to allocate a buffer of up to PATH_MAX bytes -to hold the resolved pathname, -and returns a pointer to this buffer. -The caller should deallocate this buffer using -.BR free (3). -.\" Even if we use resolved_path == NULL, then realpath() will still -.\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX -.\" bytes -- MTK, Dec 04 -.SH BUGS -Avoid using this function. -It is broken by design since (unless -using the non-standard -.I "resolved_path\ ==\ NULL" -feature) it is -impossible to determine a suitable size for the output buffer, -.IR resolved_path . -According to POSIX a buffer of size PATH_MAX suffices, but -PATH_MAX need not be a defined constant, and may have to be -obtained using -.BR pathconf (3). -And asking -.BR pathconf (3) -does not really help, since on the one hand POSIX warns that -the result of -.BR pathconf (3) -may be huge and unsuitable for mallocing memory. -And on the other -hand -.BR pathconf (3) -may return \-1 to signify that PATH_MAX is not bounded. -.LP -The libc4 and libc5 implementation contains a buffer overflow -(fixed in libc-5.4.13). -Thus, set-user-ID programs like mount need a private version. -.\" .SH HISTORY -.\" The -.\" .BR realpath () -.\" function first appeared in 4.4BSD, contributed by Jan-Simon Pendry. .SH VERSIONS On Linux this function appeared in libc 4.5.21. .SH "CONFORMING TO" @@ -177,6 +129,54 @@ The prototype of .BR realpath () is given in in libc4 and libc5, but in everywhere else. +.SH NOTES +The glibc implementation of +.BR realpath () +provides a non-standard extension. +If +.I resolved_path +is specified as NULL, then +.BR realpath () +uses +.BR malloc (3) +to allocate a buffer of up to PATH_MAX bytes +to hold the resolved pathname, +and returns a pointer to this buffer. +The caller should deallocate this buffer using +.BR free (3). +.\" Even if we use resolved_path == NULL, then realpath() will still +.\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX +.\" bytes -- MTK, Dec 04 +.\" .SH HISTORY +.\" The +.\" .BR realpath () +.\" function first appeared in 4.4BSD, contributed by Jan-Simon Pendry. +.SH BUGS +Avoid using this function. +It is broken by design since (unless +using the non-standard +.I "resolved_path\ ==\ NULL" +feature) it is +impossible to determine a suitable size for the output buffer, +.IR resolved_path . +According to POSIX a buffer of size PATH_MAX suffices, but +PATH_MAX need not be a defined constant, and may have to be +obtained using +.BR pathconf (3). +And asking +.BR pathconf (3) +does not really help, since on the one hand POSIX warns that +the result of +.BR pathconf (3) +may be huge and unsuitable for mallocing memory. +And on the other +hand +.BR pathconf (3) +may return \-1 to signify that PATH_MAX is not bounded. +.LP +The libc4 and libc5 implementation contains a buffer overflow +(fixed in libc-5.4.13). +Thus, set-user-ID programs like mount need a private version. .SH "SEE ALSO" .BR readlink (2), .BR canonicalize_file_name (3), diff --git a/man3/remove.3 b/man3/remove.3 index c4ad951af..eabe26bc5 100644 --- a/man3/remove.3 +++ b/man3/remove.3 @@ -69,15 +69,15 @@ and .BR rmdir (2). .SH "CONFORMING TO" C89, C99, 4.3BSD, POSIX.1-2001. -.SH BUGS -Infelicities in the protocol underlying NFS can cause the unexpected -disappearance of files which are still being used. .SH NOTES Under libc4 and libc5, .BR remove () was an alias for .BR unlink (2) (and hence would not remove directories). +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. .SH "SEE ALSO" .BR rm (1), .BR link (2), diff --git a/man3/rint.3 b/man3/rint.3 index 8897be6f9..852d8034e 100644 --- a/man3/rint.3 +++ b/man3/rint.3 @@ -63,6 +63,8 @@ No errors other than EDOM and ERANGE can occur. If \fIx\fP is NaN, then NaN is returned and .I errno may be set to EDOM. +.SH "CONFORMING TO" +C99. .SH NOTES SUSv2 and POSIX.1-2001 contain text about overflow (which might set .I errno @@ -74,8 +76,6 @@ of the exponent is smaller than the number of mantissa bits. For the IEEE-754 standard 32-bit and 64-bit floating point numbers the maximum value of the exponent is 128 (resp. 1024), and the number of mantissa bits is 24 (resp. 53).) -.SH "CONFORMING TO" -C99. .SH "SEE ALSO" .BR ceil (3), .BR floor (3), diff --git a/man3/round.3 b/man3/round.3 index 93809b138..c1d49c962 100644 --- a/man3/round.3 +++ b/man3/round.3 @@ -49,6 +49,8 @@ No errors other than EDOM and ERANGE can occur. If \fIx\fP is NaN, then NaN is returned and .I errno may be set to EDOM. +.SH "CONFORMING TO" +C99. .SH NOTES POSIX.1-2001 contains text about overflow (which might set .I errno @@ -60,8 +62,6 @@ of the exponent is smaller than the number of mantissa bits. For the IEEE-754 standard 32-bit and 64-bit floating point numbers the maximum value of the exponent is 128 (resp. 1024), and the number of mantissa bits is 24 (resp. 53).) -.SH "CONFORMING TO" -C99. .SH "SEE ALSO" .BR ceil (3), .BR floor (3), diff --git a/man3/rtime.3 b/man3/rtime.3 index 627e1411b..fbade730a 100644 --- a/man3/rtime.3 +++ b/man3/rtime.3 @@ -48,6 +48,27 @@ The number of returned bytes is not 4. .TP .B ETIMEDOUT The waiting time as defined in timeout has expired. +.SH "NOTES" +Only IPV4 is supported. +.LP +Some +.I in.timed +versions only support TCP. +Try the above example program with +.I use_tcp +set to 1. +.LP +Libc5 uses the prototype +.br +int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); +.br +and requires +.I +instead of +.IR . +.SH "BUGS" +.BR rtime () +in glibc <= 2.2.5 does not work properly on 64bit machines. .SH "EXAMPLE" This example requires that port 37 is up and open. You may check @@ -93,27 +114,6 @@ main(void) exit(EXIT_SUCCESS); } .fi -.SH "NOTES" -Only IPV4 is supported. -.LP -Some -.I in.timed -versions only support TCP. -Try the above example program with -.I use_tcp -set to 1. -.LP -Libc5 uses the prototype -.br -int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); -.br -and requires -.I -instead of -.IR . -.SH "BUGS" -.BR rtime () -in glibc <= 2.2.5 does not work properly on 64bit machines. .SH "SEE ALSO" .BR netdate (1), .BR ntpdate (1), diff --git a/man3/rtnetlink.3 b/man3/rtnetlink.3 index 933ab4337..6870cca21 100644 --- a/man3/rtnetlink.3 +++ b/man3/rtnetlink.3 @@ -75,6 +75,8 @@ bytes of data plus the header. returns the amount of space which will be needed in the message with .I len bytes of data. +.SH BUGS +This manual page is lacking and incomplete. .SH EXAMPLE .\" FIXME would be better to use libnetlink in the EXAMPLE code here @@ -107,8 +109,6 @@ Creating a rtnetlink message to set a MTU of a device. memcpy(RTA_DATA(rta), &mtu, sizeof(mtu)); send(rtnetlink_sk, &req, req.n.nlmsg_len); .fi -.SH BUGS -This manual page is lacking and incomplete. .SH "SEE ALSO" .BR netlink (3), .BR netlink (7), diff --git a/man3/sem_close.3 b/man3/sem_close.3 index ee8301a01..7b7572048 100644 --- a/man3/sem_close.3 +++ b/man3/sem_close.3 @@ -35,10 +35,6 @@ closes the named semaphore referred to by .IR sem , allowing any resources that the system has allocated to the calling process for this semaphore to be freed. -.SH NOTES -All open named semaphores are automatically closed on process -termination, or upon -.BR execve (2). .SH RETURN VALUE On success .BR sem_close () @@ -52,6 +48,10 @@ set to indicate the error. is not a valid semaphore. .SH CONFORMING TO POSIX.1-2001. +.SH NOTES +All open named semaphores are automatically closed on process +termination, or upon +.BR execve (2). .SH "SEE ALSO" .BR sem_getvalue (3), .BR sem_open (3), diff --git a/man3/sem_getvalue.3 b/man3/sem_getvalue.3 index 6e32b35b3..73dd56aef 100644 --- a/man3/sem_getvalue.3 +++ b/man3/sem_getvalue.3 @@ -57,12 +57,12 @@ is set to indicate the error. .B EINVAL .I sem is not a valid semaphore. +.SH CONFORMING TO +POSIX.1-2001. .SH NOTES The value of the semaphore may already have changed by the time .BR sem_getvalue () returns. -.SH CONFORMING TO -POSIX.1-2001. .SH "SEE ALSO" .BR sem_post (3), .BR sem_wait (3), diff --git a/man3/sem_wait.3 b/man3/sem_wait.3 index 91b27d38e..84aa2cbfb 100644 --- a/man3/sem_wait.3 +++ b/man3/sem_wait.3 @@ -128,6 +128,8 @@ is less than 0, or greater than or equal to 1000 million. The call timed out before the semaphore could be locked. .\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition .\" was detected", but this does not occur on Linux(?). +.SH CONFORMING TO +POSIX.1-2001. .SH NOTES A signal handler always interrupts a blocked call to one of these functions, regardless of the use of the @@ -136,8 +138,6 @@ one of these functions, regardless of the use of the flag. .\" sem_wait() is always interrupted on most other implementations, .\" but on FreeBSD 5.4 SA_RESTART does cause restarting. -.SH CONFORMING TO -POSIX.1-2001. .SH EXAMPLE .PP The (somewhat trivial) program shown below operates on an diff --git a/man3/setaliasent.3 b/man3/setaliasent.3 index 35e8bbb97..5916665f6 100644 --- a/man3/setaliasent.3 +++ b/man3/setaliasent.3 @@ -80,18 +80,30 @@ struct aliasent { int alias_local; }; .fi -.SH FILES -The default alias database is the file -.IR /etc/aliases . -This can be changed in the -.I /etc/nsswitch.conf -file. .SH "RETURN VALUE" The functions .BR getaliasent_r () and .BR getaliasbyname_r () return a non-zero value on error. +.SH FILES +The default alias database is the file +.IR /etc/aliases . +This can be changed in the +.I /etc/nsswitch.conf +file. +.SH "CONFORMING TO" +These routines are glibc-specific. +The NeXT has similar routines +.RS +.nf +#include +void alias_setent(void); +void alias_endent(void); +alias_ent *alias_getent(void); +alias_ent *alias_getbyname(char *name); +.fi +.RE .SH EXAMPLE The following example compiles with .IR "gcc example.c \-o example" . @@ -122,18 +134,6 @@ main(void) exit(EXIT_SUCCESS); } .fi -.SH "CONFORMING TO" -These routines are glibc-specific. -The NeXT has similar routines -.RS -.nf -#include -void alias_setent(void); -void alias_endent(void); -alias_ent *alias_getent(void); -alias_ent *alias_getbyname(char *name); -.fi -.RE .SH "SEE ALSO" .BR getgrent (3), .BR getpwent (3), diff --git a/man3/setnetgrent.3 b/man3/setnetgrent.3 index e3e8a1dac..cb5c7af9e 100644 --- a/man3/setnetgrent.3 +++ b/man3/setnetgrent.3 @@ -66,12 +66,12 @@ The function can be used for this without calling the above three functions. Again, a NULL pointer is a wildcard and matches any string. The function is thread-safe. +.SH "RETURN VALUE" +These functions return 1 on success and 0 for failure. .SH FILES .I /etc/netgroup .br .I /etc/nsswitch.conf -.SH "RETURN VALUE" -These functions return 1 on success and 0 for failure. .SH NOTES In the BSD implementation, .BR setnetgrent () diff --git a/man3/shm_open.3 b/man3/shm_open.3 index 3580124a1..87ce76381 100644 --- a/man3/shm_open.3 +++ b/man3/shm_open.3 @@ -225,6 +225,12 @@ An attempt was to made to a .I name that does not exist. +.SH "CONFORMING TO" +POSIX.1-2001. +.LP +POSIX.1-2001 says that the group ownership of a newly created shared +memory object is set to either the calling process's effective group ID +or "a system default group ID" .SH "NOTES" These functions are provided in glibc 2.2 and later. Programs using these @@ -246,12 +252,6 @@ The POSIX shared memory object implementation on Linux 2.4 makes use of a dedicated file system, which is normally mounted under .IR /dev/shm . -.SH "CONFORMING TO" -POSIX.1-2001. -.LP -POSIX.1-2001 says that the group ownership of a newly created shared -memory object is set to either the calling process's effective group ID -or "a system default group ID" .SH "SEE ALSO" .BR close (2), .BR fchmod (2), diff --git a/man3/sigset.3 b/man3/sigset.3 index 7a1915983..7adf3a256 100644 --- a/man3/sigset.3 +++ b/man3/sigset.3 @@ -159,6 +159,9 @@ For .BR sigignore (), see the errors under .BR sigaction (2). +.SH "CONFORMING TO" +SVr4, POSIX.1-2001. +These functions are obsolete: do not use them in new programs. .SH NOTES These functions appeared in glibc version 2.1. @@ -242,9 +245,6 @@ Instead, the previous disposition of the signal is returned. .\" previous disposition if it had not been blocked. .\" Otherwise, SIG_ERR shall be returned and errno set to .\" indicate the error. -.SH "CONFORMING TO" -SVr4, POSIX.1-2001. -These functions are obsolete: do not use them in new programs. .SH "SEE ALSO" .BR kill (2), .BR pause (2), diff --git a/man3/sigvec.3 b/man3/sigvec.3 index af095b3d1..30aa0e6af 100644 --- a/man3/sigvec.3 +++ b/man3/sigvec.3 @@ -205,6 +205,12 @@ See the ERRORS under .BR sigaction (2) and .BR sigprocmask (2). +.SH "CONFORMING TO" +All of these functions were in +4.3BSD, except +.BR siggetmask (), +whose origin is unclear. +These functions are obsolete: do not use them in new programs. .SH NOTES On 4.3BSD, the .BR signal () @@ -230,12 +236,6 @@ but this function has a different argument on the two systems. See .BR sigpause (3) for details. -.SH "CONFORMING TO" -All of these functions were in -4.3BSD, except -.BR siggetmask (), -whose origin is unclear. -These functions are obsolete: do not use them in new programs. .SH "SEE ALSO" .BR kill (2), .BR pause (2), diff --git a/man3/sockatmark.3 b/man3/sockatmark.3 index 374da0384..b1350a007 100644 --- a/man3/sockatmark.3 +++ b/man3/sockatmark.3 @@ -50,6 +50,11 @@ is not a valid file descriptor. is not a file descriptor to which .BR sockatmark () can be applied. +.SH VERSIONS +.BR sockatmark () +was added to glibc in version 2.2.4. +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES If .BR sockatmark () @@ -68,11 +73,6 @@ is implemented using the .B SIOCATMARK .BR ioctl (2) operation. -.SH "CONFORMING TO" -POSIX.1-2001 -.SH VERSIONS -.BR sockatmark () -was added to glibc in version 2.2.4. .SH BUGS Prior to glibc 2.4, .BR sockatmark () diff --git a/man3/stdarg.3 b/man3/stdarg.3 index 465aeb430..dbbbc012d 100644 --- a/man3/stdarg.3 +++ b/man3/stdarg.3 @@ -201,46 +201,6 @@ Some systems that do not supply have .B __va_copy instead, since that was the name used in the draft proposal. -.SH EXAMPLE -The function -.I foo -takes a string of format characters and prints out the argument associated -with each format character based on the type. -.RS -.nf - -#include -#include - -void -foo(char *fmt, ...) -{ - va_list ap; - int d; - char c, *s; - - va_start(ap, fmt); - while (*fmt) - switch(*fmt++) { - case 's': /* string */ - s = va_arg(ap, char *); - printf("string %s\en", s); - break; - case 'd': /* int */ - d = va_arg(ap, int); - printf("int %d\en", d); - break; - case 'c': /* char */ - /* need a cast here since va_arg only - takes fully promoted types */ - c = (char) va_arg(ap, int); - printf("char %c\en", c); - break; - } - va_end(ap); -} -.fi -.RE .SH "CONFORMING TO" The .BR va_start (), @@ -303,3 +263,43 @@ pass all of their arguments on to a function that takes a .B va_list argument, such as .BR vfprintf (3). +.SH EXAMPLE +The function +.I foo +takes a string of format characters and prints out the argument associated +with each format character based on the type. +.RS +.nf + +#include +#include + +void +foo(char *fmt, ...) +{ + va_list ap; + int d; + char c, *s; + + va_start(ap, fmt); + while (*fmt) + switch(*fmt++) { + case 's': /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case 'd': /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case 'c': /* char */ + /* need a cast here since va_arg only + takes fully promoted types */ + c = (char) va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.fi +.RE diff --git a/man3/stpcpy.3 b/man3/stpcpy.3 index 472d3b4fa..1dcd3ca94 100644 --- a/man3/stpcpy.3 +++ b/man3/stpcpy.3 @@ -46,28 +46,30 @@ The strings may not overlap, and the destination string returns a pointer to the \fBend\fP of the string \fIdest\fP (that is, the address of the terminating null byte) rather than the beginning. +.SH "CONFORMING TO" +This function is not part of the C or POSIX.1 standards, and is +not customary on Unix systems, but is not a GNU invention either. +Perhaps it comes from MS-DOS. .SH EXAMPLE For example, this program uses .BR stpcpy () to concatenate \fBfoo\fP and \fBbar\fP to produce \fBfoobar\fP, which it then prints. +.in +0.5i .nf - #include +#include - int - main (void) - { - char *to = buffer; - to = stpcpy(to, "foo"); - to = stpcpy(to, "bar"); - printf("%s\\n", buffer); - } +int +main (void) +{ + char *to = buffer; + to = stpcpy(to, "foo"); + to = stpcpy(to, "bar"); + printf("%s\\n", buffer); +} .fi -.SH "CONFORMING TO" -This function is not part of the C or POSIX.1 standards, and is -not customary on Unix systems, but is not a GNU invention either. -Perhaps it comes from MS-DOS. +.in .SH "SEE ALSO" .BR bcopy (3), .BR memccpy (3), diff --git a/man3/strcpy.3 b/man3/strcpy.3 index ad494e711..38afa973d 100644 --- a/man3/strcpy.3 +++ b/man3/strcpy.3 @@ -70,6 +70,8 @@ and .BR strncpy () functions return a pointer to the destination string \fIdest\fP. +.SH "CONFORMING TO" +SVr4, 4.3BSD, C89, C99. .SH BUGS If the destination string of a .BR strcpy () @@ -77,8 +79,6 @@ is not large enough (that is, if the programmer was stupid/lazy, and failed to check the size before copying) then anything might happen. Overflowing fixed length strings is a favourite cracker technique. -.SH "CONFORMING TO" -SVr4, 4.3BSD, C89, C99. .SH "SEE ALSO" .BR bcopy (3), .BR memccpy (3), diff --git a/man3/strfmon.3 b/man3/strfmon.3 index 9071cdf81..9c7a4013d 100644 --- a/man3/strfmon.3 +++ b/man3/strfmon.3 @@ -118,6 +118,9 @@ provided the string, including the terminating null byte, fits. Otherwise, it sets .I errno to E2BIG, returns \-1, and the contents of the array is undefined. +.SH "CONFORMING TO" +Not in POSIX.1-2001. +Present on several other systems. .SH EXAMPLE The call .RS @@ -153,9 +156,6 @@ and Portuguese locales yield .br [ **1234$57Esc] [ **1.234$57PTE ] .RE -.SH "CONFORMING TO" -Not in POSIX.1-2001. -Present on several other systems. .SH "SEE ALSO" .BR setlocale (3), .BR sprintf (3), diff --git a/man3/strptime.3 b/man3/strptime.3 index 0bd18adef..03b145e7e 100644 --- a/man3/strptime.3 +++ b/man3/strptime.3 @@ -273,28 +273,6 @@ of the format string and therefore an error occurred the function returns NULL. .SH "CONFORMING TO" SUSv2, POSIX.1-2001. -.SH EXAMPLE -The following example demonstrates the use of -.BR strptime () -and -.BR strftime (3). -.sp -.nf -#include -#include - -int -main(void) -{ - struct tm tm; - char buf[255]; - - strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm); - strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); - puts(buf); - exit(EXIT_SUCCESS); -} -.fi .SH NOTES .LP In principle, this function does not initialize \fBtm\fP but @@ -372,6 +350,28 @@ Leap seconds are not counted unless leap second support is available. .LP The GNU libc implementation does not require whitespace between two field descriptors. +.SH EXAMPLE +The following example demonstrates the use of +.BR strptime () +and +.BR strftime (3). +.sp +.nf +#include +#include + +int +main(void) +{ + struct tm tm; + char buf[255]; + + strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm); + strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); + puts(buf); + exit(EXIT_SUCCESS); +} +.fi .SH "SEE ALSO" .BR time (2), .BR getdate (3), diff --git a/man3/strsep.3 b/man3/strsep.3 index 0ffae734a..5706f4e83 100644 --- a/man3/strsep.3 +++ b/man3/strsep.3 @@ -55,6 +55,8 @@ The .BR strsep () function returns a pointer to the token, that is, it returns the original value of *\fIstringp\fP. +.SH "CONFORMING TO" +4.4BSD .SH NOTES The .BR strsep () @@ -69,8 +71,6 @@ This function suffers from the same problems as .BR strtok (3). In particular, it modifies the original string. Avoid it. -.SH "CONFORMING TO" -4.4BSD .SH "SEE ALSO" .BR index (3), .BR memchr (3), diff --git a/man3/strstr.3 b/man3/strstr.3 index 061d46a48..abb687aa1 100644 --- a/man3/strstr.3 +++ b/man3/strstr.3 @@ -58,12 +58,6 @@ but ignores the case of both arguments. .SH "RETURN VALUE" These functions return a pointer to the beginning of the substring, or NULL if the substring is not found. -.SH BUGS -Early versions of Linux libc (like 4.5.26) would not allow -an empty \fIneedle\fP argument for -.BR strstr (). -Later versions (like 4.6.27) work correctly, -and return \fIhaystack\fP when \fIneedle\fP is empty. .SH "CONFORMING TO" The .BR strstr () @@ -71,6 +65,12 @@ function conforms to C89 and C99. The .BR strcasestr () function is a non-standard extension. +.SH BUGS +Early versions of Linux libc (like 4.5.26) would not allow +an empty \fIneedle\fP argument for +.BR strstr (). +Later versions (like 4.6.27) work correctly, +and return \fIhaystack\fP when \fIneedle\fP is empty. .SH "SEE ALSO" .BR index (3), .BR memchr (3), diff --git a/man3/strtok.3 b/man3/strtok.3 index 1ba125d68..c39b12739 100644 --- a/man3/strtok.3 +++ b/man3/strtok.3 @@ -90,6 +90,38 @@ In subsequent calls, \fIstr\fP should be NULL, and Different strings may be parsed concurrently using sequences of calls to .BR strtok_r () that specify different \fIsaveptr\fP arguments. +.SH "RETURN VALUE" +The +.BR strtok () +and +.BR strtok_r () +functions return a pointer to +the next token, or NULL if there are no more tokens. +.SH "CONFORMING TO" +.TP +.BR strtok () +SVr4, POSIX.1-2001, 4.3BSD, C89, C99. +.TP +.BR strtok_r () +POSIX.1-2001 +.SH BUGS +Avoid using these functions. +If you do use them, note that: +.PP +.RS +These functions modify their first argument. +.PP +These functions cannot be used on constant strings. +.PP +The identity of the delimiting character is lost. +.PP +The +.BR strtok () +function uses a static buffer while parsing, so it's not thread safe. +Use +.BR strtok_r () +if this matters to you. +.RE .SH EXAMPLE The following program uses nested loops that employ .BR strtok_r () @@ -149,38 +181,6 @@ $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/' 3: yyy --> yyy .fi -.SH BUGS -Avoid using these functions. -If you do use them, note that: -.PP -.RS -These functions modify their first argument. -.PP -These functions cannot be used on constant strings. -.PP -The identity of the delimiting character is lost. -.PP -The -.BR strtok () -function uses a static buffer while parsing, so it's not thread safe. -Use -.BR strtok_r () -if this matters to you. -.RE -.SH "RETURN VALUE" -The -.BR strtok () -and -.BR strtok_r () -functions return a pointer to -the next token, or NULL if there are no more tokens. -.SH "CONFORMING TO" -.TP -.BR strtok () -SVr4, POSIX.1-2001, 4.3BSD, C89, C99. -.TP -.BR strtok_r () -POSIX.1-2001 .SH "SEE ALSO" .BR index (3), .BR memchr (3), diff --git a/man3/strtol.3 b/man3/strtol.3 index 961efb07c..1f0a594e8 100644 --- a/man3/strtol.3 +++ b/man3/strtol.3 @@ -109,6 +109,11 @@ The resulting value was out of range. .LP The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case no conversion was performed (no digits seen, and 0 returned). +.SH "CONFORMING TO" +.BR strtol () +conforms to SVr4, 4.3BSD, C89, C99 and POSIX.1-2001, and +.BR strtoll () +to C99 and POSIX.1-2001. .SH NOTES Since .BR strtol () @@ -141,11 +146,6 @@ may be equivalent to .BR strtoll () or to .BR strtol (). -.SH "CONFORMING TO" -.BR strtol () -conforms to SVr4, 4.3BSD, C89, C99 and POSIX.1-2001, and -.BR strtoll () -to C99 and POSIX.1-2001. .SH EXAMPLE The program shown below demonstrates the use of .BR strtol (). diff --git a/man3/strtoul.3 b/man3/strtoul.3 index dc3627e52..9d73da771 100644 --- a/man3/strtoul.3 +++ b/man3/strtoul.3 @@ -110,6 +110,11 @@ The resulting value was out of range. .LP The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case no conversion was performed (no digits seen, and 0 returned). +.SH "CONFORMING TO" +.BR strtoul () +conforms to SVr4, C89, C99 and POSIX-2001, and +.BR strtoull () +to C99 and POSIX.1-2001. .SH NOTES Since .BR strtoul () @@ -144,11 +149,6 @@ or to Negative values are considered valid input and are silently converted to the equivalent unsigned long value. -.SH "CONFORMING TO" -.BR strtoul () -conforms to SVr4, C89, C99 and POSIX-2001, and -.BR strtoull () -to C99 and POSIX.1-2001. .SH EXAMPLE See the example on the .BR strtol (3) diff --git a/man3/sysv_signal.3 b/man3/sysv_signal.3 index e8252d7ae..1a4a90913 100644 --- a/man3/sysv_signal.3 +++ b/man3/sysv_signal.3 @@ -55,6 +55,8 @@ on error. .SH ERRORS As for .BR signal (2). +.SH "CONFORMING TO" +This function is non-standard. .SH NOTES Use of .BR sysv_signal () @@ -78,8 +80,6 @@ The use of is a GNU extension; this type is only defined if the _GNU_SOURCE feature test macro is defined. -.SH "CONFORMING TO" -This function is non-standard. .SH "SEE ALSO" .BR sigaction (2), .BR signal (2), diff --git a/man3/tcgetpgrp.3 b/man3/tcgetpgrp.3 index 1ebd87dde..3ab8eb386 100644 --- a/man3/tcgetpgrp.3 +++ b/man3/tcgetpgrp.3 @@ -98,14 +98,14 @@ of the calling process. .I pgrp has a supported value, but is not the process group ID of a process in the same session as the calling process. +.SH "CONFORMING TO" +POSIX.1-2001. .SH NOTES These functions are implemented via the TIOCGPGRP and TIOCSPGRP ioctls. .SS History The ioctls appeared in 4.2BSD. The functions are POSIX inventions. -.SH "CONFORMING TO" -POSIX.1-2001. .SH "SEE ALSO" .BR setpgid (2), .BR setsid (2) diff --git a/man3/tcgetsid.3 b/man3/tcgetsid.3 index 7891d81f1..696fb15a4 100644 --- a/man3/tcgetsid.3 +++ b/man3/tcgetsid.3 @@ -56,12 +56,12 @@ is not a valid file descriptor. The calling process does not have a controlling terminal, or it has one but it is not described by .IR fd . +.SH "CONFORMING TO" +POSIX.1-2001 .SH NOTES This function is implemented via the TIOCGSID .BR ioctl (2), present since Linux 2.1.71. -.SH "CONFORMING TO" -POSIX.1-2001 .SH "SEE ALSO" .BR getsid (2) diff --git a/man3/tempnam.3 b/man3/tempnam.3 index d4ff556b5..837269131 100644 --- a/man3/tempnam.3 +++ b/man3/tempnam.3 @@ -81,6 +81,8 @@ filename, or NULL if a unique name cannot be generated. .TP .B ENOMEM Allocation of storage failed. +.SH "CONFORMING TO" +SVr4, 4.3BSD, POSIX.1-2001 .SH NOTES Although .BR tempnam (3) @@ -140,8 +142,6 @@ Use or .BR tmpfile (3) instead. -.SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001 .SH "SEE ALSO" .BR mkstemp (3), .BR mktemp (3), diff --git a/man3/timegm.3 b/man3/timegm.3 index 315c67eea..9bea9efa9 100644 --- a/man3/timegm.3 +++ b/man3/timegm.3 @@ -39,6 +39,9 @@ are the inverses to .BR localtime (3) and .BR gmtime (3). +.SH "CONFORMING TO" +Not in POSIX.1-2001. +Present on the BSDs. .SH NOTES These functions are GNU extensions. The @@ -81,9 +84,6 @@ my_timegm(struct tm *tm) } .fi .RE -.SH "CONFORMING TO" -Not in POSIX.1-2001. -Present on the BSDs. .SH "SEE ALSO" .BR gmtime (3), .BR localtime (3), diff --git a/man3/tmpnam.3 b/man3/tmpnam.3 index 46e023420..0ac7af75f 100644 --- a/man3/tmpnam.3 +++ b/man3/tmpnam.3 @@ -70,6 +70,8 @@ function returns a pointer to a unique temporary filename, or NULL if a unique name cannot be generated. .SH ERRORS No errors are defined. +.SH "CONFORMING TO" +SVr4, 4.3BSD, C89, C99, POSIX.1-2001. .SH NOTES The .BR tmpnam () @@ -128,8 +130,6 @@ Use or .BR tmpfile (3) instead. -.SH "CONFORMING TO" -SVr4, 4.3BSD, C89, C99, POSIX.1-2001. .SH "SEE ALSO" .BR mkstemp (3), .BR mktemp (3), diff --git a/man3/tsearch.3 b/man3/tsearch.3 index 4642d5c8b..60ae2a2b7 100644 --- a/man3/tsearch.3 +++ b/man3/tsearch.3 @@ -151,6 +151,11 @@ and .BR tdelete () also return NULL if \fIrootp\fP was NULL on entry. +.SH "CONFORMING TO" +SVr4, POSIX.1-2001. +The function +.BR tdestroy () +is a GNU extension. .SH NOTES .BR twalk () takes a pointer to the root, while the other functions @@ -247,11 +252,6 @@ main(void) exit(EXIT_SUCCESS); } .fi -.SH "CONFORMING TO" -SVr4, POSIX.1-2001. -The function -.BR tdestroy () -is a GNU extension. .SH "SEE ALSO" .BR bsearch (3), .BR hsearch (3), diff --git a/man3/ttyslot.3 b/man3/ttyslot.3 index d69b9d116..9009fefc1 100644 --- a/man3/ttyslot.3 +++ b/man3/ttyslot.3 @@ -104,6 +104,9 @@ On error (e.g., if none of the file descriptors 0, 1 or 2 is associated with a terminal that occurs in this data base) it returns 0 on Unix V6 and V7 and BSD-like systems, but \-1 on System V-like systems. +.SH "CONFORMING TO" +SUSv1; marked as LECACY in SUSv2; removed in POSIX.1-2001. +SUSv2 requires \-1 on error. .SH NOTES The utmp file is found various places on various systems, such as .IR /etc/utmp , @@ -124,9 +127,6 @@ Minix also has .\" .SH HISTORY .\" .BR ttyslot () .\" appeared in Unix V7. -.SH "CONFORMING TO" -SUSv1; marked as LECACY in SUSv2; removed in POSIX.1-2001. -SUSv2 requires \-1 on error. .SH "SEE ALSO" .BR getttyent (3), .BR ttyname (3), diff --git a/man3/updwtmp.3 b/man3/updwtmp.3 index 9ab4f9f21..ade43e812 100644 --- a/man3/updwtmp.3 +++ b/man3/updwtmp.3 @@ -43,6 +43,13 @@ current time and current process ID. Then it calls .BR updwtmp () to append the structure to the utmp file. +.SH FILES +.TP +.I /var/log/wtmp +database of past user logins +.SH "CONFORMING TO" +Not in POSIX.1-2001. +Present on Solaris, NetBSD, and perhaps other systems. .SH AVAILABILITY Both functions are available under glibc2, but not under libc5. However, @@ -54,12 +61,5 @@ function is included in libutil. (Hence you'll need to add .B \-lutil to your compiler command line to get it.) -.SH "CONFORMING TO" -Not in POSIX.1-2001. -Present on Solaris, NetBSD, and perhaps other systems. -.SH FILES -.TP -.I /var/log/wtmp -database of past user logins .SH "SEE ALSO" .BR wtmp (5) diff --git a/man3/wcstok.3 b/man3/wcstok.3 index 23a8d1b7b..d530c0a63 100644 --- a/man3/wcstok.3 +++ b/man3/wcstok.3 @@ -55,6 +55,8 @@ The .BR wcstok () function returns a pointer to the next token, or NULL if no further token was found. +.SH "CONFORMING TO" +C99. .SH NOTES The original \fIwcs\fP wide-character string is destructively modified during the operation. @@ -71,8 +73,6 @@ for (token = wcstok(wcs, " \\t\\n", &state); ... } .fi -.SH "CONFORMING TO" -C99. .SH "SEE ALSO" .BR strtok (3), .BR wcschr (3) diff --git a/man4/fd.4 b/man4/fd.4 index a256e987f..147ce9c1f 100644 --- a/man4/fd.4 +++ b/man4/fd.4 @@ -188,6 +188,8 @@ sends a raw command to the floppy controller. For more precise information, consult also the and include files, as well as the manual page for floppycontrol. +.SH FILES +/dev/fd* .SH NOTES The various formats allow to read and write many types of disks. However, if a floppy is formatted with a too small inter sector gap, @@ -200,8 +202,6 @@ which is used by Apple II and Macintosh computers (800k disks). Reading floppies which are hard sectored (one hole per sector, with the index hole being a little skewed) is not supported. This used to be common with older 8 inch floppies. -.SH FILES -/dev/fd* .SH AUTHORS Alain Knaff (Alain.Knaff@imag.fr), David Niemi (niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com). diff --git a/man4/null.4 b/man4/null.4 index c282bab8c..f899d98d5 100644 --- a/man4/null.4 +++ b/man4/null.4 @@ -39,13 +39,13 @@ mknod \-m 666 /dev/zero c 1 5 .br chown root:root /dev/null /dev/zero .RE -.SH NOTES -If these devices are not writable and readable for all users, many -programs will act strangely. .SH FILES .I /dev/null .br .I /dev/zero +.SH NOTES +If these devices are not writable and readable for all users, many +programs will act strangely. .SH "SEE ALSO" .BR chown (1), .BR mknod (1), diff --git a/man4/st.4 b/man4/st.4 index dd3b5769f..5ba82a2f0 100644 --- a/man4/st.4 +++ b/man4/st.4 @@ -168,7 +168,7 @@ on the system. Starting from kernel 2.6.2, the driver exports in the sysfs directory .IR /sys/class/scsi_tape the attached devices and some parameters assigned to the devices. -.SH "DATA TRANSFER" +.SS "Data Transfer" The driver supports operation in both fixed-block mode and variable-block mode (if supported by the drive). In fixed-block mode the drive @@ -223,7 +223,7 @@ The end of recorded data is signaled by returning zero bytes for two consecutive read calls. The third read returns an error. -.SH IOCTLS +.SS Ioctls The driver supports three .BR ioctl (2) requests. @@ -819,7 +819,7 @@ kernel. The solution is to tell the software to use larger transfers (often telling it to use larger blocks). If this is not possible, direct transfers can be disabled. -.SH COPYRIGHT +.\" .SH COPYRIGHT .\" Copyright \(co 1995 Robert K. Nichols. .\" .br .\" Copyright \(co 1999-2005 Kai M\(:akisara. diff --git a/man4/vcs.4 b/man4/vcs.4 index 991506edb..bc9208ee1 100644 --- a/man4/vcs.4 +++ b/man4/vcs.4 @@ -60,6 +60,14 @@ The devices for the first eight virtual consoles may be created by: No .BR ioctl (2) requests are supported. +.SH FILES +/dev/vcs[0\-63] +.br +/dev/vcsa[0\-63] +.SH AUTHOR +Andries Brouwer +.SH VERSIONS +Introduced with version 1.1.92 of the Linux kernel. .SH EXAMPLE You may do a screendump on vt3 by switching to vt1 and typing \fIcat /dev/vcs3 >foo\fP. @@ -104,14 +112,6 @@ main(void) exit(EXIT_SUCCESS); } .fi -.SH FILES -/dev/vcs[0\-63] -.br -/dev/vcsa[0\-63] -.SH AUTHOR -Andries Brouwer -.SH VERSIONS -Introduced with version 1.1.92 of the Linux kernel. .SH "SEE ALSO" .BR gpm (8), .BR console (4), diff --git a/man4/wavelan.4 b/man4/wavelan.4 index 92554fad2..a86d1e544 100644 --- a/man4/wavelan.4 +++ b/man4/wavelan.4 @@ -41,7 +41,7 @@ by the card. .\" .\" PARAMETER part .\" -.SH PARAMETERS +.SS Parameters This section apply to the module form (parameters passed on the .BR insmod (8) command line). @@ -67,7 +67,7 @@ used by .\" .\" WIRELESS part .\" -.SH "WIRELESS EXTENSIONS" +.SS "Wireless Extensions" Use .BR iwconfig (8) to manipulate wireless extensions. @@ -117,7 +117,7 @@ counters are not implemented. .\" .\" IOCTL part .\" -.SH "PRIVATE IOCTL" +.SS "Private Ioctl" You may use .BR iwpriv (8) to manipulate private ioctls. @@ -135,7 +135,7 @@ and standard deviation of the signal level. .\" .\" SPECIFIC part .\" -.SH "SPECIFIC NOTES" +.SS "Specific Notes" This driver will fail to detect some .B non NCR/ATT&T/Lucent Wavelan cards. diff --git a/man5/dir_colors.5 b/man5/dir_colors.5 index 026e3456d..bc5281291 100644 --- a/man5/dir_colors.5 +++ b/man5/dir_colors.5 @@ -178,7 +178,7 @@ for .B emacs backup files. This form should be considered obsolete. -.SH "ISO 6429 (ANSI) COLOR SEQUENCES" +.SS "ISO 6429 (ANSI) Color Sequences" Most color-capable ASCII terminals today use ISO 6429 (ANSI) color sequences, and many common terminals without color capability, including .B xterm @@ -248,7 +248,7 @@ and .B FILE codes to the numerical codes for your normal foreground and background colors. -.SH "OTHER TERMINAL TYPES (ADVANCED CONFIGURATION)" +.SS "Other Terminal Types (Advanced Configuration)" If you have a color-capable (or otherwise highlighting) terminal (or printer!) which uses a different set of codes, you can still generate a suitable setup. @@ -294,7 +294,7 @@ definition will have no effect. A different .B ENDCODE can, however, be specified, which would have the same effect. -.SH "ESCAPE SEQUENCES" +.SS "Escape Sequences" To specify control- or blank characters in the color sequences or filename extensions, either C-style \e-escaped notation or .BR stty \-style @@ -326,6 +326,18 @@ includes the following characters: Please note that escapes are necessary to enter a space, backslash, caret, or any control character anywhere in the string, as well as a hash mark as the first character. +.SH FILES +.TP +.I /etc/DIR_COLORS +System-wide configuration file. +.TP +.I ~/.dir_colors +Per-user configuration file. +.PP +This page describes the +.B dir_colors +file format as used in the fileutils-4.1 package; +other versions may differ slightly. .SH NOTES The default .B LEFTCODE @@ -344,18 +356,6 @@ definitions, which are used by ISO 6429 terminals are: The default .B ENDCODE is undefined. -.SH FILES -.TP -.I /etc/DIR_COLORS -System-wide configuration file. -.TP -.I ~/.dir_colors -Per-user configuration file. -.SH NOTES -This page describes the -.B dir_colors -file format as used in the fileutils-4.1 package; -other versions may differ slightly. .SH "SEE ALSO" .BR dircolors (1), .BR ls (1), diff --git a/man5/group.5 b/man5/group.5 index 2a84165f1..a11926954 100644 --- a/man5/group.5 +++ b/man5/group.5 @@ -43,12 +43,12 @@ If this field is empty, no password is needed. the numerical group ID. .IP user_list all the group member's user names, separated by commas. +.SH FILES +/etc/group .SH BUGS As the 4.2BSD .BR initgroups (3) man page says: No-one seems to keep /etc/group up-to-date. -.SH FILES -/etc/group .SH "SEE ALSO" .BR login (1), .BR newgrp (1), diff --git a/man5/hosts.5 b/man5/hosts.5 index 217d99e13..6311a232a 100644 --- a/man5/hosts.5 +++ b/man5/hosts.5 @@ -83,14 +83,8 @@ instead of DNS. If the local information rarely changes, and the network is not connected to the Internet, DNS offers little advantage. -.SH EXAMPLE -.nf -127.0.0.1 localhost -192.168.1.10 foo.mydomain.org foo -192.168.1.13 bar.mydomain.org bar -146.82.138.7 master.debian.org master -209.237.226.90 www.opensource.org -.fi +.SH FILES +.I /etc/hosts .SH NOTES Modifications to this file normally take effect immediately, except in cases where the file is cached by applications. @@ -110,8 +104,14 @@ though looking around at the time of writing (circa 2000), there are historical hosts.txt files on the WWW. I just found three, from 92, 94, and 95. -.SH FILES -.I /etc/hosts +.SH EXAMPLE +.nf +127.0.0.1 localhost +192.168.1.10 foo.mydomain.org foo +192.168.1.13 bar.mydomain.org bar +146.82.138.7 master.debian.org master +209.237.226.90 www.opensource.org +.fi .SH "SEE ALSO" .BR hostname (1), .BR resolver (3), diff --git a/man5/locale.5 b/man5/locale.5 index 914d76873..377092006 100644 --- a/man5/locale.5 +++ b/man5/locale.5 @@ -561,12 +561,12 @@ See the POSIX.2 standard for details. \(em database for the current locale setting of that category .br /usr/lib/nls/charmap/* \(em charmap-files +.SH "CONFORMING TO" +POSIX.2 .SH BUGS The manpage isn't complete. .\" .SH AUTHOR .\" Jochen Hein (Hein@Student.TU-Clausthal.de) -.SH "CONFORMING TO" -POSIX.2 .SH "SEE ALSO" .BR locale (1), .BR localedef (1), diff --git a/man5/passwd.5 b/man5/passwd.5 index cc455b277..5cc3ea938 100644 --- a/man5/passwd.5 +++ b/man5/passwd.5 @@ -108,6 +108,8 @@ If set to a non-existing executable, the user will be unable to login through .BR login (1). .RE +.SH FILES +.I /etc/passwd .SH NOTES If you want to create user groups, their GIDs must be equal and there must be an entry in @@ -126,8 +128,6 @@ or mail filters, etc. Trying to lock an account by simply changing the shell field yields the same result and additionally allows the use of .BR su (1). -.SH FILES -.I /etc/passwd .SH "SEE ALSO" .BR login (1), .BR passwd (1), diff --git a/man5/services.5 b/man5/services.5 index cb44035ce..610d82912 100644 --- a/man5/services.5 +++ b/man5/services.5 @@ -178,6 +178,14 @@ ftp 21/tcp telnet 23/tcp .fi .RE +.SH FILES +.TP +.I /etc/services +The Internet network services list +.TP +.I /usr/include/netdb.h +Definition of +.B _PATH_SERVICES .SH BUGS There is a maximum of 35 aliases, due to the way the .BR getservent (3) @@ -191,14 +199,6 @@ Lines longer than and .BR getservbyport (3). However, this will also cause the next line to be mis-parsed. -.SH FILES -.TP -.I /etc/services -The Internet network services list -.TP -.I /usr/include/netdb.h -Definition of -.B _PATH_SERVICES .SH "SEE ALSO" .BR listen (2), .BR endservent (3), diff --git a/man5/shells.5 b/man5/shells.5 index fb81f05d2..8619cc263 100644 --- a/man5/shells.5 +++ b/man5/shells.5 @@ -37,6 +37,8 @@ Be aware that there are programs which consult this file to find out if a user is a normal user. E.g.: ftp daemons traditionally disallow access to users with shells not included in this file. +.SH FILES +.I /etc/shells .SH EXAMPLE .I /etc/shells may contain the following paths: @@ -46,8 +48,6 @@ may contain the following paths: .br .I /bin/csh .RE -.SH FILES -.I /etc/shells .SH "SEE ALSO" .BR chsh (1), .BR getusershell (3) diff --git a/man5/slabinfo.5 b/man5/slabinfo.5 index 105ac0f55..cb725f795 100644 --- a/man5/slabinfo.5 +++ b/man5/slabinfo.5 @@ -108,9 +108,9 @@ and batchcount via: .nf echo "\fIcache_name limit batchcount\fP" > /proc/slabinfo .fi +.SH FILES +.I .SH VERSIONS .I /proc/slabinfo exists since Linux 2.1.23. SMP per-CPU caches exist since Linux 2.4.0-test3. -.SH FILES -.I diff --git a/man5/ttytype.5 b/man5/ttytype.5 index 6cdaaba49..647da22d8 100644 --- a/man5/ttytype.5 +++ b/man5/ttytype.5 @@ -44,6 +44,10 @@ the user's current tty. This facility was designed for a traditional time-sharing environment featuring character-cell terminals hardwired to a Unix minicomputer. It is little used on modern workstation and personal Unixes. +.SH FILES +.TP +.I /etc/ttytype +the tty definitions file. .SH EXAMPLE A typical .I /etc/ttytype @@ -54,10 +58,6 @@ con80x25 tty1 .br vt320 ttys0 .RE -.SH FILES -.TP -.I /etc/ttytype -the tty definitions file. .SH "SEE ALSO" .BR termcap (5), .BR terminfo (5) diff --git a/man7/arp.7 b/man7/arp.7 index df7b016ea..e02db706b 100644 --- a/man7/arp.7 +++ b/man7/arp.7 @@ -66,7 +66,7 @@ Linux will automatically add a non-permanent proxy arp entry when it receives a request for an address it forwards to and proxy arp is enabled on the receiving interface. When there is a reject route for the target no proxy arp entry is added. -.SH IOCTLS +.SS Ioctls Three ioctls are available on all .B PF_INET sockets. @@ -126,7 +126,7 @@ Linux 2.2 does not support proxy network ARP entries, so this should be set to 0xffffffff, or 0 to remove an existing proxy arp entry. .B ATF_USETRAILERS is obsolete and should not be used. -.SH SYSCTLS +.SS Sysctls ARP supports a sysctl interface to configure parameters on a global or per-interface basis. The sysctls can be accessed by reading or writing the @@ -231,20 +231,6 @@ Defaults to 3. The maximum number of packets which may be queued for each unresolved address by other network layers. Defaults to 3. -.SH BUGS -Some timer settings are specified in jiffies, which is architecture -related. -On the Alpha a jiffy is 1/1024 of a second, on most other -architectures it is 1/100s. - -There is no way to signal positive feedback from user space. -This means connection oriented protocols implemented in user space -will generate excessive ARP traffic, because ndisc will regularly -reprobe the MAC address. -The same problem applies for some kernel protocols (e.g. NFS over UDP). - -This man page mashes IPv4 specific and shared between IPv4 and IPv6 -functionality together. .SH VERSIONS The .I struct arpreq @@ -260,6 +246,20 @@ the kernel for all reachable hosts on other interfaces (when forwarding and proxy arp is enabled for the interface). The neigh/* sysctls did not exist before Linux 2.2. +.SH BUGS +Some timer settings are specified in jiffies, which is architecture +related. +On the Alpha a jiffy is 1/1024 of a second, on most other +architectures it is 1/100s. + +There is no way to signal positive feedback from user space. +This means connection oriented protocols implemented in user space +will generate excessive ARP traffic, because ndisc will regularly +reprobe the MAC address. +The same problem applies for some kernel protocols (e.g. NFS over UDP). + +This man page mashes IPv4 specific and shared between IPv4 and IPv6 +functionality together. .SH "SEE ALSO" .BR capabilities (7), .BR ip (7) diff --git a/man7/capabilities.7 b/man7/capabilities.7 index c6c599648..92da0b17b 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -511,6 +511,9 @@ all of its user IDs to non-zero values, it can do so using the .BR prctl () .B PR_SET_KEEPCAPS operation. +.SH "CONFORMING TO" +No standards govern capabilities, but the Linux capability implementation +is based on the withdrawn POSIX.1e draft standard. .SH NOTES The .I libcap @@ -520,9 +523,6 @@ to change than the interface provided by .BR capset (2) and .BR capget (2). -.SH "CONFORMING TO" -No standards govern capabilities, but the Linux capability implementation -is based on the withdrawn POSIX.1e draft standard. .SH BUGS There is as yet no file system support allowing capabilities to be associated with executable files. diff --git a/man7/ddp.7 b/man7/ddp.7 index f953567df..9a75fcbe5 100644 --- a/man7/ddp.7 +++ b/man7/ddp.7 @@ -57,7 +57,7 @@ Raw sockets may be only opened by a process with effective user ID 0 or when the process has the .B CAP_NET_RAW capability. -.SH "ADDRESS FORMAT" +.SS "Address Format" An Appletalk socket address is defined as a combination of a network number, a node number, and a port number. .PP @@ -113,9 +113,9 @@ wildcard and also implies \(lqthis node.\(rq The value of is a link local broadcast address. .\" FIXME this doesn't make sense [johnl] -.SH "SOCKET OPTIONS" +.SS "Socket Options" No protocol-specific socket options are supported. -.SH SYSCTLS +.SS Sysctls IP supports a sysctl interface to configure some global AppleTalk parameters. The sysctls can be accessed by reading or writing the @@ -139,23 +139,11 @@ The timer rate (in seconds) for the timer driving AARP. .PP The default values match the specification and should never need to be changed. -.SH IOCTLS +.SS Ioctls All ioctls described in .BR socket (7) apply to ddp. .\" FIXME Add a section about multicasting -.SH NOTES -Be very careful with the -.B SO_BROADCAST -option \- it is not privileged in Linux. -It is easy to overload the network -with careless sending to broadcast addresses. -.SH VERSIONS -Appletalk is supported by Linux 2.0 or higher. -The -.B sysctl -interface is -new in Linux 2.2. .SH ERRORS .\" FIXME document all errors. We should really fix the kernels to .\" give more uniform error returns (ENOMEM vs ENOBUFS, EPERM vs @@ -228,7 +216,19 @@ Network device not available or not capable of sending IP. .TP .B ENOPKG A kernel subsystem was not configured. -.SH COMPATIBILITY +.SH VERSIONS +Appletalk is supported by Linux 2.0 or higher. +The +.B sysctl +interface is +new in Linux 2.2. +.SH NOTES +Be very careful with the +.B SO_BROADCAST +option \- it is not privileged in Linux. +It is easy to overload the network +with careless sending to broadcast addresses. +.SS Compatibility The basic AppleTalk socket interface is compatible with .B netatalk on BSD-derived systems. diff --git a/man7/epoll.7 b/man7/epoll.7 index 46457e5e6..155be8168 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -19,6 +19,7 @@ .\" Davide Libenzi .\" .\" +.\" FIXME Section titles and orderings in this page are very inconsistent .TH EPOLL 7 2002-10-23 "Linux" "Linux Programmer's Manual" .SH NAME epoll \- I/O event notification facility @@ -46,7 +47,7 @@ Interest for certain file descriptors is then registered via .BR epoll_ctl (2). Finally, the actual wait is started by .BR epoll_wait (2). -.SH NOTES +.SS Level Triggered and Edge Triggered The .B epoll event distribution interface is able to behave both as Edge Triggered @@ -161,7 +162,7 @@ it is caller responsibility to rearm the file descriptor using .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.SH EXAMPLE FOR SUGGESTED USAGE +.SS Example for Suggested Usage While the usage of .B epoll when employed like a Level Triggered interface does have the same @@ -230,7 +231,7 @@ calling .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.SH QUESTIONS AND ANSWERS +.SS Questions and Answers .TP .B Q1 What happens if you add the same fd to an epoll_set twice? @@ -334,7 +335,7 @@ I/O space for such file descriptor. Same is valid when writing using the .BR write (2) function. -.SH POSSIBLE PITFALLS AND WAYS TO AVOID THEM +.SS Possible Pitfalls and Ways to Avoid Them .TP .B o Starvation ( Edge Triggered ) .PP @@ -377,6 +378,10 @@ data structure as removed and link it to a cleanup list. If you find another event for fd 13 in your batch processing, you will discover the fd had been previously removed and there will be no confusion. +.SH VERSIONS +.BR epoll (7) +is a new API introduced in Linux kernel 2.5.44. +Its interface should be finalized in Linux kernel 2.5.66. .SH CONFORMING TO The epoll API is Linux specific. Some other systems provide similar @@ -384,10 +389,6 @@ mechanisms, e.g., FreeBSD has .IR kqueue , and Solaris has .IR /dev/poll . -.SH VERSIONS -.BR epoll (7) -is a new API introduced in Linux kernel 2.5.44. -Its interface should be finalized in Linux kernel 2.5.66. .SH "SEE ALSO" .BR epoll_create (2), .BR epoll_ctl (2), diff --git a/man7/futex.7 b/man7/futex.7 index 55371e934..6329efb5c 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -82,6 +82,11 @@ to for more details. The same holds for asynchronous futex waiting. +.SH "VERSIONS" +.PP +Initial futex support was merged in Linux 2.5.7 +but with different semantics from those described above. +Current semantics are available from Linux 2.5.40 onwards. .SH "NOTES" .PP To reiterate, bare futexes are not intended as an easy to use @@ -93,18 +98,13 @@ below. This man page illustrates the most common use of the .BR futex (2) primitives: it is by no means the only one. -.SH "AUTHORS" -.PP -Futexes were designed and worked on by Hubertus Franke -(IBM Thomas J. Watson Research Center), -Matthew Kirkwood, Ingo Molnar (Red Hat) and -Rusty Russell (IBM Linux Technology Center). -This page written by bert hubert. -.SH "VERSIONS" -.PP -Initial futex support was merged in Linux 2.5.7 -but with different semantics from those described above. -Current semantics are available from Linux 2.5.40 onwards. +.\" .SH "AUTHORS" +.\" .PP +.\" Futexes were designed and worked on by Hubertus Franke +.\" (IBM Thomas J. Watson Research Center), +.\" Matthew Kirkwood, Ingo Molnar (Red Hat) and +.\" Rusty Russell (IBM Linux Technology Center). +.\" This page written by bert hubert. .SH "SEE ALSO" .PP .BR futex (2), diff --git a/man7/icmp.7 b/man7/icmp.7 index 1d1710750..ff6380a34 100644 --- a/man7/icmp.7 +++ b/man7/icmp.7 @@ -85,6 +85,14 @@ Maximum rate for sending packets. These packets are sent to prevent loops when a packet has crossed too many hops. +.SH VERSIONS +Support for the +.B ICMP_ADDRESS +request was removed in 2.2. +.PP +Support for +.B ICMP_SOURCE_QUENCH +was removed in Linux 2.2. .SH NOTES As many other implementations don't support .B IPPROTO_ICMP @@ -107,14 +115,6 @@ Linux ICMP internally uses a raw socket to send ICMPs. This raw socket may appear in .BR netstat (8) output with a zero inode. -.SH VERSIONS -Support for the -.B ICMP_ADDRESS -request was removed in 2.2. -.PP -Support for -.B ICMP_SOURCE_QUENCH -was removed in Linux 2.2. .SH "SEE ALSO" .BR ip (7) .PP diff --git a/man7/inotify.7 b/man7/inotify.7 index 9ead9b24c..a3b9cec9a 100644 --- a/man7/inotify.7 +++ b/man7/inotify.7 @@ -247,6 +247,16 @@ that can be created per real user ID. .IR /proc/sys/fs/inotify/max_user_watches This specifies a limit on the number of watches that can be associated with each inotify instance. +.SH "VERSIONS" +Inotify was merged into the 2.6.13 Linux kernel. +The required library interfaces were added to glibc in version 2.4. +.RB ( IN_DONT_FOLLOW , +.BR IN_MASK_ADD , +and +.B IN_ONLYDIR +were only added in version 2.5.) +.SH "CONFORMING TO" +The inotify API is Linux specific. .SH "NOTES" Inotify file descriptors can be monitored using .BR select (2), @@ -278,21 +288,11 @@ inotify file descriptor. Inotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional watches must be created. -.SH "VERSIONS" -Inotify was merged into the 2.6.13 Linux kernel. -The required library interfaces were added to glibc in version 2.4. -.RB ( IN_DONT_FOLLOW , -.BR IN_MASK_ADD , -and -.B IN_ONLYDIR -were only added in version 2.5.) .SH "BUGS" In kernels before 2.6.16, the .B IN_ONESHOT .I mask flag does not work. -.SH "CONFORMING TO" -The inotify API is Linux specific. .SH "SEE ALSO" .BR inotify_add_watch (2), .BR inotify_init (2), diff --git a/man7/ip.7 b/man7/ip.7 index 7928b5e63..96e736c3f 100644 --- a/man7/ip.7 +++ b/man7/ip.7 @@ -6,6 +6,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ +.\" FIXME Section titles and orderings in this page are very inconsistent .TH IP 7 2001-06-19 "Linux" "Linux Programmer's Manual" .SH NAME ip \- Linux IPv4 protocol implementation @@ -99,7 +100,7 @@ unless the flag has been set. Care should be taken when using this flag as it makes TCP less reliable. -.SH "ADDRESS FORMAT" +.SS Address Format An IP socket address is defined as a combination of an IP interface address and a 16-bit port number. The basic IP protocol does not supply port numbers, they @@ -194,7 +195,7 @@ means any address for binding; means any host and has the same effect on bind as .B INADDR_ANY for historical reasons. -.SH "SOCKET OPTIONS" +.SS Socket Options IP supports some protocol specific socket options that can be set with .BR setsockopt (2) and read with @@ -691,7 +692,7 @@ structure similar to When an invalid socket option is passed, .B ENOPROTOOPT is returned. -.SH SYSCTLS +.SS Sysctls The IP protocol supports the sysctl interface to configure some global options. The sysctls can be accessed by reading or writing the @@ -813,7 +814,7 @@ See .\" FIXME Document the conf/*/* sysctls .\" FIXME Document the route/* sysctls .\" FIXME document them all -.SH IOCTLS +.SS Ioctls All ioctls described in .BR socket (7) apply to ip. @@ -829,40 +830,6 @@ apply to ip. Ioctls to configure generic device parameters are described in .BR netdevice (7). .\" FIXME Add a discussion of multicasting -.SH NOTES -Be very careful with the -.B SO_BROADCAST -option \- it is not privileged in Linux. -It is easy to overload the network -with careless broadcasts. -For new application protocols -it is better to use a multicast group instead of broadcasting. -Broadcasting is discouraged. -.PP -Some other BSD sockets implementations provide -.I IP_RCVDSTADDR -and -.I IP_RECVIF -socket options to get the destination address and the interface of -received datagrams. -Linux has the more general -.I IP_PKTINFO -for the same task. -.PP -Some BSD sockets implementations also provide an -.I IP_RECVTTL -option, but an ancillary message with type -.I IP_RECVTTL -is passed with the incoming packet. -This is different from the -.I IP_TTL -option used in Linux. -.PP -Using -.I SOL_IP -socket options level isn't portable, BSD-based stacks use -.I IPPROTO_IP -level. .SH ERRORS .\" FIXME document all errors. .\" We should really fix the kernels to give more uniform @@ -981,7 +948,41 @@ Linux 2.0 only supported .BR ip_mreq . .PP The sysctls were introduced with Linux 2.2. -.SH COMPATIBILITY +.SH NOTES +Be very careful with the +.B SO_BROADCAST +option \- it is not privileged in Linux. +It is easy to overload the network +with careless broadcasts. +For new application protocols +it is better to use a multicast group instead of broadcasting. +Broadcasting is discouraged. +.PP +Some other BSD sockets implementations provide +.I IP_RCVDSTADDR +and +.I IP_RECVIF +socket options to get the destination address and the interface of +received datagrams. +Linux has the more general +.I IP_PKTINFO +for the same task. +.PP +Some BSD sockets implementations also provide an +.I IP_RECVTTL +option, but an ancillary message with type +.I IP_RECVTTL +is passed with the incoming packet. +This is different from the +.I IP_TTL +option used in Linux. +.PP +Using +.I SOL_IP +socket options level isn't portable, BSD-based stacks use +.I IPPROTO_IP +level. +.SS Compatibility For compatibility with Linux 2.0, the obsolete .BI "socket(PF_INET, SOCK_PACKET, " protocol ) syntax is still supported to open a diff --git a/man7/man.7 b/man7/man.7 index 2314029c2..bd3bd19f1 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -778,6 +778,10 @@ Once you've confirmed that the additional capability is safe, let the maintainer of this document know about the safe command or sequence that should be added to this list. +.SH FILES +.IR /usr/share/groff/ [*/] tmac/tmac.an +.br +.I /usr/man/whatis .SH NOTES .PP By all means include full URLs (or URIs) in the text itself; @@ -827,10 +831,6 @@ tbl(1) .TP .B v vgrind(1) -.SH FILES -.IR /usr/share/groff/ [*/] tmac/tmac.an -.br -.I /usr/man/whatis .SH BUGS .PP Most of the macros describe formatting (e.g., font type and spacing) instead diff --git a/man7/netdevice.7 b/man7/netdevice.7 index 5c70b583a..5dd6125b4 100644 --- a/man7/netdevice.7 +++ b/man7/netdevice.7 @@ -61,7 +61,7 @@ Normally, the user specifies which device to affect by setting to the name of the interface. All other members of the structure may share memory. -.SH IOCTLS +.SS Ioctls If an ioctl is marked as privileged then using it requires an effective user ID of 0 or the .B CAP_NET_ADMIN diff --git a/man7/netlink.7 b/man7/netlink.7 index a07daf25c..29d695fd6 100644 --- a/man7/netlink.7 +++ b/man7/netlink.7 @@ -4,6 +4,7 @@ .\" Based on the original comments from Alexey Kuznetsov .\" Modified 2005-12-27 by Hasso Tepper .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ +.\" FIXME Section titles and orderings in this page are very inconsistent .TH NETLINK 7 2005-12-27 "Linux" "Linux Programmer's Manual" .SH NAME netlink \- Communication between kernel and userspace (PF_NETLINK) @@ -345,6 +346,33 @@ Only processes with an effective UID of 0 or the capability may send or listen to a netlink multicast group. Any replies to a message received for a multicast group should be sent back to the sending PID and the multicast group. +.SH VERSIONS +The socket interface to netlink is a new feature of Linux 2.2. + +Linux 2.0 supported a more primitive device based netlink interface +(which is still available as a compatibility option). +This obsolete interface is not described here. + +NETLINK_SELINUX appeared in Linux 2.6.4. + +NETLINK_AUDIT appeared in Linux 2.6.6. + +NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10. + +NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13. + +NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in +Linux 2.6.14. + +NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15. +.SH NOTES +It is often better to use netlink via +.B libnetlink +or +.B libnl +than via the low level kernel interface. +.SH BUGS +This manual page is not complete. .SH EXAMPLE The following example creates a .B NETLINK_ROUTE @@ -420,33 +448,6 @@ for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); } .fi .in -0.25i -.SH BUGS -This manual page is not complete. -.SH NOTES -It is often better to use netlink via -.B libnetlink -or -.B libnl -than via the low level kernel interface. -.SH VERSIONS -The socket interface to netlink is a new feature of Linux 2.2. - -Linux 2.0 supported a more primitive device based netlink interface -(which is still available as a compatibility option). -This obsolete interface is not described here. - -NETLINK_SELINUX appeared in Linux 2.6.4. - -NETLINK_AUDIT appeared in Linux 2.6.6. - -NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10. - -NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13. - -NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in -Linux 2.6.14. - -NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15. .SH "SEE ALSO" .BR cmsg (3), .BR netlink (3), diff --git a/man7/packet.7 b/man7/packet.7 index 5ce68f58b..b80f5218e 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -4,6 +4,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ +.\" FIXME Section titles and orderings in this page are very inconsistent .TH PACKET 7 1999-04-29 "Linux" "Linux Programmer's Manual" .SH NAME packet, PF_PACKET \- packet interface on device level. @@ -102,7 +103,7 @@ flag is passed to .BR recvfrom (2) the real length of the packet on the wire is always returned, even when it is longer than the buffer. -.SH "ADDRESS TYPES" +.SS Address Types The sockaddr_ll is a device independent physical layer address. .in +0.25i @@ -171,7 +172,7 @@ For bind only and .B sll_ifindex are used. -.SH "SOCKET OPTIONS" +.SS Socket Options Packet sockets can be used to configure physical layer multicasting and promiscuous mode. It works by calling @@ -220,7 +221,7 @@ In addition the traditional ioctls .BR SIOCADDMULTI , .B SIOCDELMULTI can be used for the same purpose. -.SH IOCTLS +.SS Ioctls .B SIOCGSTAMP can be used to receive the time stamp of the last received packet. Argument is a @@ -231,73 +232,10 @@ In addition all standard ioctls defined in and .BR socket (7) are valid on packet sockets. -.SH "ERROR HANDLING" +.SS Error Handling Packet sockets do no error handling other than errors occurred while passing the packet to the device driver. They don't have the concept of a pending error. -.SH COMPATIBILITY -In Linux 2.0, the only way to get a packet socket was by calling -.BI "socket(PF_INET, SOCK_PACKET, " protocol )\fR. -This is still supported but strongly deprecated. -The main difference between the two methods is that -.B SOCK_PACKET -uses the old -.I struct sockaddr_pkt -to specify an interface, which doesn't provide physical layer -independence. - -.in +0.25i -.nf -struct sockaddr_pkt { - unsigned short spkt_family; - unsigned char spkt_device[14]; - unsigned short spkt_protocol; -}; -.fi -.in -0.25i - -.B spkt_family -contains -the device type, -.B spkt_protocol -is the IEEE 802.3 protocol type as defined in -.I -and -.B spkt_device -is the device name as a null terminated string, e.g. eth0. - -This structure is obsolete and should not be used in new code. -.SH NOTES -For portable programs it is suggested to use -.B PF_PACKET -via -.BR pcap (3); -although this only covers a subset of the -.B PF_PACKET -features. - -The -.B SOCK_DGRAM -packet sockets make no attempt to create or parse the IEEE 802.2 LLC -header for a IEEE 802.3 frame. -When -.B ETH_P_802_3 -is specified as protocol for sending the kernel creates the -802.3 frame and fills out the length field; the user has to supply the LLC -header to get a fully conforming packet. -Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol -fields; instead they are supplied to the user as protocol -.B ETH_P_802_2 -with the LLC header prepended. -It is thus not possible to bind to -.BR ETH_P_802_3 ; -bind to -.B ETH_P_802_2 -instead and do the protocol multiplex yourself. -The default for sending is the standard Ethernet DIX -encapsulation with the protocol filled in. - -Packet sockets are not subject to the input or output firewall chains. .SH ERRORS .TP .B ENETDOWN @@ -352,6 +290,69 @@ Older systems need: #include /* The L2 protocols */ .fi .in +.SH NOTES +For portable programs it is suggested to use +.B PF_PACKET +via +.BR pcap (3); +although this only covers a subset of the +.B PF_PACKET +features. + +The +.B SOCK_DGRAM +packet sockets make no attempt to create or parse the IEEE 802.2 LLC +header for a IEEE 802.3 frame. +When +.B ETH_P_802_3 +is specified as protocol for sending the kernel creates the +802.3 frame and fills out the length field; the user has to supply the LLC +header to get a fully conforming packet. +Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol +fields; instead they are supplied to the user as protocol +.B ETH_P_802_2 +with the LLC header prepended. +It is thus not possible to bind to +.BR ETH_P_802_3 ; +bind to +.B ETH_P_802_2 +instead and do the protocol multiplex yourself. +The default for sending is the standard Ethernet DIX +encapsulation with the protocol filled in. + +Packet sockets are not subject to the input or output firewall chains. +.SS Compatibility +In Linux 2.0, the only way to get a packet socket was by calling +.BI "socket(PF_INET, SOCK_PACKET, " protocol )\fR. +This is still supported but strongly deprecated. +The main difference between the two methods is that +.B SOCK_PACKET +uses the old +.I struct sockaddr_pkt +to specify an interface, which doesn't provide physical layer +independence. + +.in +0.25i +.nf +struct sockaddr_pkt { + unsigned short spkt_family; + unsigned char spkt_device[14]; + unsigned short spkt_protocol; +}; +.fi +.in -0.25i + +.B spkt_family +contains +the device type, +.B spkt_protocol +is the IEEE 802.3 protocol type as defined in +.I +and +.B spkt_device +is the device name as a null terminated string, e.g. eth0. + +This structure is obsolete and should not be used in new code. .SH BUGS glibc 2.1 does not have a define for .BR SOL_PACKET . diff --git a/man7/pty.7 b/man7/pty.7 index 3fe954ce8..0c9f6caac 100644 --- a/man7/pty.7 +++ b/man7/pty.7 @@ -115,15 +115,6 @@ A process finds an unused pseudo-terminal pair by trying to each pseudo-terminal master until an open succeeds. The corresponding pseudo-terminal slave (substitute "tty" for "pty" in the name of the master) can then be opened. -.SH "NOTES" -A description of the -.B TIOCPKT -.BR ioctl (2), -which controls packet mode operation, can be found in -.BR tty_ioctl (4). - -The BSD ioctl(2)s TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have -not been implemented under Linux. .SH "FILES" .I /dev/ptmx (Unix 98 master clone device) @@ -137,6 +128,15 @@ not been implemented under Linux. .I /dev/tty[p-za-e][0-9a-f] (BSD slave devices) .I +.SH "NOTES" +A description of the +.B TIOCPKT +.BR ioctl (2), +which controls packet mode operation, can be found in +.BR tty_ioctl (4). + +The BSD ioctl(2)s TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have +not been implemented under Linux. .SH "SEE ALSO" .BR select (2), .BR setsid (2), diff --git a/man7/raw.7 b/man7/raw.7 index b4b3779fb..e0cb4f3b2 100644 --- a/man7/raw.7 +++ b/man7/raw.7 @@ -6,6 +6,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ +.\" FIXME Section titles and orderings in this page are very inconsistent .TH RAW 7 1998-10-02 "Linux" "Linux Programmer's Manual" .SH NAME raw, SOCK_RAW \- Linux IPv4 raw sockets @@ -86,7 +87,7 @@ protocols or protocols with no user interface (like ICMP). When a packet is received, it is passed to any raw sockets which have been bound to its protocol before it is passed to other protocol handlers (e.g. kernel protocol modules). -.SH "ADDRESS FORMAT" +.SS Address Format Raw sockets use the standard .I sockaddr_in address structure defined in @@ -102,7 +103,7 @@ is set to the protocol of the packet. See the .I include file for valid IP protocols. -.SH "SOCKET OPTIONS" +.SS Socket Options Raw socket options can be set with .BR setsockopt (2) and read with @@ -124,6 +125,61 @@ In addition all .BR ip (7) .B IPPROTO_IP socket options valid for datagram sockets are supported. +.SS Error Handling +Errors originating from the network are only passed to the user when the +socket is connected or the +.B IP_RECVERR +flag is enabled. +For connected sockets only +.B EMSGSIZE +and +.B EPROTO +are passed for compatibility. +With +.B IP_RECVERR +all network errors are saved in the error queue. +.SH ERRORS +.TP +.B EMSGSIZE +Packet too big. +Either Path MTU Discovery is enabled (the +.B IP_MTU_DISCOVER +socket flag) or the packet size exceeds the maximum allowed IPv4 +packet size of 64KB. +.TP +.B EACCES +User tried to send to a broadcast address without having the +broadcast flag set on the socket. +.TP +.B EPROTO +An ICMP error has arrived reporting a parameter problem. +.TP +.B EFAULT +An invalid memory address was supplied. +.TP +.B EOPNOTSUPP +Invalid flag has been passed to a socket call (like +.BR MSG_OOB ). +.TP +.B EINVAL +Invalid argument. +.TP +.B EPERM +The user doesn't have permission to open raw sockets. +Only processes with a effective user ID of 0 or the +.B CAP_NET_RAW +attribute may do that. +.SH VERSIONS +.B IP_RECVERR +and +.B ICMP_FILTER +are new in Linux 2.2. +They are Linux extensions and should not be used in portable programs. + +Linux 2.0 enabled some bug-to-bug compatibility with BSD in the +raw socket code when the +SO_BSDCOMPAT socket option was set \(em since Linux 2.2, +this option no longer has that effect. .SH NOTES By default raw sockets do path MTU (Maximum Transmission Unit) discovery. This means the kernel @@ -189,61 +245,6 @@ Sending on raw sockets should take the IP protocol from this ability was lost in Linux 2.2. The workaround is to use .BR IP_HDRINCL . -.SH "ERROR HANDLING" -Errors originating from the network are only passed to the user when the -socket is connected or the -.B IP_RECVERR -flag is enabled. -For connected sockets only -.B EMSGSIZE -and -.B EPROTO -are passed for compatibility. -With -.B IP_RECVERR -all network errors are saved in the error queue. -.SH ERRORS -.TP -.B EMSGSIZE -Packet too big. -Either Path MTU Discovery is enabled (the -.B IP_MTU_DISCOVER -socket flag) or the packet size exceeds the maximum allowed IPv4 -packet size of 64KB. -.TP -.B EACCES -User tried to send to a broadcast address without having the -broadcast flag set on the socket. -.TP -.B EPROTO -An ICMP error has arrived reporting a parameter problem. -.TP -.B EFAULT -An invalid memory address was supplied. -.TP -.B EOPNOTSUPP -Invalid flag has been passed to a socket call (like -.BR MSG_OOB ). -.TP -.B EINVAL -Invalid argument. -.TP -.B EPERM -The user doesn't have permission to open raw sockets. -Only processes with a effective user ID of 0 or the -.B CAP_NET_RAW -attribute may do that. -.SH VERSIONS -.B IP_RECVERR -and -.B ICMP_FILTER -are new in Linux 2.2. -They are Linux extensions and should not be used in portable programs. - -Linux 2.0 enabled some bug-to-bug compatibility with BSD in the -raw socket code when the -SO_BSDCOMPAT socket option was set \(em since Linux 2.2, -this option no longer has that effect. .SH BUGS Transparent proxy extensions are not described. diff --git a/man7/socket.7 b/man7/socket.7 index d49d0bb6e..cf3423618 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -17,6 +17,7 @@ .\" FIXME probably all PF_* should be AF_* in this page, since .\" POSIX only specifies the latter values. .\" +.\" FIXME Section titles and orderings in this page are very inconsistent .TH SOCKET 7 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" .SH NAME socket \- Linux socket interface @@ -43,7 +44,7 @@ or See .BR socket (2) for more information on families and types. -.SH "SOCKET LAYER FUNCTIONS" +.SS Socket Layer Functions These functions are used by the user process to send or receive packets and to do other socket operations. For more information see their respective manual pages. @@ -193,7 +194,7 @@ must be installed via See the .I SIGNALS discussion below. -.SH "SOCKET OPTIONS" +.SS Socket Options These socket options can be set by using .BR setsockopt (2) and read with @@ -487,7 +488,7 @@ Gets the socket type as an integer (like Can only be read with .BR getsockopt (2). -.SH SIGNALS +.SS Signals When writing onto a connection-oriented socket that has been shut down (by the local or the remote end) .B SIGPIPE @@ -530,8 +531,8 @@ single socket), the condition that caused the may have already disappeared when the process reacts to the signal. If this happens, the process should wait again because Linux will resend the signal later. -.\" .SH ANCILLARY MESSAGES -.SH SYSCTLS +.\" .SS Ancillary Messages +.SH Sysctls The core socket networking sysctls can be accessed using the .I /proc/sys/net/core/* files or with the @@ -567,7 +568,7 @@ Maximum number of packets in the global input queue. Maximum length of ancillary data and user control data like the iovecs per socket. .\" netdev_fastroute is not documented because it is experimental -.SH IOCTLS +.SS Ioctls These operations can be accessed using .BR ioctl (2): @@ -653,6 +654,18 @@ The same as the SIOCGPGRP .BR FIOSETOWN The same as the SIOCSPGRP .BR ioctl (2). +.SH VERSIONS +.B SO_BINDTODEVICE +was introduced in Linux 2.0.30. +.B SO_PASSCRED +is new in Linux 2.2. +The sysctls are new in Linux 2.2. +.B SO_RCVTIMEO +and +.B SO_SNDTIMEO +are supported since Linux 2.3.41. +Earlier, timeouts were fixed to +a protocol specific setting, and could not be read or written. .SH NOTES Linux assumes that half of the send/receive buffer is used for internal kernel structures; thus the sysctls are twice what can be observed @@ -677,18 +690,6 @@ are not documented. The suggested interface to use them is via the libpcap library. -.SH VERSIONS -.B SO_BINDTODEVICE -was introduced in Linux 2.0.30. -.B SO_PASSCRED -is new in Linux 2.2. -The sysctls are new in Linux 2.2. -.B SO_RCVTIMEO -and -.B SO_SNDTIMEO -are supported since Linux 2.3.41. -Earlier, timeouts were fixed to -a protocol specific setting, and could not be read or written. .\" .SH AUTHORS .\" This man page was written by Andi Kleen. .SH "SEE ALSO" diff --git a/man7/tcp.7 b/man7/tcp.7 index c80d628a8..97fb474b0 100644 --- a/man7/tcp.7 +++ b/man7/tcp.7 @@ -12,6 +12,7 @@ .\" documented: tcp_mtu_probing, tcp_base_mss, and .\" tcp_workaround_signed_windows .\" +.\" FIXME Section titles and orderings in this page are very inconsistent .TH TCP 7 2005-06-15 "Linux" "Linux Programmer's Manual" .SH NAME tcp \- TCP protocol @@ -152,7 +153,7 @@ Some of these features include support for zero-copy Explicit Congestion Notification, new management of TIME_WAIT sockets, keep-alive socket options and support for Duplicate SACK extensions. -.SH "ADDRESS FORMATS" +.SS Address Formats TCP is built on top of IP (see .BR ip (7)). The address formats defined by @@ -161,7 +162,7 @@ apply to TCP. TCP only supports point-to-point communication; broadcasting and multicasting are not supported. -.SH SYSCTLS +.SS Sysctls These variables can be accessed by the .I /proc/sys/net/ipv4/* files or with the @@ -635,7 +636,7 @@ on a socket. The default value is 128K bytes. It is lowered to 64K depending on the memory available in the system. -.SH "SOCKET OPTIONS" +.SS Socket Options To set or get a TCP socket option, call .BR getsockopt (2) to read or @@ -765,7 +766,7 @@ Bound the size of the advertised window to this value. The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. This option should not be used in code intended to be portable. -.SH IOCTLS +.SS Ioctls These following .BR ioctl (2) calls return information in @@ -826,7 +827,7 @@ returns false. Returns the amount of unsent data in the socket send queue. The socket must not be in LISTEN state, otherwise an error (EINVAL) is returned. -.SH "ERROR HANDLING" +.SS Error Handling When a network error occurs, TCP tries to resend the packet. If it doesn't succeed after some time, either .B ETIMEDOUT @@ -843,22 +844,6 @@ errors are immediately passed to the user program. Use this option with care \(em it makes TCP less tolerant to routing changes and other normal network conditions. -.SH NOTES -TCP has no real out-of-band data; it has urgent data. -In Linux this means if the other end sends newer out-of-band -data the older urgent data is inserted as normal data into -the stream (even when -.B SO_OOBINLINE -is not set). -This differs from BSD-based stacks. -.PP -Linux uses the BSD compatible interpretation of the urgent -pointer field by default. -This violates RFC\ 1122, but is -required for interoperability with other stacks. -It can be changed by the -.B tcp_stdurg -sysctl. .SH ERRORS .TP .B EPIPE @@ -878,13 +863,6 @@ was not Any errors defined for .BR ip (7) or the generic socket layer may also be returned for TCP. -.SH BUGS -Not all errors are documented. -.br -IPv6 is not described. -.\" Only a single Linux kernel version is described -.\" Info for 2.2 was lost. Should be added again, -.\" or put into a separate page. .SH VERSIONS Support for Explicit Congestion Notification, zero-copy .BR sendfile (2), @@ -896,6 +874,29 @@ were introduced in 2.3. The default values and descriptions for the sysctl variables given above are applicable for the 2.4 kernel. +.SH NOTES +TCP has no real out-of-band data; it has urgent data. +In Linux this means if the other end sends newer out-of-band +data the older urgent data is inserted as normal data into +the stream (even when +.B SO_OOBINLINE +is not set). +This differs from BSD-based stacks. +.PP +Linux uses the BSD compatible interpretation of the urgent +pointer field by default. +This violates RFC\ 1122, but is +required for interoperability with other stacks. +It can be changed by the +.B tcp_stdurg +sysctl. +.SH BUGS +Not all errors are documented. +.br +IPv6 is not described. +.\" Only a single Linux kernel version is described +.\" Info for 2.2 was lost. Should be added again, +.\" or put into a separate page. .\" .SH AUTHORS .\" This man page was originally written by Andi Kleen. .\" It was updated for 2.4 by Nivedita Singhvi with input from diff --git a/man7/udp.7 b/man7/udp.7 index da9a4c6f4..3fe2f6ec5 100644 --- a/man7/udp.7 +++ b/man7/udp.7 @@ -87,12 +87,12 @@ When turned off UDP will fragment outgoing UDP packets that exceed the interface MTU. However disabling it is not recommended for performance and reliability reasons. -.SH "ADDRESS FORMAT" +.SS "Address Format" UDP uses the IPv4 .B sockaddr_in address format described in .BR ip (7). -.SH "ERROR HANDLING" +.SS "Error Handling" All fatal errors will be passed to the user as an error return even when the socket is not connected. This includes asynchronous errors @@ -125,7 +125,7 @@ and can be received by with the .B MSG_ERRQUEUE flag set. -.SH "SOCKET OPTIONS" +.SS "Socket Options" To set or get a UDP socket option, call .BR getsockopt (2) to read or @@ -140,7 +140,7 @@ the option is disabled. This option should not be used in code intended to be portable. .\" FIXME document UDP_ENCAP (new in kernel 2.5.67) -.SH IOCTLS +.SS Ioctls These ioctls can be accessed using .BR ioctl (2). The correct syntax is: diff --git a/man7/unix.7 b/man7/unix.7 index 13568ba65..1cdc335fb 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -9,6 +9,7 @@ .\" Modified, 2004-05-27, Michael Kerrisk, .\" Added SOCK_SEQPACKET .\" +.\" FIXME Section titles and orderings in this page are very inconsistent .TH UNIX 7 2004-05-27 "Linux" "Linux Programmer's Manual" .SH NAME unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local @@ -48,7 +49,7 @@ and delivers messages in the order that they were sent. Unix sockets support passing file descriptors or process credentials to other processes using ancillary data. -.SH "ADDRESS FORMAT" +.SS Address Format A Unix address is defined as a filename in the filesystem or as a unique string in the abstract namespace. Sockets created by @@ -87,7 +88,7 @@ The socket's address in this namespace is given by the rest of the bytes in .BR sun_path . Note that names in the abstract namespace are not zero-terminated. -.SH "SOCKET OPTIONS" +.SS Socket Options For historical reasons these socket options are specified with a SOL_SOCKET type even though they are PF_UNIX specific. They can be set with @@ -102,7 +103,7 @@ ancillary message. When this option is set and the socket is not yet connected a unique name in the abstract namespace will be generated automatically. Expects an integer boolean flag. -.SH "(UN)SUPPORTED FEATURES" +.SS (Un)supported Features The following paragraphs describe domain-specific details and unsupported features of the sockets API for Unix domain sockets on Linux. @@ -130,7 +131,7 @@ value imposes an upper limit on the size of outgoing datagrams. This limit is calculated as the doubled (see .BR socket (7)) option value less 32 bytes used for overhead. -.SH "ANCILLARY MESSAGES" +.SS Ancillary Messages Ancillary data is sent and received using .BR sendmsg (2) and @@ -186,40 +187,6 @@ To receive a message the .B SO_PASSCRED option must be enabled on the socket. -.SH VERSIONS -.B SCM_CREDENTIALS -and the abstract namespace were introduced with Linux 2.2 and should not -be used in portable programs. -(Some BSD-derived systems also support credential passing, -but the implementation details differ.) -.SH NOTES -In the Linux implementation, sockets which are visible in the -filesystem honour the permissions of the directory they are in. -Their owner, group and their permissions can be changed. -Creation of a new socket will fail if the process does not have write and -search (execute) permission on the directory the socket is created in. -Connecting to the socket object requires read/write permission. -This behavior differs from many BSD-derived systems which -ignore permissions for Unix sockets. -Portable programs should not rely on -this feature for security. - -Binding to a socket with a filename creates a socket -in the file system that must be deleted by the caller when it is no -longer needed (using -.BR unlink (2)). -The usual Unix close-behind semantics apply; the socket can be unlinked -at any time and will be finally removed from the file system when the last -reference to it is closed. - -To pass file descriptors or credentials over a SOCK_STREAM, you need -to send or receive at least one byte of non-ancillary data in the same -.BR sendmsg (2) -or -.BR recvmsg (2) -call. - -Unix domain stream sockets do not support the notion of out-of-band data. .SH ERRORS .TP .B ENOMEM @@ -290,6 +257,40 @@ The sender passed invalid credentials in the Other errors can be generated by the generic socket layer or by the filesystem while generating a filesystem socket object. See the appropriate manual pages for more information. +.SH VERSIONS +.B SCM_CREDENTIALS +and the abstract namespace were introduced with Linux 2.2 and should not +be used in portable programs. +(Some BSD-derived systems also support credential passing, +but the implementation details differ.) +.SH NOTES +In the Linux implementation, sockets which are visible in the +filesystem honour the permissions of the directory they are in. +Their owner, group and their permissions can be changed. +Creation of a new socket will fail if the process does not have write and +search (execute) permission on the directory the socket is created in. +Connecting to the socket object requires read/write permission. +This behavior differs from many BSD-derived systems which +ignore permissions for Unix sockets. +Portable programs should not rely on +this feature for security. + +Binding to a socket with a filename creates a socket +in the file system that must be deleted by the caller when it is no +longer needed (using +.BR unlink (2)). +The usual Unix close-behind semantics apply; the socket can be unlinked +at any time and will be finally removed from the file system when the last +reference to it is closed. + +To pass file descriptors or credentials over a SOCK_STREAM, you need +to send or receive at least one byte of non-ancillary data in the same +.BR sendmsg (2) +or +.BR recvmsg (2) +call. + +Unix domain stream sockets do not support the notion of out-of-band data. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), diff --git a/man7/uri.7 b/man7/uri.7 index cd46e46ae..0fba60e2b 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -44,6 +44,7 @@ .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) .\" +.\" FIXME Section titles and orderings in this page are very inconsistent .TH URI 7 2000-03-14 "Linux" "Linux Programmer's Manual" .SH NAME uri, url, urn \- uniform resource identifier (URI), including a URL or URN @@ -540,6 +541,13 @@ permitted, and can only be used when there is no defined base (such as in dialog boxes). Don't use abbreviated URIs as hypertext links inside a document; use the standard format as described here. +.SH "CONFORMING TO" +.PP +.IR http://www.ietf.org/rfc/rfc2396.txt +(IETF RFC\ 2396), +.I http://www.w3.org/TR/REC-html40 +(HTML 4.0). +.UE .SH NOTES Any tool accepting URIs (e.g., a web browser) on a Linux system should be able to handle (directly or indirectly) all of the schemes described here, @@ -577,7 +585,7 @@ It is expected that GNOME and KDE will converge to common URI formats, and a future version of this man page will describe the converged result. Efforts to aid this convergence are encouraged. -.SH SECURITY +.SS Security .PP A URI does not in itself pose a security threat. There is no general guarantee that a URL, which at one time @@ -620,13 +628,6 @@ intended to be secret. In particular, the use of a password within the 'userinfo' component of a URI is strongly recommended against except in those rare cases where the 'password' parameter is intended to be public. -.SH "CONFORMING TO" -.PP -.IR http://www.ietf.org/rfc/rfc2396.txt -(IETF RFC\ 2396), -.I http://www.w3.org/TR/REC-html40 -(HTML 4.0). -.UE .SH BUGS .PP Documentation may be placed in a variety of locations, so there diff --git a/man7/x25.7 b/man7/x25.7 index 8c51da6c5..3ca08c334 100644 --- a/man7/x25.7 +++ b/man7/x25.7 @@ -4,6 +4,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ +.\" FIXME Section titles and orderings in this page are very inconsistent .TH X25 7 1998-12-01 "Linux" "Linux Programmer's Manual" .SH NAME x25, PF_X25 \- ITU-T X.25 / ISO-8208 protocol interface. @@ -39,7 +40,7 @@ there is a temporary lack of system resources or when other constraints (such as socket memory or buffer size limits) become effective. If that occurs, the X.25 connection will be reset. -.SH "SOCKET ADDRESSES" +.SS Socket Addresses The .B AF_X25 socket address family uses the @@ -64,7 +65,7 @@ to be interpreted as a null-terminated string. consists of up to 15 (not counting the terminating 0) ASCII characters forming the X.121 address. Only the decimal digit characters from `0' to `9' are allowed. -.SH "SOCKET OPTIONS" +.SS Socket Options The following X.25 specific socket options can be set by using .BR setsockopt (2) and read with @@ -90,6 +91,8 @@ If the first byte of the data written to the socket is 1 the Q-bit of the corresponding outgoing data packets will be set. If the first byte is 0 the Q-bit will not be set. +.SH VERSIONS +The PF_X25 protocol family is a new feature of Linux 2.2. .SH BUGS Plenty, as the X.25 PLP implementation is .BR CONFIG_EXPERIMENTAL . @@ -106,8 +109,6 @@ interface are not binary compatible. X.25 N-Reset events are not propagated to the user process yet. Thus, if a reset occurred, data might be lost without notice. -.SH VERSIONS -The PF_X25 protocol family is a new feature of Linux 2.2. .SH "SEE ALSO" .BR socket (2), .BR socket (7) diff --git a/man8/zic.8 b/man8/zic.8 index 976ba0679..0b3fcc291 100644 --- a/man8/zic.8 +++ b/man8/zic.8 @@ -403,14 +403,14 @@ or .q Rolling if the leap second time given by the other fields should be interpreted as local wall clock time. +.SH FILES +/usr/local/etc/zoneinfo standard directory used for created files .SH NOTES For areas with more than two types of local time, you may need to use local standard time in the .B AT field of the earliest transition time's rule to ensure that the earliest transition time recorded in the compiled file is correct. -.SH FILES -/usr/local/etc/zoneinfo standard directory used for created files .SH "SEE ALSO" .BR tzfile (5), .BR zdump (8)