diff --git a/Changes b/Changes index c69870695..f22286cc5 100644 --- a/Changes +++ b/Changes @@ -8,6 +8,8 @@ Contributors The following people contributed notes, ideas, or patches that have been incorporated in changes in this release: +Andi Kleen +John Heffner Apologies if I missed anyone! @@ -15,9 +17,6 @@ Apologies if I missed anyone! New pages --------- -Andi Kleen -John Heffner - Global changes -------------- diff --git a/Changes.old b/Changes.old index b6ddf0218..f40a154ad 100644 --- a/Changes.old +++ b/Changes.old @@ -5476,7 +5476,7 @@ Samuel Thibault Serge E. Hallyn Thomas Huriaux Timo Sirainen -Val Henson +Val Henson Apologies if I missed anyone! diff --git a/man2/_exit.2 b/man2/_exit.2 index 9cb68707f..3aa6e23d8 100644 --- a/man2/_exit.2 +++ b/man2/_exit.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,9 +40,10 @@ _exit, _Exit \- terminate the current process .SH DESCRIPTION The function .BR _exit () -terminates the calling process "immediately". Any open file descriptors +terminates the calling process "immediately". +Any open file descriptors belonging to the process are closed; any children of the process are -inherited by process 1, +inherited by process 1, .IR init , and the process's parent is sent a .B SIGCHLD @@ -74,7 +75,7 @@ The function is like \fBexit\fP(), but does not call any functions registered with .BR atexit () -or +or .BR on_exit (). Whether it flushes standard I/O buffers and removes temporary files created with @@ -83,11 +84,12 @@ is implementation dependent. On the other hand, .BR _exit () does close open file descriptors, and this may cause an unknown delay, -waiting for pending output to finish. If the delay is undesired, +waiting for pending output to finish. +If the delay is undesired, it may be useful to call functions like \fItcflush\fP() before calling \fB_exit\fP(). Whether any pending I/O is cancelled, and which pending I/O may be -cancelled upon \fB_exit\fP(), is implementation-dependent. +cancelled upon \fB_exit\fP(), is implementation-dependent. .SH "SEE ALSO" .BR execve (2), .BR exit_group (2), diff --git a/man2/accept.2 b/man2/accept.2 index 54b255023..f120cc213 100644 --- a/man2/accept.2 +++ b/man2/accept.2 @@ -69,7 +69,7 @@ and is listening for connections after a The argument .I addr -is a pointer to a +is a pointer to a .I sockaddr structure. This structure is filled in with the address of the peer socket, @@ -77,7 +77,7 @@ as known to the communications layer. The exact format of the address returned .I addr is determined by the socket's address family (see -.BR socket (2) +.BR socket (2) and the respective protocol man pages). The .I addrlen @@ -85,7 +85,8 @@ argument is a value-result argument: it should initially contain the size of the structure pointed to by .IR addr ; on return it will contain the actual length (in bytes) of the address -returned. When +returned. +When .I addr is NULL nothing is filled in. .PP @@ -93,10 +94,11 @@ If no pending connections are present on the queue, and the socket is not marked as non-blocking, .BR accept () -blocks the caller until a connection is present. If the socket is marked +blocks the caller until a connection is present. +If the socket is marked non-blocking and no pending connections are present on the queue, .BR accept () -fails with the error EAGAIN. +fails with the error EAGAIN. .PP In order to be notified of incoming connections on a socket, you can use .BR select (2) @@ -105,8 +107,8 @@ or A readable event will be delivered when a new connection is attempted and you may then call .BR accept () -to get a socket for that connection. Alternatively, you can set the socket -to deliver +to get a socket for that connection. +Alternatively, you can set the socket to deliver .B SIGIO when activity occurs on a socket; see .BR socket (7) @@ -117,11 +119,13 @@ such as DECNet, .BR accept () can be thought of as merely dequeuing the next connection request and not -implying confirmation. Confirmation can be implied by +implying confirmation. +Confirmation can be implied by a normal read or write on the new file descriptor, and rejection can be -implied by closing the new socket. Currently only -DECNet -has these semantics on Linux. +implied by closing the new socket. +Currently only +DECNet +has these semantics on Linux. .SH NOTES There may not always be a connection waiting after a .B SIGIO @@ -152,19 +156,21 @@ On error, \-1 is returned, and .I errno is set appropriately. .SH "ERROR HANDLING" -Linux +Linux .BR accept () -passes already-pending network errors on the new socket -as an error code from -.BR accept (). +passes already-pending network errors on the new socket +as an error code from +.BR accept (). This behaviour differs from other BSD socket -implementations. For reliable operation the application should detect -the network errors defined for the protocol after +implementations. +For reliable operation the application should detect +the network errors defined for the protocol after .BR accept () and treat -them like +them like .BR EAGAIN -by retrying. In case of TCP/IP these are +by retrying. +In case of TCP/IP these are .BR ENETDOWN , .BR EPROTO , .BR ENOPROTOOPT , @@ -190,7 +196,7 @@ A connection has been aborted. .TP .B EINTR The system call was interrupted by a signal that was caught -before a valid connection arrived. +before a valid connection arrived. .TP .B EINVAL Socket is not listening for connections, or @@ -208,7 +214,7 @@ The descriptor references a file, not a socket. .TP .B EOPNOTSUPP The referenced socket is not of type -.BR SOCK_STREAM . +.BR SOCK_STREAM . .PP .BR accept () may fail if: @@ -219,7 +225,7 @@ The argument is not in a writable part of the user address space. .TP .B ENOBUFS, ENOMEM -Not enough free memory. +Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory. .TP @@ -234,7 +240,8 @@ may fail if: Firewall rules forbid connection. .PP In addition, network errors for the new socket and as defined -for the protocol may be returned. Various Linux kernels can +for the protocol may be returned. +Various Linux kernels can return other errors such as .BR ENOSR , .BR ESOCKTNOSUPPORT , @@ -244,18 +251,18 @@ The value .B ERESTARTSYS may be seen during a trace. .SH "CONFORMING TO" -SVr4, 4.4BSD, +SVr4, 4.4BSD, .RB ( accept () -first appeared in 4.2BSD), POSIX.1-2001. +first appeared in 4.2BSD), POSIX.1-2001. .\" The BSD man page documents five possible error returns .\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). -.\" POSIX.1-2001 documents errors +.\" POSIX.1-2001 documents errors .\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, -.\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. +.\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. .\" In addition, SUSv2 documents EFAULT and ENOSR. .LP On Linux, the new socket returned by -.BR accept () +.BR accept () does \fInot\fP inherit file status flags such as .BR O_NONBLOCK and @@ -264,9 +271,9 @@ from the listening socket. This behaviour differs from the canonical BSD sockets implementation. .\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also .\" do not inherit file status flags -- MTK Jun 05 -Portable programs should not rely on inheritance or non-inheritance -of file status flags and always explicitly set all required flags on -the socket returned from +Portable programs should not rely on inheritance or non-inheritance +of file status flags and always explicitly set all required flags on +the socket returned from .BR accept (). .SH NOTE The third argument of @@ -281,14 +288,16 @@ Quoting Linus Torvalds: .\" .I fails: only italicizes a single line "_Any_ sane library _must_ have "socklen_t" be the same size -as int. Anything else breaks any BSD socket layer stuff. +as int. +Anything else breaks any BSD socket layer stuff. POSIX initially \fIdid\fP make it a size_t, and I (and hopefully others, but -obviously not too many) complained to them very loudly indeed. Making -it a size_t is completely broken, exactly because size_t very seldom is -the same size as "int" on 64-bit architectures, for example. And it +obviously not too many) complained to them very loudly indeed. +Making it a size_t is completely broken, exactly because size_t very +seldom is the same size as "int" on 64-bit architectures, for example. +And it \fIhas\fP to be the same size as "int" because that's what the BSD socket -interface is. -Anyway, the POSIX people eventually got a clue, and created "socklen_t". +interface is. +Anyway, the POSIX people eventually got a clue, and created "socklen_t". They shouldn't have touched it in the first place, but once they did they felt it had to have a named type for some unfathomable reason (probably somebody didn't like losing face over having done the original diff --git a/man2/access.2 b/man2/access.2 index 98e41d391..e8a067bbd 100644 --- a/man2/access.2 +++ b/man2/access.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -81,17 +81,19 @@ actually attempting an operation. This is to allow set-user-ID programs to easily determine the invoking user's authority. -Only access bits are checked, not the file type or contents. Therefore, if +Only access bits are checked, not the file type or contents. +Therefore, if a directory is found to be "writable," it probably means that files can be created in the directory, and not that the directory can be written as a -file. Similarly, a DOS file may be found to be "executable," but the +file. +Similarly, a DOS file may be found to be "executable," but the .BR execve (2) call will still fail. If the process has appropriate privileges, an implementation may indicate success for .B X_OK -even if none of the execute file permission bits are set. +even if none of the execute file permission bits are set. .SH "RETURN VALUE" On success (all requested permissions granted), zero is returned. On error (at least one bit in @@ -155,7 +157,7 @@ executed. .SH "LINUX NOTES" In kernels before 2.6.20, .BR access () -ignored the effect of the +ignored the effect of the .B MS_NOEXEC flag if it was used to .BR mount (2) diff --git a/man2/acct.2 b/man2/acct.2 index 9ebb9241e..e958255bc 100644 --- a/man2/acct.2 +++ b/man2/acct.2 @@ -43,10 +43,11 @@ acct \- switch process accounting on or off .SH DESCRIPTION When called with the name of an existing file as argument, accounting is turned on, records for each terminating process are appended to -\fIfilename\fP as it terminates. An argument of NULL causes -accounting to be turned off. +\fIfilename\fP as it terminates. +An argument of NULL causes accounting to be turned off. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -71,11 +72,11 @@ Error writing to the file .IR filename . .TP .B EISDIR -.I filename +.I filename is a directory. .TP .B ELOOP -Too many symbolic links were encountered in resolving +Too many symbolic links were encountered in resolving .IR filename . .TP .B ENAMETOOLONG @@ -98,8 +99,8 @@ The kernel configuration parameter controlling this feature is CONFIG_BSD_PROCESS_ACCT. .TP .B ENOTDIR -A component used as a directory in -.I filename +A component used as a directory in +.I filename is not in fact a directory. .TP .B EPERM @@ -109,20 +110,20 @@ On Linux the capability is required. .TP .B EROFS -.I filename +.I filename refers to a file on a read-only file system. .TP .B EUSERS There are no more free file structures or we ran out of memory. .SH "CONFORMING TO" -SVr4, 4.3BSD (but not POSIX). -.\" SVr4 documents an EBUSY error condition, but no EISDIR or ENOSYS. +SVr4, 4.3BSD (but not POSIX). +.\" SVr4 documents an EBUSY error condition, but no EISDIR or ENOSYS. .\" Also AIX and HP-UX document EBUSY (attempt is made .\" to enable accounting when it is already enabled), as does Solaris .\" (attempt is made to enable accounting using the same file that is .\" currently being used). .SH NOTES -No accounting is produced for programs running when a crash occurs. In -particular, nonterminating processes are never accounted for. +No accounting is produced for programs running when a crash occurs. +In particular, nonterminating processes are never accounted for. .SH "SEE ALSO" .BR acct (5). diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index fcd514915..c3cf28036 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -39,7 +39,7 @@ The system call .BR adjtimex () reads and optionally sets adjustment parameters for this algorithm. It takes a pointer to a -.I timex +.I timex structure, updates kernel parameters from field values, and returns the same structure with current kernel values. This structure is declared as follows: @@ -123,9 +123,9 @@ or to set to a value other than those listed above, or to set .I buf.tick -to a value outside the range +to a value outside the range .RB 900000/ HZ -to +to .RB 1100000/ HZ , where .B HZ @@ -142,7 +142,7 @@ capability is required. intended to be portable. See .BR adjtime (3) -for a more portable, but less flexible, +for a more portable, but less flexible, method of adjusting the system clock. .SH "SEE ALSO" .BR settimeofday (2), diff --git a/man2/alarm.2 b/man2/alarm.2 index 33152f173..2fd310434 100644 --- a/man2/alarm.2 +++ b/man2/alarm.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,8 +37,8 @@ alarm \- set an alarm clock for delivery of a signal .BI "unsigned int alarm(unsigned int " seconds ); .fi .SH DESCRIPTION -.BR alarm () -arranges for a +.BR alarm () +arranges for a .B SIGALRM signal to be delivered to the process in .I seconds @@ -60,7 +60,7 @@ alarm was due to be delivered, or zero if there was no previously scheduled alarm. .SH NOTES .BR alarm () -and +and .BR setitimer () share the same timer; calls to one will interfere with use of the other. diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index 5d215e741..c57dcc74c 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -27,7 +27,7 @@ alloc_hugepages, free_hugepages \- allocate or free huge pages .SH SYNOPSIS .nf -.BI "void *alloc_hugepages(int " key ", void *" addr ", size_t " len , +.BI "void *alloc_hugepages(int " key ", void *" addr ", size_t " len , .BI " int " prot ", int " flag ); .\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, .\" unsigned long len, int prot, int flag); @@ -45,14 +45,17 @@ They existed only on i386 and ia64 (when built with CONFIG_HUGETLB_PAGE). In Linux 2.4.20 the syscall numbers exist, but the calls return ENOSYS. .LP On i386 the memory management hardware knows about ordinary pages (4 KiB) -and huge pages (2 or 4 MiB). Similarly ia64 knows about huge pages of -several sizes. These system calls serve to map huge pages into the +and huge pages (2 or 4 MiB). +Similarly ia64 knows about huge pages of +several sizes. +These system calls serve to map huge pages into the process' memory or to free them again. Huge pages are locked into memory, and are not swapped. .LP The .I key -parameter is an identifier. When zero the pages are private, and +parameter is an identifier. +When zero the pages are private, and not inherited by children. When positive the pages are shared with other applications using the same .IR key , @@ -75,8 +78,8 @@ Addresses must be properly aligned. .LP The .I len -parameter is the length of the required segment. It must be -a multiple of the huge page size. +parameter is the length of the required segment. +It must be a multiple of the huge page size. .LP The .I prot @@ -87,18 +90,21 @@ The .I flag parameter is ignored, unless .I key -is positive. In that case, if +is positive. +In that case, if .I flag is IPC_CREAT, then a new huge page segment is created when none -with the given key existed. If this flag is not set, then ENOENT +with the given key existed. +If this flag is not set, then ENOENT is returned when no segment with the given key exists. -.IR +.IR .SH "RETURN VALUE" On success, .BR alloc_hugepages () returns the allocated virtual address, and .BR free_hugepages () -returns zero. On error, \-1 is returned, and +returns zero. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -108,7 +114,8 @@ 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 +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 @@ -120,7 +127,8 @@ This can be read and written. Gives info on the number of configured hugetlb pages and on their size in the three variables HugePages_Total, HugePages_Free, Hugepagesize. .SH NOTES -The system calls are gone. Now the hugetlbfs filesystem can be used instead. +The system calls are gone. +Now the hugetlbfs filesystem can be used instead. Memory backed by huge pages (if the CPU supports them) is obtained by using .BR mmap () diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 index 66a7b84a9..bd30f4dfb 100644 --- a/man2/arch_prctl.2 +++ b/man2/arch_prctl.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .TH ARCH_PRCTL 2 2003-02-02 "Linux 2.4.20" "Linux Programmer's Manual" @@ -36,13 +36,13 @@ function sets architecture specific process or thread state. .I code selects a subfunction and passes argument -.I addr -to it. +.I addr +to it. .LP Sub functions for x86-64 are: .TP .B ARCH_SET_FS -Set the 64bit base for the +Set the 64bit base for the .I FS register to .IR addr . @@ -50,14 +50,14 @@ register to .B ARCH_GET_FS Return the 64bit base value for the .I FS -register of the current thread in the +register of the current thread in the .I unsigned long -pointed to by the -.I address +pointed to by the +.I address parameter .TP .B ARCH_SET_GS -Set the 64bit base for the +Set the 64bit base for the .I GS register to .IR addr . @@ -65,10 +65,10 @@ register to .B ARCH_GET_GS Return the 64bit base value for the .I GS -register of the current thread in the +register of the current thread in the .I unsigned long -pointed to by the -.I address +pointed to by the +.I address parameter. .SH NOTES .BR arch_prctl () @@ -79,13 +79,14 @@ The 64bit base changes when a new 32bit segment selector is loaded. .B ARCH_SET_GS is disabled in some kernels. -Context switches for 64bit segment bases are rather expensive. It may be a +Context switches for 64bit segment bases are rather expensive. +It may be a faster alternative to set a 32bit base using a segment selector by setting up an LDT with .BR modify_ldt (2) -or using the +or using the .BR set_thread_area (2) -system call in a 2.5 kernel. +system call in a 2.5 kernel. .BR arch_prctl () is only needed when you want to set bases that are larger than 4GB. Memory in the first 2GB of address space can be allocated by using @@ -99,16 +100,16 @@ As of version 2.3.5, glibc provides no prototype for You have to declare it yourself for now. This may be fixed in future glibc versions. -.I FS +.I FS may be already used by the threading library. .SH ERRORS .TP .B EFAULT -.I addr +.I addr points to an unmapped address or is outside the process address space. .TP .B EINVAL -.I code +.I code is not a valid subcommand. .TP .B EPERM @@ -118,7 +119,7 @@ is outside the process address space. Man page written by Andi Kleen. .SH "CONFORMING TO" .BR arch_prctl () -is a Linux/x86-64 extension and should not be used in programs intended +is a Linux/x86-64 extension and should not be used in programs intended to be portable. .SH "SEE ALSO" .BR mmap (2), diff --git a/man2/bind.2 b/man2/bind.2 index 6196557fb..97b1af74c 100644 --- a/man2/bind.2 +++ b/man2/bind.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -96,8 +96,9 @@ before a socket may receive connections (see .BR accept (2)). -The rules used in name binding vary between address families. Consult -the manual entries in Section 7 for detailed information. For +The rules used in name binding vary between address families. +Consult the manual entries in Section 7 for detailed information. +For .B AF_INET see .BR ip (7), @@ -127,7 +128,7 @@ see .BR netlink (7). The actual structure passed for the -.I my_addr +.I my_addr argument will depend on the address family. The .I sockaddr @@ -142,12 +143,12 @@ struct sockaddr { .fi .in -0.25in -The only purpose of this structure is to cast the structure -pointer passed in -.I my_addr -in order to avoid compiler warnings. -The following example shows how this is done when binding a socket -in the Unix +The only purpose of this structure is to cast the structure +pointer passed in +.I my_addr +in order to avoid compiler warnings. +The following example shows how this is done when binding a socket +in the Unix .RB ( AF_UNIX ) domain: @@ -166,30 +167,31 @@ main(int argc, char *argv[]) { int sfd; struct sockaddr_un addr; - - sfd = socket(AF_UNIX, SOCK_STREAM, 0); - if (sfd == -1) { - perror("socket"); - exit(EXIT_FAILURE); + + sfd = socket(AF_UNIX, SOCK_STREAM, 0); + if (sfd == -1) { + perror("socket"); + exit(EXIT_FAILURE); } - memset(&addr, 0, sizeof(struct sockaddr_un)); + memset(&addr, 0, sizeof(struct sockaddr_un)); /* Clear structure */ - addr.sun_family = AF_UNIX; - strncpy(addr.sun_path, MY_SOCK_PATH, + addr.sun_family = AF_UNIX; + strncpy(addr.sun_path, MY_SOCK_PATH, sizeof(addr.sun_path) - 1); if (bind(sfd, (struct sockaddr *) &addr, - sizeof(struct sockaddr_un)) == -1) { - perror("bind"); - exit(EXIT_FAILURE); + sizeof(struct sockaddr_un)) == -1) { + perror("bind"); + exit(EXIT_FAILURE); } ... } .fi .in -0.25in .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -213,8 +215,8 @@ The socket is already bound to an address. .I sockfd is a descriptor for a file, not a socket. .PP -The following errors are specific to UNIX domain -.RB ( AF_UNIX ) +The following errors are specific to UNIX domain +.RB ( AF_UNIX ) sockets: .TP .B EACCES @@ -223,7 +225,7 @@ Search permission is denied on a component of the path prefix. .BR path_resolution (2).) .TP .B EADDRNOTAVAIL -A non-existent interface was requested or the requested +A non-existent interface was requested or the requested address was not local. .TP .B EFAULT @@ -261,11 +263,11 @@ The transparent proxy options are not described. .SH "CONFORMING TO" SVr4, 4.4BSD, POSIX.1-2001 (the .BR bind () -function first appeared in 4.2BSD). +function first appeared in 4.2BSD). .\" SVr4 documents an additional -.\" .B ENOSR +.\" .B ENOSR .\" general error condition, and -.\" additional +.\" additional .\" .B EIO .\" and .\" .B EISDIR @@ -276,7 +278,7 @@ The third argument of is in reality an .I int (and this is what 4.x BSD and libc4 and libc5 have). -Some POSIX confusion resulted in the present +Some POSIX confusion resulted in the present .IR socklen_t , also used by glibc. See also diff --git a/man2/brk.2 b/man2/brk.2 index 08448a20b..eecad1cbf 100644 --- a/man2/brk.2 +++ b/man2/brk.2 @@ -66,7 +66,7 @@ is set to On success, .BR sbrk () -returns a pointer to the start of the new area. +returns a pointer to the start of the new area. On error, \-1 is returned, and .I errno is set to @@ -75,7 +75,7 @@ is set to 4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001. .BR brk () -and +and .BR sbrk () are not defined in the C Standard and are deliberately excluded from the POSIX.1 standard (see paragraphs B.1.1.1.3 and B.8.3.3). @@ -94,24 +94,24 @@ The return value described above for .BR brk () is the behaviour provided by the glibc wrapper function for the Linux .BR brk () -system call. -(On most other implementations, the return value from -.BR brk () +system call. +(On most other implementations, the return value from +.BR brk () is the same.) -However, +However, the actual Linux system call returns the new program break on success. -On failure, the system call returns the current break +On failure, the system call returns the current break (thus for example, the call .I brk(0) can be used to obtain the current break). -The glibc wrapper function does some work to provide the 0 +The glibc wrapper function does some work to provide the 0 and \-1 return values described above. -On Linux, +On Linux, .BR sbrk () is implemented as a library function that uses the .BR brk () -system call, and does some internal bookkeeping so that it can +system call, and does some internal bookkeeping so that it can return the old break value. .SH "SEE ALSO" .BR execve (2), diff --git a/man2/cacheflush.2 b/man2/cacheflush.2 index 10e36899a..881d6a5ff 100644 --- a/man2/cacheflush.2 +++ b/man2/cacheflush.2 @@ -33,7 +33,8 @@ cacheflush \- flush contents of instruction and/or data cache .SH DESCRIPTION .BR cacheflush () flushes contents of indicated cache(s) for user addresses in the range -addr to (addr+nbytes-1). Cache may be one of: +addr to (addr+nbytes-1). +Cache may be one of: .TP .B ICACHE Flush the instruction cache. @@ -42,12 +43,14 @@ Flush the instruction cache. Write back to memory and invalidate the affected valid cache lines. .TP .B BCACHE -Same as +Same as .BR (ICACHE|DCACHE) . .SH "RETURN VALUE" .BR cacheflush () -returns 0 on success or \-1 on error. If errors are detected, -errno will indicate the error. +returns 0 on success or \-1 on error. +If errors are detected, +.I errno +will indicate the error. .SH ERRORS .TP .B EFAULT @@ -56,12 +59,12 @@ Some or all of the address range addr to (addr+nbytes-1) is not accessible. .B EINVAL cache parameter is not one of ICACHE, DCACHE, or BCACHE. .SH BUGS -The current implementation ignores the -.I addr -and -.I nbytes -arguments. +The current implementation ignores the +.I addr +and +.I nbytes +arguments. Therefore, the whole cache is always flushed. .SH NOTE -This system call is only available on MIPS based systems. It should -not be used in programs intended to be portable. +This system call is only available on MIPS based systems. +It should not be used in programs intended to be portable. diff --git a/man2/capget.2 b/man2/capget.2 index 96e4be698..46055e874 100644 --- a/man2/capget.2 +++ b/man2/capget.2 @@ -29,7 +29,8 @@ call, and a set of permitted capabilities that it can make effective or inheritable. .PP These two functions are the raw kernel interface for getting and -setting capabilities. Not only are these system calls specific to Linux, +setting capabilities. +Not only are these system calls specific to Linux, but the kernel API is likely to change and use of these functions (in particular the format of the .B cap_user_*_t @@ -43,7 +44,7 @@ if possible you should use those interfaces in applications. If you wish to use the Linux extensions in applications, you should use the easier-to-use interfaces .BR capsetp (3) -and +and .BR capgetp (3). .SS "Current details" Now that you have been warned, some current kernel details. @@ -66,46 +67,48 @@ typedef struct __user_cap_data_struct { .fi .in -4n .sp -The calls will return EINVAL, and set the -.I version +The calls will return EINVAL, and set the +.I version field of .I hdr to _LINUX_CAPABILITY_VERSION when another version was specified. -The calls operate on the capabilities of the thread specified by the -.I pid +The calls operate on the capabilities of the thread specified by the +.I pid field of .I hdr when that is non-zero, or on the capabilities of the calling thread if .I pid is 0. -If +If .I pid -refers to a single-threaded process, then +refers to a single-threaded process, then .I pid can be specified as a traditional process ID; operating on a thread of a multithreaded process requires a thread ID -of the type returned by +of the type returned by .BR gettid (2). -For -.BR capset (), +For +.BR capset (), .I pid can also be: \-1, meaning perform the change on all threads except the caller and .IR init (8); or a value less than \-1, in which case the change is applied to all members of the process group whose ID is \-\fIpid\fP. - + For details on the data, see .BR capabilities (7). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP .B EFAULT -Bad memory address. Neither of +Bad memory address. +Neither of .I hdrp and .I datap @@ -126,12 +129,12 @@ to modify the capabilities of a thread other than itself, but lacked sufficient privilege; the .B CAP_SETPCAP capability is required. -(A bug in kernels before 2.6.11 meant that this error could also +(A bug in kernels before 2.6.11 meant that this error could also occur if a thread without this capability tried to change its own capabilities by specifying the .I pid field as a non-zero value (i.e., the value returned by -.BR getpid (2)) +.BR getpid (2)) instead of 0.) .TP .B ESRCH @@ -147,5 +150,5 @@ library and is available from here: .B ftp://ftp.kernel.org/pub/linux/libs/security/linux-privs .SH "SEE ALSO" .BR clone (2), -.BR gettid (2), +.BR gettid (2), .BR capabilities (7) diff --git a/man2/chdir.2 b/man2/chdir.2 index e6650805a..1352ca2c8 100644 --- a/man2/chdir.2 +++ b/man2/chdir.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,17 +50,19 @@ is identical to the only difference is that the directory is given as an open file descriptor. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -Depending on the file system, other errors can be returned. The more +Depending on the file system, other errors can be returned. +The more general errors for .BR chdir () are listed below: .TP .B EACCES -Search permission is denied for one of the directories +Search permission is denied for one of the directories in the path prefix of .IR path . (See also @@ -113,7 +115,7 @@ The current working directory is left unchanged by The prototype for .BR fchdir () is only available if -.B _BSD_SOURCE +.B _BSD_SOURCE is defined, or .B _XOPEN_SOURCE is defined with the value 500. diff --git a/man2/chmod.2 b/man2/chmod.2 index 0a8ea6132..a8610af48 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -114,15 +114,17 @@ directories, see On NFS file systems, restricting the permissions will immediately influence already open files, because the access control is done on the server, but -open files are maintained by the client. Widening the permissions may be +open files are maintained by the client. +Widening the permissions may be delayed for other clients if attribute caching is enabled on them. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -Depending on the file system, other errors can be returned. The more -general errors for +Depending on the file system, other errors can be returned. +The more general errors for .BR chmod () are listed below: .TP diff --git a/man2/chown.2 b/man2/chown.2 index 5a8e849ff..122c20b49 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -64,7 +64,8 @@ or is specified as \-1, then that ID is not changed. When the owner or group of an executable file are changed by a non-superuser, -the S_ISUID and S_ISGID mode bits are cleared. POSIX does not specify whether +the S_ISUID and S_ISGID mode bits are cleared. +POSIX does not specify whether this also should happen when root does the .BR chown (); the Linux behaviour depends on the kernel version. @@ -76,12 +77,13 @@ the S_ISGID bit indicates mandatory locking, and is not cleared by a .BR chown (). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -Depending on the file system, other errors can be returned. The more -general errors for +Depending on the file system, other errors can be returned. +The more general errors for .BR chown () are listed below. .TP @@ -166,13 +168,15 @@ used by the superuser (that is, ordinary users cannot give away files). .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no .\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. .\" fchown(): -.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK +.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK .\" error conditions. .SH RESTRICTIONS The \fBchown\fP() semantics are deliberately violated on NFS file systems -which have UID mapping enabled. Additionally, the semantics of all system +which have UID mapping enabled. +Additionally, the semantics of all system calls which access the file contents are violated, because \fBchown\fP() -may cause immediate access revocation on already open files. Client side +may cause immediate access revocation on already open files. +Client side caching may lead to a delay between the time where ownership have been changed to allow access for a user and the time where the file can actually be accessed by the user on other clients. diff --git a/man2/chroot.2 b/man2/chroot.2 index 37738d653..e3e199d94 100644 --- a/man2/chroot.2 +++ b/man2/chroot.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,8 +41,8 @@ chroot \- change root directory .BR chroot () changes the root directory to that specified in .IR path . -This directory will be used for pathnames beginning with /. The root -directory is inherited by all children of the current process. +This directory will be used for pathnames beginning with /. +The root directory is inherited by all children of the current process. Only a privileged process (Linux: one with the .B CAP_SYS_CHROOT @@ -60,12 +60,13 @@ by doing `mkdir foo; chroot foo; cd ..'. This call does not close open file descriptors, and such file descriptors may allow access to files outside the chroot tree. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -Depending on the file system, other errors can be returned. The more -general errors are listed below: +Depending on the file system, other errors can be returned. +The more general errors are listed below: .TP .B EACCES Search permission is denied on a component of the path prefix. @@ -103,7 +104,7 @@ is not a directory. .B EPERM The caller has insufficient privilege. .SH "CONFORMING TO" -SVr4, 4.4BSD, SUSv2 (marked LEGACY). +SVr4, 4.4BSD, SUSv2 (marked LEGACY). This function is not part of POSIX.1-2001. .\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions. .\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions. @@ -117,7 +118,7 @@ The root directory is left unchanged by FreeBSD has a stronger .BR jail () system call. -.\" FIXME -- eventually say something about containers, +.\" FIXME -- eventually say something about containers, .\" virtual servers, etc.? .SH "SEE ALSO" .BR chdir (2), diff --git a/man2/clone.2 b/man2/clone.2 index 3c745c606..ae8892b63 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -13,7 +13,7 @@ .\" Mostly upgraded to 2.4.x .\" Added prototype for sys_clone() plus description .\" Added CLONE_THREAD with a brief description of thread groups -.\" Added CLONE_PARENT and revised entire page remove ambiguity +.\" Added CLONE_PARENT and revised entire page remove ambiguity .\" between "calling process" and "parent process" .\" Added CLONE_PTRACE and CLONE_VFORK .\" Added EPERM and EINVAL error codes @@ -57,7 +57,7 @@ creates a new process, in a manner similar to .BR fork (2). .BR clone () is a library function layered on top -of the underlying +of the underlying .BR clone () system call, hereinafter referred to as .BR sys_clone . @@ -67,13 +67,14 @@ is given towards the end of this page. Unlike .BR fork (2), -these calls +these calls allow the child process to share parts of its execution context with the calling process, such as the memory space, the table of file -descriptors, and the table of signal handlers. (Note that on this manual -page, "calling process" normally corresponds to "parent process". But see -the description of -.B CLONE_PARENT +descriptors, and the table of signal handlers. +(Note that on this manual +page, "calling process" normally corresponds to "parent process". +But see the description of +.B CLONE_PARENT below.) The main use of @@ -82,15 +83,15 @@ is to implement threads: multiple threads of control in a program that run concurrently in a shared memory space. When the child process is created with -.BR clone (), +.BR clone (), it executes the function application -.IR fn ( arg ). +.IR fn ( arg ). (This differs from -.BR fork (2), +.BR fork (2), where execution continues in the child from the point -of the -.BR fork (2) +of the +.BR fork (2) call.) The .I fn @@ -102,22 +103,23 @@ argument is passed to the .I fn function. -When the +When the .IR fn ( arg ) -function application returns, the child process terminates. The -integer returned by +function application returns, the child process terminates. +The integer returned by .I fn -is the exit code for the child process. The child process may also -terminate explicitly by calling +is the exit code for the child process. +The child process may also terminate explicitly by calling .BR exit (2) or after receiving a fatal signal. The .I child_stack -argument specifies the location of the stack used by the child -process. Since the child and calling process may share memory, +argument specifies the location of the stack used by the child process. +Since the child and calling process may share memory, it is not possible for the child process to execute in the -same stack as the calling process. The calling process must therefore +same stack as the calling process. +The calling process must therefore set up memory space for the child stack and pass a pointer to this space to .BR clone (). @@ -135,11 +137,11 @@ sent to the parent when the child dies. If this signal is specified as anything other than .BR SIGCHLD , then the parent process must specify the -.B __WALL -or +.B __WALL +or .B __WCLONE -options when waiting for the child with -.BR wait (2). +options when waiting for the child with +.BR wait (2). If no signal is specified, then the parent process is not signaled when the child terminates. @@ -161,20 +163,22 @@ is not set, then (as with .BR fork (2)) the child's parent is the calling process. -Note that it is the parent process, as returned by +Note that it is the parent process, as returned by .BR getppid (2), which is signaled when the child terminates, so that -if +if .B CLONE_PARENT -is set, then the parent of the calling process, rather than the +is set, then the parent of the calling process, rather than the calling process itself, will be signaled. .TP .B CLONE_FS If .B CLONE_FS is set, the caller and the child processes share the same file system -information. This includes the root of the file system, the current -working directory, and the umask. Any call to +information. +This includes the root of the file system, the current +working directory, and the umask. +Any call to .BR chroot (2), .BR chdir (2), or @@ -182,7 +186,7 @@ or performed by the calling process or the child process also affects the other process. -If +If .B CLONE_FS is not set, the child process works on a copy of the file system information of the calling process at the time of the @@ -199,7 +203,7 @@ If .B CLONE_FILES is set, the calling process and the child processes share the same file descriptor table. -Any file descriptor created by the calling process or by the child +Any file descriptor created by the calling process or by the child process is also valid in the other process. Similarly, if one of the processes closes a file descriptor, or changes its associated flags (using the @@ -213,21 +217,23 @@ is not set, the child process inherits a copy of all file descriptors opened in the calling process at the time of .BR clone (). (The duplicated file descriptors in the child refer to the -same open file descriptions (see +same open file descriptions (see .BR open (2)) as the corresponding file descriptors in the calling process.) Subsequent operations that open or close file descriptors, or change file descriptor flags, -performed by either the calling +performed by either the calling process or the child process do not affect the other process. .TP .BR CLONE_NEWNS " (since Linux 2.4.19)" Start the child in a new namespace. -Every process lives in a namespace. The +Every process lives in a namespace. +The .I namespace of a process is the data (the set of mounts) describing the file hierarchy -as seen by that process. After a +as seen by that process. +After a .BR fork (2) or .BR clone (2) @@ -265,12 +271,15 @@ call. If .B CLONE_SIGHAND is set, the calling process and the child processes share the same table of -signal handlers. If the calling process or child process calls +signal handlers. +If the calling process or child process calls .BR sigaction (2) -to change the behavior associated with a signal, the behavior is -changed in the other process as well. However, the calling process and child +to change the behavior associated with a signal, the behavior is +changed in the other process as well. +However, the calling process and child processes still have distinct signal masks and sets of pending -signals. So, one of them may block or unblock some signals using +signals. +So, one of them may block or unblock some signals using .BR sigprocmask (2) without affecting the other process. @@ -279,7 +288,8 @@ If is not set, the child process inherits a copy of the signal handlers of the calling process at the time .BR clone () -is called. Calls to +is called. +Calls to .BR sigaction (2) performed later by one of the processes have no effect on the other process. @@ -293,14 +303,14 @@ if is specified .TP .B CLONE_PTRACE -If +If .B CLONE_PTRACE is specified, and the calling process is being traced, then trace the child also (see .BR ptrace (2)). .TP .BR CLONE_UNTRACED " (since Linux 2.5.46)" -If +If .B CLONE_UNTRACED is specified, then a tracing process cannot force .B CLONE_PTRACE @@ -324,10 +334,10 @@ resources via a call to .BR execve (2) or .BR _exit (2) -(as with +(as with .BR vfork (2)). -If +If .B CLONE_VFORK is not set then both the calling process and the child are schedulable after the call, and an application should not rely on execution occurring @@ -337,7 +347,8 @@ in any particular order. If .B CLONE_VM is set, the calling process and the child processes run in the same memory -space. In particular, memory writes performed by the calling process +space. +In particular, memory writes performed by the calling process or by the child process are also visible in the other process. Moreover, any memory mapping or unmapping performed with .BR mmap (2) @@ -357,9 +368,11 @@ processes do not affect the other, as with .BR CLONE_PID " (obsolete)" If .B CLONE_PID -is set, the child process is created with the same process ID as -the calling process. This is good for hacking the system, but otherwise -of not much use. Since 2.3.21 this flag can be +is set, the child process is created with the same process ID as +the calling process. +This is good for hacking the system, but otherwise +of not much use. +Since 2.3.21 this flag can be specified only by the system boot process (PID 0). It disappeared in Linux 2.5.16. .TP @@ -376,7 +389,7 @@ Thread groups were a feature added in Linux 2.4 to support the POSIX threads notion of a set of threads that share a single PID. Internally, this shared PID is the so-called thread group identifier (TGID) for the thread group. -Since Linux 2.4, calls to +Since Linux 2.4, calls to .BR getpid (2) return the TGID of the caller. @@ -389,7 +402,7 @@ and a thread can obtain its own TID using .BR gettid (2). -When a call is made to +When a call is made to .BR clone () without specifying .BR CLONE_THREAD , @@ -403,13 +416,13 @@ A new thread created with .B CLONE_THREAD has the same parent process as the caller of .BR clone () -(i.e., like +(i.e., like .BR CLONE_PARENT ), so that calls to .BR getppid (2) return the same value for all of the threads in a thread group. When a -.B CLONE_THREAD +.B CLONE_THREAD thread terminates, the thread that created it using .BR clone () is not sent a @@ -468,16 +481,16 @@ A call to returns a signal set that is the union of the signals pending for the whole process and the signals that are pending for the calling thread. -If +If .BR kill (2) is used to send a signal to a thread group, and the thread group has installed a handler for the signal, then the handler will be invoked in exactly one, arbitrarily selected member of the thread group that has not blocked the signal. -If multiple threads in a group are waiting to accept the same signal using +If multiple threads in a group are waiting to accept the same signal using .BR sigwaitinfo (2), the kernel will arbitrarily select one of these threads -to receive a signal sent using +to receive a signal sent using .BR kill (2). .TP .BR CLONE_SYSVSEM " (since Linux 2.5.10)" @@ -514,31 +527,34 @@ in child memory when the child exits, and do a wakeup on the futex at that address. The address involved may be changed by the .BR set_tid_address (2) -system call. This is used by threading libraries. +system call. +This is used by threading libraries. .SS "sys_clone" The .B sys_clone system call corresponds more closely to .BR fork (2) in that execution in the child continues from the point of the -call. Thus, +call. +Thus, .B sys_clone only requires the .I flags -and +and .I child_stack -arguments, which have the same meaning as for -.BR clone (). +arguments, which have the same meaning as for +.BR clone (). (Note that the order of these arguments differs from -.BR clone ().) +.BR clone ().) -Another difference for +Another difference for .B sys_clone is that the .I child_stack -argument may be zero, in which case copy-on-write semantics ensure that the +argument may be zero, in which case copy-on-write semantics ensure that the child gets separate copies of stack pages when either process modifies -the stack. In this case, for correct operation, the +the stack. +In this case, for correct operation, the .B CLONE_VM option should not be specified. @@ -555,7 +571,8 @@ will be written in case CLONE_CHILD_SETTID was specified. .\" gettid() returns current->pid; .\" getpid() returns current->tgid; On success, the thread ID of the child process is returned -in the caller's thread of execution. On failure, a \-1 will be returned +in the caller's thread of execution. +On failure, a \-1 will be returned in the caller's context, no child process will be created, and .I errno will be set appropriately. @@ -592,9 +609,9 @@ were specified in .IR flags . .TP .B EINVAL -Returned by +Returned by .BR clone () -when a zero value is specified for +when a zero value is specified for .IR child_stack . .TP .B ENOMEM @@ -623,16 +640,16 @@ as the parent of the calling process. However, for kernel versions 2.4.7 to 2.4.18 the .B CLONE_THREAD flag implied the -.B CLONE_PARENT +.B CLONE_PARENT flag (as in kernel 2.6). -For a while there was -.B CLONE_DETACHED +For a while there was +.B CLONE_DETACHED (introduced in 2.5.32): -parent wants no child-exit signal. +parent wants no child-exit signal. In 2.6.2 the need to give this -together with -.B CLONE_THREAD +together with +.B CLONE_THREAD disappeared. This flag is still defined, but has no effect. @@ -641,7 +658,7 @@ On x86, should not be called through vsyscall, but directly through .IR "int $0x80" . -On IA-64, a different system call is used: +On IA-64, a different system call is used: .nf .BI "int clone2(int (*" "fn" ")(void *), " @@ -653,7 +670,7 @@ On IA-64, a different system call is used: .PP The .BR clone2 () -system call operates in the same way as +system call operates in the same way as .BR clone (), except that .I child_stack_base @@ -671,10 +688,10 @@ calls are Linux specific and should not be used in programs intended to be portable. .SH BUGS Versions of the GNU C library that include the NPTL threading library -contain a wrapper function for +contain a wrapper function for .BR getpid () that performs caching of PIDs. -In programs linked against such libraries, calls to +In programs linked against such libraries, calls to .BR getpid () may return the same value, even when the threads were not created using .B CLONE_THREAD diff --git a/man2/close.2 b/man2/close.2 index 084d40d14..f4ea323c8 100644 --- a/man2/close.2 +++ b/man2/close.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -79,24 +79,28 @@ call was interrupted by a signal. .B EIO An I/O error occurred. .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents an additional ENOLINK error condition. .SH NOTES -Not checking the return value of +Not checking the return value of .BR close () is a common but nevertheless -serious programming error. It is quite possible that errors on a +serious programming error. +It is quite possible that errors on a previous .BR write (2) operation are first reported at the final .BR close (). Not checking the return value when closing the file may lead to -silent loss of data. This can especially be observed with NFS +silent loss of data. +This can especially be observed with NFS and with disk quota. .PP A successful close does not guarantee that the data has been successfully -saved to disk, as the kernel defers writes. It is not common for a filesystem -to flush the buffers when the stream is closed. If you need to be sure that +saved to disk, as the kernel defers writes. +It is not common for a filesystem +to flush the buffers when the stream is closed. +If you need to be sure that the data is physically stored use .BR fsync (2). (It will depend on the disk hardware at this point.) diff --git a/man2/connect.2 b/man2/connect.2 index 31bf45f29..12f7fc5ba 100644 --- a/man2/connect.2 +++ b/man2/connect.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -82,7 +82,7 @@ system call connects the socket referred to by the file descriptor to the address specified by .IR serv_addr . The -.IR addrlen +.IR addrlen argument specifies the size of .IR serv_addr . The format of the address in @@ -100,7 +100,8 @@ is of type then .I serv_addr is the address to which datagrams are sent by default, and the only -address from which datagrams are received. If the socket is of type +address from which datagrams are received. +If the socket is of type .B SOCK_STREAM or .BR SOCK_SEQPACKET , @@ -112,21 +113,22 @@ Generally, connection-based protocol sockets may successfully .BR connect () only once; connectionless protocol sockets may use .BR connect () -multiple times to change their association. Connectionless sockets may -dissolve the association by connecting to an address with the +multiple times to change their association. +Connectionless sockets may +dissolve the association by connecting to an address with the .I sa_family member of -.B sockaddr -set to +.B sockaddr +set to .BR AF_UNSPEC . .SH "RETURN VALUE" -If the connection or binding succeeds, zero is returned. On error, \-1 is -returned, and +If the connection or binding succeeds, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -The following are general socket errors only. There may be other -domain-specific error codes. +The following are general socket errors only. +There may be other domain-specific error codes. .TP .B EACCES For Unix domain sockets, which are identified by pathname: @@ -137,7 +139,7 @@ in the path prefix. .BR path_resolution (2).) .TP .B EACCES, EPERM -The user tried to connect to a broadcast address without having the socket +The user tried to connect to a broadcast address without having the socket broadcast flag enabled or the connection request failed because of a local firewall rule. .TP @@ -145,17 +147,18 @@ firewall rule. Local address is already in use. .TP .B EAFNOSUPPORT -The passed address didn't have the correct address family in its +The passed address didn't have the correct address family in its .I sa_family field. .TP .B EAGAIN -No more free local ports or insufficient entries in the routing cache. For +No more free local ports or insufficient entries in the routing cache. +For .B PF_INET -see the +see the .B net.ipv4.ip_local_port_range -sysctl in -.BR ip (7) +sysctl in +.BR ip (7) on how to increase the number of local ports. .TP .B EALREADY @@ -173,25 +176,27 @@ The socket structure address is outside the user's address space. .TP .B EINPROGRESS The socket is non-blocking and the connection cannot be completed -immediately. It is possible to +immediately. +It is possible to .BR select (2) -or -.BR poll (2) -for completion by selecting the socket for writing. After +or +.BR poll (2) +for completion by selecting the socket for writing. +After .BR select (2) indicates writability, use .BR getsockopt (2) -to read the +to read the .B SO_ERROR -option at level +option at level .B SOL_SOCKET -to determine whether +to determine whether .BR connect () -completed successfully +completed successfully .RB ( SO_ERROR -is zero) or unsuccessfully +is zero) or unsuccessfully .RB ( SO_ERROR -is one of the usual error codes listed here, +is one of the usual error codes listed here, explaining the reason for the failure). .TP .B EINTR @@ -209,23 +214,25 @@ Network is unreachable. The file descriptor is not associated with a socket. .TP .B ETIMEDOUT -Timeout while attempting connection. The server may be too -busy to accept new connections. Note that for IP sockets the timeout may +Timeout while attempting connection. +The server may be too +busy to accept new connections. +Note that for IP sockets the timeout may be very long when syncookies are enabled on the server. .SH "CONFORMING TO" SVr4, 4.4BSD, (the .BR connect () -function first appeared in 4.2BSD), POSIX.1-2001. +function first appeared in 4.2BSD), POSIX.1-2001. .\" SVr4 documents the additional -.\" general error codes -.\" .BR EADDRNOTAVAIL , -.\" .BR EINVAL , -.\" .BR EAFNOSUPPORT , -.\" .BR EALREADY , -.\" .BR EINTR , -.\" .BR EPROTOTYPE , +.\" general error codes +.\" .BR EADDRNOTAVAIL , +.\" .BR EINVAL , +.\" .BR EAFNOSUPPORT , +.\" .BR EALREADY , +.\" .BR EINTR , +.\" .BR EPROTOTYPE , .\" and -.\" .BR ENOSR . +.\" .BR ENOSR . .\" It also .\" documents many additional error conditions not described here. .SH NOTE @@ -234,7 +241,7 @@ The third argument of is in reality an .I int (and this is what 4.x BSD and libc4 and libc5 have). -Some POSIX confusion resulted in the present +Some POSIX confusion resulted in the present .IR socklen_t , also used by glibc. See also diff --git a/man2/create_module.2 b/man2/create_module.2 index 92dcbddb4..24374f9ad 100644 --- a/man2/create_module.2 +++ b/man2/create_module.2 @@ -2,7 +2,7 @@ .\" This file is distributed according to the GNU General Public License. .\" See the file COPYING in the top level source directory for details. .\" -.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" .TH CREATE_MODULE 2 "2002" Linux "Linux Module Support" @@ -49,7 +49,7 @@ capability). .BR create_module () is Linux specific. .SH NOTES -This system call is only present on Linux up until kernel 2.4; +This system call is only present on Linux up until kernel 2.4; it was removed in Linux 2.6. .\" Removed in Linux-2.5.48 .SH "SEE ALSO" diff --git a/man2/delete_module.2 b/man2/delete_module.2 index eba70f95b..78fb4dbfe 100644 --- a/man2/delete_module.2 +++ b/man2/delete_module.2 @@ -2,7 +2,7 @@ .\" This file is distributed according to the GNU General Public License. .\" See the file COPYING in the top level source directory for details. .\" -.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" .TH DELETE_MODULE 2 "2002" Linux "Linux Module Support" @@ -23,7 +23,8 @@ is NULL, all unused modules marked auto-clean will be removed. This system call requires privilege. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned and +On success, zero is returned. +On error, \-1 is returned and .I errno is set appropriately. .SH ERRORS diff --git a/man2/dup.2 b/man2/dup.2 index 295b0dfcf..d81147ce5 100644 --- a/man2/dup.2 +++ b/man2/dup.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,8 +40,8 @@ dup, dup2 \- duplicate a file descriptor .BI "int dup2(int " oldfd ", int " newfd ); .fi .SH DESCRIPTION -.BR dup () -and +.BR dup () +and .BR dup2 () create a copy of the file descriptor .IR oldfd . @@ -57,8 +57,8 @@ on one of the descriptors, the offset is also changed for the other. The two descriptors do not share file descriptor flags (the close-on-exec flag). -The close-on-exec flag -.RB ( FD_CLOEXEC ; +The close-on-exec flag +.RB ( FD_CLOEXEC ; see .BR fcntl (2)) for the duplicate descriptor is off. @@ -70,8 +70,8 @@ uses the lowest-numbered unused descriptor for the new descriptor. .RI "makes " newfd " be the copy of " oldfd ", closing " newfd first if necessary. .SH "RETURN VALUE" -.BR dup () -and +.BR dup () +and .BR dup2 () return the new descriptor, or \-1 if an error occurred (in which case, .I errno @@ -88,8 +88,8 @@ is out of the allowed range for file descriptors. (Linux only) This may be returned by .BR dup2 () during a race condition with -.BR open () -and +.BR open () +and .BR dup (). .TP .B EINTR @@ -107,7 +107,8 @@ is different from that returned by .BR fcntl( "..., " F_DUPFD ", ..." ) when .I newfd -is out of range. On some systems +is out of range. +On some systems .BR dup2 () also sometimes returns .B EINVAL @@ -118,13 +119,14 @@ If .I newfd was open, any errors that would have been reported at .BR close () -time, are lost. A careful programmer will not use +time, are lost. +A careful programmer will not use .BR dup2 () without closing .I newfd first. .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional .\" EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. .\" The EBUSY return is Linux specific. diff --git a/man2/epoll_create.2 b/man2/epoll_create.2 index 98ceb4835..b17c36b28 100644 --- a/man2/epoll_create.2 +++ b/man2/epoll_create.2 @@ -34,13 +34,15 @@ Open an file descriptor by requesting the kernel allocate an event backing store dimensioned for .I size -descriptors. The +descriptors. +The .I size is not the maximum size of the backing store but just a hint to the kernel about how to dimension internal structures. The returned file descriptor will be used for all the subsequent calls to the .B epoll -interface. The file descriptor returned by +interface. +The file descriptor returned by .BR epoll_create (2) must be closed by using .BR close (2). @@ -48,7 +50,7 @@ must be closed by using When successful, .BR epoll_create (2) returns a non-negative integer identifying the descriptor. -When an error occurs, +When an error occurs, .BR epoll_create (2) returns \-1 and .I errno diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 index cf36b46c3..7d732898f 100644 --- a/man2/epoll_ctl.2 +++ b/man2/epoll_ctl.2 @@ -74,9 +74,9 @@ The associated file is available for operations. .TP .BR EPOLLRDHUP " (since kernel 2.6.17)" -Stream socket peer closed connection, +Stream socket peer closed connection, or shut down writing half of connection. -(This flag is especially useful for writing simple code to detect +(This flag is especially useful for writing simple code to detect peer shutdown when using Edge Triggered monitoring.) .TP .B EPOLLPRI @@ -100,7 +100,8 @@ will always wait for this event; it is not necessary to set it in Sets the Edge Triggered behaviour for the associated file descriptor. The default behaviour for .B epoll -is Level Triggered. See +is Level Triggered. +See .BR epoll (7) for more detailed information about Edge and Level Triggered event distribution architectures. @@ -112,7 +113,8 @@ This means that after an event is pulled out with the associated file descriptor is internally disabled and no other events will be reported by the .B epoll -interface. The user must call +interface. +The user must call .BR epoll_ctl (2) with .B EPOLL_CTL_MOD @@ -157,9 +159,10 @@ The is ignored and can be NULL (but see BUGS below). .RE .SH "RETURN VALUE" -When successful, +When successful, .BR epoll_ctl (2) -returns zero. When an error occurs, +returns zero. +When an error occurs, .BR epoll_ctl (2) returns \-1 and .I errno @@ -180,12 +183,12 @@ is already in .IR epfd . .TP .B EINVAL -.IR epfd +.IR epfd is not an .B epoll file descriptor, or -.IR fd +.IR fd is the same as .IR epfd , or the requested operation @@ -216,13 +219,13 @@ is Linux specific, and was introduced in kernel 2.5.44. .SH BUGS In kernel versions before 2.6.9, the .B EPOLL_CTL_DEL -operation required a non-NULL pointer in +operation required a non-NULL pointer in .IR event , even though this argument is ignored. Since kernel 2.6.9, .I event can be specified as NULL -when using +when using .BR EPOLL_CTL_DEL . .SH "SEE ALSO" .BR epoll_create (2), diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 index 75cb5b791..ed52ad09f 100644 --- a/man2/epoll_wait.2 +++ b/man2/epoll_wait.2 @@ -19,7 +19,7 @@ .\" Davide Libenzi .\" .\" -.\" FIXME 2.6.19-rc5 has epoll_pwait(); this should be documented +.\" FIXME 2.6.19-rc5 has epoll_pwait(); this should be documented .\" on this page. .\" .TH EPOLL_WAIT 2 "23 October 2002" Linux "Linux Programmer's Manual" @@ -29,7 +29,7 @@ epoll_wait \- wait for an I/O event on an epoll file descriptor .nf .B #include .sp -.BI "int epoll_wait(int " epfd ", struct epoll_event *" events , +.BI "int epoll_wait(int " epfd ", struct epoll_event *" events , .BI " int " maxevents ", int " timeout); .fi .SH DESCRIPTION @@ -39,7 +39,8 @@ file descriptor .I epfd for a maximum time of .I timeout -milliseconds. The memory area pointed to by +milliseconds. +The memory area pointed to by .I events will contain the events that will be available for the caller. Up to @@ -48,7 +49,8 @@ are returned by .BR epoll_wait (2). The .I maxevents -parameter must be greater than zero. Specifying a +parameter must be greater than zero. +Specifying a .I timeout of \-1 makes .BR epoll_wait (2) @@ -56,7 +58,7 @@ wait indefinitely, while specifying a .I timeout equal to zero makes .BR epoll_wait (2) -to return immediately even if no events are available +to return immediately even if no events are available (return code equal to zero). The .I struct epoll_event @@ -87,12 +89,13 @@ while the .I events member will contain the returned event bit field. .SH "RETURN VALUE" -When successful, +When successful, .BR epoll_wait (2) returns the number of file descriptors ready for the requested I/O, or zero if no file descriptor became ready during the requested .I timeout -milliseconds. When an error occurs, +milliseconds. +When an error occurs, .BR epoll_wait (2) returns \-1 and .I errno @@ -115,7 +118,7 @@ requested events occurred or the expired. .TP .B EINVAL -.IR epfd +.IR epfd is not an .B epoll file descriptor, or diff --git a/man2/execve.2 b/man2/execve.2 index 41dc2b898..2a372a467 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,15 +51,15 @@ executable which is not itself a script, which will be invoked as \fIargv\fP is an array of argument strings passed to the new program. \fIenvp\fP is an array of strings, conventionally of the form -\fBkey=value\fR, which are passed as environment to the new -program. Both \fIargv\fP and \fIenvp\fP must be terminated by a null -pointer. The argument vector and environment can be accessed by the +\fBkey=value\fR, which are passed as environment to the new program. +Both \fIargv\fP and \fIenvp\fP must be terminated by a null pointer. +The argument vector and environment can be accessed by the called program's main function, when it is defined as \fBint main(int argc, char *argv[], char *envp[])\fR. \fBexecve\fP() does not return on success, and the text, data, bss, and stack of the calling process are overwritten by that of the program -loaded. +loaded. If the current program is being ptraced, a \fBSIGTRAP\fP is sent to it after a successful \fBexecve\fP(). @@ -74,20 +74,21 @@ process is set to the group of the program file. The effective user ID of the process is copied to the saved set-user-ID; similarly, the effective group ID is copied to the saved set-group-ID. -This copying takes place after any effective ID changes that occur +This copying takes place after any effective ID changes that occur because of the set-user-ID and set-group-ID permission bits. -If the executable is an a.out dynamically-linked +If the executable is an a.out dynamically-linked binary executable containing shared-library stubs, the Linux dynamic linker .BR ld.so (8) -is called at the start of execution to bring +is called at the start of execution to bring needed shared libraries into memory and link the executable with them. If the executable is a dynamically-linked ELF executable, the interpreter named in the PT_INTERP segment is used to load the needed -shared libraries. This interpreter is typically +shared libraries. +This interpreter is typically \fI/lib/ld-linux.so.1\fR for binaries linked with the Linux libc version 5, or \fI/lib/ld-linux.so.2\fR for binaries linked with the GNU libc version 2. @@ -106,7 +107,7 @@ in The set of pending signals is cleared .RB ( sigpending (2)). .IP * 4 -The dispositions of any signals that are being caught are +The dispositions of any signals that are being caught are reset to being ignored. .IP * 4 Any alternate signal stack is not preserved @@ -141,27 +142,27 @@ Exit handlers are not preserved .RB ( atexit (3), .BR on_exit (3)). .PP -The process attributes in the preceding list are all specified +The process attributes in the preceding list are all specified in POSIX.1-2001. -The following Linux-specific process attributes are also +The following Linux-specific process attributes are also not preserved during an .BR execve (): .IP * 4 -The +The .BR prctl (2) -.B PR_SET_DUMPABLE +.B PR_SET_DUMPABLE flag is set, unless a set-user-ID or set-group ID program is being executed, in which case it is cleared. .IP * 4 -The +The .BR prctl (2) .B PR_SET_KEEPCAPS flag is cleared. .IP * 4 The process name, as set by .BR prctl (2) -.BR PR_SET_NAME +.BR PR_SET_NAME (and displayed by .IR "ps -o comm" ), is reset to the name of the new executable file. @@ -179,17 +180,17 @@ Mutexes, condition variables, and other pthreads objects are not preserved. The equivalent of \fIsetlocale(LC_ALL, "C")\fP is executed at program start-up. .IP * 4 -POSIX.1-2001 specifies that the dispositions of any signals that +POSIX.1-2001 specifies that the dispositions of any signals that are ignored or set to the default are left unchanged. -POSIX.1-2001 specifies one exception: if SIGCHLD is being ignored, -then an implementation may leave the disposition unchanged or +POSIX.1-2001 specifies one exception: if SIGCHLD is being ignored, +then an implementation may leave the disposition unchanged or reset it to the default; Linux does the former. .IP * 4 Any outstanding asynchronous I/O operations are cancelled .RB ( aio_read (3), .BR aio_write (3)). .IP * 4 -For the handling of capabilities during +For the handling of capabilities during .BR execve (2), see .BR capabilities (7). @@ -200,9 +201,9 @@ is set appropriately. .SH ERRORS .TP .B E2BIG -The total number of bytes in the environment +The total number of bytes in the environment .RI ( envp ) -and argument list +and argument list .RI ( argv ) is too large. .TP @@ -256,7 +257,7 @@ is too long. The system limit on the total number of open files has been reached. .TP .B ENOENT -The file +The file .I filename or a script or ELF interpreter does not exist, or a shared library needed for file or interpreter cannot be found. @@ -277,7 +278,7 @@ or a script or ELF interpreter is not a directory. .B EPERM The file system is mounted .IR nosuid , -the user is not the superuser, +the user is not the superuser, and the file has the set-user-ID or set-group-ID bit set. .TP .B EPERM @@ -287,9 +288,9 @@ file has the set-user-ID or set-group-ID bit set. .B ETXTBSY Executable was open for writing by one or more processes. .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2001 does not document the #! behavior -but is otherwise compatible. +but is otherwise compatible. .\" SVr4 documents additional error .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, @@ -302,15 +303,15 @@ Linux ignores the set-user-ID and set-group-ID bits on scripts. The result of mounting a filesystem .I nosuid vary between Linux kernel versions: -some will refuse execution of set-user-ID and set-group-ID +some will refuse execution of set-user-ID and set-group-ID executables when this would give the user powers she did not have already (and return EPERM), -some will just ignore the set-user-ID and set-group-ID bits and +some will just ignore the set-user-ID and set-group-ID bits and .BR exec () successfully. A maximum line length of 127 characters is allowed for the first line in -a #! executable shell script. +a #! executable shell script. .\" .SH BUGS .\" Some Linux versions have failed to check permissions on ELF .\" interpreters. This is a security hole, because it allows users to @@ -319,14 +320,14 @@ a #! executable shell script. .\" that could be exploited for denial of service by a suitably crafted .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. .SH HISTORICAL -With Unix V6 the argument list of an +With Unix V6 the argument list of an .BR exec () call was ended by 0, while the argument list of .I main was ended by \-1. Thus, this -argument list was not directly usable in a further -.BR exec () +argument list was not directly usable in a further +.BR exec () call. Since Unix V7 both are NULL. .SH "SEE ALSO" diff --git a/man2/exit_group.2 b/man2/exit_group.2 index 5f4882266..9ebdcdf50 100644 --- a/man2/exit_group.2 +++ b/man2/exit_group.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man2/faccessat.2 b/man2/faccessat.2 index 81798f128..6c1936a8c 100644 --- a/man2/faccessat.2 +++ b/man2/faccessat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,53 +43,53 @@ system call operates in exactly the same way as .BR access (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR access (2) for a relative pathname). -If +If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR access (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .I flags is constructed by ORing together zero or more of the following values: .TP .B AT_EACCESS -Perform access checks using the effective user and group IDs. -By default, +Perform access checks using the effective user and group IDs. +By default, .BR faccessat () uses the real IDs (like .BR access (2)). .TP .B AT_SYMLINK_NOFOLLOW -If +If .I pathname -is a symbolic link, do not dereference it: +is a symbolic link, do not dereference it: instead return information about the link itself. .SH "RETURN VALUE" On success, (all requested permissions granted) -.BR faccessat () -returns 0. +.BR faccessat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -98,7 +98,7 @@ The same errors that occur for .BR access (2) can also occur for .BR faccessat (). -The following additional errors can occur for +The following additional errors can occur for .BR faccessat (): .TP .B EBADF @@ -127,9 +127,9 @@ The .B AT_EACCESS and .B AT_SYMLINK_NOFOLLOW -flags are actually implemented within the glibc wrapper function for +flags are actually implemented within the glibc wrapper function for .BR faccessat (). -If either of these flags are specified, then the wrapper function employs +If either of these flags are specified, then the wrapper function employs .BR fstatat (2) to determine access permissions. .SH VERSIONS diff --git a/man2/fchmodat.2 b/man2/fchmodat.2 index 88f65ef3f..38ffadb7c 100644 --- a/man2/fchmodat.2 +++ b/man2/fchmodat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,47 +42,47 @@ system call operates in exactly the same way as .BR chmod (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR chmod (2) for a relative pathname). -If +If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR chmod (2)). -If +If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .I flags can either be 0, or include the following flag: .TP .B AT_SYMLINK_NOFOLLOW -If +If .I pathname -is a symbolic link, do not dereference it: +is a symbolic link, do not dereference it: instead operate on the link itself. This flag is not currently implemented. .SH "RETURN VALUE" On success, -.BR fchmodat () -returns 0. +.BR fchmodat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -91,7 +91,7 @@ The same errors that occur for .BR chmod (2) can also occur for .BR fchmodat (). -The following additional errors can occur for +The following additional errors can occur for .BR fchmodat (): .TP .B EBADF @@ -109,7 +109,7 @@ is relative and is a file descriptor referring to a file other than a directory. .TP .B ENOTSUP -.IR flags +.IR flags specified .BR AT_SYMLINK_NOFOLLOW , which is not supported. diff --git a/man2/fchownat.2 b/man2/fchownat.2 index 6522afb42..0724cf28c 100644 --- a/man2/fchownat.2 +++ b/man2/fchownat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,7 +32,7 @@ file descriptor .B #define _ATFILE_SOURCE .B #include .sp -.BI "int fchownat(int " dirfd ", const char *" pathname , +.BI "int fchownat(int " dirfd ", const char *" pathname , .BI " uid_t " owner ", gid_t " group ", int " flags ); .fi .SH DESCRIPTION @@ -42,51 +42,51 @@ system call operates in exactly the same way as .BR chown (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR chown (2) for a relative pathname). -If +If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR chown (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .I flags can either be 0, or include the following flag: .TP .B AT_SYMLINK_NOFOLLOW -If +If .I pathname -is a symbolic link, do not dereference it: +is a symbolic link, do not dereference it: instead operate on the link itself, like -.BR lchown (2). +.BR lchown (2). (By default, .BR fchownat () dereferences symbolic links, like .BR chown (2).) .SH "RETURN VALUE" On success, -.BR fchownat () -returns 0. +.BR fchownat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -95,7 +95,7 @@ The same errors that occur for .BR chown (2) can also occur for .BR fchownat (). -The following additional errors can occur for +The following additional errors can occur for .BR fchownat (): .TP .B EBADF diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 79e832ff3..502e8a39f 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -14,7 +14,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -22,7 +22,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,12 +44,12 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool -.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. +.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. .\" 2005-04-08 Jamie Lokier , mtk .\" Described behaviour of F_SETOWN/F_SETSIG in .\" multi-threaded processes, and generally cleaned .\" up the discussion of F_SETOWN. -.\" 2005-05-20, Johannes Nicolai , +.\" 2005-05-20, Johannes Nicolai , .\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4 .\" and earlier. Added text on permissions required to send signal. .\" @@ -90,7 +90,7 @@ See for further details. .SS "File descriptor flags" The following commands manipulate the flags associated with -a file descriptor. +a file descriptor. Currently, only one such flag is defined: .BR FD_CLOEXEC , the close-on-exec flag. @@ -114,7 +114,7 @@ initialized by .\" .BR creat (2), and possibly modified by .BR fcntl (2). -Duplicated file descriptors +Duplicated file descriptors (made with .BR dup (), .BR fcntl (F_DUPFD), @@ -131,7 +131,7 @@ Read the file status flags. .B F_SETFL Set the file status flags to the value specified by .IR arg . -File access mode +File access mode .RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR ) and file creation flags (i.e., @@ -140,12 +140,12 @@ in .I arg are ignored. On Linux this command can only change the -.BR O_APPEND , +.BR O_APPEND , .BR O_ASYNC , .BR O_DIRECT , .BR O_NOATIME , -and -.BR O_NONBLOCK +and +.BR O_NONBLOCK flags. .\" FIXME According to POSIX.1-2001, O_SYNC should also be modifiable .\" via fcntl(2), but currently Linux does not permit this @@ -322,7 +322,7 @@ Because of the buffering performed by the library, the use of record locking with routines in that package should be avoided; use .BR read (2) -and +and .BR write (2) instead. .SS "Mandatory locking" @@ -331,9 +331,9 @@ The above record locks may be either advisory or mandatory, and are advisory by default. Advisory locks are not enforced and are useful only between -cooperating processes. +cooperating processes. -Mandatory locks are enforced for all processes. +Mandatory locks are enforced for all processes. If a process tries to perform an incompatible access (e.g., .BR read (2) or @@ -342,33 +342,33 @@ on a file region that has an incompatible mandatory lock, then the result depends upon whether the .B O_NONBLOCK flag is enabled for its open file description. -If the +If the .B O_NONBLOCK flag is not enabled, then system call is blocked until the lock is removed or converted to a mode that is compatible with the access. -If the -.B O_NONBLOCK +If the +.B O_NONBLOCK flag is enabled, then the system call fails with the error -.BR EAGAIN +.BR EAGAIN or .BR EWOULDBLOCK. To make use of mandatory locks, mandatory locking must be enabled -both on the file system that contains the file to be locked, +both on the file system that contains the file to be locked, and on the file itself. Mandatory locking is enabled on a file system using the "\-o mand" option to .BR mount (8), -or the +or the .B MS_MANDLOCK -flag for +flag for .BR mount (2). Mandatory locking is enabled on a file by disabling group execute permission on the file and enabling the set-group-ID permission bit (see .BR chmod (1) -and +and .BR chmod (2)). .SS "Managing signals" .BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " and " F_SETSIG @@ -398,8 +398,8 @@ If you set the .B O_ASYNC status flag on a file descriptor (either by providing this flag with the .BR open (2) -.\" FIXME The statement that O_ASYNC can be used in open() does not -.\" match reality; setting O_ASYNC via open() does not seem to be +.\" FIXME The statement that O_ASYNC can be used in open() does not +.\" match reality; setting O_ASYNC via open() does not seem to be .\" effective. .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 call, or by using the @@ -418,7 +418,7 @@ Sending a signal to the owner process (group) specified by is subject to the same permissions checks as are described for .BR kill (2), where the sending process is the one that employs -.BR F_SETOWN +.BR F_SETOWN (but see BUGS below). .sp If the file descriptor @@ -427,15 +427,16 @@ refers to a socket, .B F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band -data arrives on that socket. (SIGURG is sent in any situation where +data arrives on that socket. +(SIGURG is sent in any situation where .BR select (2) would report the socket as having an "exceptional condition".) .\" The following appears to be rubbish. It doesn't seem to -.\" be true according to the kernel source, and I can write +.\" be true according to the kernel source, and I can write .\" a program that gets a terminal-generated SIGIO even though .\" it is not the foreground process group of the terminal. .\" -- MTK, 8 Apr 05 -.\" +.\" .\" If the file descriptor .\" .I fd .\" refers to a terminal device, then SIGIO @@ -445,10 +446,10 @@ If a non-zero value is given to .B F_SETSIG in a multi-threaded process running with a threading library that supports thread groups (e.g., NPTL), -then a positive value given to +then a positive value given to .B F_SETOWN has a different meaning: -.\" The relevant place in the (2.6) kernel source is the +.\" The relevant place in the (2.6) kernel source is the .\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. @@ -473,9 +474,9 @@ to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to .BR F_SETOWN . -.\" send_sigurg()/send_sigurg_to_task() bypasses +.\" send_sigurg()/send_sigurg_to_task() bypasses .\" kill_fasync()/send_sigio()/send_sigio_to_task() -.\" to directly call send_group_sig_info() +.\" to directly call send_group_sig_info() .\" -- MTK, Apr 2005 (kernel 2.6.11) Note also that Linux imposes a limit on the number of real-time signals that may be queued to a @@ -483,20 +484,22 @@ process (see .BR getrlimit (2) and .BR signal (7)) -and if this limit is reached, then the kernel reverts to +and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread. .\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 .TP .B F_GETSIG -Get the signal sent when input or output becomes possible. A value of -zero means SIGIO is sent. Any other value (including SIGIO) is the +Get the signal sent when input or output becomes possible. +A value of zero means SIGIO is sent. +Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. .TP .B F_SETSIG -Sets the signal sent when input or output becomes possible. A value of -zero means to send the default SIGIO signal. Any other value (including +Sets the signal sent when input or output becomes possible. +A value of zero means to send the default SIGIO signal. +Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. .sp @@ -505,7 +508,7 @@ Additionally, passing a non-zero value to changes the signal recipient from a whole process to a specific thread within a process. See the description of -.B F_SETOWN +.B F_SETOWN for more details. .sp By using @@ -521,7 +524,8 @@ If the .I si_code field indicates the source is SI_SIGIO, the .I si_fd -field gives the file descriptor associated with the event. Otherwise, +field gives the file descriptor associated with the event. +Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms .RB ( select (2), @@ -532,8 +536,9 @@ with set etc.) to determine which file descriptors are available for I/O. .sp By selecting a real time signal (value >= SIGRTMIN), multiple -I/O events may be queued using the same signal numbers. (Queuing is -dependent on available memory). Extra information is available +I/O events may be queued using the same signal numbers. +(Queuing is dependent on available memory). +Extra information is available if SA_SIGINFO is set for the signal handler, as above. .PP Using these mechanisms, a program can implement fully asynchronous I/O @@ -551,7 +556,8 @@ is specific to BSD and Linux. .B F_GETSIG and .B F_SETSIG -are Linux specific. POSIX has asynchronous I/O and the +are Linux specific. +POSIX has asynchronous I/O and the .I aio_sigevent structure to achieve similar things; these are also available in Linux as part of the GNU C Library (Glibc). @@ -583,12 +589,12 @@ This will cause the calling process to be notified when the file is opened for writing or is truncated. .\" The following became true in kernel 2.6.10: .\" See the man-pages-2.09 Changelog for further info. -A read lease can only be placed on a file descriptor that +A read lease can only be placed on a file descriptor that is opened read-only. .TP .B F_WRLCK Take out a write lease. -This will cause the caller to be notified when +This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if no other process currently has the file open. @@ -657,24 +663,24 @@ and assuming the lease breaker has not unblocked its system call, the kernel permits the lease breaker's system call to proceed. If the lease breaker's blocked -.BR open () -or +.BR open () +or .BR truncate () -is interrupted by a signal handler, -then the system call fails with the error -.BR EINTR , +is interrupted by a signal handler, +then the system call fails with the error +.BR EINTR , but the other steps still occur as described above. -If the lease breaker is killed by a signal while blocked in -.BR open () -or +If the lease breaker is killed by a signal while blocked in +.BR open () +or .BR truncate (), then the other steps still occur as described above. -If the lease breaker specifies the -.B O_NONBLOCK -flag when calling +If the lease breaker specifies the +.B O_NONBLOCK +flag when calling .BR open (), -then the call immediately fails with the error -.BR EWOULDBLOCK , +then the call immediately fails with the error +.BR EWOULDBLOCK , but the other steps still occur as described above. The default signal used to notify the lease holder is SIGIO, @@ -722,7 +728,7 @@ DN_ATTRIB The attributes of a file were changed (chown, chmod, utime[s]) .TE .sp -(In order to obtain these definitions, the _GNU_SOURCE feature test macro +(In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined.) .sp Directory notifications are normally "one-shot", and the application @@ -766,10 +772,11 @@ so that multiple notifications can be queued. .B NOTE: New applications should consider using the -.I inotify +.I inotify interface (available since kernel 2.6.13), -which provides a superior interface for obtaining notifications of -file system events. See +which provides a superior interface for obtaining notifications of +file system events. +See .BR inotify (7). .SH "RETURN VALUE" For a successful call, the return value depends on the operation: @@ -830,14 +837,16 @@ the command was interrupted by a signal. For .BR F_GETLK " and " F_SETLK , the command was interrupted by a signal before the lock was checked or -acquired. Most likely when locking a remote file (e.g. locking over +acquired. +Most likely when locking a remote file (e.g. locking over NFS), but can sometimes happen locally. .TP .B EINVAL For .BR F_DUPFD , .I arg -is negative or is greater than the maximum allowable value. For +is negative or is greater than the maximum allowable value. +For .BR F_SETSIG , .I arg is not an allowable signal number. @@ -869,7 +878,8 @@ and POSIX.1-2001 allows .I l_len -to be negative. (And if it is, the interval described by the lock +to be negative. +(And if it is, the interval described by the lock covers bytes .IR l_start + l_len up to and including @@ -907,7 +917,7 @@ In Linux 2.4 and earlier, there is bug that can occur when an unprivileged process uses .B F_SETOWN to specify the owner -of a socket file descriptor +of a socket file descriptor as a process (group) other than the caller. In this case, .BR fcntl () @@ -920,9 +930,9 @@ has permission to send signals to. Despite this error return, the file descriptor owner is set, and signals will be sent to the owner. .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. Only the operations F_DUPFD, -F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, F_SETLKW, +F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, F_SETLKW, F_GETOWN, and F_SETOWN are specified in POSIX.1-2001. F_GETSIG, F_SETSIG, F_NOTIFY, F_GETLEASE, and F_SETLEASE diff --git a/man2/fdatasync.2 b/man2/fdatasync.2 index f7c8d8154..49cd2315c 100644 --- a/man2/fdatasync.2 +++ b/man2/fdatasync.2 @@ -13,7 +13,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -21,7 +21,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,8 @@ fdatasync \- synchronize a file's in-core data with that on disk .SH DESCRIPTION .BR fdatasync () flushes all data buffers of a file to disk (before the system -call returns). It resembles +call returns). +It resembles .BR fsync () but is not required to update the metadata such as access time. @@ -46,16 +47,19 @@ Applications that access databases or log files often write a tiny data fragment (e.g., one line in a log file) and then call .BR fsync () immediately in order to ensure that the written data is physically -stored on the harddisk. Unfortunately, +stored on the harddisk. +Unfortunately, .BR fsync () will always initiate two write operations: one for the newly written data and another one in order to update the modification time stored -in the inode. If the modification time is not a part of the transaction +in the inode. +If the modification time is not a part of the transaction concept .BR fdatasync () can be used to avoid unnecessary inode disk write operations. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man2/flock.2 b/man2/flock.2 index 11adb34bd..f131a129a 100644 --- a/man2/flock.2 +++ b/man2/flock.2 @@ -1,6 +1,6 @@ .\" Hey Emacs! This file is -*- nroff -*- source. .\" -.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and .\" and Copyright 2002 Michael Kerrisk .\" .\" Permission is granted to make and distribute verbatim copies of this @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -73,7 +73,7 @@ Locks created by .BR flock () are associated with an open file table entry. This means that duplicate file descriptors (created by, for example, -.BR fork (2) +.BR fork (2) or .BR dup (2)) refer to the same lock, and this lock may be modified @@ -107,7 +107,8 @@ are preserved across an A shared or exclusive lock can be placed on a file regardless of the mode in which the file was opened. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -142,7 +143,8 @@ possibly implemented in terms of appears on most Unix systems. .SH NOTES .BR flock (2) -does not lock files over NFS. Use +does not lock files over NFS. +Use .BR fcntl (2) instead: that does work over NFS, given a sufficiently recent version of Linux and a server which supports locking. @@ -186,7 +188,7 @@ Converting a lock the existing lock is first removed, and then a new lock is established. Between these two steps, a pending lock request by another process may be granted, -with the result that the conversion either blocks, or fails if +with the result that the conversion either blocks, or fails if .B LOCK_NB was specified. (This is the original BSD behaviour, diff --git a/man2/fork.2 b/man2/fork.2 index 5d6c762a4..d437798f2 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,8 +48,8 @@ fork \- create a child process .SH DESCRIPTION .BR fork () creates a new process by duplicating the calling process. -The new process, referred to as the \fIchild\fP, -is an exact duplicate of the calling process, +The new process, referred to as the \fIchild\fP, +is an exact duplicate of the calling process, referred to as the \fIparent\fP, except for the following points: .IP * 4 The child has its own unique process ID, @@ -62,7 +62,7 @@ The child does not inherit its parent's memory locks .RB ( mlock (2), .BR mlockall (2)). .IP * 4 -Process resource utilisations +Process resource utilisations .RB ( getrusage (2)) and CPU time counters .RB ( times (2)) @@ -82,30 +82,30 @@ The parent does not inherit timers from its parent .BR alarm (3), .BR timer_create (3)). .IP * 4 -The child does not inherit outstanding asynchronous I/O operations +The child does not inherit outstanding asynchronous I/O operations from its parent .RB ( aio_read (3), .BR aio_write (3)). -.PP -The process attributes in the preceding list are all specified +.PP +The process attributes in the preceding list are all specified in POSIX.1-2001. The parent and child also differ with respect to the following Linux-specific process attributes: .IP * 4 -The child does not inherit directory change notifications (dnotify) +The child does not inherit directory change notifications (dnotify) from its parent (see the description of -.B F_NOTIFY -in +.B F_NOTIFY +in .BR fcntl (2)). .IP * 4 The .BR prctl (2) .B PR_SET_PDEATHSIG -setting is reset so that the child does not receive a signal +setting is reset so that the child does not receive a signal when its parent terminates. .IP * 4 -Memory mappings that have been marked with the +Memory mappings that have been marked with the .BR madvise (2) .B MADV_DONTFORK flag are not inherited across a @@ -117,42 +117,42 @@ The termination signal of the child is always SIGCHLD .PP Note the following further points: .IP * 4 -The child process is created with a single thread \(em the -one that called +The child process is created with a single thread \(em the +one that called .BR fork (2). The entire virtual address space of the parent is replicated in the child, -including the states of mutexes, condition variables, +including the states of mutexes, condition variables, and other pthreads objects; the use of .BR pthread_atfork (3) may be helpful for dealing with problems that this can cause. .IP * 4 The child inherits copies of the parent's set of open file descriptors. -Each file descriptor in the child refers to the same +Each file descriptor in the child refers to the same open file description (see .BR open (2)) as the corresponding file descriptor in the parent. -This means that the two descriptors share open file status flags, -current file offset, +This means that the two descriptors share open file status flags, +current file offset, and signal-driven I/O attributes (see the description of .B F_SETOWN -and +and .B F_SETSIG -in +in .BR fcntl (2)). .IP * 4 -The child inherits copies of the parent's set of open message +The child inherits copies of the parent's set of open message queue descriptors (see .BR mq_overview (7)). -Each descriptor in the child refers to the same +Each descriptor in the child refers to the same open message queue description as the corresponding descriptor in the parent. This means that the two descriptors share the same flags .RI ( mq_flags ). .SH "RETURN VALUE" On success, the PID of the child process is returned in the parent's thread -of execution, and a 0 is returned in the child's thread of execution. On -failure, a \-1 will be returned in the parent's context, no child process -will be created, and +of execution, and a 0 is returned in the child's thread of execution. +On failure, a \-1 will be returned in the parent's context, +no child process will be created, and .I errno will be set appropriately. .SH ERRORS diff --git a/man2/fstatat.2 b/man2/fstatat.2 index 9c4a94aae..d02796e65 100644 --- a/man2/fstatat.2 +++ b/man2/fstatat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,7 +32,7 @@ fstatat \- get file status relative to a directory file descriptor .B #include .sp .BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \ -buf , +buf , .BI " int " flags ); .fi .SH DESCRIPTION @@ -42,51 +42,51 @@ system call operates in exactly the same way as .BR stat (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR stat (2) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR stat (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .I flags can either be 0, or include the following flag: .TP .B AT_SYMLINK_NOFOLLOW -If +If .I pathname -is a symbolic link, do not dereference it: +is a symbolic link, do not dereference it: instead return information about the link itself, like -.BR lstat (2). +.BR lstat (2). (By default, .BR fstatat () dereferences symbolic links, like .BR stat (2).) .SH "RETURN VALUE" On success, -.BR fstatat () -returns 0. +.BR fstatat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -95,7 +95,7 @@ The same errors that occur for .BR stat (2) can also occur for .BR fstatat (). -The following additional errors can occur for +The following additional errors can occur for .BR fstatat (): .TP .B EBADF diff --git a/man2/fsync.2 b/man2/fsync.2 index 4f8cc3ca7..834e0bb4a 100644 --- a/man2/fsync.2 +++ b/man2/fsync.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,15 +45,15 @@ fsync, fdatasync \- synchronize a file's in-core state with storage device .BI "int fdatasync(int " fd ); .SH DESCRIPTION .BR fsync () -transfers ("flushes") all modified in-core data of -(i.e., modified buffer cache pages for) the +transfers ("flushes") all modified in-core data of +(i.e., modified buffer cache pages for) the file referred to by the file descriptor .I fd -to the disk device (or other permanent storage device) +to the disk device (or other permanent storage device) where that file resides. The call blocks until the device reports that the transfer has completed. It also flushes metadata information associated with the file (see -.BR stat (2)). +.BR stat (2)). Calling .BR fsync () @@ -64,18 +64,18 @@ For that an explicit on a file descriptor for the directory is also needed. .BR fdatasync () -is similar to +is similar to .BR fsync (), -but does not flush modified metadata unless that metadata +but does not flush modified metadata unless that metadata is needed in order to allow a subsequent data retrieval to be correctly handled. -For example, changes to -.I st_atime -or +For example, changes to +.I st_atime +or .I st_mtime (respectively, time of last access and time of last modification; see -.BR stat (2)) +.BR stat (2)) do not require flushing because they are not necessary for a subsequent data read to be handled correctly. On the other hand, a change to the file size @@ -89,7 +89,8 @@ The aim of is to reduce disk activity for applications that do not require all metadata to be synchronised with the disk. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -107,8 +108,8 @@ is bound to a special file which does not support synchronization. .SH NOTES If the underlying hard disk has write caching enabled, then the data may not really be on permanent storage when -.BR fsync () -/ +.BR fsync () +/ .BR fdatasync () return. .\" See diff --git a/man2/futex.2 b/man2/futex.2 index f75e28db7..e3a90df87 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -7,8 +7,8 @@ .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE .\" .\" FIXME -.\" 2.6.18 adds (Ingo Molnar) priority inheritance support: -.\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need +.\" 2.6.18 adds (Ingo Molnar) priority inheritance support: +.\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI. These need .\" to be documented in the manual page. Probably there is sufficient .\" material in the kernel source file Documentation/pi-futex.txt. .\" @@ -38,15 +38,17 @@ addresses for the same memory in separate processes may not be equal, the kernel maps them internally so the same memory mapped in different locations will correspond for .BR futex () -calls). It is typically used to +calls). +It is typically used to implement the contended case of a lock in shared memory, as described in .BR futex (7). .PP -When a +When a .BR futex (7) operation did not finish uncontended in userspace, a call needs to be made -to the kernel to arbitrate. Arbitration can either mean putting the calling +to the kernel to arbitrate. +Arbitration can either mean putting the calling process to sleep or, conversely, waking a waiting process. .PP Callers of this function are expected to adhere to the semantics as set out in @@ -71,10 +73,12 @@ This operation atomically verifies that the futex address .I uaddr still contains the value .IR val , -and sleeps awaiting FUTEX_WAKE on this futex address. If the +and sleeps awaiting FUTEX_WAKE on this futex address. +If the .I timeout argument is non-NULL, its contents describe the maximum -duration of the wait, which is infinite otherwise. The arguments +duration of the wait, which is infinite otherwise. +The arguments .I uaddr2 and .I val3 @@ -84,7 +88,7 @@ For .BR futex (7), this call is executed if decrementing the count gave a negative value (indicating contention), and will sleep until another process releases -the futex and executes the FUTEX_WAKE operation. +the futex and executes the FUTEX_WAKE operation. .TP .B FUTEX_WAKE This operation wakes at most \fIval\fR @@ -117,7 +121,7 @@ and .I val3 are ignored. -To prevent race conditions, the caller should test if the futex has +To prevent race conditions, the caller should test if the futex has been upped after FUTEX_FD returns. .\" FIXME . Check that this flag does eventually get removed. @@ -127,7 +131,8 @@ in June 2007; any applications that use it should be fixed now. .BR FUTEX_REQUEUE " (since Linux 2.5.70)" This operation was introduced in order to avoid a "thundering herd" effect when FUTEX_WAKE is used and all processes woken up need to acquire another -futex. This call wakes up +futex. +This call wakes up .I val processes, and requeues all other waiters on the futex at address .IR uaddr2 . @@ -139,7 +144,8 @@ are ignored. .TP .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" There was a race in the intended use of FUTEX_REQUEUE, so -FUTEX_CMP_REQUEUE was introduced. This is similar to FUTEX_REQUEUE, +FUTEX_CMP_REQUEUE was introduced. +This is similar to FUTEX_REQUEUE, but first checks whether the location .I uaddr still contains the value @@ -154,9 +160,12 @@ Depending on which operation was executed, the returned value can have differing meanings. .TP .B FUTEX_WAIT -Returns 0 if the process was woken by a FUTEX_WAKE call. In case of timeout, -ETIMEDOUT is returned. If the futex was not equal to the expected value, -the operation returns EWOULDBLOCK. Signals (or other spurious wakeups) +Returns 0 if the process was woken by a FUTEX_WAKE call. +In case of timeout, +ETIMEDOUT is returned. +If the futex was not equal to the expected value, +the operation returns EWOULDBLOCK. +Signals (or other spurious wakeups) cause FUTEX_WAIT to return EINTR. .TP .B FUTEX_WAKE @@ -193,7 +202,8 @@ The system limit on the total number of open files has been reached. .SH "NOTES" .PP To reiterate, bare futexes are not intended as an easy to use abstraction -for end-users. Implementors are expected to be assembly literate and to have +for end-users. +Implementors are expected to be assembly literate and to have read the sources of the futex userspace library referenced below. .\" .SH "AUTHORS" .\" .PP @@ -205,16 +215,19 @@ read the sources of the futex userspace library referenced below. .SH "VERSIONS" .PP Initial futex support was merged in Linux 2.5.7 but with different semantics -from what was described above. A 4-parameter system call with the semantics -given here was introduced in Linux 2.5.40. In Linux 2.5.70 one parameter -was added. In Linux 2.6.7 a sixth parameter was added \(em messy, especially +from what was described above. +A 4-parameter system call with the semantics +given here was introduced in Linux 2.5.40. +In Linux 2.5.70 one parameter +was added. +In Linux 2.6.7 a sixth parameter was added \(em messy, especially on the s390 architecture. .SH "CONFORMING TO" This system call is Linux specific. .SH "SEE ALSO" .PP -.BR futex (7), +.BR futex (7), `Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' -(proceedings of the Ottawa Linux Symposium 2002), +(proceedings of the Ottawa Linux Symposium 2002), futex example library, futex-*.tar.bz2 . diff --git a/man2/futimesat.2 b/man2/futimesat.2 index c4adf905b..6b66bd56f 100644 --- a/man2/futimesat.2 +++ b/man2/futimesat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,7 +32,7 @@ directory file descriptor .B #define _ATFILE_SOURCE .B #include .sp -.BI "int futimesat(int " dirfd ", const char *" pathname , +.BI "int futimesat(int " dirfd ", const char *" pathname , .BI " const struct timeval " times [2]); .fi .SH DESCRIPTION @@ -42,36 +42,36 @@ system call operates in exactly the same way as .BR utimes (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR utimes (2) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR utimes (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .SH "RETURN VALUE" On success, -.BR futimesat () +.BR futimesat () returns a 0. On error, \-1 is returned and .I errno @@ -81,7 +81,7 @@ The same errors that occur for .BR utimes (2) can also occur for .BR futimesat (). -The following additional errors can occur for +The following additional errors can occur for .BR futimesat (): .TP .B EBADF @@ -100,7 +100,7 @@ A similar system call exists on Solaris. .SH GLIBC NOTES If .I pathname -is NULL, then the glibc +is NULL, then the glibc .BR futimes () wrapper function updates the times for the file referred to by .IR dirfd . diff --git a/man2/get_kernel_syms.2 b/man2/get_kernel_syms.2 index 37c1bc1d3..07f5e75cb 100644 --- a/man2/get_kernel_syms.2 +++ b/man2/get_kernel_syms.2 @@ -2,7 +2,7 @@ .\" This file is distributed according to the GNU General Public License. .\" See the file COPYING in the top level source directory for details. .\" -.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" .TH GET_KERNEL_SYMS 2 "2002" Linux "Linux Module Support" @@ -38,11 +38,11 @@ The value associated with a symbol of this form is the address at which the module is loaded. .PP The symbols exported from each module follow their magic module tag -and the modules are returned in the reverse of the +and the modules are returned in the reverse of the order in which they were loaded. .SH "RETURN VALUE" Returns the number of symbols copied to -.IR table . +.IR table . There is no possible error return. .SH "CONFORMING TO" .BR get_kernel_syms () @@ -61,7 +61,7 @@ favor of (which is itself nowadays deprecated in favor of other interfaces described on its manual page). .SH NOTES -This system call is only present on Linux up until kernel 2.4; +This system call is only present on Linux up until kernel 2.4; it was removed in Linux 2.6. .\" Removed in Linux-2.5.48 .SH "SEE ALSO" diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2 index 539b50922..f41f0ea8e 100644 --- a/man2/get_mempolicy.2 +++ b/man2/get_mempolicy.2 @@ -8,26 +8,26 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. -.\" +.\" .\" 2006-02-03, mtk, substantial wording changes and other improvements .\" .TH GET_MEMPOLICY 2 "2006-02-07" "SuSE Labs" "Linux Programmer's Manual" .SH SYNOPSIS get_mempolicy \- Retrieve NUMA memory policy for a process .SH NAME -.B "#include " +.B "#include " .nf .sp -.BI "int get_mempolicy(int *" policy ", unsigned long *" nodemask , -.BI " unsigned long " maxnode ", unsigned long " addr , +.BI "int get_mempolicy(int *" policy ", unsigned long *" nodemask , +.BI " unsigned long " maxnode ", unsigned long " addr , .BI " unsigned long " flags ); .fi .\" TBD rewrite this. it is confusing. @@ -39,18 +39,18 @@ depending on the setting of A NUMA machine has different memory controllers with different distances to specific CPUs. -The memory policy defines in which node memory is allocated for -the process. +The memory policy defines in which node memory is allocated for +the process. If .IR flags is specified as 0, -then information about the calling process's default policy +then information about the calling process's default policy (as set by .BR set_mempolicy (2)) is returned. -If +If .I flags specifies .BR MPOL_F_ADDR , @@ -62,52 +62,52 @@ This policy may be different from the process's default policy if has been used to establish a policy for the page containing .IR addr . -If +If .I policy is not NULL, then it is used to return the policy. -If -.IR nodemask -is not NULL, then it is used to return the nodemask associated +If +.IR nodemask +is not NULL, then it is used to return the nodemask associated with the policy. -.I maxnode -is the maximum bit number plus one that can be stored into +.I maxnode +is the maximum bit number plus one that can be stored into .IR nodemask . -The bit number is always rounded to a multiple of +The bit number is always rounded to a multiple of .IR "unsigned long" . -.\" +.\" .\" If -.\" .I flags +.\" .I flags .\" specifies both .\" .B MPOL_F_NODE -.\" and +.\" and .\" .BR MPOL_F_ADDR , -.\" then +.\" then .\" .I policy .\" instead returns the number of the node on which the address .\" .I addr .\" is allocated. -.\" +.\" .\" If -.\" .I flags +.\" .I flags .\" specifies .\" .B MPOL_F_NODE .\" but not .\" .BR MPOL_F_ADDR , .\" and the process's current policy is .\" .BR MPOL_INTERLEAVE , -.\" then +.\" then .\" checkme: Andi's text below says that the info is returned in .\" 'nodemask', not 'policy': .\" .I policy -.\" instead returns the number of the next node that will be used for +.\" instead returns the number of the next node that will be used for .\" interleaving allocation. .\" FIXME . -.\" The other valid flag is +.\" The other valid flag is .\" .I MPOL_F_NODE. -.\" It is only valid when the policy is +.\" It is only valid when the policy is .\" .I MPOL_INTERLEAVE. .\" In this case not the interleave mask, but an unsigned long with the next -.\" node that would be used for interleaving is returned in +.\" node that would be used for interleaving is returned in .\" .I nodemask. .\" Other flag values are reserved. @@ -118,15 +118,15 @@ On success, .BR get_mempolicy () returns 0; on error, \-1 is returned and -.I errno +.I errno is set to indicate the error. .\" .SH ERRORS .\" FIXME writeme -- no errors are listed on this page .\" . .\" .TP .\" .B EINVAL -.\" .I nodemask -.\" is non-NULL, and +.\" .I nodemask +.\" is non-NULL, and .\" .I maxnode .\" is too small; .\" or @@ -144,15 +144,15 @@ is set to indicate the error. .\" is NULL. .\" (And there are other EINVAL cases.) .SH NOTES -This manual page is incomplete: +This manual page is incomplete: it does not document the details the -.BR MPOL_F_NODE -flag, -which modifies the operation of +.BR MPOL_F_NODE +flag, +which modifies the operation of .BR get_mempolicy (). -This is deliberate: this flag is not intended for application use, -and its operation may change or it may be removed altogether in -future kernel versions. +This is deliberate: this flag is not intended for application use, +and its operation may change or it may be removed altogether in +future kernel versions. .B Do not use it. .SH "VERSIONS AND LIBRARY SUPPORT" See diff --git a/man2/get_thread_area.2 b/man2/get_thread_area.2 index d1c462e42..f2bfdbdd2 100644 --- a/man2/get_thread_area.2 +++ b/man2/get_thread_area.2 @@ -14,14 +14,14 @@ get_thread_area \- Get a Thread Local Storage (TLS) area .BI "int get_thread_area(struct user_desc *" u_info ); .SH "DESCRIPTION" .BR get_thread_area () -returns an entry in the current thread's Thread Local Storage (TLS) array. -The index of the entry corresponds to the value -of \fIu_info->\fR\fIentry_number\fR, passed in by the user. -If the value is in bounds, \fBget_thread_info\fR copies the corresponding +returns an entry in the current thread's Thread Local Storage (TLS) array. +The index of the entry corresponds to the value +of \fIu_info->\fR\fIentry_number\fR, passed in by the user. +If the value is in bounds, \fBget_thread_info\fR copies the corresponding TLS entry into the area pointed to by \fIu_info\fR. .SH "RETURN VALUE" .BR get_thread_area () -returns 0 on success. +returns 0 on success. Otherwise, it returns \-1 and sets .I errno appropriately. diff --git a/man2/getcontext.2 b/man2/getcontext.2 index c3ececa47..3630365d8 100644 --- a/man2/getcontext.2 +++ b/man2/getcontext.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -72,7 +72,8 @@ The function \fBgetcontext\fP() initializes the structure pointed at by \fIucp\fP to the currently active context. .LP The function \fBsetcontext\fP() restores the user context -pointed at by \fIucp\fP. A successful call does not return. +pointed at by \fIucp\fP. +A successful call does not return. The context should have been obtained by a call of \fBgetcontext\fP(), or \fBmakecontext\fP(), or passed as third argument to a signal handler. @@ -91,20 +92,24 @@ When this member is NULL, the thread exits. If the context was obtained by a call to a signal handler, then old standard text says that "program execution continues with the program instruction following the instruction interrupted -by the signal". However, this sentence was removed in SUSv2, +by the signal". +However, this sentence was removed in SUSv2, and the present verdict is "the result is unspecified". .SH "RETURN VALUE" When successful, \fBgetcontext\fP() returns 0 and \fBsetcontext\fP() -does not return. On error, both return \-1 and set \fIerrno\fP +does not return. +On error, both return \-1 and set \fIerrno\fP appropriately. .SH ERRORS None defined. .SH NOTES The earliest incarnation of this mechanism was the -\fIsetjmp\fP()/\fIlongjmp\fP() mechanism. Since that does not define +\fIsetjmp\fP()/\fIlongjmp\fP() mechanism. +Since that does not define the handling of the signal context, the next stage was the \fIsigsetjmp\fP()/\fIsiglongjmp\fP() pair. -The present mechanism gives much more control. On the other hand, +The present mechanism gives much more control. +On the other hand, there is no easy way to detect whether a return from \fBgetcontext\fP() is from the first call, or via a \fBsetcontext\fP() call. The user has to invent her own bookkeeping device, and a register @@ -113,7 +118,8 @@ variable won't do since registers are restored. When a signal occurs, the current user context is saved and a new context is created by the kernel for the signal handler. Do not leave the handler using \fIlongjmp\fP(): it is undefined -what would happen with contexts. Use \fIsiglongjmp\fP() or +what would happen with contexts. +Use \fIsiglongjmp\fP() or \fIsetcontext\fP() instead. .SH "CONFORMING TO" SUSv2, POSIX.1-2001. diff --git a/man2/getdents.2 b/man2/getdents.2 index 247dd235a..30af079be 100644 --- a/man2/getdents.2 +++ b/man2/getdents.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,14 +49,14 @@ This page documents the bare kernel system call interface. .PP The system call .BR getdents () -reads several +reads several .I dirent structures from the directory pointed at by .I fd into the memory area pointed to by .IR dirp . -The parameter +The parameter .I count is the size of the memory area. .PP diff --git a/man2/getdomainname.2 b/man2/getdomainname.2 index 3f3b0d177..ac801421c 100644 --- a/man2/getdomainname.2 +++ b/man2/getdomainname.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,7 +41,8 @@ If the null-terminated domain name requires more than \fIlen\fP bytes, .BR getdomainname () returns the first \fIlen\fP bytes (glibc) or returns an error (libc). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man2/getdtablesize.2 b/man2/getdtablesize.2 index ddf11007a..0a2755d98 100644 --- a/man2/getdtablesize.2 +++ b/man2/getdtablesize.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,7 +39,8 @@ one more than the largest possible value for a file descriptor. The current limit on the number of open files per process. .SH NOTES .BR getdtablesize () -is implemented as a libc library function. The glibc version calls +is implemented as a libc library function. +The glibc version calls .BR getrlimit (2) and returns the current .B RLIMIT_NOFILE @@ -54,7 +55,7 @@ SVr4, 4.4BSD (the .BR getdtablesize () function first appeared in 4.2BSD). It is not specified in POSIX.1-2001; -portable applications should employ +portable applications should employ .I sysconf(_SC_OPEN_MAX) instead of this call. .SH "SEE ALSO" diff --git a/man2/getgid.2 b/man2/getgid.2 index 5fbc40657..8dec945e2 100644 --- a/man2/getgid.2 +++ b/man2/getgid.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man2/getgroups.2 b/man2/getgroups.2 index cdb5644fb..d4a0014f8 100644 --- a/man2/getgroups.2 +++ b/man2/getgroups.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -47,7 +47,8 @@ Up to supplementary group IDs (of the calling process) are returned in .IR list . It is unspecified whether the effective group ID of the calling process -is included in the returned list. (Thus, an application should also call +is included in the returned list. +(Thus, an application should also call .BR getegid (2) and add or remove the resulting value.) If @@ -71,7 +72,8 @@ On error, \-1 is returned, and is set appropriately. .TP .BR setgroups () -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -93,7 +95,7 @@ For is less than the number of supplementary group IDs, but is not zero. .TP .B EPERM -The calling process has insufficient privilege to call +The calling process has insufficient privilege to call .BR setgroups (). .SH NOTES A process can have up to at least NGROUPS_MAX supplementary group IDs diff --git a/man2/gethostid.2 b/man2/gethostid.2 index c251efdfc..89c68d6b3 100644 --- a/man2/gethostid.2 +++ b/man2/gethostid.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,9 +36,10 @@ gethostid, sethostid \- get or set the unique identifier of the current host .br .BI "int sethostid(long " hostid ); .SH DESCRIPTION -Get or set a unique 32-bit identifier for the current machine. The 32-bit -identifier is intended to be unique among all UNIX systems in -existence. This normally resembles the Internet address for the local +Get or set a unique 32-bit identifier for the current machine. +The 32-bit identifier is intended to be unique among all UNIX systems in +existence. +This normally resembles the Internet address for the local machine, as returned by .BR gethostbyname (3), and thus usually never needs to be set. @@ -57,11 +58,11 @@ returns the 32-bit identifier for the current host as set by .BR sethostid (2). .SH "CONFORMING TO" 4.2BSD; these functions were dropped in 4.4BSD. -SVr4 includes +SVr4 includes .BR gethostid () but not .BR sethostid (). -POSIX.1-2001 specifies +POSIX.1-2001 specifies .BR gethostid () but not .BR sethostid (). diff --git a/man2/gethostname.2 b/man2/gethostname.2 index 655a22221..bd83c7f1d 100644 --- a/man2/gethostname.2 +++ b/man2/gethostname.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,10 +46,12 @@ system call returns a null-terminated hostname (set earlier by .BR sethostname ()) in the array \fIname\fP that has a length of \fIlen\fP bytes. In case the null-terminated hostname does not fit, no error is -returned, but the hostname is truncated. It is unspecified +returned, but the hostname is truncated. +It is unspecified whether the truncated hostname will be null-terminated. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -88,34 +90,34 @@ SUSv2 guarantees that `Host names are limited to 255 bytes'. POSIX.1-2001 guarantees that `Host names (not including the terminating null byte) are limited to HOST_NAME_MAX bytes'. .SH "GLIBC NOTES" -The GNU C library implements -.BR gethostname () -as a library function that calls +The GNU C library implements +.BR gethostname () +as a library function that calls .BR uname (2) -and copies up to +and copies up to .I len -bytes from the returned -.I nodename +bytes from the returned +.I nodename field into .IR name . Having performed the copy, the function then checks if the length of the .I nodename was greater than or equal to .IR len , -and if it is, then the function returns \-1 with -.I errno +and if it is, then the function returns \-1 with +.I errno set to .BR ENAMETOOLONG . -Versions of glibc before 2.2 +Versions of glibc before 2.2 .\" At least glibc 2.0 and 2.1, older versions not checked handle the case where the length of the .I nodename was greater than or equal to .IR len -differently: nothing is copied into +differently: nothing is copied into .I name and the function returns \-1 with -.I errno +.I errno set to .BR ENAMETOOLONG . .SH "SEE ALSO" diff --git a/man2/getitimer.2 b/man2/getitimer.2 index eeafb295e..4deac497d 100644 --- a/man2/getitimer.2 +++ b/man2/getitimer.2 @@ -17,8 +17,9 @@ getitimer, setitimer \- get or set value of an interval timer .BI " struct itimerval *" ovalue ); .fi .SH DESCRIPTION -The system provides each process with three interval timers, each decrementing -in a distinct time domain. When any timer expires, a signal is sent to the +The system provides each process with three interval timers, +each decrementing in a distinct time domain. +When any timer expires, a signal is sent to the process, and the timer (potentially) restarts. .TP 1.5i .B ITIMER_REAL @@ -33,10 +34,11 @@ upon expiration. .TP .B ITIMER_PROF decrements both when the process executes and when the system is executing -on behalf of the process. Coupled with +on behalf of the process. +Coupled with .BR ITIMER_VIRTUAL , -this timer is usually used to profile the time spent by the application in user -and kernel space. +this timer is usually used to profile the time spent by the +application in user and kernel space. .B SIGPROF is delivered upon expiration. .LP @@ -71,7 +73,8 @@ or The element .I it_value is set to the amount of time remaining on the timer, or zero if the timer -is disabled. Similarly, +is disabled. +Similarly, .I it_interval is set to the reset value. The function @@ -105,10 +108,12 @@ on the system timer resolution and on the system load. Upon expiration, a signal will be generated and the timer reset. If the timer expires while the process is active (always true for .BR ITIMER_VIRTUAL ) -the signal will be delivered immediately when generated. Otherwise the +the signal will be delivered immediately when generated. +Otherwise the delivery will be offset by a small time dependent on the system loading. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -130,7 +135,7 @@ or A child created via .BR fork (2) does not inherit its parent's interval timers. -Interval timers are preserved across an +Interval timers are preserved across an .BR execve (2). .SH "CONFORMING TO" POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). @@ -150,7 +155,7 @@ has been delivered. The second signal in such an event will be lost. On Linux, timer values are represented in jiffies. -If a request is made set a timer with a value whose jiffies +If a request is made set a timer with a value whose jiffies representation exceeds MAX_SEC_IN_JIFFIES (defined in .IR include/linux/jiffies.h ), @@ -161,7 +166,7 @@ this means that the ceiling value for a timer is approximately 99.42 days. On certain systems (including x86), -Linux kernels before version 2.6.12 have a bug which will produce +Linux kernels before version 2.6.12 have a bug which will produce premature timer expirations of up to one jiffy under some circumstances. This bug is fixed in kernel 2.6.12. .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x. @@ -174,7 +179,7 @@ should fail if a value is specified that is outside of the range 0 to 999999. However, Linux does not give an error, but instead silently adjusts the corresponding seconds value for the timer. -In the future (scheduled for March 2007), +In the future (scheduled for March 2007), this non-conformance will be repaired: existing applications should be fixed now to ensure that they supply a properly formed diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 index cef0a858d..ef9c37046 100644 --- a/man2/getpagesize.2 +++ b/man2/getpagesize.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -64,7 +64,7 @@ In SUSv2 the call is labeled LEGACY, and in POSIX.1-2001 it has been dropped; HP-UX does not have this call. -Portable applications should employ +Portable applications should employ .I sysconf(_SC_PAGESIZE) instead of this call. .SH NOTES @@ -75,7 +75,8 @@ If it is, it returns the kernel symbol PAGE_SIZE, which is architecture and machine model dependent. Generally, one uses binaries that are architecture but not machine model dependent, in order to have a single binary -distribution per architecture. This means that a user program +distribution per architecture. +This means that a user program should not find PAGE_SIZE at compile time from a header file, but use an actual system call, at least for those architectures (like sun4) where this dependency exists. diff --git a/man2/getpeername.2 b/man2/getpeername.2 index bb053c714..0ec677dab 100644 --- a/man2/getpeername.2 +++ b/man2/getpeername.2 @@ -53,10 +53,11 @@ The parameter should be initialized to indicate the amount of space pointed to by .IR name . -On return it contains the actual size of the name returned (in bytes). The -name is truncated if the buffer provided is too small. +On return it contains the actual size of the name returned (in bytes). +The name is truncated if the buffer provided is too small. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -67,7 +68,7 @@ The argument is not a valid descriptor. .TP .B EFAULT -The +The .I name parameter points to memory not in a valid part of the process address space. @@ -92,13 +93,13 @@ SVr4, 4.4BSD (the .BR getpeername () function call first appeared in 4.2BSD), POSIX.1-2001. .SH NOTE -The third argument of +The third argument of .BR getpeername () -is in reality an +is in reality an .I int * (and this is what 4.x BSD and libc4 and libc5 have). -Some POSIX confusion resulted in the present -.IR socklen_t , +Some POSIX confusion resulted in the present +.IR socklen_t , also used by glibc. See also .BR accept (2). diff --git a/man2/getpid.2 b/man2/getpid.2 index 07611fe30..ace18c67e 100644 --- a/man2/getpid.2 +++ b/man2/getpid.2 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .TH GETPID 2 1993-07-23 "Linux 0.99.11" "Linux Programmer's Manual" @@ -33,7 +33,8 @@ getpid, getppid \- get process identification .B pid_t getppid(void); .SH DESCRIPTION .BR getpid () -returns the process ID of the current process. (This is often used by +returns the process ID of the current process. +(This is often used by routines that generate unique temporary filenames.) .BR getppid () diff --git a/man2/getpriority.2 b/man2/getpriority.2 index d7fe13da8..7d5664a06 100644 --- a/man2/getpriority.2 +++ b/man2/getpriority.2 @@ -70,9 +70,9 @@ is one of .BR PRIO_PGRP , or .BR PRIO_USER , -and +and .I who -is interpreted relative to +is interpreted relative to .I which (a process identifier for .BR PRIO_PROCESS , @@ -93,10 +93,12 @@ lower priorities cause more favorable scheduling. The .BR getpriority () call returns the highest priority (lowest numerical value) -enjoyed by any of the specified processes. The +enjoyed by any of the specified processes. +The .BR setpriority () call sets the priorities of all of the specified processes -to the specified value. Only the superuser may lower priorities. +to the specified value. +Only the superuser may lower priorities. .SH "RETURN VALUE" Since .BR getpriority () @@ -121,7 +123,7 @@ or .BR PRIO_USER . .TP .B ESRCH -No process was located using the +No process was located using the .I which and .I who @@ -134,7 +136,7 @@ may fail if: .B EPERM A process was located, but its effective user ID did not match either the effective or the real user ID of the caller, -and was not privileged (on Linux: did not have the +and was not privileged (on Linux: did not have the .B CAP_SYS_NICE capability). But see NOTES below. @@ -145,7 +147,7 @@ have the required privilege (on Linux: did not have the .B CAP_SYS_NICE capability). Since Linux 2.6.12, this error only occurs if the caller attempts -to set a process priority outside the range of the +to set a process priority outside the range of the .B RLIMIT_NICE soft resource limit of the target process; see .BR getrlimit (2) @@ -154,20 +156,20 @@ for details. A child created by .BR fork (2) inherits its parent's nice value. -The nice value is preserved across -.BR execve (2). +The nice value is preserved across +.BR execve (2). The details on the condition for EPERM depend on the system. The above description is what POSIX.1-2001 says, and seems to be followed on all System V-like systems. -Linux kernels before 2.6.12 required the real or +Linux kernels before 2.6.12 required the real or effective user ID of the caller to match the real user of the process \fIwho\fP (instead of its effective user ID). Linux 2.6.12 and later require the effective user ID of the caller to match the real or effective user ID of the process \fIwho\fP. All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, -4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same +4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same manner as Linux >= 2.6.12. .LP The actual priority range varies between kernel versions. diff --git a/man2/getresuid.2 b/man2/getresuid.2 index 02164e1d0..f627f965a 100644 --- a/man2/getresuid.2 +++ b/man2/getresuid.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,7 +33,7 @@ getresuid, getresgid \- get real, effective and saved user or group ID .sp .BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid ); .br -.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); +.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); .SH DESCRIPTION .BR getresuid () and @@ -42,7 +42,8 @@ and get the real UID, effective UID, and saved set-user-ID (resp. group ID's) of the current process. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -51,7 +52,7 @@ is set appropriately. One of the arguments specified an address outside the calling program's address space. .SH "CONFORMING TO" -These calls are non-standard; +These calls are non-standard; they also appear on HP-UX and some of the BSDs. The prototype is given by glibc since version 2.3.2 diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index 723bf58ba..74c9d9326 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,7 +43,7 @@ .\" Modified 2004-06-16 by Michael Kerrisk .\" Added notes on CAP_SYS_RESOURCE .\" -.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formally included +.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formally included .\" coverage of getrusage(2), has been split, so that the latter .\" is now covered in its own getrusage.2. .\" @@ -75,13 +75,13 @@ getrlimit, setrlimit \- get/set resource limits and .BR setrlimit () get and set resource limits respectively. -Each resource has an associated soft and hard limit, as defined by the +Each resource has an associated soft and hard limit, as defined by the .I rlimit structure (the .I rlim argument to both .BR getrlimit () -and +and .BR setrlimit ()): .PP .in +0.5i @@ -96,7 +96,7 @@ struct rlimit { The soft limit is the value that the kernel enforces for the corresponding resource. The hard limit acts as a ceiling for the soft limit: -an unprivileged process may only set its soft limit to a value in the +an unprivileged process may only set its soft limit to a value in the range from 0 up to the hard limit, and (irreversibly) lower its hard limit. A privileged process (under Linux: one with the .B CAP_SYS_RESOURCE @@ -161,8 +161,8 @@ perform an orderly termination upon first receipt of The maximum size of the process's data segment (initialized data, uninitialized data, and heap). This limit affects calls to -.BR brk () -and +.BR brk () +and .BR sbrk (), which fail with the error .B ENOMEM @@ -173,8 +173,8 @@ The maximum size of files that the process may create. Attempts to extend a file beyond this limit result in delivery of a .B SIGXFSZ signal. -By default, this signal terminates a process, but a process can -catch this signal instead, in which case the relevant system call (e.g., +By default, this signal terminates a process, but a process can +catch this signal instead, in which case the relevant system call (e.g., .BR write () .BR truncate ()) fails with the error @@ -184,7 +184,7 @@ fails with the error .\" to be precise: Linux 2.4.0-test9; no longer in 2.4.25 / 2.5.65 A limit on the combined number of .BR flock () -locks and +locks and .BR fcntl () leases that this process may establish. .TP @@ -193,9 +193,9 @@ The maximum number of bytes of memory that may be locked into RAM. In effect this limit is rounded down to the nearest multiple of the system page size. -This limit affects +This limit affects .BR mlock (2) -and +and .BR mlockall (2) and the .BR mmap (2) @@ -204,16 +204,16 @@ operation. Since Linux 2.6.9 it also affects the .BR shmctl (2) .B SHM_LOCK -operation, where it sets a maximum on the total bytes in +operation, where it sets a maximum on the total bytes in shared memory segments (see .BR shmget (2)) that may be locked by the real user ID of the calling process. -The +The .BR shmctl (2) .B SHM_LOCK locks are accounted for separately from the per-process memory -locks established by -.BR mlock (2), +locks established by +.BR mlock (2), .BR mlockall (2), and .BR mmap (2) @@ -238,10 +238,10 @@ against this limit according to the formula: bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) + attr.mq_maxmsg * attr.mq_msgsize -.fi -where +.fi +where .I attr -is the +is the .I mq_attr structure specified as the fourth argument to .BR mq_open (). @@ -268,16 +268,16 @@ Specifies a value one greater than the maximum file descriptor number that can be opened by this process. Attempts .RB ( open (), -.BR pipe (), -.BR dup (), +.BR pipe (), +.BR dup (), etc.) to exceed this limit yield the error .BR EMFILE . .TP .B RLIMIT_NPROC -The maximum number of processes (or, more precisely on Linux, threads) +The maximum number of processes (or, more precisely on Linux, threads) that can be created for the real user ID of the calling process. -Upon encountering this limit, +Upon encountering this limit, .BR fork () fails with the error .BR EAGAIN . @@ -291,11 +291,11 @@ affects calls to specifying .BR MADV_WILLNEED . .\" As at kernel 2.6.12, this limit still does nothing in 2.6 though -.\" talk of making it do something has surfaced from time to time in LKML +.\" talk of making it do something has surfaced from time to time in LKML .\" -- MTK, Jul 05 .TP .BR RLIMIT_RTPRIO " (Since Linux 2.6.12, but see BUGS)" -Specifies a ceiling on the real-time priority that may be set for +Specifies a ceiling on the real-time priority that may be set for this process using .BR sched_setscheduler (2) and @@ -306,7 +306,7 @@ Specifies the limit on the number of signals that may be queued for the real user ID of the calling process. Both standard and real-time signals are counted for the purpose of checking this limit. -However, the limit is only enforced for +However, the limit is only enforced for .BR sigqueue (2); it is always possible to use .BR kill (2) @@ -324,10 +324,11 @@ To handle this signal, a process must employ an alternate signal stack .RB ( sigaltstack (2)). .PP .B RLIMIT_OFILE -is the BSD name for +is the BSD name for .BR RLIMIT_NOFILE . .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -341,7 +342,7 @@ points outside the accessible address space. is not valid; or, for .BR setrlimit (): -.IR rlim->rlim_cur +.IR rlim->rlim_cur was greater than .IR rlim->rlim_max . .TP @@ -363,11 +364,11 @@ signals delivered when a process encountered the soft and hard limits were delivered one (CPU) second later than they should have been. This was fixed in kernel 2.6.8. -In 2.6.x kernels before 2.6.17, a -.B RLIMIT_CPU -limit of 0 is wrongly treated as "no limit" (like +In 2.6.x kernels before 2.6.17, a +.B RLIMIT_CPU +limit of 0 is wrongly treated as "no limit" (like .BR RLIM_INFINITY ). -Since kernel 2.6.17, setting a limit of 0 does have an effect, +Since kernel 2.6.17, setting a limit of 0 does have an effect, but is actually treated as a limit of 1 second. .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2 @@ -375,12 +376,12 @@ A kernel bug means that .B RLIMIT_RTPRIO does not work in kernel 2.6.12; the problem is fixed in kernel 2.6.13. -In kernel 2.6.12, there was an off-by-one mismatch +In kernel 2.6.12, there was an off-by-one mismatch between the priority ranges returned by .BR getpriority (2) and .BR RLIMIT_NICE . -This had the effect that actual ceiling for the nice value +This had the effect that actual ceiling for the nice value was calculated as .IR "19\ \-\ rlim_cur" . This was fixed in kernel 2.6.13. @@ -388,10 +389,10 @@ This was fixed in kernel 2.6.13. Kernels before 2.4.22 did not diagnose the error .B EINVAL -for +for .BR setrlimit () when -.IR rlim->rlim_cur +.IR rlim->rlim_cur was greater than .IR rlim->rlim_max . .SH NOTES @@ -403,7 +404,7 @@ Resource limits are preserved across .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. .BR RLIMIT_MEMLOCK -and +and .BR RLIMIT_NPROC derive from BSD and are not specified in POSIX.1-2001; they are present on the BSDs and Linux, but on few other implementations. diff --git a/man2/getrusage.2 b/man2/getrusage.2 index 7b1a6726d..b95e29bcb 100644 --- a/man2/getrusage.2 +++ b/man2/getrusage.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,13 +19,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formerly included -.\" coverage of getrusage(2), has been split, so that the latter is -.\" now covered in its own getrusage.2. For older details of change +.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formerly included +.\" coverage of getrusage(2), has been split, so that the latter is +.\" now covered in its own getrusage.2. For older details of change .\" history, etc, see getrlimit.2 .\" .\" Modified 2004-11-16, mtk, Noted that the non-conformance @@ -44,14 +44,14 @@ getrusage \- get resource usage .PP .BR getrusage () returns current resource usages, for a \fIwho\fP -of either +of either .B RUSAGE_SELF -or +or .BR RUSAGE_CHILDREN . The former asks for resources used by the current process, the latter for resources used by those of its children that have terminated and have been waited for. -.PP +.PP .in +0.5i .nf struct rusage { @@ -75,7 +75,8 @@ struct rusage { .fi .in -0.5i .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -88,8 +89,8 @@ points outside the accessible address space. .I who is invalid. .SH "CONFORMING TO" -SVr4, 4.3BSD. -POSIX.1-2001 specifies +SVr4, 4.3BSD. +POSIX.1-2001 specifies .BR getrusage (), but only specifies the fields .I ru_utime @@ -123,9 +124,9 @@ In linux 2.4 only the fields .IR ru_stime , .IR ru_minflt , and -.IR ru_majflt +.IR ru_majflt are maintained. -Since Linux 2.6, +Since Linux 2.6, .I ru_nvcsw and .I ru_nivcsw diff --git a/man2/getsockname.2 b/man2/getsockname.2 index 3807af44e..938439b77 100644 --- a/man2/getsockname.2 +++ b/man2/getsockname.2 @@ -46,9 +46,10 @@ getsockname \- get socket name .fi .SH DESCRIPTION .BR getsockname () -returns the current +returns the current .I name -for the specified socket. The +for the specified socket. +The .I namelen parameter should be initialized to indicate the amount of space pointed to by @@ -56,7 +57,8 @@ the amount of space pointed to by On return it contains the actual size of the name returned (in bytes). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -67,7 +69,7 @@ The argument is not a valid descriptor. .TP .B EFAULT -The +The .I name parameter points to memory not in a valid part of the process address space. @@ -89,9 +91,9 @@ SVr4, 4.4BSD (the .BR getsockname () function call appeared in 4.2BSD), POSIX.1-2001. .\" SVr4 documents additional ENOMEM -.\" and ENOSR error codes. +.\" and ENOSR error codes. .SH NOTE -The third argument of +The third argument of .BR getsockname () is in reality an `int *' (and this is what 4.x BSD and libc4 and libc5 have). Some POSIX confusion resulted in the present socklen_t, also used by glibc. diff --git a/man2/getsockopt.2 b/man2/getsockopt.2 index 302065736..63731ddf4 100644 --- a/man2/getsockopt.2 +++ b/man2/getsockopt.2 @@ -36,7 +36,7 @@ .\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) .\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) -.\" Modified 1999 by Andi Kleen . +.\" Modified 1999 by Andi Kleen . .\" Removed most stuff because it is in socket.7 now. .\" .TH GETSOCKOPT 2 1999-05-24 "Linux Man Page" "Linux Programmer's Manual" @@ -60,7 +60,8 @@ and .BR setsockopt () manipulate the .I options -associated with a socket. Options may exist at multiple +associated with a socket. +Options may exist at multiple protocol levels; they are always present at the uppermost .B socket level. @@ -73,7 +74,8 @@ is specified as .BR SOL_SOCKET . To manipulate options at any other level the protocol number of the appropriate protocol -controlling the option is supplied. For example, +controlling the option is supplied. +For example, to indicate that an option is to be interpreted by the .B TCP protocol, @@ -92,23 +94,26 @@ are used to access option values for For .BR getsockopt () they identify a buffer in which the value for the -requested option(s) are to be returned. For +requested option(s) are to be returned. +For .BR getsockopt (), .I optlen is a value-result parameter, initially containing the size of the buffer pointed to by .IR optval , and modified on return to indicate the actual size of -the value returned. If no option value is -to be supplied or returned, +the value returned. +If no option value is to be supplied or returned, .I optval may be NULL. .I Optname and any specified options are passed uninterpreted to the appropriate -protocol module for interpretation. The include file +protocol module for interpretation. +The include file .I -contains definitions for socket level options, described below. Options at +contains definitions for socket level options, described below. +Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. @@ -125,7 +130,8 @@ For a description of the available socket options see .BR socket (7) and the appropriate protocol man pages. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -136,9 +142,10 @@ The argument is not a valid descriptor. .TP .B EFAULT -The address pointed to by +The address pointed to by .I optval -is not in a valid part of the process address space. For +is not in a valid part of the process address space. +For .BR getsockopt (), this error may also be returned if .I optlen @@ -146,7 +153,7 @@ is not in a valid part of the process address space. .TP .B EINVAL .I optlen -invalid in +invalid in .BR setsockopt (). .TP .B ENOPROTOOPT @@ -157,22 +164,22 @@ The argument .I s is a file, not a socket. .SH "CONFORMING TO" -SVr4, 4.4BSD (these system calls first appeared in 4.2BSD), +SVr4, 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001. .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does -.\" not document the +.\" not document the .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO .\" options .SH NOTE -The +The .I optlen -argument of +argument of .BR getsockopt " and " setsockopt -is in reality an +is in reality an .I "int [*]" (and this is what 4.x BSD and libc4 and libc5 have). -Some POSIX confusion resulted in the present -.IR socklen_t , +Some POSIX confusion resulted in the present +.IR socklen_t , also used by glibc. See also .BR accept (2). diff --git a/man2/gettid.2 b/man2/gettid.2 index 5b7228a7a..6bd37cc1d 100644 --- a/man2/gettid.2 +++ b/man2/gettid.2 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,13 +38,15 @@ gettid \- get thread identification .fi .B pid_t gettid(void); .SH DESCRIPTION -\fBgettid\fP() returns the thread ID of the current process. This is equal +\fBgettid\fP() returns the thread ID of the current process. +This is equal to the process ID (as returned by .BR getpid (2)), unless the process is part of a thread group (created by specifying the CLONE_THREAD flag to the .BR clone (2) -system call). All processes in the same thread group +system call). +All processes in the same thread group have the same PID, but each one has a unique TID. .SH "RETURN VALUE" On success, returns the thread ID of the current process. diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 index 812953cd5..9c2f8ef1b 100644 --- a/man2/gettimeofday.2 +++ b/man2/gettimeofday.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -53,11 +53,11 @@ The functions and .BR settimeofday () can get and set the time as well as a timezone. -The +The .I tv -argument is a -.I struct timeval -(as specified in +argument is a +.I struct timeval +(as specified in .IR ): .sp .in +0.25i @@ -71,9 +71,9 @@ struct timeval { .sp and gives the number of seconds and microseconds since the Epoch (see .BR time (2)). -The +The .I tz -argument is a +argument is a .IR "struct timezone" : .sp .in +0.25i @@ -87,7 +87,7 @@ struct timezone { .PP If either .I tv -or +or .I tz is NULL, the corresponding structure is not set or returned. .\" The following is covered under EPERM below: @@ -95,8 +95,8 @@ is NULL, the corresponding structure is not set or returned. .\" Only the superuser may use .\" .BR settimeofday (). .PP -The use of the -.I timezone +The use of the +.I timezone structure is obsolete; the .I tz argument should normally be specified as NULL. @@ -105,17 +105,19 @@ The field has never been used under Linux; it has not been and will not be supported by libc or glibc. Each and every occurrence of this field in the kernel source -(other than the declaration) is a bug. Thus, the following +(other than the declaration) is a bug. +Thus, the following is purely of historic interest. The field .I tz_dsttime contains a symbolic constant (values are given below) that indicates in which part of the year Daylight Saving Time -is in force. (Note: its value is constant throughout the year: +is in force. +(Note: its value is constant throughout the year: it does not indicate that DST is in force, it just selects an algorithm.) -The daylight saving time algorithms defined are as follows : +The daylight saving time algorithms defined are as follows : .PP \fB DST_NONE\fP /* not on dst */ .br @@ -143,8 +145,10 @@ Of course it turned out that the period in which Daylight Saving Time is in force cannot be given by a simple algorithm, one per country; indeed, this period is determined by unpredictable political -decisions. So this method of representing time zones -has been abandoned. Under Linux, in a call to +decisions. +So this method of representing time zones +has been abandoned. +Under Linux, in a call to .BR settimeofday () the .I tz_dsttime @@ -160,12 +164,13 @@ argument, the .I tv argument is NULL and the .I tz_minuteswest -field is non-zero. In such a case it is assumed that the CMOS clock +field is non-zero. +In such a case it is assumed that the CMOS clock is on local time, and that it has to be incremented by this amount to get UTC system time. No doubt it is a bad idea to use this feature. .PP -The following macros are defined to operate on a +The following macros are defined to operate on a .IR "struct timeval" : .sp .nf @@ -192,7 +197,7 @@ is set appropriately). .SH ERRORS .TP .B EFAULT -One of +One of .I tv or .I tz @@ -202,7 +207,7 @@ pointed outside the accessible address space. Timezone (or something else) is invalid. .TP .B EPERM -The calling process has insufficient privilege to call +The calling process has insufficient privilege to call .BR settimeofday (); under Linux the .B CAP_SYS_TIME @@ -220,14 +225,14 @@ are (since glibc2.2.2) only available if .B _BSD_SOURCE is defined. .LP -Traditionally, the fields of -.I struct timeval +Traditionally, the fields of +.I struct timeval were longs. .SH "CONFORMING TO" -SVr4, 4.3BSD. +SVr4, 4.3BSD. POSIX.1-2001 describes .BR gettimeofday () -but not +but not .BR settimeofday (). .SH "SEE ALSO" .BR date (1), diff --git a/man2/getuid.2 b/man2/getuid.2 index a2fcd0fa7..e061a165c 100644 --- a/man2/getuid.2 +++ b/man2/getuid.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man2/getxattr.2 b/man2/getxattr.2 index a0a452027..ed31ad641 100644 --- a/man2/getxattr.2 +++ b/man2/getxattr.2 @@ -66,7 +66,7 @@ The length of the attribute is returned. .PP .BR lgetxattr () -is identical to +is identical to .BR getxattr (), except in the case of a symbolic link, where the link itself is interrogated, not the file that it refers to. diff --git a/man2/idle.2 b/man2/idle.2 index 9fa4b9f5d..a14f28a25 100644 --- a/man2/idle.2 +++ b/man2/idle.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man2/init_module.2 b/man2/init_module.2 index 10be572be..534b6698c 100644 --- a/man2/init_module.2 +++ b/man2/init_module.2 @@ -2,7 +2,7 @@ .\" This file is distributed according to the GNU General Public License. .\" See the file COPYING in the top level source directory for details. .\" -.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" .TH INIT_MODULE 2 "2002" "Linux" "Linux Module Support" @@ -60,7 +60,8 @@ the rest of the module. .PP This system call requires privilege. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned and +On success, zero is returned. +On error, \-1 is returned and .I errno is set appropriately. .SH ERRORS @@ -81,7 +82,7 @@ slot is filled in incorrectly, .I image->name does not correspond to the original module name, some .I image->deps -entry does not correspond to a loaded module, +entry does not correspond to a loaded module, or some other similar inconsistency. .TP .B ENOENT diff --git a/man2/inotify_add_watch.2 b/man2/inotify_add_watch.2 index 5a8eec0c7..629cea4f5 100644 --- a/man2/inotify_add_watch.2 +++ b/man2/inotify_add_watch.2 @@ -35,11 +35,11 @@ inotify_add_watch \- add a watch to an initialized inotify instance .BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); .SH DESCRIPTION .BR inotify_add_watch () -adds a new watch, or modifies an existing watch, +adds a new watch, or modifies an existing watch, for the file whose location is specified in .IR pathname ; the caller must have read permission for this file. -The +The .I fd argument is a file descriptor referring to the inotify instance whose watch list is to be modified. @@ -55,13 +55,13 @@ for a description of the bits that can be set in A successful call to .BR inotify_add_watch () -returns the unique watch descriptor associated with +returns the unique watch descriptor associated with .I pathname for this inotify instance. -If +If .I pathname was not previously being watched by this inotify instance, -then the watch descriptor is newly allocated. +then the watch descriptor is newly allocated. If .I pathname was already being watched, then the descriptor @@ -69,10 +69,10 @@ for the existing watch is returned. The watch descriptor is returned by later .BR read (2)s -from the inotify file descriptor. +from the inotify file descriptor. These reads fetch .I inotify_event -structures indicating file system events; +structures indicating file system events; the returned watch descriptor identifies the object for which the event occurred. .SH "RETURN VALUE" @@ -111,5 +111,5 @@ Inotify was merged into the 2.6.13 Linux kernel. This system call is Linux specific. .SH "SEE ALSO" .BR inotify_init (2), -.BR inotify_rm_watch (2), +.BR inotify_rm_watch (2), .BR inotify (7). diff --git a/man2/inotify_init.2 b/man2/inotify_init.2 index ab63fd0ce..3e9f35aef 100644 --- a/man2/inotify_init.2 +++ b/man2/inotify_init.2 @@ -59,5 +59,5 @@ Inotify was merged into the 2.6.13 Linux kernel. This system call is Linux specific. .SH "SEE ALSO" .BR inotify_add_watch (2), -.BR inotify_rm_watch (2), +.BR inotify_rm_watch (2), .BR inotify (7). diff --git a/man2/inotify_rm_watch.2 b/man2/inotify_rm_watch.2 index 49242b6fc..8fdde3b03 100644 --- a/man2/inotify_rm_watch.2 +++ b/man2/inotify_rm_watch.2 @@ -41,7 +41,8 @@ from the inotify instance associated with the file descriptor Removing a watch causes an .B IN_IGNORED -event to be generated for this watch descriptor. (See +event to be generated for this watch descriptor. +(See .BR inotify (7).) .SH "RETURN VALUE" On success, @@ -67,5 +68,5 @@ Inotify was merged into the 2.6.13 Linux kernel. This system call is Linux specific. .SH "SEE ALSO" .BR inotify_init (2), -.BR inotify_add_watch (2), +.BR inotify_add_watch (2), .BR inotify (7). diff --git a/man2/intro.2 b/man2/intro.2 index f207418d1..7eea2e057 100644 --- a/man2/intro.2 +++ b/man2/intro.2 @@ -56,8 +56,9 @@ A _syscall macro desired system call .SS Setup -The important thing to know about a system call is its prototype. You -need to know how many arguments, their types, and the function return type. +The important thing to know about a system call is its prototype. +You need to know how many arguments, their types, +and the function return type. There are six macros that make the actual call into the system easier. They have the form: .sp @@ -65,7 +66,7 @@ They have the form: .RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...) .RS .HP -where \fIX\fP is 0\(en5, which are the number of arguments taken by the +where \fIX\fP is 0\(en5, which are the number of arguments taken by the system call .HP \fItype\fP is the return type of the system call @@ -79,7 +80,8 @@ system call .RE .sp These macros create a function called \fIname\fP with the arguments you -specify. Once you include the _syscall() in your source file, +specify. +Once you include the _syscall() in your source file, you call the system call by \fIname\fP. .SH EXAMPLE .sp @@ -94,7 +96,7 @@ _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 +int main(void) { struct sysinfo s_info; @@ -126,11 +128,13 @@ Swap: total 27881472 / free 24698880 Number of processes = 40 .fi .SH NOTES -The _syscall() macros DO NOT produce a prototype. You may have to +The _syscall() macros DO NOT produce a prototype. +You may have to create one, especially for C++ users. .sp System calls are not required to return only positive or negative error -codes. You need to read the source to be sure how it will return errors. +codes. +You need to read the source to be sure how it will return errors. Usually, it is the negative of a standard error code, e.g., \-\fBEPERM\fP. The _syscall() macros will return the result \fIr\fP of the system call when \fIr\fP is nonnegative, but will return \-1 and set the variable @@ -141,7 +145,8 @@ For the error codes, see .sp Some system calls, such as .BR mmap (), -require more than five arguments. These are handled by pushing the +require more than five arguments. +These are handled by pushing the arguments on the stack and passing a pointer to the block of arguments. .sp When defining a system call, the argument types MUST be passed by-value @@ -152,19 +157,19 @@ about yet is via .BR syscall (2). However, this mechanism can only be used if using a libc (such as glibc) that supports -.BR syscall (2), -and if the +.BR syscall (2), +and if the .I header file contains the required SYS_foo definition. Otherwise, the use of a _syscall macro is required. Some architectures, notably ia64, do not provide the _syscall macros. On these architectures, -.BR syscall (2) +.BR syscall (2) must be used. .SH "CONFORMING TO" Certain codes are used to indicate Unix variants and standards to -which calls in the section conform. +which calls in the section conform. See .BR standards (7). .SH FILES diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 index 8ed7d6dfa..fc999a52a 100644 --- a/man2/io_cancel.2 +++ b/man2/io_cancel.2 @@ -27,23 +27,23 @@ io_cancel \- cancel an outstanding asynchronous I/O operation .nf .\" .ad l .\" .hy 0 -.\" +.\" .B #include .\"#include .sp .\" .HP 16 -.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb , +.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb , .BI " struct io_event *" result ); .\" .ad .\" .hy .fi .SH "DESCRIPTION" .PP -\fBio_cancel\fR() attempts to cancel an asynchronous I/O operation -previously submitted with the \fBio_submit\fR system call. -\fIctx_id\fR is the AIO context ID of the operation to be cancelled. -If the AIO context is found, the event will be cancelled and then copied -into the memory pointed to by \fIresult\fR without being placed +\fBio_cancel\fR() attempts to cancel an asynchronous I/O operation +previously submitted with the \fBio_submit\fR system call. +\fIctx_id\fR is the AIO context ID of the operation to be cancelled. +If the AIO context is found, the event will be cancelled and then copied +into the memory pointed to by \fIresult\fR without being placed into the completion queue. .SH "RETURN VALUE" .PP @@ -67,16 +67,16 @@ The \fIiocb\fR specified was not cancelled. The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. .SH "CONFORMING TO" .PP -\fBio_cancel\fR() is Linux specific and should not be used +\fBio_cancel\fR() is Linux specific and should not be used in programs that are intended to be portable. .SH "SEE ALSO" .PP -\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2), +\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_submit\fR(2). .\" .SH "NOTES" -.\" +.\" .\" .PP .\" The asynchronous I/O system calls were written by Benjamin LaHaise. -.\" +.\" .\" .SH AUTHOR .\" Kent Yoder. diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 index f219245a8..fdc1429a8 100644 --- a/man2/io_destroy.2 +++ b/man2/io_destroy.2 @@ -37,9 +37,9 @@ io_destroy \- destroy an asynchronous I/O context .fi .SH "DESCRIPTION" .PP -\fBio_destroy\fR() removes the asynchronous I/O context from the list of -I/O contexts and then destroys it. -\fBio_destroy\fR() can also cancel any outstanding asynchronous I/O +\fBio_destroy\fR() removes the asynchronous I/O context from the list of +I/O contexts and then destroys it. +\fBio_destroy\fR() can also cancel any outstanding asynchronous I/O actions on \fIctx\fR and block on completion. .SH "RETURN VALUE" .PP @@ -58,19 +58,19 @@ The context pointed to is invalid. \fBio_destroy\fR() is not implemented on this architecture. .SH "CONFORMING TO" .PP -\fBio_destroy\fR() is Linux specific and should not be used in programs +\fBio_destroy\fR() is Linux specific and should not be used in programs that are intended to be portable. .SH "VERSIONS" .PP The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. .SH "SEE ALSO" .PP -\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2), +\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2), \fBio_cancel\fR(2). .\" .SH "NOTES" -.\" +.\" .\" .PP .\" The asynchronous I/O system calls were written by Benjamin LaHaise. -.\" +.\" .\" .SH AUTHOR .\" Kent Yoder. diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 index bd3483796..8836c48ed 100644 --- a/man2/io_getevents.2 +++ b/man2/io_getevents.2 @@ -32,7 +32,7 @@ io_getevents \- read asynchronous I/O events from the completion queue .\" #include .sp .\" .HP 19 -.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr , +.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr , .BI " struct io_event *" events \ ", struct timespec *" timeout ); .\" .ad @@ -40,24 +40,24 @@ io_getevents \- read asynchronous I/O events from the completion queue .fi .SH "DESCRIPTION" .PP -\fBio_getevents\fR() attempts to read at least \fImin_nr\fR events and -up to \fInr\fR events from the completion queue of the AIO context -specified by \fIctx_id\fR. -\fItimeout\fR specifies the amount of time to wait for events, +\fBio_getevents\fR() attempts to read at least \fImin_nr\fR events and +up to \fInr\fR events from the completion queue of the AIO context +specified by \fIctx_id\fR. +\fItimeout\fR specifies the amount of time to wait for events, where a NULL timeout waits until at least \fImin_nr\fR events -have been seen. -Note that \fItimeout\fR is relative and will be updated if not NULL +have been seen. +Note that \fItimeout\fR is relative and will be updated if not NULL and the operation blocks. .SH "RETURN VALUE" .PP -On success, -\fBio_getevents\fR() returns the number of events read: 0 if no events are +On success, +\fBio_getevents\fR() returns the number of events read: 0 if no events are available or < \fImin_nr\fR if the \fItimeout\fR has elapsed; on failure, it returns one of the errors listed under ERRORS. .SH "ERRORS" .TP .B EINVAL -\fIctx_id\fR is invalid. \fImin_nr\fR is out of range or \fInr\fR is +\fIctx_id\fR is invalid. \fImin_nr\fR is out of range or \fInr\fR is out of range. .TP .B EFAULT @@ -67,19 +67,19 @@ Either \fIevents\fR or \fItimeout\fR is an invalid pointer. \fBio_getevents\fR() is not implemented on this architecture. .SH "CONFORMING TO" .PP -\fBio_getevents\fR() is Linux specific and should not be used in +\fBio_getevents\fR() is Linux specific and should not be used in programs that are intended to be portable. .SH "VERSIONS" .PP The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. .SH "SEE ALSO" .PP -\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2), +\fBio_setup\fR(2), \fBio_submit\fR(2), \fBio_getevents\fR(2), \fBio_cancel\fR(2), \fBio_destroy\fR(2). .\" .SH "NOTES" -.\" +.\" .\" .PP .\" The asynchronous I/O system calls were written by Benjamin LaHaise. -.\" +.\" .\" .SH AUTHOR .\" Kent Yoder. diff --git a/man2/io_setup.2 b/man2/io_setup.2 index afca76563..4c128183d 100644 --- a/man2/io_setup.2 +++ b/man2/io_setup.2 @@ -37,20 +37,20 @@ io_setup \- create an asynchronous I/O context .fi .SH "DESCRIPTION" .PP -\fBio_setup\fR() creates an asynchronous I/O context capable of receiving -at least \fInr_events\fR. -\fIctxp\fR must not point to an AIO context that already exists, and must -be initialized to 0 prior to the call. -On successful creation of the AIO context, \fI*ctxp\fR is filled in +\fBio_setup\fR() creates an asynchronous I/O context capable of receiving +at least \fInr_events\fR. +\fIctxp\fR must not point to an AIO context that already exists, and must +be initialized to 0 prior to the call. +On successful creation of the AIO context, \fI*ctxp\fR is filled in with the resulting handle. .SH "RETURN VALUE" .PP -\fBio_setup\fR() returns 0 on success; +\fBio_setup\fR() returns 0 on success; on failure, it returns one of the errors listed under ERRORS. .SH "ERRORS" .TP .B EINVAL -\fIctxp\fR is not initialized, or the specified \fInr_events\fR +\fIctxp\fR is not initialized, or the specified \fInr_events\fR exceeds internal limits. \fInr_events\fR should be greater than 0. .TP .B EFAULT @@ -66,14 +66,14 @@ The specified \fInr_events\fR exceeds the user's limit of available events. \fBio_setup\fR() is not implemented on this architecture. .SH "CONFORMING TO" .PP -\fBio_setup\fR() is Linux specific and should not be used in programs +\fBio_setup\fR() is Linux specific and should not be used in programs that are intended to be portable. .SH "VERSIONS" .PP The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. .SH "SEE ALSO" .PP -\fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_submit\fR(2), +\fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_submit\fR(2), \fBio_cancel\fR(2). .\" .SH "NOTES" .\" .PP diff --git a/man2/io_submit.2 b/man2/io_submit.2 index a08b2c9a5..6e251ba79 100644 --- a/man2/io_submit.2 +++ b/man2/io_submit.2 @@ -37,22 +37,22 @@ io_submit \- submit asynchronous I/O blocks for processing .fi .SH "DESCRIPTION" .PP -\fBio_submit\fR() queues \fInr\fR I/O request blocks for processing in -the AIO context \fIctx_id\fR. \fIiocbpp\fR should be an array of -\fInr\fR AIO request blocks, +\fBio_submit\fR() queues \fInr\fR I/O request blocks for processing in +the AIO context \fIctx_id\fR. \fIiocbpp\fR should be an array of +\fInr\fR AIO request blocks, which will be submitted to context \fIctx_id\fR. .SH "RETURN VALUE" .PP -On success, +On success, \fBio_submit\fR() returns the number of \fIiocb\fRs submitted (which may be 0 if \fInr\fR is zero); on failure, it returns one of the errors listed under ERRORS. .SH "ERRORS" .TP .B EINVAL -The \fIaio_context\fR specified by \fIctx_id\fR is invalid. -\fInr\fR is less than 0. The \fIiocb\fR at *iocbpp[0] is not properly -initialized, or the operation specified is invalid for the file descriptor +The \fIaio_context\fR specified by \fIctx_id\fR is invalid. +\fInr\fR is less than 0. The \fIiocb\fR at *iocbpp[0] is not properly +initialized, or the operation specified is invalid for the file descriptor in the \fIiocb\fR. .TP .B EFAULT @@ -68,14 +68,14 @@ Insufficient resources are available to queue any \fIiocb\fRs. \fBio_submit\fR() is not implemented on this architecture. .SH "CONFORMING TO" .PP -\fBio_submit\fR() is Linux specific and should not be used in +\fBio_submit\fR() is Linux specific and should not be used in programs that are intended to be portable. .SH "VERSIONS" .PP The asynchronous I/O system calls first appeared in Linux 2.5, August 2002. .SH "SEE ALSO" .PP -\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2), +\fBio_setup\fR(2), \fBio_destroy\fR(2), \fBio_getevents\fR(2), \fBio_cancel\fR(2). .\" .SH "NOTES" .\" .PP diff --git a/man2/ioctl.2 b/man2/ioctl.2 index 7474ec4b4..a6bf869b9 100644 --- a/man2/ioctl.2 +++ b/man2/ioctl.2 @@ -46,22 +46,24 @@ ioctl \- control device .SH DESCRIPTION The .BR ioctl () -function manipulates the underlying device parameters of special files. In -particular, many operating characteristics of character special files +function manipulates the underlying device parameters of special files. +In particular, many operating characteristics of character special files (e.g. terminals) may be controlled with .BR ioctl () -requests. The argument +requests. +The argument .I d must be an open file descriptor. .PP -The second argument is a device-dependent request code. The third -argument is an untyped pointer to memory. It's traditionally +The second argument is a device-dependent request code. +The third argument is an untyped pointer to memory. +It's traditionally .BI "char *" argp (from the days before .B "void *" was valid C), and will be so named for this discussion. .PP -An +An .BR ioctl () .I request has encoded in it whether the argument is an @@ -70,14 +72,15 @@ parameter or .I out parameter, and the size of the argument .I argp -in bytes. Macros and defines used in specifying an +in bytes. +Macros and defines used in specifying an .BR ioctl () .I request are located in the file .IR . .SH "RETURN VALUE" Usually, on success zero is returned. -A few +A few .BR ioctl () requests use the return value as an output parameter and return a nonnegative value on success. @@ -116,17 +119,17 @@ Often the call has unwanted side effects, that can be avoided under Linux by giving it the O_NONBLOCK flag. .SH "CONFORMING TO" -No single standard. +No single standard. Arguments, returns, and semantics of -.BR ioctl (2) +.BR ioctl (2) vary according to the device driver in question (the call is used as a catch-all for operations that don't cleanly fit the Unix stream I/O -model). -See +model). +See .BR ioctl_list (2) -for a list of many of the known +for a list of many of the known .BR ioctl () -calls. +calls. The .BR ioctl () function call appeared in Version 7 AT&T Unix. diff --git a/man2/ioctl_list.2 b/man2/ioctl_list.2 index d1ec13883..f86a5ee26 100644 --- a/man2/ioctl_list.2 +++ b/man2/ioctl_list.2 @@ -2,31 +2,32 @@ .\" Sun 17 Sep 1995 .\" Michael Elizabeth Chastain .\" -.\" +.\" .\" // Copyright -.\" +.\" .\" Ioctl List 1.3.27 is copyright 1995 by Michael Elizabeth Chastain. .\" It is licensed under the Gnu Public License, Version 2. -.\" -.\" -.\" +.\" +.\" +.\" .\" // Change Log -.\" +.\" .\" 1.3.27 421 ioctls. .\" Type information for non-pointer args. .\" SIOCDEVPRIVATE, SIOCPROTOPRIVATE ioctls. .\" Descriptions of extended arguments. -.\" +.\" .\" 1.2.9 365 ioctls. .\" First public version. -.\" -.\" +.\" +.\" .TH IOCTL_LIST 2 2003-03-30 "Linux 1.3" "Linux Programmer's Manual" .SH NAME ioctl_list \- list of ioctl calls in Linux/i386 kernel .SH DESCRIPTION This is Ioctl List 1.3.27, a list of ioctl calls in Linux/i386 kernel -1.3.27. It contains 421 ioctls from /usr/include/{asm,linux}/*.h. +1.3.27. +It contains 421 ioctls from /usr/include/{asm,linux}/*.h. For each ioctl, its numerical value, its name, and its argument type are given. .PP @@ -36,7 +37,8 @@ If the kernel uses the argument for both input and output, this is marked with // I-O. .PP Some ioctls take more arguments or return more values than a single -structure. These are marked // MORE and documented further in a +structure. +These are marked // MORE and documented further in a separate section. .PP This list is very incomplete. @@ -49,9 +51,12 @@ tried to build some structure into them. .LP The old Linux situation was that of mostly 16-bit constants, where the last byte is a serial number, and the preceding byte(s) give a type -indicating the driver. Sometimes the major number was used: 0x03 -for the HDIO_* ioctls, 0x06 for the LP* ioctls. And sometimes -one or more ASCII letters were used. For example, TCGETS has value +indicating the driver. +Sometimes the major number was used: 0x03 +for the HDIO_* ioctls, 0x06 for the LP* ioctls. +And sometimes +one or more ASCII letters were used. +For example, TCGETS has value 0x00005401, with 0x54 = 'T' indicating the terminal driver, and CYGETTIMEOUT has value 0x00435906, with 0x43 0x59 = 'C' 'Y' indicating the cyclades driver. @@ -78,7 +83,8 @@ it does not help in checking, but it causes varying values for the various architectures. .SH "RETURN VALUE" Decent ioctls return 0 on success and \-1 on error, while -any output value is stored via the argument. However, +any output value is stored via the argument. +However, quite a few ioctls in fact return an output value. This is not yet indicated below. .nf @@ -567,16 +573,18 @@ This is not yet indicated below. // More arguments. Some ioctl's take a pointer to a structure which contains additional -pointers. These are documented here in alphabetical order. +pointers. +These are documented here in alphabetical order. CDROMREADAUDIO takes an input pointer 'const struct cdrom_read_audio *'. The 'buf' field points to an output buffer of length 'nframes * CD_FRAMESIZE_RAW'. CDROMREADCOOKED, CDROMREADMODE1, CDROMREADMODE2, and CDROMREADRAW take -an input pointer 'const struct cdrom_msf *'. They use the same pointer -as an output pointer to 'char []'. The length varies by request. For -CDROMREADMODE1, most drivers use 'CD_FRAMESIZE', but the Optics Storage +an input pointer 'const struct cdrom_msf *'. +They use the same pointer as an output pointer to 'char []'. +The length varies by request. +For CDROMREADMODE1, most drivers use 'CD_FRAMESIZE', but the Optics Storage driver uses 'OPT_BLOCKSIZE' instead (both have the numerical value 2048). @@ -596,29 +604,35 @@ The 'ifr_data' field is a pointer to another structure as follows: EQL_GETMASTERCFG struct master_config * EQL_SETMASTERCFG const struct master_config * -FDRAWCMD takes a 'struct floppy raw_cmd *'. If 'flags & FD_RAW_WRITE' +FDRAWCMD takes a 'struct floppy raw_cmd *'. +If 'flags & FD_RAW_WRITE' is non-zero, then 'data' points to an input buffer of length 'length'. If 'flags & FD_RAW_READ' is non-zero, then 'data' points to an output buffer of length 'length'. GIO_FONTX and PIO_FONTX take a 'struct console_font_desc *' or a 'const struct console_font_desc *', respectively. 'chardata' points to -a buffer of 'char [charcount]'. This is an output buffer for GIO_FONTX +a buffer of 'char [charcount]'. +This is an output buffer for GIO_FONTX and an input buffer for PIO_FONTX. GIO_UNIMAP and PIO_UNIMAP take a 'struct unimapdesc *' or a 'const struct unimapdesc *', respectively. 'entries' points to a buffer -of 'struct unipair [entry_ct]'. This is an output buffer for GIO_UNIMAP +of 'struct unipair [entry_ct]'. +This is an output buffer for GIO_UNIMAP and an input buffer for PIO_UNIMAP. KDADDIO, KDDELIO, KDDISABIO, and KDENABIO enable or disable access to -I/O ports. They are essentially alternate interfaces to 'ioperm'. +I/O ports. +They are essentially alternate interfaces to 'ioperm'. KDMAPDISP and KDUNMAPDISP enable or disable memory mappings or I/O port -access. They are not implemented in the kernel. +access. +They are not implemented in the kernel. SCSI_IOCTL_PROBE_HOST takes an input pointer 'const int *', which is a -length. It uses the same pointer as an output pointer to a 'char []' +length. +It uses the same pointer as an output pointer to a 'char []' buffer of this length. SIOCADDRT and SIOCDELRT take an input pointer whose type depends on @@ -628,7 +642,8 @@ the protocol: AX.25 const struct ax25_route * NET/ROM const struct nr_route_struct * -SIOCGIFCONF takes a 'struct ifconf *'. The 'ifc_buf' field points to a +SIOCGIFCONF takes a 'struct ifconf *'. +The 'ifc_buf' field points to a buffer of length 'ifc_len' bytes, into which the kernel writes a list of type 'struct ifreq []'. @@ -637,8 +652,10 @@ SIOCSIFHWADDR takes an input pointer whose type depends on the protocol: Most protocols const struct ifreq * AX.25 const char [AX25_ADDR_LEN] -TIOCLINUX takes a 'const char *'. It uses this to distinguish several -independent sub-cases. In the table below, 'N + foo' means 'foo' after +TIOCLINUX takes a 'const char *'. +It uses this to distinguish several +independent sub-cases. +In the table below, 'N + foo' means 'foo' after an N-byte pad. 'struct selection' is implicitly defined in 'drivers/char/selection.c' diff --git a/man2/ioperm.2 b/man2/ioperm.2 index 8c89ea5a7..90d77cbdd 100644 --- a/man2/ioperm.2 +++ b/man2/ioperm.2 @@ -3,7 +3,7 @@ .\" Copyright (c) 1993 Michael Haardt .\" (michael@moria.de) .\" Fri Apr 2 11:32:09 MET DST 1993 -.\" +.\" .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of @@ -25,7 +25,7 @@ .\" USA. .\" .\" Modified Sat Jul 24 15:12:05 1993 by Rik Faith -.\" Modified Tue Aug 1 16:27 1995 by Jochen Karrer +.\" Modified Tue Aug 1 16:27 1995 by Jochen Karrer .\" .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond .\" Modified Mon Feb 15 17:28:41 CET 1999 by Andries E. Brouwer @@ -46,26 +46,27 @@ ioperm \- set port input/output permissions .SH DESCRIPTION \fBioperm\fP() sets the port access permission bits for the process for \fInum\fP bytes starting from port address \fBfrom\fP to the value -\fBturn_on\fP. +\fBturn_on\fP. If \fBturn_on\fP is non-zero, the calling process must be privileged .RB ( CAP_SYS_RAWIO ). -Only the first 0x3ff I/O ports can be specified in this manner. +Only the first 0x3ff I/O ports can be specified in this manner. For more ports, the .BR iopl () function must be used. Permissions are not inherited on -.BR fork (), -but on +.BR fork (), +but on .BR exec () -they are. +they are. This is useful for giving port access permissions to non-privileged tasks. This call is mostly for the i386 architecture. On many other architectures it does not exist or will always return an error. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -91,7 +92,7 @@ intended to be portable. .SH NOTES Libc5 treats it as a system call and has a prototype in .IR . -Glibc1 does not have a prototype. +Glibc1 does not have a prototype. Glibc2 has a prototype both in .I and in diff --git a/man2/iopl.2 b/man2/iopl.2 index 2341fdb57..6789dc89d 100644 --- a/man2/iopl.2 +++ b/man2/iopl.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,11 +19,11 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" Modified Tue Aug 1 16:47 1995 by Jochen Karrer +.\" Modified Tue Aug 1 16:47 1995 by Jochen Karrer .\" .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond .\" Modified Fri Nov 27 14:50:36 CET 1998 by Andries Brouwer @@ -43,18 +43,19 @@ changes the I/O privilege level of the current process, as specified in .IR level . This call is necessary to allow 8514-compatible X servers to run under -Linux. Since these X servers require access to all 65536 I/O ports, the +Linux. +Since these X servers require access to all 65536 I/O ports, the .BR ioperm () call is not sufficient. In addition to granting unrestricted I/O port access, running at a higher -I/O privilege level also allows the process to disable interrupts. This -will probably crash the system, and is not recommended. +I/O privilege level also allows the process to disable interrupts. +This will probably crash the system, and is not recommended. Permissions are inherited by -.BR fork () -and -.BR exec (). +.BR fork () +and +.BR exec (). The I/O privilege level for a normal process is 0. @@ -62,7 +63,8 @@ This call is mostly for the i386 architecture. On many other architectures it does not exist or will always return an error. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -75,7 +77,7 @@ is greater than 3. This call is unimplemented. .TP .B EPERM -The calling process has insufficient privilege to call +The calling process has insufficient privilege to call .BR iopl (); the .B CAP_SYS_RAWIO @@ -86,7 +88,8 @@ intended to be portable. .SH NOTES Libc5 treats it as a system call and has a prototype in .IR . -Glibc1 does not have a prototype. Glibc2 has a prototype both in +Glibc1 does not have a prototype. +Glibc2 has a prototype both in .I and in .IR . diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 index ab247c190..e7a9813fc 100644 --- a/man2/ioprio_set.2 +++ b/man2/ioprio_set.2 @@ -138,7 +138,8 @@ See the NOTES section for more information on scheduling classes and priorities. I/O priorities are supported for reads and for synchronous (O_DIRECT, -O_SYNC) writes. I/O priorities are not supported for asynchronous +O_SYNC) writes. +I/O priorities are not supported for asynchronous writes because they are issued outside the context of the program dirtying the memory, and thus program-specific priorities do not apply. .SH "RETURN VALUE" @@ -235,7 +236,8 @@ These nice levels are grouped in three scheduling classes each one containing one or more priority levels: .TP .BR IOPRIO_CLASS_RT " (1)" -This is the real-time I/O class. This scheduling class is given +This is the real-time I/O class. +This scheduling class is given higher priority than any other class: processes from this class are given first access to the disk every time. @@ -264,8 +266,9 @@ Priority levels range from 0 (highest) to 7 (lowest). .BR IOPRIO_CLASS_IDLE " (3)" This is the idle scheduling class. Processes running at this level only get I/O -time when no one else needs the disk. The idle class has no class -data. +time when no one else needs the disk. +The idle class has no class +data. Attention is required when assigning this priority class to a process, since it may become starved if higher priority processes are constantly accessing the disk. diff --git a/man2/ipc.2 b/man2/ipc.2 index e0c75d000..0c1f12f33 100644 --- a/man2/ipc.2 +++ b/man2/ipc.2 @@ -29,7 +29,7 @@ ipc \- System V IPC system calls .SH SYNOPSIS .nf .BI "int ipc(unsigned int " call ", int " first ", int " second \ -", int " third , +", int " third , .BI " void *" ptr ", long " fifth ); .fi .SH DESCRIPTION diff --git a/man2/kill.2 b/man2/kill.2 index b0eff3c09..bff782109 100644 --- a/man2/kill.2 +++ b/man2/kill.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -116,20 +116,20 @@ Linux allows a process to signal itself, but on Linux the call \fIkill(\-1,sig)\fP does not signal the current process. .LP POSIX.1-2001 requires that if a process sends a signal to itself, -and the sending thread does not have the signal blocked, +and the sending thread does not have the signal blocked, and no other thread has it unblocked or is waiting for it in \fIsigwait\fP(), at least one unblocked signal must be delivered to the sending thread before the \fIkill\fP(). .SH BUGS -In 2.6 kernels up to and including 2.6.7, +In 2.6 kernels up to and including 2.6.7, there was a bug that meant that when sending signals to a process group, .BR kill () -failed with the error -.B EPERM +failed with the error +.B EPERM if the caller did have permission to send the signal to \fIany\fP (rather -than \fIall\fP) of the members of the process group. -Notwithstanding this error return, the signal was still delivered +than \fIall\fP) of the members of the process group. +Notwithstanding this error return, the signal was still delivered to all of the processes for which the caller had permission to signal. .SH "LINUX HISTORY" Across different kernel versions, Linux has enforced different rules diff --git a/man2/killpg.2 b/man2/killpg.2 index eed3f8b36..c2e7e7d25 100644 --- a/man2/killpg.2 +++ b/man2/killpg.2 @@ -35,7 +35,7 @@ .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond .\" Modified 2004-06-16 by Michael Kerrisk .\" Added notes on CAP_KILL -.\" Modified 2004-06-21 by aeb +.\" Modified 2004-06-21 by aeb .\" .TH KILLPG 2 2004-06-21 "BSD Man Page" "Linux Programmer's Manual" .SH NAME @@ -72,7 +72,8 @@ saved set-user-ID of the target process. In the case of SIGCONT it suffices when the sending and receiving processes belong to the same session. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -94,8 +95,9 @@ The process group was given as 0 but the sending process does not have a process group. .SH NOTES There are various differences between the permission checking -in BSD-type systems and System V-type systems. See the POSIX rationale -for +in BSD-type systems and System V-type systems. +See the POSIX rationale +for .BR kill (). A difference not mentioned by POSIX concerns the return value EPERM: BSD documents that no signal is sent and EPERM returned diff --git a/man2/link.2 b/man2/link.2 index e762da65a..cf89917f2 100644 --- a/man2/link.2 +++ b/man2/link.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,7 +50,8 @@ both names refer to the same file (and so have the same permissions and ownership) and it is impossible to tell which name was the \`original'. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -127,13 +128,14 @@ even if the same filesystem is mounted on both.) .SH NOTES Hard links, as created by .BR link (), -cannot span filesystems. Use +cannot span filesystems. +Use .BR symlink () if this is required. POSIX.1-2001 says that .BR link () -should dereference +should dereference .I oldpath if it is a symbolic link. However, Linux does not do so: if @@ -141,7 +143,7 @@ However, Linux does not do so: if is a symbolic link, then .I newpath is created as a (hard) link to the same symbolic link file -(i.e., +(i.e., .I newpath becomes a symbolic link to the same file that .I oldpath @@ -158,7 +160,8 @@ SVr4, 4.3BSD, POSIX.1-2001 (except as noted above). .\" X/OPEN does not document EFAULT, ENOMEM or EIO. .SH BUGS On NFS file systems, the return code may be wrong in case the NFS server -performs the link creation and dies before it can say so. Use +performs the link creation and dies before it can say so. +Use .BR stat (2) to find out if the link got created. .SH "SEE ALSO" diff --git a/man2/linkat.2 b/man2/linkat.2 index ce3db2f98..b48ca3950 100644 --- a/man2/linkat.2 +++ b/man2/linkat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,7 +31,7 @@ linkat \- create a file link relative to directory file descriptors .B #define _ATFILE_SOURCE .B #include .sp -.BI "int linkat(int " olddirfd ", const char *" oldpath , +.BI "int linkat(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath ", int " flags ); .fi .SH DESCRIPTION @@ -41,51 +41,51 @@ system call operates in exactly the same way as .BR link (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I oldpath is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR olddirfd -(rather than relative to the current working directory of +.IR olddirfd +(rather than relative to the current working directory of the calling process, as is done by .BR link (2) for a relative pathname). If .I oldpath -is relative and +is relative and .I olddirfd is the special value .BR AT_FDCWD , then .I oldpath -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR link (2)). If .IR oldpath -is absolute, then -.I olddirfd +is absolute, then +.I olddirfd is ignored. The interpretation of .I newpath -is as for -.IR oldpath , +is as for +.IR oldpath , except that a relative pathname is interpreted relative to the directory referred to by the file descriptor .IR newdirfd . By default, .BR linkat (2), -does not dereference +does not dereference .I oldpath -if it is a symbolic link (like +if it is a symbolic link (like .BR link (2)). Since Linux 2.6.18, the flag .B AT_SYMLINK_FOLLOW -can be specified +can be specified .I flags to cause .I oldpath @@ -95,8 +95,8 @@ Before kernel 2.6.18, the argument was unused, and had to be specified as 0. .SH "RETURN VALUE" On success, -.BR linkat () -returns 0. +.BR linkat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -105,7 +105,7 @@ The same errors that occur for .BR link (2) can also occur for .BR linkat (). -The following additional errors can occur for +The following additional errors can occur for .BR linkat (): .TP .B EBADF diff --git a/man2/listen.2 b/man2/listen.2 index 784cbbaa0..d1aacc918 100644 --- a/man2/listen.2 +++ b/man2/listen.2 @@ -35,7 +35,7 @@ .\" Modified 950727 by aeb, following a suggestion by Urs Thuermann .\" .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond -.\" Modified 1998 by Andi Kleen +.\" Modified 1998 by Andi Kleen .\" Modified 11 May 2001 by Sam Varshavchik .\" .TH LISTEN 2 1993-07-23 "BSD Man Page" "Linux Programmer's Manual" @@ -64,29 +64,32 @@ or The .I backlog parameter defines the maximum length the queue of pending connections may -grow to. If a connection request arrives with the queue full the client +grow to. +If a connection request arrives with the queue full the client may receive an error with an indication of .B ECONNREFUSED or, if the underlying protocol supports retransmission, the request may be ignored so that retries succeed. .SH NOTES -The behaviour of the -.I backlog +The behaviour of the +.I backlog parameter on TCP sockets changed with Linux 2.2. -Now it specifies the queue length for -.I completely +Now it specifies the queue length for +.I completely established sockets waiting to be accepted, instead of the number of incomplete -connection requests. The maximum length of the queue for incomplete sockets -can be set using the +connection requests. +The maximum length of the queue for incomplete sockets +can be set using the .B tcp_max_syn_backlog sysctl. -When syncookies are enabled there is no logical maximum +When syncookies are enabled there is no logical maximum length and this sysctl setting is ignored. -See +See .BR tcp (7) for more information. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -112,18 +115,18 @@ operation. 4.4BSD, POSIX.1-2001. The .BR listen () -function call first appeared in 4.2BSD. +function call first appeared in 4.2BSD. .SH BUGS -If the socket is of type -.BR AF_INET , +If the socket is of type +.BR AF_INET , and the .I backlog argument is greater -than the constant -.B SOMAXCONN +than the constant +.B SOMAXCONN (128 in Linux 2.0 & 2.2), it is silently truncated -to -.BR SOMAXCONN . +to +.BR SOMAXCONN . .\" The following is now rather historic information (MTK, Jun 05) .\" Don't rely on this value in portable applications since BSD .\" (and some BSD-derived systems) limit the backlog to 5. diff --git a/man2/listxattr.2 b/man2/listxattr.2 index 7d50246a5..78e78c2d8 100644 --- a/man2/listxattr.2 +++ b/man2/listxattr.2 @@ -64,7 +64,7 @@ The length of the attribute name is returned. .PP .BR llistxattr () -is identical to +is identical to .BR listxattr (), except in the case of a symbolic link, where the list of names of extended attributes associated with the link itself is retrieved, diff --git a/man2/llseek.2 b/man2/llseek.2 index 685a4c095..02354198a 100644 --- a/man2/llseek.2 +++ b/man2/llseek.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,12 +33,12 @@ _llseek \- reposition read/write file offset .B #include .B #include .sp -.B _syscall5(int, _llseek, unsigned int, fd, unsigned long, hi, +.B _syscall5(int, _llseek, unsigned int, fd, unsigned long, hi, .B " " unsigned long, lo, loff_t *, res, unsigned int, wh) /* Using \fBsyscall\fP(2) may be preferable; see \fBintro\fP(2) */ .sp .BI "int _llseek(unsigned int " fd ", unsigned long " offset_high , -.BI " unsigned long " offset_low ", loff_t *" result , +.BI " unsigned long " offset_low ", loff_t *" result , .BI " unsigned int " whence ); .fi .SH DESCRIPTION @@ -83,4 +83,4 @@ This function is Linux specific, and should not be used in programs intended to be portable. .SH "SEE ALSO" .BR lseek (2), -.BR lseek64 (3) +.BR lseek64 (3) diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 index 4495ee59f..89582eae8 100644 --- a/man2/lookup_dcookie.2 +++ b/man2/lookup_dcookie.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,13 +34,13 @@ lookup_dcookie \- return a directory entry's path Look up the full path of the directory entry specified by the value .I cookie . -The cookie is an opaque identifier uniquely identifying a particular directory -entry. The buffer given is filled in with the full path of the directory -entry. +The cookie is an opaque identifier uniquely identifying a particular +directory entry. +The buffer given is filled in with the full path of the directory entry. For .BR lookup_dcookie () -to return successfully, +to return successfully, the kernel must still hold a cookie reference to the directory entry. .SH "NOTES" .BR lookup_dcookie () @@ -73,7 +73,7 @@ The kernel could not allocate memory for the temporary buffer holding the path. .TP .B EPERM -The process does not have the capability +The process does not have the capability .B CAP_SYS_ADMIN required to look up cookie values. .TP diff --git a/man2/lseek.2 b/man2/lseek.2 index c3a1c48a3..a360f69cc 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -81,13 +81,13 @@ The function allows the file offset to be set beyond the end of the file (but this does not change the size of the file). If data is later written at this point, subsequent reads of the data -in the gap (a "hole") return null bytes ('\\0') until +in the gap (a "hole") return null bytes ('\\0') until data is actually written into the gap. .SH "RETURN VALUE" Upon successful completion, .BR lseek () returns the resulting offset location as measured in bytes from the -beginning of the file. +beginning of the file. Otherwise, a value of \fI(off_t)\-1\fP is returned and .I errno is set to indicate the error. @@ -107,7 +107,7 @@ or beyond the end of a seekable device. .TP .B EOVERFLOW .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) -The resulting file offset cannot be represented in an +The resulting file offset cannot be represented in an .IR off_t . .TP .B ESPIPE @@ -117,7 +117,7 @@ is associated with a pipe, socket, or FIFO. SVr4, 4.3BSD, POSIX.1-2001. .SH RESTRICTIONS Some devices are incapable of seeking and POSIX does not specify which -devices must support +devices must support .BR lseek (). Linux specific restrictions: using \fBlseek\fP() on a tty device returns @@ -157,4 +157,4 @@ subject to race conditions. .BR open (2), .BR fseek (3), .BR lseek64 (3), -.BR posix_fallocate (3) +.BR posix_fallocate (3) diff --git a/man2/madvise.2 b/man2/madvise.2 index d80c9808b..c08e0d824 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,21 +49,24 @@ the address range beginning at address .I start and with size .I length -bytes. It allows an application to tell the kernel how it expects to use +bytes. +It allows an application to tell the kernel how it expects to use some mapped or shared memory areas, so that the kernel can choose appropriate read-ahead and caching techniques. -This call does not influence the semantics of the application +This call does not influence the semantics of the application (except in the case of .BR MADV_DONTNEED ), but -may influence its performance. The kernel is free to ignore the advice. +may influence its performance. +The kernel is free to ignore the advice. .LP -The advice is indicated in the +The advice is indicated in the .I advice parameter which can be .TP .B MADV_NORMAL -No special treatment. This is the default. +No special treatment. +This is the default. .TP .B MADV_RANDOM Expect page references in random order. @@ -89,13 +92,13 @@ without an underlying file. .TP .BR MADV_REMOVE " (Since Linux 2.6.16)" Free up a given range of pages -and its associated backing store. +and its associated backing store. Currently, .\" 2.6.18-rc5 -only shmfs/tmpfs supports this; other filesystems return -ENOSYS. -.\" Databases want to use this feature to drop a section of their -.\" bufferpool (shared memory segments) - without writing back to -.\" disk/swap space. This feature is also useful for supporting +only shmfs/tmpfs supports this; other filesystems return -ENOSYS. +.\" Databases want to use this feature to drop a section of their +.\" bufferpool (shared memory segments) - without writing back to +.\" disk/swap space. This feature is also useful for supporting .\" hot-plug memory on UML. .TP .BR MADV_DONTFORK " (Since Linux 2.6.16)" @@ -108,22 +111,22 @@ the physical location of a pagei(s) if the parent writes to it after a (Such page relocations cause problems for hardware that DMAs into the page(s).) .\" [PATCH] madvise MADV_DONTFORK/MADV_DOFORK -.\" Currently, copy-on-write may change the physical address of -.\" a page even if the user requested that the page is pinned in -.\" memory (either by mlock or by get_user_pages). This happens -.\" if the process forks meanwhile, and the parent writes to that -.\" page. As a result, the page is orphaned: in case of -.\" get_user_pages, the application will never see any data hardware -.\" DMA's into this page after the COW. In case of mlock'd memory, +.\" Currently, copy-on-write may change the physical address of +.\" a page even if the user requested that the page is pinned in +.\" memory (either by mlock or by get_user_pages). This happens +.\" if the process forks meanwhile, and the parent writes to that +.\" page. As a result, the page is orphaned: in case of +.\" get_user_pages, the application will never see any data hardware +.\" DMA's into this page after the COW. In case of mlock'd memory, .\" the parent is not getting the realtime/security benefits of mlock. -.\" -.\" In particular, this affects the Infiniband modules which do DMA from +.\" +.\" In particular, this affects the Infiniband modules which do DMA from .\" and into user pages all the time. -.\" -.\" This patch adds madvise options to control whether memory range is -.\" inherited across fork. Useful e.g. for when hardware is doing DMA -.\" from/into these pages. Could also be useful to an application -.\" wanting to speed up its forks by cutting large areas out of +.\" +.\" This patch adds madvise options to control whether memory range is +.\" inherited across fork. Useful e.g. for when hardware is doing DMA +.\" from/into these pages. Could also be useful to an application +.\" wanting to speed up its forks by cutting large areas out of .\" consideration. .TP .BR MADV_DOFORK " (Since Linux 2.6.16)" @@ -132,9 +135,10 @@ Undo the effect of restoring the default behaviour, whereby a mapping is inherited across .BR fork (2). .SH "RETURN VALUE" -On success +On success .BR madvise () -returns zero. On error, it returns \-1 and +returns zero. +On error, it returns \-1 and .I errno is set appropriately. .SH ERRORS @@ -146,14 +150,14 @@ A kernel resource was temporarily unavailable. The map exists, but the area maps something that isn't a file. .TP .B EINVAL -The value +The value .IR len is negative, .\" .I len .\" is zero, .I start is not page-aligned, -.I advice +.I advice is not a valid value, or the application is attempting to release locked or shared pages (with MADV_DONTNEED). .TP @@ -179,10 +183,11 @@ The Linux implementation requires that the address .I start be page-aligned, and allows .I length -to be zero. If there are some parts of the specified address range +to be zero. +If there are some parts of the specified address range that are not mapped, the Linux version of .BR madvise () -ignores them and applies the call to the rest (but returns +ignores them and applies the call to the rest (but returns .B ENOMEM from the system call, as it should). .SH HISTORY @@ -194,7 +199,7 @@ POSIX.1b. POSIX.1-2001 describes .BR posix_madvise () with constants POSIX_MADV_NORMAL, etc., -with a behaviour close to that described here. +with a behaviour close to that described here. There is a similar .BR posix_fadvise () for file access. diff --git a/man2/mbind.2 b/man2/mbind.2 index 2ecc6045d..3e309ebd6 100644 --- a/man2/mbind.2 +++ b/man2/mbind.2 @@ -8,15 +8,15 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. -.\" +.\" .\" 2006-02-03, mtk, substantial wording changes and other improvements .\" .TH MBIND 2 "2006-02-07" "SuSE Labs" "Linux Programmer's Manual" @@ -26,41 +26,41 @@ mbind \- Set memory policy for a memory range .nf .B "#include " .sp -.BI "int mbind(void *" start ", unsigned long " len ", int " policy , -.BI " unsigned long *" nodemask ", unsigned long " maxnode , +.BI "int mbind(void *" start ", unsigned long " len ", int " policy , +.BI " unsigned long *" nodemask ", unsigned long " maxnode , .BI " unsigned " flags ); .sp .BI "cc ... -lnuma" .fi .SH DESCRIPTION .BR mbind () -sets the NUMA memory -.I policy +sets the NUMA memory +.I policy for the memory range starting with .I start and continuing for -.IR len -bytes. +.IR len +bytes. The memory of a NUMA machine is divided into multiple nodes. -The memory policy defines in which node memory is allocated. +The memory policy defines in which node memory is allocated. .BR mbind () -only has an effect for new allocations; if the pages inside +only has an effect for new allocations; if the pages inside the range have been already touched before setting the policy, then the policy has no effect. -Available policies are +Available policies are .BR MPOL_DEFAULT , .BR MPOL_BIND , .BR MPOL_INTERLEAVE , and .BR MPOL_PREFERRED . -All policies except +All policies except .B MPOL_DEFAULT require the caller to specify the nodes to which the policy applies in the -.I nodemask +.I nodemask parameter. -.I nodemask -is a bitmask of nodes containing up to +.I nodemask +is a bitmask of nodes containing up to .I maxnode bits. The actual number of bytes transferred via this argument @@ -68,46 +68,46 @@ is rounded up to the next multiple of .IR "sizeof(unsigned long)" , but the kernel will only use bits up to .IR maxnode . -A NULL argument means an empty set of nodes. +A NULL argument means an empty set of nodes. -The +The .B MPOL_DEFAULT policy is the default and means to use the underlying process policy (which can be modified with -.BR set_mempolicy (2)). +.BR set_mempolicy (2)). Unless the process policy has been changed this means to allocate -memory on the node of the CPU that triggered the allocation. -.I nodemask +memory on the node of the CPU that triggered the allocation. +.I nodemask should be specified as NULL. The .B MPOL_BIND -policy is a strict policy that restricts memory allocation to the -nodes specified in +policy is a strict policy that restricts memory allocation to the +nodes specified in .IR nodemask . There won't be allocations on other nodes. .B MPOL_INTERLEAVE -interleaves allocations to the nodes specified in +interleaves allocations to the nodes specified in .IR nodemask . This optimizes for bandwidth instead of latency. -To be effective the memory area should be fairly large, +To be effective the memory area should be fairly large, at least 1MB or bigger. .B MPOL_PREFERRED -sets the preferred node for allocation. +sets the preferred node for allocation. The kernel will try to allocate in this -node first and fall back to other nodes if the -preferred nodes is low on free memory. -Only the first node in the -.I nodemask -is used. -If no node is set in the mask, then the memory is allocated on +node first and fall back to other nodes if the +preferred nodes is low on free memory. +Only the first node in the +.I nodemask +is used. +If no node is set in the mask, then the memory is allocated on the node of the CPU that triggered the allocation allocation). If .B MPOL_MF_STRICT -is passed in +is passed in .IR flags and .I policy @@ -120,64 +120,64 @@ In 2.6.16 or later the kernel will also try to move pages to the requested node with this flag. If -.B MPOL_MF_MOVE -is passed in +.B MPOL_MF_MOVE +is passed in .IR flags , then an attempt will be made to -move all the pages in the mapping so that they follow the policy. -Pages that are shared with other processes are not moved. -If +move all the pages in the mapping so that they follow the policy. +Pages that are shared with other processes are not moved. +If .B MPOL_MF_STRICT is also specified, then the call will fail with the error -.B EIO +.B EIO if some pages could not be moved. If -.B MPOL_MF_MOVE_ALL -is passed in -.IR flags , -then all pages in the mapping will be moved regardless of whether +.B MPOL_MF_MOVE_ALL +is passed in +.IR flags , +then all pages in the mapping will be moved regardless of whether other processes use the pages. The calling process must be privileged .RB ( CAP_SYS_NICE ) to use this flag. -If +If .B MPOL_MF_STRICT is also specified, then the call will fail with the error -.B EIO +.B EIO if some pages could not be moved. .SH RETURN VALUE On success, .BR mbind () returns 0; on error, \-1 is returned and -.I errno +.I errno is set to indicate the error. .SH ERRORS -.TP +.TP .B EFAULT There was a unmapped hole in the specified memory range or a passed pointer was not valid. -.TP +.TP .B EINVAL An invalid value was specified for .I flags or .IR mode ; -or +or .I start + len -was less than +was less than .IR start ; or .I policy -was +was .B MPOL_DEFAULT and .I nodemask pointed to a non-empty set; or .I policy -was +was .B MPOL_BIND or .B MPOL_INTERLEAVE @@ -188,9 +188,9 @@ pointed to an empty set, .B ENOMEM System out of memory. .TP -.B EIO +.B EIO .B MPOL_MF_STRICT -was specified and an existing page was already on a node +was specified and an existing page was already on a node that does not follow the policy. .SH NOTES NUMA policy is not supported on file mappings. @@ -200,21 +200,21 @@ is ignored on huge page mappings right now. It is unfortunate that the same flag, .BR MPOL_DEFAULT , -has different effects for +has different effects for .BR mbind (2) and .BR set_mempolicy (2). -To select "allocation on the node of the CPU that +To select "allocation on the node of the CPU that triggered the allocation" (like .BR set_mempolicy () .BR MPOL_DEFAULT ) -when calling +when calling .BR mbind (), -specify a -.I policy -of +specify a +.I policy +of .B MPOL_PREFERRED -with an empty +with an empty .IR nodemask . .SH "VERSIONS AND LIBRARY SUPPORT" The @@ -222,12 +222,12 @@ The .BR get_mempolicy (), and .BR set_mempolicy () -system calls were added to the Linux kernel with version 2.6.7. -They are only available on kernels compiled with +system calls were added to the Linux kernel with version 2.6.7. +They are only available on kernels compiled with .BR CONFIG_NUMA . Support for huge page policy was added with 2.6.16. -For interleave policy to be effective on huge page mappings the +For interleave policy to be effective on huge page mappings the policied memory needs to be tens of megabytes or larger. .B MPOL_MF_MOVE @@ -236,31 +236,31 @@ and are only available on Linux 2.6.16 and later. These system calls should not be used directly. -Instead, the higher level interface provided by the +Instead, the higher level interface provided by the .BR numa (3) -functions in the -.I numactl +functions in the +.I numactl package is recommended. The .I numactl package is available at .IR ftp://ftp.suse.com/pub/people/ak/numa/ . -You can link with +You can link with .I -lnuma -to get system call definitions. -.I libnuma -is available in the +to get system call definitions. +.I libnuma +is available in the .I numactl -package. -This package also has the +package. +This package also has the .I numaif.h header. .SH CONFORMING TO This system call is Linux specific. .SH SEE ALSO -.BR numa (3), -.BR numactl (8), +.BR numa (3), +.BR numactl (8), .BR set_mempolicy (2), -.BR get_mempolicy (2), +.BR get_mempolicy (2), .BR mmap (2) diff --git a/man2/mincore.2 b/man2/mincore.2 index 275adac7f..812332034 100644 --- a/man2/mincore.2 +++ b/man2/mincore.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,13 +42,13 @@ mincore \- determine whether pages are resident in memory .BI "int mincore(void *" start ", size_t " length ", unsigned char *" vec ); .SH DESCRIPTION .BR mincore () -returns a vector that indicates whether pages -of the calling process's virtual memory are resident in core (RAM), +returns a vector that indicates whether pages +of the calling process's virtual memory are resident in core (RAM), and so will not cause a disk access (page fault) if referenced. The kernel returns residency information about the pages starting at the address .IR start , -and continuing for +and continuing for .I length bytes. @@ -57,7 +57,7 @@ The argument must be a multiple of the system page size. The .I length -argument need not be a multiple of the page size, +argument need not be a multiple of the page size, but since residency information is returned for whole pages, .I length is effectively rounded up to the next multiple of the page size. @@ -68,9 +68,9 @@ The .I vec argument must point to an array containing at least (length+PAGE_SIZE-1) / PAGE_SIZE bytes. -On return, -the least significant bit of each byte will be set if -the corresponding page is currently resident in memory, +On return, +the least significant bit of each byte will be set if +the corresponding page is currently resident in memory, and be clear otherwise. (The settings of the other bits in each byte are undefined; these bits are reserved for possible later use.) @@ -121,8 +121,8 @@ contained unmapped memory. .SH BUGS Before kernel 2.6.21, .BR mincore () -did not return correct information for -.B MAP_PRIVATE +did not return correct information for +.B MAP_PRIVATE mappings, or for non-linear mappings (established using .BR remap_file_pages (2)). .\" Linux (up to now, 2.6.5), @@ -143,8 +143,8 @@ mappings, or for non-linear mappings (established using .SH "CONFORMING TO" .BR mincore () is not specified in POSIX.1-2001, -and it is not available on all Unix implementations. -.\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8, +and it is not available on all Unix implementations. +.\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8, .\" AIX 5.1, SunOS 4.1 .SH HISTORY The diff --git a/man2/mkdir.2 b/man2/mkdir.2 index b867a839f..dbcfb6c71 100644 --- a/man2/mkdir.2 +++ b/man2/mkdir.2 @@ -24,7 +24,8 @@ attempts to create a directory named The parameter .I mode -specifies the permissions to use. It is modified by the process's +specifies the permissions to use. +It is modified by the process's .I umask in the usual way: the permissions of the created directory are .RI ( mode " & ~" umask " & 0777)." @@ -32,7 +33,8 @@ Other mode bits of the created directory depend on the operating system. For Linux, see below. The newly created directory will be owned by the effective user ID of the -process. If the directory containing the file has the set-group-ID +process. +If the directory containing the file has the set-group-ID bit set, or if the filesystem is mounted with BSD group semantics, the new directory will inherit the group ownership from its parent; otherwise it will be owned by the effective group ID of the process. @@ -106,13 +108,14 @@ SVr4, BSD, POSIX.1-2001. .\" SVr4 documents additional EIO, EMULTIHOP .SH NOTES Under Linux apart from the permission bits, only the S_ISVTX mode bit -is honored. That is, under Linux the created directory actually gets mode +is honored. +That is, under Linux the created directory actually gets mode .RI ( mode " & ~" umask " & 01777)." See also .BR stat (2). .PP -There are many infelicities in the protocol underlying NFS. Some -of these affect +There are many infelicities in the protocol underlying NFS. +Some of these affect .BR mkdir (). .SH "SEE ALSO" .BR mkdir (1), diff --git a/man2/mkdirat.2 b/man2/mkdirat.2 index 7fa0364f4..ab665b264 100644 --- a/man2/mkdirat.2 +++ b/man2/mkdirat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,37 +40,37 @@ system call operates in exactly the same way as .BR mkdir (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR mkdir (2) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR mkdir (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .SH "RETURN VALUE" On success, -.BR mkdirat () -returns 0. +.BR mkdirat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -79,7 +79,7 @@ The same errors that occur for .BR mkdir (2) can also occur for .BR mkdirat (). -The following additional errors can occur for +The following additional errors can occur for .BR mkdirat (): .TP .B EBADF diff --git a/man2/mknod.2 b/man2/mknod.2 index 21318f025..c80d405e9 100644 --- a/man2/mknod.2 +++ b/man2/mknod.2 @@ -70,7 +70,8 @@ If already exists, or is a symbolic link, this call fails with an EEXIST error. The newly created node will be owned by the effective user ID of the -process. If the directory containing the node has the set-group-ID +process. +If the directory containing the node has the set-group-ID bit set, or if the filesystem is mounted with BSD group semantics, the new node will inherit the group ownership from its parent directory; otherwise it will be owned by the effective group ID of the process. @@ -144,14 +145,15 @@ does not support the type of node requested. .I pathname refers to a file on a read-only filesystem. .SH "CONFORMING TO" -SVr4, 4.4BSD, POSIX.1-2001 (but see below). +SVr4, 4.4BSD, POSIX.1-2001 (but see below). .\" The Linux version differs from the SVr4 version in that it .\" does not require root permission to create pipes, also in that no .\" EMULTIHOP, ENOLINK, or EINTR error is documented. .SH NOTES POSIX.1-2001 says: "The only portable use of .BR mknod () -is to create a FIFO-special file. If +is to create a FIFO-special file. +If .I mode is not S_IFIFO or .I dev @@ -166,8 +168,8 @@ and FIFOs with .BR mkfifo (2). .\" Unix domain sockets with .BR socket " (and " bind ), -There are many infelicities in the protocol underlying NFS. Some -of these affect +There are many infelicities in the protocol underlying NFS. +Some of these affect .BR mknod (). .SH "SEE ALSO" .BR fcntl (2), diff --git a/man2/mknodat.2 b/man2/mknodat.2 index 252053c06..8e3bee224 100644 --- a/man2/mknodat.2 +++ b/man2/mknodat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,14 +18,14 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" .TH MKNODAT 2 2006-04-06 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME -mknodat \- create a special or ordinary file relative to a directory +mknodat \- create a special or ordinary file relative to a directory file descriptor .SH SYNOPSIS .nf @@ -42,37 +42,37 @@ system call operates in exactly the same way as .BR mknod (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR mknod (2) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR mknod (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .SH "RETURN VALUE" On success, -.BR mknodat () -returns 0. +.BR mknodat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -81,7 +81,7 @@ The same errors that occur for .BR mknod (2) can also occur for .BR mknodat (). -The following additional errors can occur for +The following additional errors can occur for .BR mknodat (): .TP .B EBADF diff --git a/man2/mlock.2 b/man2/mlock.2 index 133ac0c47..0bb77df9c 100644 --- a/man2/mlock.2 +++ b/man2/mlock.2 @@ -44,7 +44,7 @@ mlock, munlock, mlockall, munlockall \- lock and unlock memory and .BR mlockall () respectively lock part or all of the calling process's virtual address -space into RAM, preventing that memory from being paged to the +space into RAM, preventing that memory from being paged to the swap area. .BR munlock () and @@ -61,7 +61,7 @@ locks pages in the address range starting at and continuing for .I len bytes. -All pages that contain a part of the specified address range are +All pages that contain a part of the specified address range are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked. @@ -76,9 +76,11 @@ memory range can be moved to external swap space again by the kernel. .SS "mlockall() and munlockall()" .BR mlockall () locks all pages mapped into the address space of the -calling process. This includes the pages of the code, data and stack +calling process. +This includes the pages of the code, data and stack segment, as well as shared libraries, user space kernel data, shared -memory, and memory\-mapped files. All mapped pages are guaranteed +memory, and memory\-mapped files. +All mapped pages are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked. @@ -93,7 +95,8 @@ the process. .TP .B MCL_FUTURE Lock all pages which will become mapped into the address space of the -process in the future. These could be for instance new pages required +process in the future. +These could be for instance new pages required by a growing heap and stack as well as new memory mapped files or shared memory regions. .PP @@ -107,7 +110,7 @@ may fail if it would cause the number of locked bytes to exceed the permitted maximum (see below). In the same circumstances, stack growth may likewise fail: the kernel will deny stack expansion and deliver a -.BR SIGSEGV +.BR SIGSEGV signal to the process. .BR munlockall () @@ -115,13 +118,16 @@ unlocks all pages mapped into the address space of the calling process. .SH "NOTES" Memory locking has two main applications: real-time algorithms and -high-security data processing. Real-time applications require +high-security data processing. +Real-time applications require deterministic timing, and, like scheduling, paging is one major cause -of unexpected program execution delays. Real-time applications will +of unexpected program execution delays. +Real-time applications will usually also switch to a real-time scheduler with .BR sched_setscheduler (2). Cryptographic security software often handles critical bytes like -passwords or secret keys as data structures. As a result of paging, +passwords or secret keys as data structures. +As a result of paging, these secrets could be transferred onto a persistent swap store medium, where they might be accessible to the enemy long after the security software has erased the secrets in RAM and terminated. @@ -134,11 +140,12 @@ Real-time processes that are using to prevent delays on page faults should reserve enough locked stack pages before entering the time-critical section, so that no page fault can be caused by function calls. -This can be achieved by calling a function that allocates a -sufficiently large automatic variable (an array) and writes to the -memory occupied by this array in order to touch these stack pages. +This can be achieved by calling a function that allocates a +sufficiently large automatic variable (an array) and writes to the +memory occupied by this array in order to touch these stack pages. This way, enough pages will be mapped for the stack and can be -locked into RAM. The dummy writes ensure that not even copy-on-write +locked into RAM. +The dummy writes ensure that not even copy-on-write page faults can occur in the critical section. Memory locks are not inherited by a child created via @@ -208,7 +215,7 @@ This limit is not enforced if the process is privileged half of RAM. .\" In the case of mlock(), this check is somewhat buggy: it doesn't .\" take into account whether the to-be-locked range overlaps with -.\" already locked pages. Thus, suppose we allocate +.\" already locked pages. Thus, suppose we allocate .\" (num_physpages / 4 + 1) of memory, and lock those pages once using .\" mlock(), and then lock the *same* page range a second time. .\" In the case, the second mlock() call will fail, since the check @@ -218,13 +225,13 @@ half of RAM. .B EPERM (Linux 2.6.9 and later) the caller was not privileged .RB ( CAP_IPC_LOCK ) -and its +and its .B RLIMIT_MEMLOCK soft resource limit was 0. .TP .B EPERM (Linux 2.6.8 and earlier) -The calling process has insufficient privilege to call +The calling process has insufficient privilege to call .BR munlockall (). Under Linux the .B CAP_IPC_LOCK @@ -270,17 +277,17 @@ flag to be inherited across a .BR fork (2). This was rectified in kernel 2.4.18. -Since kernel 2.6.9, if a privileged process calls +Since kernel 2.6.9, if a privileged process calls .I mlockall(MCL_FUTURE) -and later drops privileges (loses the -.B CAP_IPC_LOCK -capability by, for example, -setting its effective UID to a non-zero value), -then subsequent memory allocations (e.g., +and later drops privileges (loses the +.B CAP_IPC_LOCK +capability by, for example, +setting its effective UID to a non-zero value), +then subsequent memory allocations (e.g., .BR mmap (2), .BR brk (2)) -will fail if the -.B RLIMIT_MEMLOCK +will fail if the +.B RLIMIT_MEMLOCK resource limit is encountered. .\" See the following LKML thread: .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2 @@ -293,8 +300,8 @@ and .BR munlock () are available, .B _POSIX_MEMLOCK_RANGE -is defined in and the number of bytes in a page -can be determined from the constant +is defined in and the number of bytes in a page +can be determined from the constant .B PAGESIZE (if defined) in or by calling .IR sysconf(_SC_PAGESIZE) . diff --git a/man2/mmap.2 b/man2/mmap.2 index d99cb1b04..be3f49110 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,7 +50,7 @@ mmap, munmap \- map or unmap files or devices into memory .fi .SH DESCRIPTION .BR mmap () -creates a new mapping in the virtual address space of +creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in .IR start . @@ -63,8 +63,8 @@ If is NULL, then the kernel chooses the address at which to create the mapping; this is the most portable method of creating a new mapping. -If -.I start +If +.I start is not NULL, then the kernel takes it as a hint about where to place the mapping; on Linux, the mapping will be created at the next higher page boundary. @@ -72,7 +72,7 @@ The address of the new mapping is returned as the result of the call. The contents of a file mapping (as opposed to an anonymous mapping; see .B MAP_ANONYMOUS -below), are initialised using +below), are initialised using .I length bytes starting at offset .I offset @@ -84,7 +84,7 @@ must be a multiple of the page size as returned by .LP The .I prot -argument describes the desired memory protection of the mapping +argument describes the desired memory protection of the mapping (and must not conflict with the open mode of the file). It is either .B PROT_NONE @@ -107,12 +107,12 @@ The argument determines whether updates to the mapping are visible to other processes mapping the same region, and whether updates are caried through to the underlying file. -This behaviour is determined by including exactly one +This behaviour is determined by including exactly one of the following values in .IR flags : .TP 1.1i .B MAP_SHARED -Share this mapping. +Share this mapping. Updates to the mapping are visible to other processes that map this file, and are carried through to the underlying file. The file may not actually be updated until @@ -158,8 +158,8 @@ the use of this option is discouraged. This flag is ignored. .\" Introduced in 1.1.36, removed in 1.3.24. (Long ago, it signalled that attempts to write to the underlying file -should fail with -.BR ETXTBUSY . +should fail with +.BR ETXTBUSY . But this was a source of denial-of-service attacks.) .TP .B MAP_EXECUTABLE @@ -171,16 +171,16 @@ This flag is ignored. .\" MAP_DENYWRITE? .TP .B MAP_NORESERVE -Do not reserve swap space for this mapping. +Do not reserve swap space for this mapping. When swap space is reserved, one has the guarantee that it is possible to modify the mapping. When swap space is not reserved one might get SIGSEGV upon a write if no physical memory is available. See also the discussion of the file .I /proc/sys/vm/overcommit_memory -in +in .BR proc (5). -In kernels before 2.6, this flag only had effect for +In kernels before 2.6, this flag only had effect for private writable mappings. .TP .BR MAP_LOCKED " (since Linux 2.5.37)" @@ -190,13 +190,13 @@ This flag is ignored in older kernels. .\" If set, the mapped pages will not be swapped out. .TP .B MAP_GROWSDOWN -Used for stacks. +Used for stacks. Indicates to the kernel virtual memory system that the mapping should extend downwards in memory. .TP .B MAP_ANON -Synonym for -.BR MAP_ANONYMOUS . +Synonym for +.BR MAP_ANONYMOUS . Deprecated. .TP .B MAP_ANONYMOUS @@ -207,40 +207,41 @@ The and .I offset arguments are ignored; -however, some implementations require +however, some implementations require .I fd -to be \-1 if -.B MAP_ANONYMOUS -(or -.BR MAP_ANON ) +to be \-1 if +.B MAP_ANONYMOUS +(or +.BR MAP_ANON ) is specified, and portable applications should ensure this. -The use of +The use of .B MAP_ANONYMOUS -in conjunction with +in conjunction with .B MAP_SHARED is only supported on Linux since kernel 2.4. .TP .B MAP_FILE -Compatibility flag. Ignored. +Compatibility flag. +Ignored. .TP .B MAP_32BIT Put the mapping into the first 2GB of the process address space. Ignored when .B MAP_FIXED -is set. +is set. This flag is currently only supported on x86-64 for 64bit programs. .TP .BR MAP_POPULATE " (since Linux 2.5.46)" -Populate (prefault) page tables for a file mapping, +Populate (prefault) page tables for a file mapping, by performing read-ahead on the file. Later accesses to the mapping will not be blocked by page faults. .TP .BR MAP_NONBLOCK " (since Linux 2.5.46)" Only meaningful in conjunction with .BR MAP_POPULATE . -Don't perform read-ahead: -only create page tables entries for pages +Don't perform read-ahead: +only create page tables entries for pages that are already present in RAM. .LP Of the above flags, only @@ -248,7 +249,7 @@ Of the above flags, only is specified in POSIX.1-2001. However, most systems also support .B MAP_ANONYMOUS -(or its synonym +(or its synonym .BR MAP_ANON ). .LP Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV, @@ -260,9 +261,11 @@ is preserved across .BR fork (2), with the same attributes. .LP -A file is mapped in multiples of the page size. For a file that is not +A file is mapped in multiples of the page size. +For a file that is not a multiple of the page size, the remaining memory is zeroed when mapped, -and writes to that region are not written out to the file. The effect of +and writes to that region are not written out to the file. +The effect of changing the size of the underlying file of a mapping on the pages that correspond to added or removed regions of the file is unspecified. @@ -270,15 +273,19 @@ The .BR munmap () system call deletes the mappings for the specified address range, and causes further references to addresses within the range to generate -invalid memory references. The region is also automatically unmapped -when the process is terminated. On the other hand, closing the file +invalid memory references. +The region is also automatically unmapped +when the process is terminated. +On the other hand, closing the file descriptor does not unmap the region. .LP The address .I start -must be a multiple of the page size. All pages containing a part +must be a multiple of the page size. +All pages containing a part of the indicated range are unmapped, and subsequent references -to these pages will generate SIGSEGV. It is not an error if the +to these pages will generate SIGSEGV. +It is not an error if the indicated range does not contain any mapped pages. For file-backed mappings, the @@ -292,17 +299,17 @@ The .I st_ctime and .I st_mtime -field for a file mapped with -.B PROT_WRITE -and -.B MAP_SHARED +field for a file mapped with +.B PROT_WRITE +and +.B MAP_SHARED will be updated after a write to the mapped region, and before a subsequent .BR msync () -with the -.B MS_SYNC -or -.BR MS_ASYNC +with the +.B MS_SYNC +or +.BR MS_ASYNC flag, if one occurs. .SH "RETURN VALUE" On success, @@ -310,7 +317,7 @@ On success, returns a pointer to the mapped area. On error, the value .B MAP_FAILED -(that is, +(that is, .I "(void *) \-1)" is returned, and .I errno @@ -319,14 +326,14 @@ On success, .BR munmap () returns 0, on failure \-1, and .I errno -is set (probably to +is set (probably to .BR EINVAL ). .SH NOTES It is architecture dependent whether .B PROT_READ implies .B PROT_EXEC -or not. +or not. Portable programs should always set .B PROT_EXEC if they intend to execute code in the new mapping. @@ -334,20 +341,20 @@ if they intend to execute code in the new mapping. .TP .B EACCES A file descriptor refers to a non-regular file. -Or -.B MAP_PRIVATE +Or +.B MAP_PRIVATE was requested, but .I fd is not open for reading. -Or -.B MAP_SHARED -was requested and -.B PROT_WRITE +Or +.B MAP_SHARED +was requested and +.B PROT_WRITE is set, but .I fd is not open in read/write (O_RDWR) mode. -Or -.B PROT_WRITE +Or +.B PROT_WRITE is set, but the file is append-only. .TP .B EAGAIN @@ -356,7 +363,7 @@ The file has been locked, or too much memory has been locked (see .TP .B EBADF .I fd -is not a valid file descriptor (and +is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP @@ -407,7 +414,7 @@ was mounted no-exec. .\" (Since 2.4.25 / 2.6.0.) .TP .B ETXTBSY -.B MAP_DENYWRITE +.B MAP_DENYWRITE was set but the object specified by .I fd is open for writing. @@ -439,8 +446,8 @@ SVr4, 4.4BSD, POSIX.1-2001. .\" SVr4 documents additional error codes ENXIO and ENODEV. .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. .SH BUGS -On Linux there are no guarantees like those suggested above under -.BR MAP_NORESERVE . +On Linux there are no guarantees like those suggested above under +.BR MAP_NORESERVE . By default, any process can be killed at any moment when the system runs out of memory. @@ -451,7 +458,7 @@ flag only has effect if is specified as .BR PROT_NONE . -SUSv3 specifies that +SUSv3 specifies that .BR mmap () should fail if .I length diff --git a/man2/mmap2.2 b/man2/mmap2.2 index 8b2cfe958..596ce62bb 100644 --- a/man2/mmap2.2 +++ b/man2/mmap2.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,7 +45,7 @@ mmap2 \- map files or devices into memory .BI " int " flags ", int " fd ", off_t " pgoffset ); .fi .SH DESCRIPTION -The +The .BR mmap2 () system call operates in exactly the same way as .BR mmap (2), @@ -56,9 +56,10 @@ This enables applications that use a 32-bit to map larger files (typically up to 2^44 bytes). .SH "RETURN VALUE" -On success, +On success, .BR mmap2 () -returns a pointer to the mapped area. On error \-1 is returned +returns a pointer to the mapped area. +On error \-1 is returned and .I errno is set appropriately. diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2 index be0c07dfc..acc99c989 100644 --- a/man2/modify_ldt.2 +++ b/man2/modify_ldt.2 @@ -33,7 +33,7 @@ modify_ldt \- get or set ldt .br .B #include .sp -.BI "_syscall3(int, modify_ldt, int, " func ", void *, " ptr , +.BI "_syscall3(int, modify_ldt, int, " func ", void *, " ptr , .BI " unsigned long, " bytecount ) /* Using \fBsyscall\fP(2) may be preferable; see \fBintro\fP(2) */ .sp diff --git a/man2/mount.2 b/man2/mount.2 index 81307897d..14385cb58 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -59,7 +59,7 @@ or a dummy) to the directory specified by .IR target . .BR umount () -and +and .BR umount2 () remove the attachment of the (topmost) filesystem mounted on .IR target . @@ -157,18 +157,19 @@ Mount file system read-only. .\" FIXME Document MS_REC, available since 2.4.11. .\" This flag has meaning in conjunction with MS_BIND and .\" also with the shared sub-tree flags. -.TP +.TP .BR MS_RELATIME "(Since Linux 2.6.20)" When a file on this file system is accessed, only update the file's last accessed time (atime) if the current value -of atime is less than or equal to the file's last modified (mtime) +of atime is less than or equal to the file's last modified (mtime) or last status change time (ctime). This option is useful for programs, such as .BR mutt (1), that need to know when a file has been read since it was last modified. .TP .B MS_REMOUNT -Remount an existing mount. This is allows you to change the +Remount an existing mount. +This is allows you to change the .I mountflags and .I data @@ -183,13 +184,13 @@ call; is ignored. The following -.I mountflags +.I mountflags can be changed: .BR MS_RDONLY , .BR MS_SYNCHRONOUS , .BR MS_MANDLOCK ; before kernel 2.6.16, the following could also be changed: -.BR MS_NOATIME +.BR MS_NOATIME and .BR MS_NODIRATIME ; and, additionally, before kernel 2.4, the following could also be changed: @@ -200,7 +201,7 @@ and, additionally, before kernel 2.4, the following could also be changed: .B MS_SYNCHRONOUS Make writes on this file system synchronous (as though the -.B O_SYNC +.B O_SYNC flag to .BR open (2) was specified for all file opens to this file system). @@ -213,8 +214,8 @@ From kernel 2.6.16 onwards, and .B MS_NODIRATIME are also settable on a per-mount-point basis. -The -.B MS_RELATIME +The +.B MS_RELATIME flag is also settable on a per-mount-point basis. .PP The @@ -238,7 +239,8 @@ unmounts a target, but allows additional controlling the behaviour of the operation: .TP .BR MNT_FORCE " (since Linux 2.1.116)" -Force unmount even if busy. This can cause data loss. +Force unmount even if busy. +This can cause data loss. (Only for NFS mounts.) .\" FIXME Can MNT_FORCE result in data loss? According to .\" the Solaris manual page it can cause data loss on Solaris. @@ -263,24 +265,28 @@ A second call specifying .B MNT_EXPIRE unmounts an expired mount point. -This flag cannot be specified with either +This flag cannot be specified with either .B MNT_FORCE or .BR MNT_DETACH . .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS The error values given below result from filesystem type independent -errors. Each filesystem type may have its own special errors and its -own special behavior. See the kernel source code for details. +errors. +Each filesystem type may have its own special errors and its +own special behavior. +See the kernel source code for details. .TP .B EACCES -A component of a path was not searchable. (See also +A component of a path was not searchable. +(See also .BR path_resolution (2).) Or, mounting a read-only filesystem was attempted without giving the -.B MS_RDONLY +.B MS_RDONLY flag. Or, the block device .I source @@ -299,7 +305,8 @@ successfully marked an unbusy file system as expired. .TP .B EBUSY .I source -is already mounted. Or, it cannot be remounted read-only, +is already mounted. +Or, it cannot be remounted read-only, because it still holds files open for writing. Or, it cannot be mounted on .I target @@ -321,7 +328,7 @@ was attempted, but .I source was not already mounted on .IR target . -Or, a move +Or, a move .RB ( MS_MOVE ) was attempted, but .I source @@ -399,7 +406,7 @@ on a filesystem mounted with .B MS_NOSUID would fail with .BR EPERM . -Since Linux 2.4 the set-user-ID and set-group-ID bits are +Since Linux 2.4 the set-user-ID and set-group-ID bits are just silently ignored in this case. .\" The change is in patch-2.4.0-prerelease. .SH "SEE ALSO" diff --git a/man2/mprotect.2 b/man2/mprotect.2 index 384ac6d62..90f61d313 100644 --- a/man2/mprotect.2 +++ b/man2/mprotect.2 @@ -1,4 +1,4 @@ -.\" -*- nroff -*- +.\" -*- nroff -*- .\" .\" Copyright (C) 1995 Michael Shields . .\" @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and author of this work. .\" @@ -61,21 +61,23 @@ The memory can contain executing code. .\" FIXME .\" Document MAP_GROWSUP and MAP_GROWSDOWN .PP -The new protection replaces any existing protection. For example, if the +The new protection replaces any existing protection. +For example, if the memory had previously been marked \fBPROT_READ\fR, and \fBmprotect\fR() is then called with \fIprot\fR \fBPROT_WRITE\fR, it will no longer be readable. .SH "RETURN VALUE" On success, .BR mprotect () -returns zero. On error, \-1 is returned, and +returns zero. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP .B EACCES -The memory cannot be given the specified access. This can happen, -for example, if you +The memory cannot be given the specified access. +This can happen, for example, if you .BR mmap (2) a file to which you have read-only access, then ask .BR mprotect () @@ -89,7 +91,7 @@ The memory cannot be accessed. \fIaddr\fR is not a valid pointer, or not a multiple of PAGESIZE. .TP .B ENOMEM -Internal kernel structures could not be allocated. +Internal kernel structures could not be allocated. Or: addresses in the range .RI [ addr , .IR addr + len ] diff --git a/man2/mq_getsetattr.2 b/man2/mq_getsetattr.2 index 6cf63425c..c0e4c8561 100644 --- a/man2/mq_getsetattr.2 +++ b/man2/mq_getsetattr.2 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,7 +44,7 @@ This is the low-level system call used to implement .BR mq_getattr (3) and .BR mq_setattr (3). -For an explanation of how this system call operates, +For an explanation of how this system call operates, see the description of .BR mq_setattr (3). .SH CONFORMING TO diff --git a/man2/mremap.2 b/man2/mremap.2 index d03ea5648..47a5ddb34 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -30,7 +30,7 @@ .\" .TH MREMAP 2 2005-09-13 "Linux 2.6.13" "Linux Programmer's Manual" .SH NAME -mremap \- re-map a virtual memory address +mremap \- re-map a virtual memory address .SH SYNOPSIS .nf .B #define _GNU_SOURCE @@ -41,28 +41,33 @@ mremap \- re-map a virtual memory address .BI " size_t " new_size ", int " flags ); .fi .SH DESCRIPTION -\fBmremap\fR() expands (or shrinks) an existing memory mapping, potentially -moving it at the same time (controlled by the \fIflags\fR argument and +\fBmremap\fR() expands (or shrinks) an existing memory mapping, potentially +moving it at the same time (controlled by the \fIflags\fR argument and the available virtual address space). \fIold_address\fR is the old address of the virtual memory block that you -want to expand (or shrink). Note that \fIold_address\fR has to be page -aligned. \fIold_size\fR is the old size of the +want to expand (or shrink). +Note that \fIold_address\fR has to be page +aligned. \fIold_size\fR is the old size of the virtual memory block. \fInew_size\fR is the requested size of the -virtual memory block after the resize. +virtual memory block after the resize. -In Linux the memory is divided into pages. A user process has (one or) -several linear virtual memory segments. Each virtual memory segment has one -or more mappings to real memory pages (in the page table). Each virtual -memory segment has its own protection (access rights), which may cause +In Linux the memory is divided into pages. +A user process has (one or) +several linear virtual memory segments. +Each virtual memory segment has one +or more mappings to real memory pages (in the page table). +Each virtual memory segment has its own +protection (access rights), which may cause a segmentation violation if the memory is accessed incorrectly (e.g., -writing to a read-only segment). Accessing virtual memory outside of the +writing to a read-only segment). +Accessing virtual memory outside of the segments will also cause a segmentation violation. \fBmremap\fR() uses the Linux page table scheme. -\fBmremap\fR() changes the -mapping between virtual addresses and memory pages. This can be used to -implement a very efficient \fBrealloc\fR(). +\fBmremap\fR() changes the +mapping between virtual addresses and memory pages. +This can be used to implement a very efficient \fBrealloc\fR(). The \fIflags\fR bit-mask argument may be 0, or include the following flag: .TP @@ -71,11 +76,11 @@ By default, if there is not sufficient space to expand a mapping at its current location, then .BR mremap () fails. -If this flag is specified, then the kernel is permitted to +If this flag is specified, then the kernel is permitted to relocate the mapping to a new virtual address, if necessary. If the mapping is relocated, -then absolute pointers into the old mapping location -become invalid (offsets relative to the starting address of +then absolute pointers into the old mapping location +become invalid (offsets relative to the starting address of the mapping should be employed). .TP .BR MREMAP_FIXED " (since Linux 2.3.31)" @@ -94,15 +99,15 @@ Any previous mapping at the address range specified by and .I new_size is unmapped. -If +If .B MREMAP_FIXED -is specified, then -.BR MREMAP_MAYMOVE +is specified, then +.BR MREMAP_MAYMOVE must also be specified. .PP -If the memory segment specified by +If the memory segment specified by .I old_address -and +and .I old_size is locked (using .BR mlock () @@ -117,7 +122,7 @@ On error, the value .SH ERRORS .TP .B EAGAIN -The caller tried to expand a memory segment that is locked, +The caller tried to expand a memory segment that is locked, but this was not possible without exceeding the RLIMIT_MEMLOCK resource limit. .TP @@ -130,28 +135,28 @@ whole address space requested, but those mappings are of different types. .TP .B EINVAL An invalid argument was given. -Possible causes are: \fIold_address\fR was not +Possible causes are: \fIold_address\fR was not page aligned; a value other than .B MREMAP_MAYMOVE -or +or .B MREMAP_FIXED was specified in .IR flags ; .I new_size was zero; .I new_size -or +or .I new_address was invalid; or the new address range specified by -.I new_address -and +.I new_address +and .I new_size overlapped the old address range specified by .I old_address and .IR old_size ; -or +or .B MREMAP_FIXED was specified without also specifying .BR MREMAP_MAYMOVE . @@ -159,7 +164,7 @@ was specified without also specifying .B ENOMEM The memory area cannot be expanded at the current virtual address, and the .B MREMAP_MAYMOVE -flag is not set in \fIflags\fP. +flag is not set in \fIflags\fP. Or, there is not enough (virtual) memory available. .SH NOTES Prior to version 2.4, glibc did not expose the definition of @@ -186,6 +191,6 @@ call with completely different semantics. .BR feature_test_macros (7) .P Your favorite OS text book for more information on paged memory. -(\fIModern Operating Systems\fR by Andrew S. Tannenbaum, +(\fIModern Operating Systems\fR by Andrew S. Tannenbaum, \fIInside Linux\fR by Randolf Bentson, \fIThe Design of the UNIX Operating System\fR by Maurice J. Bach.) diff --git a/man2/msgctl.2 b/man2/msgctl.2 index 6af880df7..675ed744c 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -66,11 +66,11 @@ struct msqid_ds { time_t msg_stime; /* Time of last msgsnd() */ time_t msg_rtime; /* Time of last msgrcv() */ time_t msg_ctime; /* Time of last change */ - unsigned long __msg_cbytes; /* Current number of bytes in + unsigned long __msg_cbytes; /* Current number of bytes in queue (non-standard) */ - msgqnum_t msg_qnum; /* Current number of messages + msgqnum_t msg_qnum; /* Current number of messages in queue */ - msglen_t msg_qbytes; /* Maximum number of bytes + msglen_t msg_qbytes; /* Maximum number of bytes allowed in queue */ pid_t msg_lspid; /* PID of last msgsnd() */ pid_t msg_lrpid; /* PID of last msgrcv() */ @@ -120,7 +120,7 @@ to the kernel data structure associated with this message queue, updating also its .I msg_ctime member. -The following members of the structure are updated: +The following members of the structure are updated: .IR msg_qbytes , .IR msg_perm.uid , .IR msg_perm.gid , @@ -128,7 +128,7 @@ and (the least significant 9 bits of) .IR msg_perm.mode . The effective UID of the calling process must match the owner .RI ( msg_perm.uid ) -or creator +or creator .RI ( msg_perm.cuid ) of the message queue, or the caller must be privileged. Appropriate privilege (Linux: the @@ -150,11 +150,11 @@ or its effective user ID must be either that of the creator or owner of the message queue. .TP .BR IPC_INFO " (Linux specific)" -Returns information about system-wide message queue limits and +Returns information about system-wide message queue limits and parameters in the structure pointed to by .IR buf . This structure is of type -.IR msginfo +.IR msginfo (thus, a cast is required), defined in .I @@ -163,18 +163,18 @@ if the _GNU_SOURCE feature test macro is defined: .in +2n struct msginfo { - int msgpool; /* Size in bytes of buffer pool used + int msgpool; /* Size in bytes of buffer pool used to hold message data; unused */ int msgmap; /* Max. # of entries in message map; unused */ int msgmax; /* Max. # of bytes that can be written in a single message */ int msgmnb; /* Max. # of bytes that can be written to - queue; used to initialize msg_qbytes + queue; used to initialize msg_qbytes during queue creation (msgget()) */ int msgmni; /* Max. # of message queues */ int msgssz; /* Message segment size; unused */ - int msgtql; /* Max. # of messages on all queues + int msgtql; /* Max. # of messages on all queues in system; unused */ unsigned short int msgseg; /* Max. # of segments; unused */ @@ -182,15 +182,15 @@ struct msginfo { .in -2n .fi -The +The .IR msgmni , .IR msgmax , and .I msgmnb settings can be changed via -.I /proc +.I /proc files of the same name; see -.BR proc (5) +.BR proc (5) for details. .TP .BR MSG_INFO " (Linux specific)" @@ -198,21 +198,21 @@ Returns a .I msginfo structure containing the same information as for .BR IPC_INFO , -except that the following fields are returned with information +except that the following fields are returned with information about system resources consumed by message queues: the .I msgpool -field returns the number of message queues that currently exist +field returns the number of message queues that currently exist on the system; the .I msgmap -field returns the total number of messages in all queues +field returns the total number of messages in all queues on the system; and the .I msgtql -field returns the total number of bytes in all messages +field returns the total number of bytes in all messages in all queues on the system. .TP .BR MSG_STAT " (Linux specific)" -Returns a -.I msqid_ds +Returns a +.I msqid_ds structure as for .BR IPC_STAT . However, the @@ -229,13 +229,13 @@ and return 0. A successful .B IPC_INFO -or +or .B MSG_INFO operation returns the index of the highest used entry in the kernel's internal array recording information about all message queues. (This information can be used with repeated -.B MSG_STAT +.B MSG_STAT operations to obtain information about all queues on the system.) A successful .B MSG_STAT @@ -284,7 +284,7 @@ or .IR msqid . Or: for a .B MSG_STAT -operation, the index value specified in +operation, the index value specified in .I msqid referred to an array slot that is currently unused. .TP diff --git a/man2/msgget.2 b/man2/msgget.2 index 635c1fdd0..dc0d1797c 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -77,11 +77,11 @@ and a message queue already exists for .IR key , then .BR msgget () -fails with +fails with .I errno set to .BR EEXIST . -(This is analogous to the effect of the combination +(This is analogous to the effect of the combination .B O_CREAT | O_EXCL for .BR open (2).) @@ -90,7 +90,7 @@ Upon creation, the least significant bits of the argument .I msgflg define the permissions of the message queue. These permission bits have the same format and semantics -as the permissions specified for the +as the permissions specified for the .I mode argument of .BR open (2). diff --git a/man2/msgop.2 b/man2/msgop.2 index 9a5d41ad5..fa444f1c8 100644 --- a/man2/msgop.2 +++ b/man2/msgop.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -26,7 +26,7 @@ .\" Language clean-ups. .\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX .\" Added note on restart behaviour of msgsnd() and msgrcv() -.\" Formatting clean-ups (argument and field names marked as .I +.\" Formatting clean-ups (argument and field names marked as .I .\" instead of .B) .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements @@ -62,7 +62,7 @@ in order to send a message, and read permission to receive a message. .PP The .I msgp -argument is a pointer to caller-defined structure +argument is a pointer to caller-defined structure of the following general form: .in +0.5i .nf @@ -110,7 +110,7 @@ During queue creation this field is initialised to bytes, but this limit can be modified using .BR msgctl ().) If insufficient space is available in the queue, then the default -behaviour of +behaviour of .BR msgsnd () is to block until space becomes available. If @@ -120,9 +120,9 @@ is specified in then the call instead fails with the error .BR EAGAIN . -A blocked +A blocked .BR msgsnd () -call may also fail if the queue is removed +call may also fail if the queue is removed (in which case the system call fails with .I errno set to @@ -133,7 +133,7 @@ with set to .BR EINTR ). .RB ( msgsnd " and " msgrcv -are never automatically restarted after being interrupted by a +are never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler.) @@ -155,7 +155,7 @@ The system call removes a message from the queue specified by .I msqid and places it in the buffer -pointed to +pointed to .IR msgp . .PP The argument @@ -167,15 +167,15 @@ of the structure pointed to by the argument. If the message text has length greater than .IR msgsz , -then the behaviour depends on whether -.BR MSG_NOERROR -is specified in +then the behaviour depends on whether +.BR MSG_NOERROR +is specified in .IR msgflg . If .BR MSG_NOERROR is specified, then the message text will be truncated (and the truncated part will be -lost); if +lost); if .BR MSG_NOERROR is not specified, then the message isn't removed from the queue and @@ -287,7 +287,7 @@ array. .SH ERRORS When .BR msgsnd () -fails, +fails, .I errno will be set to one among the following values: .TP 11 @@ -296,7 +296,7 @@ The calling process does not have write permission on the message queue, and does not have the .BR CAP_IPC_OWNER capability. -.TP +.TP .B EAGAIN The message can't be sent due to the .I msg_qbytes @@ -328,13 +328,13 @@ value (less than 0 or greater than the system value .BR MSGMAX ). .TP .B ENOMEM -The system does not have enough memory to make a copy of the +The system does not have enough memory to make a copy of the message pointed to by .IR msgp . .PP When .BR msgrcv () -fails, +fails, .I errno will be set to one among the following values: .TP 11 @@ -351,11 +351,11 @@ The calling process does not have read permission on the message queue, and does not have the .BR CAP_IPC_OWNER capability. -.TP +.TP .B EAGAIN No message was available in the queue and -.B IPC_NOWAIT -was specified in +.B IPC_NOWAIT +was specified in .IR msgflg . .TP .B EFAULT @@ -385,7 +385,7 @@ and no message of the requested type existed on the message queue. .SH "CONFORMING TO" SVr4, POSIX.1-2001. .SH NOTES -The +The .I msgp argument is declared as \fIstruct msgbuf *\fP with libc4, libc5, glibc 2.0, glibc 2.1. It is declared as \fIvoid *\fP diff --git a/man2/msync.2 b/man2/msync.2 index e0d3c3e27..3af3be17a 100644 --- a/man2/msync.2 +++ b/man2/msync.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,44 +34,47 @@ msync \- synchronize a file with a memory map flushes changes made to the in-core copy of a file that was mapped into memory using .BR mmap (2) -back to disk. Without use of this call +back to disk. +Without use of this call there is no guarantee that changes are written back before .BR munmap (2) -is called. To be more precise, the part of the file that +is called. +To be more precise, the part of the file that corresponds to the memory area starting at .I start and having length .I length -is updated. +is updated. The .I flags -argument may have the bits -.BR MS_ASYNC , -.BR MS_SYNC , -and +argument may have the bits +.BR MS_ASYNC , +.BR MS_SYNC , +and .B MS_INVALIDATE -set, but not both -.B MS_ASYNC -and +set, but not both +.B MS_ASYNC +and .BR MS_SYNC . -.B MS_ASYNC +.B MS_ASYNC specifies that an update be scheduled, but the call returns immediately. -.B MS_SYNC +.B MS_SYNC asks for an update and waits for it to complete. -.B MS_INVALIDATE +.B MS_INVALIDATE asks to invalidate other mappings of the same file (so that they can be updated with the fresh values just written). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP .BR EBUSY -MS_INVALIDATE was specified in -.IR flags , +MS_INVALIDATE was specified in +.IR flags , and a memory lock exists for the specified address range. .TP .BR EINVAL @@ -79,7 +82,7 @@ and a memory lock exists for the specified address range. is not a multiple of PAGESIZE; or any bit other than MS_ASYNC | MS_INVALIDATE | MS_SYNC is set in .IR flags ; -or both +or both MS_SYNC and MS_ASYNC are set in .IR flags . .TP diff --git a/man2/nanosleep.2 b/man2/nanosleep.2 index 782c442c2..6a95baf61 100644 --- a/man2/nanosleep.2 +++ b/man2/nanosleep.2 @@ -39,23 +39,25 @@ nanosleep \- pause execution for a specified time delays the execution of the program for at least the time specified in .IR *req . The function can return earlier if a signal has been delivered to the -process. In this case, it returns \-1, sets \fIerrno\fR to +process. +In this case, it returns \-1, sets \fIerrno\fR to .BR EINTR , and writes the remaining time into the structure pointed to by .IR rem -unless +unless .I rem is NULL. The value of .I *rem -can then be used to call +can then be used to call .BR nanosleep () again and complete the specified pause. The structure .I timespec -is used to specify intervals of time with nanosecond precision. It is +is used to specify intervals of time with nanosecond precision. +It is specified in .I and has the form @@ -84,7 +86,7 @@ On successfully sleeping for the requested interval, .BR nanosleep () returns 0. If the call is interrupted by a signal handler or encounters an error, -then it returns \-1, with +then it returns \-1, with .I errno set to indicate the error. .SH ERRORS @@ -94,7 +96,8 @@ Problem with copying information from user space. .TP .B EINTR The pause has been interrupted by a non-blocked signal that was -delivered to the process. The remaining sleep time has been written +delivered to the process. +The remaining sleep time has been written into *\fIrem\fR so that the process can easily call .BR nanosleep () again and continue with the pause. @@ -115,7 +118,8 @@ Therefore, .BR nanosleep () pauses always for at least the specified time, however it can take up to 10 ms longer than specified until the process becomes runnable -again. For the same reason, the value returned in case of a delivered +again. +For the same reason, the value returned in case of a delivered signal in *\fIrem\fR is usually rounded to the next larger multiple of 1/\fIHZ\fR\ s. .SS "Old behaviour" @@ -128,18 +132,18 @@ like .I SCHED_FIFO or .IR SCHED_RR . -This special extension was removed in kernel 2.5.39, +This special extension was removed in kernel 2.5.39, hence is still present in current 2.4 kernels, but not in 2.6 kernels. .PP In Linux 2.4, if .BR nanosleep () -is stopped by a signal (e.g., SIGTSTP), +is stopped by a signal (e.g., SIGTSTP), then the call fails with the error -.BR EINTR +.BR EINTR after the process is resumed by a SIGCONT signal. -If the system call is subsequently restarted, -then the time that the process spent in the stopped state is +If the system call is subsequently restarted, +then the time that the process spent in the stopped state is \fInot\fP counted against the sleep interval. .SH "CONFORMING TO" POSIX.1-2001. diff --git a/man2/nfsservctl.2 b/man2/nfsservctl.2 index 196c3f283..7651b25b4 100644 --- a/man2/nfsservctl.2 +++ b/man2/nfsservctl.2 @@ -41,7 +41,8 @@ union nfsctl_res { }; .fi .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH "CONFORMING TO" diff --git a/man2/nice.2 b/man2/nice.2 index 79d4d6490..eda065078 100644 --- a/man2/nice.2 +++ b/man2/nice.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,11 +37,11 @@ nice \- change process priority .BI "int nice(int " inc ); .SH DESCRIPTION .BR nice () -adds +adds .I inc to the nice value for the calling process. (A higher nice value means a low priority.) -Only the super\%user may specify a negative increment, +Only the super\%user may specify a negative increment, or priority increase. The range for nice values is described in .BR getpriority (2). @@ -60,12 +60,12 @@ but has insufficient privileges. Under Linux the .B CAP_SYS_NICE capability is required. -(But see the discussion of the +(But see the discussion of the .B RLIMIT_NICE resource limit in .BR setrlimit (2).) .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. However, the Linux and (g)libc (earlier than glibc 2.2.4) return value is nonstandard, see below. SVr4 documents an additional EINVAL error code. diff --git a/man2/open.2 b/man2/open.2 index dcb6e562d..8649009ba 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,16 +51,16 @@ open, creat \- open and possibly create a file or device .fi .SH DESCRIPTION Given a -.IR pathname +.IR pathname for a file, .BR open () -returns a file descriptor, a small, non-negative integer +returns a file descriptor, a small, non-negative integer for use in subsequent system calls .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)." The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process. .PP -The new file descriptor is set to remain open across an +The new file descriptor is set to remain open across an .BR execve (2) (i.e., the .B FD_CLOEXEC @@ -68,7 +68,7 @@ file descriptor flag described in .BR fcntl (2) is initially disabled). The file offset is set to the beginning of the file (see -.BR lseek (2)). +.BR lseek (2)). .PP A call to .BR open () @@ -98,16 +98,16 @@ These request opening the file read-only, write-only, or read/write, respectively. In addition, zero or more file creation flags and file status flags -can be +can be .RI bitwise- or 'd in .IR flags . -The -.I file creation flags -are +The +.I file creation flags +are .BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", and " O_TRUNC . -The -.I file status flags +The +.I file status flags are all of the remaining flags listed below. The distinction between these two groups of flags is that the file status flags can be retrieved and (in some cases) @@ -116,14 +116,16 @@ modified using The full list of file creation flags and file status flags is as follows: .TP .B O_APPEND -The file is opened in append mode. Before each +The file is opened in append mode. +Before each .BR write (), the file offset is positioned at the end of the file, as if with .BR lseek (). .B O_APPEND may lead to corrupted files on NFS file systems if more than one process -appends data to a file at once. This is because NFS does not support +appends data to a file at once. +This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition. .TP @@ -132,7 +134,7 @@ Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via .BR fcntl (2)) when input or output becomes possible on this file descriptor. -This feature is only available for terminals, pseudo-terminals, +This feature is only available for terminals, pseudo-terminals, sockets, and (since Linux 2.6) pipes and FIFOs. See .BR fcntl (2) @@ -141,7 +143,8 @@ for further details. .B O_CREAT If the file does not exist it will be created. The owner (user ID) of the file is set to the effective user ID -of the process. The group ownership (group ID) is set either to +of the process. +The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on filesystem type and mount options, and the mode of the parent directory, see, e.g., the mount options @@ -163,17 +166,18 @@ or data is guaranteed to have been transferred. Under Linux 2.4 transfer sizes, and the alignment of user buffer and file offset must all be multiples of the logical block size -of the file system. Under Linux 2.6 alignment to 512-byte boundaries +of the file system. +Under Linux 2.6 alignment to 512-byte boundaries suffices. .\" Alignment should satisfy requirements for the underlying device .\" There may be coherency problems. .sp -A semantically similar (but deprecated) interface for block devices +A semantically similar (but deprecated) interface for block devices is described in .BR raw (8). .TP .B O_DIRECTORY -If \fIpathname\fR is not a directory, cause the open to fail. +If \fIpathname\fR is not a directory, cause the open to fail. .\" But see the following and its replies: .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail @@ -188,16 +192,20 @@ When used with .BR O_CREAT , if the file already exists it is an error and the .BR open () -will fail. In this context, a symbolic link exists, regardless +will fail. +In this context, a symbolic link exists, regardless of where it points to. .B O_EXCL is broken on NFS file systems; programs which rely on it for performing -locking tasks will contain a race condition. The solution for performing +locking tasks will contain a race condition. +The solution for performing atomic file locking using a lockfile is to create a unique file on the same file system (e.g., incorporating hostname and pid), use .BR link (2) -to make a link to the lockfile. If \fBlink\fP() returns 0, the lock is -successful. Otherwise, use +to make a link to the lockfile. +If \fBlink\fP() returns 0, the lock is +successful. +Otherwise, use .BR stat (2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful. @@ -209,10 +217,10 @@ Allow files whose sizes cannot be represented in an (but can be represented in an .IR off64_t ) to be opened. -The +The .B _LARGEFILE64_SOURCE macro must be defined in order to obtain this definition. -Setting the +Setting the .B _FILE_OFFSET_BITS feature test macro to 64 (rather than using .BR O_LARGEFILE ) @@ -229,7 +237,7 @@ This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all filesystems. One example is NFS, where the server maintains the access time. -.\" FIXME? The O_NOATIME flag also affects the treatment of st_atime +.\" FIXME? The O_NOATIME flag also affects the treatment of st_atime .\" by mmap() and readdir(2), MTK, Dec 04. .TP .B O_NOCTTY @@ -241,8 +249,8 @@ refers to a terminal device \(em see process does not have one. .TP .B O_NOFOLLOW -If \fIpathname\fR is a symbolic link, then the open fails. This is a -FreeBSD extension, which was added to Linux in version 2.1.126. +If \fIpathname\fR is a symbolic link, then the open fails. +This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed. .\" The headers from glibc 2.0.100 and later include a @@ -250,7 +258,8 @@ followed. .\" used\fR. .TP .BR O_NONBLOCK " or " O_NDELAY -When possible, the file is opened in non-blocking mode. Neither the +When possible, the file is opened in non-blocking mode. +Neither the .BR open () nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. @@ -262,7 +271,8 @@ in conjunction with mandatory file locks and with file leases, see .BR fcntl (2). .TP .B O_SYNC -The file is opened for synchronous I/O. Any +The file is opened for synchronous I/O. +Any .BR write ()s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware. @@ -272,7 +282,8 @@ the data has been physically written to the underlying hardware. If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. If the file is a FIFO or terminal device file, the O_TRUNC -flag is ignored. Otherwise the effect of O_TRUNC is unspecified. +flag is ignored. +Otherwise the effect of O_TRUNC is unspecified. .PP Some of these optional flags can be altered using .BR fcntl () @@ -280,7 +291,8 @@ after the file has been opened. The argument .I mode -specifies the permissions to use in case a new file is created. It is +specifies the permissions to use in case a new file is created. +It is modified by the process's .BR umask in the usual way: the permissions of the created file are @@ -345,8 +357,8 @@ with equal to .BR O_CREAT|O_WRONLY|O_TRUNC . .SH "RETURN VALUE" -.BR open () -and +.BR open () +and .BR creat () return the new file descriptor, or \-1 if an error occurred (in which case, @@ -361,7 +373,7 @@ cannot create them; use .BR mknod (2) instead. .LP -On NFS file systems with UID mapping enabled, \fBopen\fP() may +On NFS file systems with UID mapping enabled, \fBopen\fP() may return a file descriptor but e.g. \fBread\fP(2) requests are denied with \fBEACCES\fP. This is because the client performs \fBopen\fP() by checking the @@ -395,13 +407,13 @@ already exists and were used. .TP .B EFAULT -.IR pathname +.IR pathname points outside your accessible address space. .TP .B EFBIG .I pathname refers to a regular file, too large to be opened; see O_LARGEFILE above. -(POSIX.1-2001 specifies the error +(POSIX.1-2001 specifies the error .B EOVERFLOW for this case.) .\" FIXME Maybe this deviation from the standard will get repaired. @@ -511,7 +523,7 @@ macro to get their definitions. .LP The (undefined) effect of .B O_RDONLY | O_TRUNC -varies among implementations. +varies among implementations. On many systems the file is actually truncated. .\" Linux 2.0, 2.5: truncate .\" Solaris 5.7, 5.8: truncate @@ -523,8 +535,10 @@ On many systems the file is actually truncated. The .B O_DIRECT flag was introduced in SGI IRIX, where it has alignment restrictions -similar to those of Linux 2.4. IRIX has also a fcntl(2) call to -query appropriate alignments, and sizes. FreeBSD 4.x introduced +similar to those of Linux 2.4. +IRIX has also a fcntl(2) call to +query appropriate alignments, and sizes. +FreeBSD 4.x introduced a flag of same name, but without alignment restrictions. Support was added under Linux in kernel version 2.4.10. Older Linux kernels simply ignore this flag. @@ -539,7 +553,7 @@ on some serious mind-controlling substances." \(em Linus Currently, it is not possible to enable signal-driven I/O by specifying .B O_ASYNC -when calling +when calling .BR open (); use .BR fcntl (2) @@ -553,7 +567,8 @@ amongst others POSIX provides for three different variants of synchronised I/O, corresponding to the flags \fBO_SYNC\fR, \fBO_DSYNC\fR and -\fBO_RSYNC\fR. Currently (2.1.130) these are all synonymous under Linux. +\fBO_RSYNC\fR. +Currently (2.1.130) these are all synonymous under Linux. .SH "SEE ALSO" .BR close (2), .BR dup (2), diff --git a/man2/openat.2 b/man2/openat.2 index 06ed200b7..b11c3d54a 100644 --- a/man2/openat.2 +++ b/man2/openat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,36 +42,36 @@ system call operates in exactly the same way as .BR open (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR open (2) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR open (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .SH "RETURN VALUE" On success, -.BR openat () +.BR openat () returns a new file descriptor. On error, \-1 is returned and .I errno @@ -81,7 +81,7 @@ The same errors that occur for .BR open (2) can also occur for .BR openat (). -The following additional errors can occur for +The following additional errors can occur for .BR openat (): .TP .B EBADF @@ -100,29 +100,29 @@ for two reasons. First, .BR openat () -allows an application to avoid race conditions that could +allows an application to avoid race conditions that could occur when using .BR open (2) to open files in directories other than the current working directory. These race conditions result from the fact that some component of the directory prefix given to .BR open () -could be changed in parallel with the call to +could be changed in parallel with the call to .BR open (). Such races can be avoided by opening a file descriptor for the target directory, -and then specifying that file descriptor as the +and then specifying that file descriptor as the .I dirfd argument of .BR openat (). Second, .BR openat () -allows the implementation of a per-thread "current working +allows the implementation of a per-thread "current working directory", via file descriptor(s) maintained by the application. (This functionality can also be obtained by tricks based on the use of -.IR /proc/self/fd/ dirfd, +.IR /proc/self/fd/ dirfd, but less efficiently.) .SH "CONFORMING TO" This system call is non-standard but is proposed @@ -132,7 +132,7 @@ A similar system call exists on Solaris. .\" primarily referred to "extended *at*tributes", which are .\" handled by Solaris' O_XATTR flag, but was also intended .\" to refer to the notion of "at a relative location". -.\" +.\" .\" See the following for a discussion of the inconsistent .\" naming of the *at() functions: .\" http://www.opengroup.org/austin/mailarchives/ag/msg09103.html diff --git a/man2/outb.2 b/man2/outb.2 index c32804d99..a95d0efce 100644 --- a/man2/outb.2 +++ b/man2/outb.2 @@ -3,7 +3,7 @@ .\" Copyright (c) 1995 Paul Gortmaker .\" (gpg109@rsphy1.anu.edu.au) .\" Wed Nov 29 10:58:54 EST 1995 -.\" +.\" .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of @@ -36,13 +36,14 @@ The out* functions do port output, the in* functions do port input; the b-suffix functions are byte-width and the w-suffix functions word-width; the _p-suffix functions pause until the I/O completes. .LP -They are primarily designed for internal kernel use, +They are primarily designed for internal kernel use, but can be used from user space. .\" , given the following information .\" in addition to that given in .\" .BR outb (9). .sp -You compile with \fB\-O\fP or \fB\-O2\fP or similar. The functions +You compile with \fB\-O\fP or \fB\-O2\fP or similar. +The functions are defined as inline macros, and will not be substituted in without optimization enabled, causing unresolved references at link time. .sp @@ -51,10 +52,12 @@ You use or alternatively .BR iopl (2) to tell the kernel to allow the user space application to access the -I/O ports in question. Failure to do this will cause the application +I/O ports in question. +Failure to do this will cause the application to receive a segmentation fault. .SH "CONFORMING TO" -\fBoutb\fP() and friends are hardware specific. The +\fBoutb\fP() and friends are hardware specific. +The .I value argument is passed first and the .I port diff --git a/man2/path_resolution.2 b/man2/path_resolution.2 index 0232d8b64..eb134e500 100644 --- a/man2/path_resolution.2 +++ b/man2/path_resolution.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -28,12 +28,16 @@ Some Unix/Linux system calls have as parameter one or more filenames. A filename (or pathname) is resolved as follows. .SS "Step 1: Start of the resolution process" If the pathname starts with the '/' character, the starting lookup directory -is the root directory of the current process. (A process inherits its -root directory from its parent. Usually this will be the root directory -of the file hierarchy. A process may get a different root directory +is the root directory of the current process. +(A process inherits its +root directory from its parent. +Usually this will be the root directory +of the file hierarchy. +A process may get a different root directory by use of the .BR chroot (2) -system call. A process may get an entirely private namespace in case +system call. +A process may get an entirely private namespace in case it \(em or one of its ancestors \(em was started by an invocation of the .BR clone (2) system call that had the CLONE_NEWNS flag set.) @@ -41,7 +45,8 @@ This handles the '/' part of the pathname. If the pathname does not start with the '/' character, the starting lookup directory of the resolution process is the current working -directory of the process. (This is also inherited from the parent. +directory of the process. +(This is also inherited from the parent. It can be changed by use of the .BR chdir (2) system call.) @@ -54,7 +59,8 @@ Now, for each non-final component of the pathname, where a component is a substring delimited by '/' characters, this component is looked up in the current lookup directory. -If the process does not have search permission on the current lookup directory, +If the process does not have search permission on +the current lookup directory, an EACCES error is returned ("Permission denied"). If the component is not found, an ENOENT error is returned @@ -69,7 +75,8 @@ next component. If the component is found and is a symbolic link (symlink), we first resolve this symbolic link (with the current lookup directory -as starting lookup directory). Upon error, that error is returned. +as starting lookup directory). +Upon error, that error is returned. If the result is not a directory, an ENOTDIR error is returned. If the resolution of the symlink is successful and returns a directory, we set the current lookup directory to that directory, and go to @@ -78,7 +85,8 @@ Note that the resolution process here involves recursion. In order to protect the kernel against stack overflow, and also to protect against denial of service, there are limits on the maximum recursion depth, and on the maximum number of symlinks -followed. An ELOOP error is returned when the maximum is +followed. +An ELOOP error is returned when the maximum is exceeded ("Too many levels of symbolic links"). .\" .\" presently: max recursion depth during symlink resolution: 5 @@ -92,7 +100,8 @@ directory (at least as far as the path resolution process is concerned \(em it may have to be a directory, or a non-directory, because of the requirements of the specific system call), and (ii) it is not necessarily an error if the component is not found \(em -maybe we are just creating it. The details on the treatment +maybe we are just creating it. +The details on the treatment of the final entry are described in the manual pages of the specific system calls. .SS ". and .." @@ -129,20 +138,23 @@ will operate on the symlink, while .BR stat (2) operates on the file pointed to by the symlink. .SS "Length limit" -There is a maximum length for pathnames. If the pathname (or some +There is a maximum length for pathnames. +If the pathname (or some intermediate pathname obtained while resolving symbolic links) is too long, an ENAMETOOLONG error is returned ("File name too long"). .SS "Empty pathname" In the original Unix, the empty pathname referred to the current directory. Nowadays POSIX decrees that an empty pathname must not be resolved -successfully. Linux returns ENOENT in this case. +successfully. +Linux returns ENOENT in this case. .SS "Permissions" The permission bits of a file consist of three groups of three bits, cf.\& .BR chmod (1) and .BR stat (2). The first group of three is used when the effective user ID of -the current process equals the owner ID of the file. The second group +the current process equals the owner ID of the file. +The second group of three is used when the group ID of the file either equals the effective group ID of the current process, or is one of the supplementary group IDs of the current process (as set by @@ -161,23 +173,26 @@ changed by the system call (Here "fsuid" stands for something like "file system user ID". The concept was required for the implementation of a user space NFS server at a time when processes could send a signal to a process -with the same effective user ID. It is obsolete now. Nobody should use +with the same effective user ID. +It is obsolete now. +Nobody should use .BR setfsuid (2).) -Similarly, Linux uses the fsgid ("file system group ID") -instead of the effective group ID. See +Similarly, Linux uses the fsgid ("file system group ID") +instead of the effective group ID. +See .BR setfsgid (2). .\" FIXME say something about filesystem mounted read-only ? .SS "Bypassing permission checks: superuser and capabilities" On a traditional Unix system, the superuser .RI ( root , -user ID 0) is all-powerful, and bypasses all permissions restrictions +user ID 0) is all-powerful, and bypasses all permissions restrictions when accessing files. .\" (but for exec at least one x bit must be set) -- AEB -.\" but there is variation across systems on this point: for -.\" example, HP-UX and Tru64 are as described by AEB. However, -.\" on some implementations (e.g., Solaris, FreeBSD), -.\" access(X_OK) by superuser will report success, regardless +.\" but there is variation across systems on this point: for +.\" example, HP-UX and Tru64 are as described by AEB. However, +.\" on some implementations (e.g., Solaris, FreeBSD), +.\" access(X_OK) by superuser will report success, regardless .\" of the file's execute permission bits. -- MTK (Oct 05) On Linux, superuser privileges are divided into capabilities (see diff --git a/man2/pause.2 b/man2/pause.2 index ba48082ac..92a26eb81 100644 --- a/man2/pause.2 +++ b/man2/pause.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,7 +48,8 @@ to call a signal-catching function. The .BR pause () function only returns when a signal was caught and the -signal-catching function returned. In this case +signal-catching function returned. +In this case .BR pause () returns \-1, and .I errno diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 index 8db268cf2..df8bcabc1 100644 --- a/man2/pciconfig_read.2 +++ b/man2/pciconfig_read.2 @@ -9,16 +9,18 @@ pciconfig_read, pciconfig_write, pciconfig_iobase \- pci device information hand .nf .B #include .sp -.BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , +.BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , .BI " unsigned long " off ", unsigned long " len ", void *" buf ); -.BI "int pciconfig_write(unsigned long " bus ", unsigned long " dfn , +.BI "int pciconfig_write(unsigned long " bus ", unsigned long " dfn , .BI " unsigned long " off ", unsigned long " len ", void *" buf ); .BI "int pciconfig_iobase(long " which ", unsigned long " bus , -.BI " unsigned long " devfn ); +.BI " unsigned long " devfn ); .fi .SH DESCRIPTION .TP -Most of the interaction with PCI devices is already handled by the kernel PCI layer, and thus these calls should not normally need to be accessed from userspace. +Most of the interaction with PCI devices is already handled by the +kernel PCI layer, +and thus these calls should not normally need to be accessed from userspace. .TP .BR pciconfig_read () Reads to @@ -27,7 +29,7 @@ buf from device .I dev -at offset +at offset .I off value. @@ -39,32 +41,37 @@ buf to device .I dev -at offset +at offset .I off value. .TP .BR pciconfig_iobase () -You pass it a bus/devfn pair and get a physical address for either the memory offset (for things like prep, this is 0xc0000000), the IO base for PIO cycles, or the ISA holes if any. +You pass it a bus/devfn pair and get a physical address for either the +memory offset (for things like prep, this is 0xc0000000), +the IO base for PIO cycles, or the ISA holes if any. .SH "RETURN VALUE" .TP .BR pciconfig_read () -On success zero is returned. On error, \-1 is returned and errno is set appropriately. +On success zero is returned. +On error, \-1 is returned and errno is set appropriately. .TP .BR pciconfig_write () -On success zero is returned. On error, \-1 is returned and errno is set appropriately. +On success zero is returned. +On error, \-1 is returned and errno is set appropriately. .TP .BR pciconfig_iobase () -Returns information on locations of various I/O regions in physical memory according to the -.I which -value. Values for +Returns information on locations of various I/O regions in physical memory according to the +.I which +value. +Values for .I which are: IOBASE_BRIDGE_NUMBER, IOBASE_MEMORY, IOBASE_IO, IOBASE_ISA_IO, IOBASE_ISA_MEM. .SH ERRORS .TP .B EINVAL .I len -value is invalid. +value is invalid. This does not apply to .BR pciconfig_iobase (). .TP @@ -74,14 +81,14 @@ I/O error. .B ENODEV For .BR pciconfig_iobase (), -"hose" value is NULL? +"hose" value is NULL? For the other calls, could not find a slot. .TP .B ENOSYS The system has not implemented these calls (CONFIG_PCI not defined). .TP .B EOPNOTSUPP -This return value is only valid for +This return value is only valid for .BR pciconfig_iobase (). .TP It is returned if the value for @@ -90,8 +97,8 @@ which is invalid. .TP .B EPERM -User does not have the CAP_SYS_ADMIN capability. -This does not apply to +User does not have the CAP_SYS_ADMIN capability. +This does not apply to .BR pciconfig_iobase (). .SH "CONFORMING TO" These calls are Linux specific, available since Linux 2.0.26/2.1.11. diff --git a/man2/personality.2 b/man2/personality.2 index 2643dc0f2..4a15d0cd5 100644 --- a/man2/personality.2 +++ b/man2/personality.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,8 +36,10 @@ personality \- set the process execution domain .BI "int personality(unsigned long " persona ); .SH DESCRIPTION Linux supports different execution domains, or personalities, for each -process. Among other things, execution domains tell Linux how to map -signal numbers into signal actions. The execution domain system allows +process. +Among other things, execution domains tell Linux how to map +signal numbers into signal actions. +The execution domain system allows Linux to provide limited support for binaries compiled under other Unix-like operating systems. @@ -45,14 +47,16 @@ This function will return the current .BR personality () when .I persona -equals 0xffffffff. Otherwise, it will make the execution domain +equals 0xffffffff. +Otherwise, it will make the execution domain referenced by .I persona the new execution domain of the current process. .SH "RETURN VALUE" On success, the previous .I persona -is returned. On error, \-1 is returned, and +is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -61,5 +65,5 @@ is set appropriately. The kernel was unable to change the personality. .SH "CONFORMING TO" .BR personality () -is Linux specific and should not be used in programs intended to +is Linux specific and should not be used in programs intended to be portable. diff --git a/man2/pipe.2 b/man2/pipe.2 index 8da88d3f3..28914a896 100644 --- a/man2/pipe.2 +++ b/man2/pipe.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,12 +39,13 @@ pipe \- create pipe creates a pair of file descriptors, pointing to a pipe inode, and places them in the array pointed to by .IR filedes . -.I filedes[0] +.I filedes[0] is for reading, .I filedes[1] is for writing. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -62,17 +63,17 @@ The system limit on the total number of open files has been reached. POSIX.1-2001. .SH EXAMPLE .\" fork.2 refers to this example program. -The following program creates a pipe, and then -.BR fork (2)s -to create a child process. -After the +The following program creates a pipe, and then +.BR fork (2)s +to create a child process. +After the .BR fork (2), each process closes the descriptors that it doesn't need for the pipe -(see +(see .BR pipe (7)). -The parent then writes the string contained in the program's -command-line argument to the pipe, -and the child reads this string a byte at a time from the pipe +The parent then writes the string contained in the program's +command-line argument to the pipe, +and the child reads this string a byte at a time from the pipe and echoes it on standard output. .nf diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 index 820916bd0..5a1be7e69 100644 --- a/man2/pivot_root.2 +++ b/man2/pivot_root.2 @@ -32,24 +32,30 @@ the current root of all relevant processes or threads. \fBpivot_root\fP() may or may not change the current root and the current working directory (cwd) of any processes or threads which use the old -root directory. The caller of \fBpivot_root\fP() +root directory. +The caller of \fBpivot_root\fP() must ensure that processes with root or cwd at the old root operate -correctly in either case. An easy way to ensure this is to change their +correctly in either case. +An easy way to ensure this is to change their root and cwd to \fInew_root\fP before invoking \fBpivot_root\fP(). The paragraph above is intentionally vague because the implementation -of \fBpivot_root\fP() may change in the future. At the time of writing, +of \fBpivot_root\fP() may change in the future. +At the time of writing, \fBpivot_root\fP() changes root and cwd of each process or -thread to \fInew_root\fP if they point to the old root directory. This +thread to \fInew_root\fP if they point to the old root directory. +This is necessary in order to prevent kernel threads from keeping the old root directory busy with their root and cwd, even if they never access -the file system in any way. In the future, there may be a mechanism for +the file system in any way. +In the future, there may be a mechanism for kernel threads to explicitly relinquish any access to the file system, such that this fairly intrusive mechanism can be removed from \fBpivot_root\fP(). Note that this also applies to the current process: \fBpivot_root\fP() may -or may not affect its cwd. It is therefore recommended to call +or may not affect its cwd. +It is therefore recommended to call \fBchdir("/")\fP immediately after \fBpivot_root\fP(). The following restrictions apply to \fInew_root\fP and \fIput_old\fP: @@ -71,15 +77,18 @@ If the current root is not a mount point (e.g. after \fBchroot(2)\fP or \fBpivot_root\fP(), see also below), not the old root directory, but the mount point of that file system is mounted on \fIput_old\fP. .SH NOTES -\fInew_root\fP does not have to be a mount point. In this case, +\fInew_root\fP does not have to be a mount point. +In this case, \fI/proc/mounts\fP will show the mount point of the file system containing \fInew_root\fP as root (\fI/\fP). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and \fIerrno\fP is set appropriately. .SH ERRORS \fBpivot_root\fP() may return (in \fIerrno\fP) any of the errors returned by -\fBstat(2)\fP. Additionally, it may return: +\fBstat(2)\fP. +Additionally, it may return: .TP .B EBUSY \fInew_root\fP or \fIput_old\fP are on the current root file system, diff --git a/man2/poll.2 b/man2/poll.2 index b927b13af..6348422b5 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -83,7 +83,7 @@ is an output parameter, filled by the kernel with the events that actually occurred. The bits returned in .I revents -can include any of those specified in +can include any of those specified in .IR events , or one of the values .BR POLLERR , @@ -101,7 +101,7 @@ of the file descriptors, then .BR poll () blocks until one of the events occurs. -The +The .I timeout argument specifies an upper limit on the time for which .BR poll () @@ -121,16 +121,16 @@ are defined in : There is data to read. .TP .B POLLPRI -There is urgent data to read (e.g., out-of-band data on TCP socket; +There is urgent data to read (e.g., out-of-band data on TCP socket; pseudo-terminal master in packet mode has seen state change in slave). .TP .B POLLOUT Writing now will not block. .TP .BR POLLRDHUP " (since Linux 2.6.17)" -Stream socket peer closed connection, +Stream socket peer closed connection, or shut down writing half of connection. -The +The .B _GNU_SOURCE feature test macro must be defined in order to obtain this definition. .TP @@ -141,14 +141,14 @@ Error condition (output only). Hang up (output only). .TP .B POLLNVAL -Invalid request: +Invalid request: .I fd not open (output only). .RE .PP -When compiling with +When compiling with .B _XOPEN_SOURCE -defined, one also has the following, +defined, one also has the following, which convey no further information beyond the bits listed above: .RS .TP @@ -168,13 +168,13 @@ Equivalent to Priority data may be written. .RE .PP -Linux also knows about, but does not use +Linux also knows about, but does not use .BR POLLMSG . .SS ppoll() -The relationship between +The relationship between .BR poll () -and -.BR ppoll () +and +.BR ppoll () is analogous to the relationship between .BR select () and @@ -185,9 +185,9 @@ like allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. .PP -Other than the difference in the +Other than the difference in the .I timeout -argument, the following +argument, the following .BR ppoll () call: .nf @@ -215,7 +215,7 @@ is necessary. The .I timeout -argument specifies an upper limit on the amount of time that +argument specifies an upper limit on the amount of time that .BR ppoll () will block. This argument is a pointer to a structure of the following form: @@ -231,7 +231,7 @@ struct timespec { If .I timeout -is specified as NULL, then +is specified as NULL, then .BR ppoll () can block indefinitely. .SH "RETURN VALUE" @@ -240,7 +240,8 @@ the number of structures which have non-zero .I revents fields (in other words, those descriptors with events or errors reported). A value of 0 indicates that the call timed out and no file -descriptors were ready. On error, \-1 is returned, and +descriptors were ready. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -265,16 +266,16 @@ There was no space to allocate file descriptor tables. .SH "LINUX NOTES" The Linux .BR ppoll () -system call modifies its -.I timeout +system call modifies its +.I timeout argument. However, the glibc wrapper function hides this behaviour by using a local variable for the timeout argument that is passed to the system call. -Thus, the glibc +Thus, the glibc .BR ppoll () -function does not modify its -.I timeout +function does not modify its +.I timeout argument. .SH BUGS See the discussion of spurious readiness notifications under the @@ -288,13 +289,13 @@ is Linux specific. .\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). .SH VERSIONS The -.BR poll () +.BR poll () system call was introduced in Linux 2.1.23. -The +The .BR poll () library call was introduced in libc 5.4.28 (and provides emulation using select() if your kernel does not -have a +have a .BR poll () system call). diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index 9d7128cd7..cd9a00823 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,15 +40,16 @@ to perform appropriate optimisations. The \fIadvice\fP applies to a (not necessarily existent) region starting at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of -the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. The -advice is not binding; it merely constitutes an expectation on behalf of +the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. +The advice is not binding; it merely constitutes an expectation on behalf of the application. Permissible values for \fIadvice\fP include: .TP .B POSIX_FADV_NORMAL Indicates that the application has no advice to give about its access -pattern for the specified data. If no advice is given for an open file, +pattern for the specified data. +If no advice is given for an open file, this is the default assumption. .TP .B POSIX_FADV_SEQUENTIAL @@ -67,7 +68,7 @@ The specified data will be accessed in the near future. .B POSIX_FADV_DONTNEED The specified data will not be accessed in the near future. .SH "RETURN VALUE" -On success, zero is returned. +On success, zero is returned. On error, an error number is returned. .SH ERRORS .TP @@ -92,19 +93,21 @@ These changes affect the entire file, not just the specified region (but other open file handles to the same file are unaffected). \fBPOSIX_FADV_WILLNEED\fP initiates a -non-blocking read of the specified region into the page cache. -The amount of data read may be decreased by the kernel depending -on virtual memory load. -(A few megabytes will usually be fully satisfied, +non-blocking read of the specified region into the page cache. +The amount of data read may be decreased by the kernel depending +on virtual memory load. +(A few megabytes will usually be fully satisfied, and more is rarely useful.) -In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the +In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the same semantics as \fBPOSIX_FADV_WILLNEED\fP. This was probably a bug; since kernel 2.6.18, this flag is a no-op. \fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with -the specified region. This is useful, for example, while streaming large -files. A program may periodically request the kernel to free cached data +the specified region. +This is useful, for example, while streaming large +files. +A program may periodically request the kernel to free cached data that has already been used, so that more useful cached pages are not discarded instead. @@ -115,13 +118,13 @@ call \fBfsync\fP() or \fBfdatasync\fP() first. POSIX.1-2001. Note that the type of the .I len -parameter was changed from -.I size_t -to -.I off_t +parameter was changed from +.I size_t +to +.I off_t in POSIX.1-2003 TC1. .SH BUGS -In kernels before 2.6.6, if +In kernels before 2.6.6, if .I len was specified as 0, then this was interpreted literally as "zero bytes", rather than as meaning "all bytes through to the end of the file". diff --git a/man2/prctl.2 b/man2/prctl.2 index 0bbc99930..25ed5f0a9 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,13 +18,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG .\" Modified 27 Jun 02, Michael Kerrisk -.\" Added PR_SET_DUMPABLE, PR_GET_DUMPABLE, +.\" Added PR_SET_DUMPABLE, PR_GET_DUMPABLE, .\" PR_SET_KEEPCAPS, PR_GET_KEEPCAPS .\" Modified 2006-08-30 Guillem Jover .\" Updated Linux versions where the options where introduced. @@ -55,8 +55,8 @@ Set the parent process death signal of the calling process to \fIarg2\fP (either a signal value in the range 1..maxsig, or 0 to clear). This is the signal that the calling process will get when its -parent dies. -This value is cleared upon a +parent dies. +This value is cleared upon a .BR fork (). .TP .B PR_GET_PDEATHSIG @@ -70,20 +70,20 @@ Set the state of the flag determining whether core dumps are produced for this process upon delivery of a signal whose default behaviour is to produce a core dump. (Normally this flag is set for a process by default, but it is cleared -when a set-user-ID or set-group-ID program is executed and also by +when a set-user-ID or set-group-ID program is executed and also by various system calls that manipulate process UIDs and GIDs). In kernels up to and including 2.6.12, .I arg2 must be either 0 (process is not dumpable) or 1 (process is dumpable). Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted, -which caused any binary which normally would not be dumped -to be dumped readable by root only; +which caused any binary which normally would not be dumped +to be dumped readable by root only; for security reasons, this feature has been removed. .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2 .\" Subject: Fix prctl privilege escalation (CVE-2006-2451) .\" From: Marcel Holtmann .\" Date: 2006-07-12 11:12:00 -(See also the description of +(See also the description of .I /proc/sys/fs/suid_dumpable in .BR proc (5).) @@ -92,7 +92,7 @@ in (Since Linux 2.3.20) Return (as the function result) the current state of the calling process's dumpable flag. -.\" Since Linux 2.6.13, the dumpable flag can have the value 2, +.\" Since Linux 2.6.13, the dumpable flag can have the value 2, .\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable .\" flags has a non-zero value. This was fixed in 2.6.14. .TP @@ -137,12 +137,12 @@ Return the endian-ness of the calling process. .TP .B PR_SET_ENDIAN (Since Linux 2.6.18, PowerPC only) -Set the endian-ness of the calling process to the value given +Set the endian-ness of the calling process to the value given in \fIarg2\fP, which should be one of the following: .BR PR_ENDIAN_BIG , .BR PR_ENDIAN_LITTLE , or -.BR PR_ENDIAN_PPC_LITTLE +.BR PR_ENDIAN_PPC_LITTLE (PowerPC pseudo little endian). .TP .B PR_SET_UNALIGN @@ -205,7 +205,7 @@ and is not zero or a signal number. .SH "CONFORMING TO" This call is Linux specific. -IRIX has a +IRIX has a .BR prctl () system call (also introduced in Linux 2.1.44 as irix_prctl on the MIPS architecture), @@ -218,8 +218,8 @@ get the maximum number of processors the calling process can use, find out whether a specified process is currently blocked, get or set the maximum stack size, etc. .SH AVAILABILITY -The -.BR prctl () +The +.BR prctl () system call was introduced in Linux 2.1.57. .\" The library interface was added in glibc 2.0.6 .SH "SEE ALSO" diff --git a/man2/pread.2 b/man2/pread.2 index 907a7c0a6..2cd6a6064 100644 --- a/man2/pread.2 +++ b/man2/pread.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 033194be0..8afe00f15 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -6,7 +6,7 @@ .\" .\" changes Copyright 1999 Mike Coleman (mkc@acm.org) .\" -- major revision to fully document ptrace semantics per recent Linux -.\" kernel (2.2.10) and glibc (2.1.2) +.\" kernel (2.2.10) and glibc (2.1.2) .\" Sun Nov 7 03:18:35 CST 1999 .\" .\" This is free documentation; you can redistribute it and/or @@ -53,27 +53,27 @@ ptrace \- process trace .SH DESCRIPTION The .BR ptrace () -system call provides a means by which a parent process may observe -and control the execution of another process, -and examine and change its core image and registers. +system call provides a means by which a parent process may observe +and control the execution of another process, +and examine and change its core image and registers. It is primarily used to implement breakpoint debugging and system call tracing. .LP The parent can initiate a trace by calling -.BR fork (2) -and having the resulting child do a PTRACE_TRACEME, +.BR fork (2) +and having the resulting child do a PTRACE_TRACEME, followed (typically) by an .BR exec (3). Alternatively, the parent may commence trace of an existing process using PTRACE_ATTACH. .LP -While being traced, the child will stop each time a signal is delivered, -even if the signal is being ignored. -(The exception is SIGKILL, which has its usual effect.) +While being traced, the child will stop each time a signal is delivered, +even if the signal is being ignored. +(The exception is SIGKILL, which has its usual effect.) The parent will be notified at its next .BR wait (2) -and may inspect and modify the child process while it is stopped. -The parent then causes the child to continue, +and may inspect and modify the child process while it is stopped. +The parent then causes the child to continue, optionally ignoring the delivered signal (or even delivering a different signal instead). .LP @@ -84,23 +84,24 @@ via PTRACE_DETACH. The value of \fIrequest\fP determines the action to be performed: .TP PTRACE_TRACEME -Indicates that this process is to be traced by its parent. Any signal +Indicates that this process is to be traced by its parent. +Any signal (except SIGKILL) delivered to this process will cause it to stop and its parent to be notified via .BR wait (). Also, all subsequent calls to .BR exec () -by this process will cause a SIGTRAP to be sent to it, -giving the parent a chance to gain control before the new program -begins execution. -A process probably shouldn't make this request if its parent -isn't expecting to trace it. +by this process will cause a SIGTRAP to be sent to it, +giving the parent a chance to gain control before the new program +begins execution. +A process probably shouldn't make this request if its parent +isn't expecting to trace it. (\fIpid\fP, \fIaddr\fP, and \fIdata\fP are ignored.) .LP -The above request is used only by the child process; -the rest are used only by the parent. +The above request is used only by the child process; +the rest are used only by the parent. In the following requests, \fIpid\fP specifies the child process -to be acted on. +to be acted on. For requests other than PTRACE_KILL, the child process must be stopped. .TP @@ -109,9 +110,9 @@ Reads a word at the location .IR addr in the child's memory, returning the word as the result of the .BR ptrace () -call. +call. Linux does not have separate text and data address spaces, so the two -requests are currently equivalent. +requests are currently equivalent. (The argument \fIdata\fP is ignored.) .TP PTRACE_PEEKUSR @@ -119,11 +120,11 @@ Reads a word at offset .I addr in the child's .B USER -area, which holds the registers and other information about the process -(see and ). +area, which holds the registers and other information about the process +(see and ). The word is returned as the result of the .BR ptrace () -call. +call. Typically the offset must be word-aligned, though this might vary by architecture. (\fIdata\fP is ignored.) .TP @@ -132,7 +133,8 @@ Copies the word .IR data to location .IR addr -in the child's memory. As above, the two requests are currently equivalent. +in the child's memory. +As above, the two requests are currently equivalent. .TP PTRACE_POKEUSR Copies the word @@ -141,16 +143,16 @@ to offset .I addr in the child's .B USER -area. -As above, the offset must typically be word-aligned. -In order to maintain the integrity of the kernel, +area. +As above, the offset must typically be word-aligned. +In order to maintain the integrity of the kernel, some modifications to the .B USER area are disallowed. .TP PTRACE_GETREGS, PTRACE_GETFPREGS -Copies the child's general purpose or floating-point registers, -respectively, to location \fIdata\fP in the parent. +Copies the child's general purpose or floating-point registers, +respectively, to location \fIdata\fP in the parent. See for information on the format of this data. (\fIaddr\fP is ignored.) .TP @@ -162,60 +164,62 @@ from the child to location \fIdata\fP in the parent. (\fIaddr\fP is ignored.) .TP PTRACE_SETREGS, PTRACE_SETFPREGS -Copies the child's general purpose or floating-point registers, -respectively, from location \fIdata\fP in the parent. +Copies the child's general purpose or floating-point registers, +respectively, from location \fIdata\fP in the parent. As for PTRACE_POKEUSER, some general -purpose register modifications may be disallowed. +purpose register modifications may be disallowed. (\fIaddr\fP is ignored.) .TP PTRACE_SETSIGINFO (since Linux 2.3.99-pre6) Set signal information. -Copies a \fIsiginfo_t\fP structure from location \fIdata\fP in the +Copies a \fIsiginfo_t\fP structure from location \fIdata\fP in the parent to the child. This will only affect signals that would normally be delivered to -the child and were caught by the tracer. It may be difficult to tell +the child and were caught by the tracer. +It may be difficult to tell these normal signals from synthetic signals generated by .BR ptrace () itself. (\fIaddr\fP is ignored.) .TP PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats) -Sets ptrace options from \fIdata\fP in the parent. +Sets ptrace options from \fIdata\fP in the parent. (\fIaddr\fP is ignored.) \fIdata\fP is interpreted as a bitmask of options, which are specified by the following flags: .RS .TP PTRACE_O_TRACESYSGOOD (since Linux 2.4.6) -When delivering syscall traps, set bit 7 in the signal number -(i.e., deliver (SIGTRAP | 0x80) +When delivering syscall traps, set bit 7 in the signal number +(i.e., deliver (SIGTRAP | 0x80) This makes it easy for the tracer to tell the difference -between normal traps and those caused by a syscall. +between normal traps and those caused by a syscall. (PTRACE_O_TRACESYSGOOD may not work on all architectures.) .TP PTRACE_O_TRACEFORK (since Linux 2.5.46) Stop the child at the next .BR fork () -call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically -start tracing the newly forked process, +call with SIGTRAP | PTRACE_EVENT_FORK << 8 and automatically +start tracing the newly forked process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. .TP PTRACE_O_TRACEVFORK (since Linux 2.5.46) Stop the child at the next .BR vfork () -call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start +call with SIGTRAP | PTRACE_EVENT_VFORK << 8 and automatically start tracing the newly vforked process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. .TP PTRACE_O_TRACECLONE (since Linux 2.5.46) Stop the child at the next .BR clone () -call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start +call with SIGTRAP | PTRACE_EVENT_CLONE << 8 and automatically start tracing the newly cloned process, which will start with a SIGSTOP. The PID for the new process can be retrieved with PTRACE_GETEVENTMSG. This option may not catch .BR clone () -calls in all cases. If the child calls +calls in all cases. +If the child calls .BR clone () with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be delivered instead if PTRACE_O_TRACEVFORK is set; otherwise if the child calls @@ -236,93 +240,96 @@ call with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8. PTRACE_O_TRACEEXIT (since Linux 2.5.60) Stop the child at exit with SIGTRAP | PTRACE_EVENT_EXIT << 8. The child's exit status can be retrieved with PTRACE_GETEVENTMSG. -This stop will be done early during process exit when registers -are still available, allowing the tracer to see where the exit occurred, -whereas the normal exit notification is done after the process +This stop will be done early during process exit when registers +are still available, allowing the tracer to see where the exit occurred, +whereas the normal exit notification is done after the process is finished exiting. Even though context is available, the tracer cannot prevent the exit from happening at this point. .RE .TP PTRACE_GETEVENTMSG (since Linux 2.5.46) -Retrieve a message (as an -.IR "unsigned long" ) +Retrieve a message (as an +.IR "unsigned long" ) about the ptrace event that just happened, placing it in the location \fIdata\fP in the parent. -For PTRACE_EVENT_EXIT this is the child's exit status. For -PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE this -is the PID of the new process. +For PTRACE_EVENT_EXIT this is the child's exit status. +For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE this +is the PID of the new process. Since Linux 2.6.18, the PID of the new process is also available for PTRACE_EVENT_VFORK_DONE. (\fIaddr\fP is ignored.) .TP PTRACE_CONT -Restarts the stopped child process. If \fIdata\fP is non-zero and not +Restarts the stopped child process. +If \fIdata\fP is non-zero and not SIGSTOP, it is interpreted as a signal to be delivered to the child; -otherwise, no signal is delivered. +otherwise, no signal is delivered. Thus, for example, the parent can control -whether a signal sent to the child is delivered or not. +whether a signal sent to the child is delivered or not. (\fIaddr\fP is ignored.) .TP PTRACE_SYSCALL, PTRACE_SINGLESTEP -Restarts the stopped child as for PTRACE_CONT, but arranges for -the child to be stopped at the next entry to or exit from a system call, -or after execution of a single instruction, respectively. -(The child will also, as usual, be stopped upon receipt of a signal.) -From the parent's perspective, the child will appear to have been -stopped by receipt of a SIGTRAP. -So, for PTRACE_SYSCALL, for example, the idea is to inspect -the arguments to the system call at the first stop, -then do another PTRACE_SYSCALL and inspect the return value of -the system call at the second stop. +Restarts the stopped child as for PTRACE_CONT, but arranges for +the child to be stopped at the next entry to or exit from a system call, +or after execution of a single instruction, respectively. +(The child will also, as usual, be stopped upon receipt of a signal.) +From the parent's perspective, the child will appear to have been +stopped by receipt of a SIGTRAP. +So, for PTRACE_SYSCALL, for example, the idea is to inspect +the arguments to the system call at the first stop, +then do another PTRACE_SYSCALL and inspect the return value of +the system call at the second stop. (\fIaddr\fP is ignored.) .TP PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14) For PTRACE_SYSEMU, continue and stop on entry to the next syscall, -which will not be executed. For PTRACE_SYSEMU_SINGLESTEP, do the same -but also singlestep if not a syscall. This call is used by programs like +which will not be executed. +For PTRACE_SYSEMU_SINGLESTEP, do the same +but also singlestep if not a syscall. +This call is used by programs like User Mode Linux that want to emulate all the child's system calls. -(\fIaddr\fP and \fIdata\fP are ignored; +(\fIaddr\fP and \fIdata\fP are ignored; not supported on all architectures.) .TP PTRACE_KILL -Sends the child a SIGKILL to terminate it. +Sends the child a SIGKILL to terminate it. (\fIaddr\fP and \fIdata\fP are ignored.) .TP PTRACE_ATTACH Attaches to the process specified in .IR pid , -making it a traced "child" of the current process; -the behavior of the child is as if it had done a PTRACE_TRACEME. -The current process actually becomes the parent of the child +making it a traced "child" of the current process; +the behavior of the child is as if it had done a PTRACE_TRACEME. +The current process actually becomes the parent of the child process for most purposes (e.g., it will receive notification of child events and appears in .BR ps (1) output as the child's parent), but a .BR getppid (2) -by the child will still return the PID of the original parent. -The child is sent a SIGSTOP, but will not necessarily have stopped +by the child will still return the PID of the original parent. +The child is sent a SIGSTOP, but will not necessarily have stopped by the completion of this call; use .BR wait () -to wait for the child to stop. +to wait for the child to stop. (\fIaddr\fP and \fIdata\fP are ignored.) .TP PTRACE_DETACH -Restarts the stopped child as for PTRACE_CONT, but first detaches -from the process, undoing the reparenting effect of PTRACE_ATTACH, -and the effects of PTRACE_TRACEME. -Although perhaps not intended, under Linux a traced child can be +Restarts the stopped child as for PTRACE_CONT, but first detaches +from the process, undoing the reparenting effect of PTRACE_ATTACH, +and the effects of PTRACE_TRACEME. +Although perhaps not intended, under Linux a traced child can be detached in this way regardless of which method was used to initiate -tracing. +tracing. (\fIaddr\fP is ignored.) .SH NOTES Although arguments to .BR ptrace () -are interpreted according to the prototype given, +are interpreted according to the prototype given, GNU libc currently declares .BR ptrace () -as a variadic function with only the \fIrequest\fP argument fixed. -This means that unneeded trailing arguments may be omitted, +as a variadic function with only the \fIrequest\fP argument fixed. +This means that unneeded trailing arguments may be omitted, though doing so makes use of undocumented .BR gcc (1) behavior. @@ -333,18 +340,18 @@ the process with PID 1, may not be traced. The layout of the contents of memory and the USER area are quite OS- and architecture-specific. .LP -The size of a "word" is determined by the OS variant +The size of a "word" is determined by the OS variant (e.g., for 32-bit Linux it's 32 bits, etc.). .LP -Tracing causes a few subtle differences in the semantics of +Tracing causes a few subtle differences in the semantics of traced processes. -For example, if a process is attached to with PTRACE_ATTACH, -its original parent can no longer receive notification via +For example, if a process is attached to with PTRACE_ATTACH, +its original parent can no longer receive notification via .BR wait () -when it stops, and there is no way for the new parent to +when it stops, and there is no way for the new parent to effectively simulate this notification. .LP -When the parent receives an event with PTRACE_EVENT_* set, +When the parent receives an event with PTRACE_EVENT_* set, the child is not in the normal signal delivery path. This means the parent cannot do .BR ptrace (PTRACE_CONT) @@ -356,32 +363,32 @@ after receiving one of these messages. .LP This page documents the way the .BR ptrace () -call works currently in Linux. -Its behavior differs noticeably on other flavors of Unix. +call works currently in Linux. +Its behavior differs noticeably on other flavors of Unix. In any case, use of .BR ptrace () is highly OS- and architecture-specific. .LP -The SunOS man page describes +The SunOS man page describes .BR ptrace () -as "unique and arcane", which it is. +as "unique and arcane", which it is. 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 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. +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 BUGS -On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared -with a different value than the one for 2.4. +On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared +with a different value than the one for 2.4. This leads to applications compiled with such headers failing when run on 2.4 kernels. This can be worked around by redefining PTRACE_SETOPTIONS to @@ -389,38 +396,39 @@ PTRACE_OLDSETOPTIONS, if that is defined. .SH ERRORS .TP .B EBUSY -(i386 only) There was an error with allocating or freeing a debug +(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 +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, +\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 +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 +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 +.BR init (PID 1). .TP .B ESRCH -The specified process does not exist, or is not currently being traced +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 diff --git a/man2/query_module.2 b/man2/query_module.2 index cc9f83235..733b55032 100644 --- a/man2/query_module.2 +++ b/man2/query_module.2 @@ -2,7 +2,7 @@ .\" This file is distributed according to the GNU General Public License. .\" See the file COPYING in the top level source directory for details. .\" -.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" .TH QUERY_MODULE 2 "2002" "Linux" "Linux Module Support" @@ -12,7 +12,7 @@ query_module \- query the kernel for various bits pertaining to modules .nf .B #include .sp -.BI "int query_module(const char *" name ", int " which ", void *" buf , +.BI "int query_module(const char *" name ", int " which ", void *" buf , .BI " size_t " bufsize ", size_t *" ret ); .fi .SH DESCRIPTION @@ -22,7 +22,7 @@ The returned information is placed in the buffer pointed to by .IR buf . The caller must specify the size of .I buf -in +in .IR bufsize . The precise nature and format of the returned information depend on the operation specified by @@ -37,11 +37,11 @@ The following values can be specified for .IR which : .TP .B 0 -Always returns success. +Always returns success. Used to probe for availability of the system call. .TP .B QM_MODULES -Returns the names of all loaded modules. +Returns the names of all loaded modules. The returned buffer consists of a sequence of null-terminated strings; .I ret is set to the number of @@ -54,8 +54,8 @@ The returned buffer consists of a sequence of null-terminated strings; is set to the number of modules. .TP .B QM_REFS -Returns the names of all modules using the indicated module. This is -the inverse of +Returns the names of all modules using the indicated module. +This is the inverse of .BR QM_DEPS . The returned buffer consists of a sequence of null-terminated strings; .I ret @@ -63,7 +63,7 @@ is set to the number of modules. .TP .B QM_SYMBOLS Returns the symbols and values exported by the kernel or the indicated -module. +module. The returned buffer is an array of structures of the following form .RS .PP @@ -84,8 +84,8 @@ is set to the number of symbols. .RE .TP .B QM_INFO -Returns miscellaneous information about the indicated module. The output -buffer format is: +Returns miscellaneous information about the indicated module. +The output buffer format is: .RS .PP .nf @@ -105,8 +105,8 @@ is the size of the module in bytes, and is a mask of .BR MOD_RUNNING , .BR MOD_AUTOCLEAN , -etc. that indicates the current status of the module -(see the kernel source file +etc. that indicates the current status of the module +(see the kernel source file .IR include/linux/module.h ). .I ret is set to the size of the @@ -114,7 +114,8 @@ is set to the size of the structure. .RE .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned and +On success, zero is returned. +On error, \-1 is returned and .I errno is set appropriately. .SH ERRORS @@ -132,7 +133,7 @@ Invalid .IR which ; or .I name -is NULL (indicating "the kernel"), +is NULL (indicating "the kernel"), but this is not permitted with the specified value of .IR which . .\" Not permitted with QM_DEPS, QM_REFS, or QM_INFO. @@ -150,14 +151,14 @@ is set to the minimum size needed. .BR query_module () is Linux specific. .SH NOTES -This system call is only present on Linux up until kernel 2.4; +This system call is only present on Linux up until kernel 2.4; it was removed in Linux 2.6. .\" Removed in Linux-2.5.48 Some of the information that was available via .BR query_module () can be obtained from .IR /proc/modules , -.IR /proc/kallsyms , +.IR /proc/kallsyms , and .IR /sys/modules . .SH "SEE ALSO" diff --git a/man2/quotactl.2 b/man2/quotactl.2 index bcde2e24e..b5b3b3000 100644 --- a/man2/quotactl.2 +++ b/man2/quotactl.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,11 +50,11 @@ .\" Q_SETINFO .\" Q_SETQUOTA .\" Q_SYNC -.\" Q_V1_GETQUOTA Q_V1_GETSTATS Q_V1_RSQUASH Q_V1_SETQLIM +.\" Q_V1_GETQUOTA Q_V1_GETSTATS Q_V1_RSQUASH Q_V1_SETQLIM .\" Q_V1_SETQUOTA Q_V1_SETUSE -.\" Q_V2_GETINFO Q_V2_GETQUOTA Q_V2_SETFLAGS Q_V2_SETGRACE +.\" Q_V2_GETINFO Q_V2_GETQUOTA Q_V2_SETFLAGS Q_V2_SETGRACE .\" Q_V2_SETINFO Q_V2_SETQUOTA Q_V2_SETUSE -.\" Q_XGETQSTAT Q_XGETQUOTA Q_XQUOTAOFF Q_XQUOTAON Q_XQUOTARM +.\" Q_XGETQSTAT Q_XGETQUOTA Q_XQUOTAOFF Q_XQUOTAON Q_XQUOTARM .\" Q_XSETQLIM .\" .\" Linux 2.6.16 has: @@ -97,14 +97,17 @@ quotactl \- manipulate disk quota .SH DESCRIPTION The quota system defines for each user and/or group a soft limit and a hard limit bounding the amount of disk space that can be -used on a given file system. The hard limit cannot be crossed. -The soft limit can be crossed, but warnings will ensue. Moreover, +used on a given file system. +The hard limit cannot be crossed. +The soft limit can be crossed, but warnings will ensue. +Moreover, the user cannot be above the soft limit for more than one week (by default) at a time: after this week the soft limit counts as hard limit. The .BR quotactl () -system call manipulates these quota. Its first argument is +system call manipulates these quota. +Its first argument is of the form .BI QCMD( subcmd , type ) where @@ -135,7 +138,8 @@ The is one of .TP 1.1i .B Q_QUOTAON -Enable quota. The +Enable quota. +The .I addr argument is the pathname of the file containing the quota for the filesystem. @@ -144,7 +148,8 @@ the quota for the filesystem. Disable quota. .TP .B Q_GETQUOTA -Get limits and current usage of disk space. The +Get limits and current usage of disk space. +The .I addr argument is a pointer to a dqblk structure (defined in .IR ). @@ -170,7 +175,8 @@ Get collected stats. .SH "RETURN VALUE" On success, .BR quotactl () -returns 0. On error, \-1 is returned, and +returns 0. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -189,7 +195,8 @@ value. .TP .B EINVAL .I type -is not a known quota type. Or, +is not a known quota type. +Or, .I special could not be found. .TP diff --git a/man2/read.2 b/man2/read.2 index 09bd205c5..f049099d0 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -66,7 +66,8 @@ because we are reading from a pipe, or from a terminal), or because \fBread\fP() was interrupted by a signal. On error, \-1 is returned, and .I errno -is set appropriately. In this case it is left unspecified whether +is set appropriately. +In this case it is left unspecified whether the file position (if any) changes. .SH ERRORS .TP @@ -89,7 +90,7 @@ The call was interrupted by a signal before any data was read. .B EINVAL .I fd is attached to an object which is unsuitable for reading; -or the file was opened with the +or the file was opened with the .B O_DIRECT flag, and either the address specified in .IR buf , @@ -98,10 +99,12 @@ the value specified in or the current file offset is not suitably aligned. .TP .B EIO -I/O error. This will happen for example when the process is in a +I/O error. +This will happen for example when the process is in a background process group, tries to read from its controlling tty, and either it is ignoring or blocking SIGTTIN or its process group -is orphaned. It may also occur when there is a low-level I/O error +is orphaned. +It may also occur when there is a low-level I/O error while reading from a disk or tape. .TP .B EISDIR @@ -120,19 +123,22 @@ set to EINTR) or to return the number of bytes already read. SVr4, 4.3BSD, POSIX.1-2001. .SH RESTRICTIONS On NFS file systems, reading small amounts of data will only update the -time stamp the first time, subsequent calls may not do so. This is caused +time stamp the first time, subsequent calls may not do so. +This is caused by client side attribute caching, because most if not all NFS clients -leave st_atime (last file access time) +leave st_atime (last file access time) updates to the server and client side reads satisfied from the client's cache will not cause st_atime updates on the server as there are no -server side reads. UNIX semantics can be obtained by disabling client +server side reads. +UNIX semantics can be obtained by disabling client side attribute caching, but in most situations this will substantially increase server load and decrease performance. .PP -Many filesystems and disks were considered to be fast enough that the -implementation of +Many filesystems and disks were considered to be fast enough that the +implementation of .B O_NONBLOCK -was deemed unnecessary. So, O_NONBLOCK may not be available on files +was deemed unnecessary. +So, O_NONBLOCK may not be available on files and/or disks. .SH "SEE ALSO" .BR close (2), diff --git a/man2/readahead.2 b/man2/readahead.2 index 87d0089e4..eca9ea40f 100644 --- a/man2/readahead.2 +++ b/man2/readahead.2 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,7 +45,7 @@ argument specifies the starting point from which data is to be read and .I count specifies the number of bytes to be read. -I/O is performed in whole pages, so that +I/O is performed in whole pages, so that .I offset is effectively rounded down to a page boundary and bytes are read up to the next page boundary greater than or @@ -59,7 +59,7 @@ The current file offset of the open file referred to by .I fd is left unchanged. .SH "RETURN VALUE" -On success, +On success, .BR readahead () returns 0; on failure, \-1 is returned, with .I errno @@ -76,7 +76,7 @@ does not refer to a file type to which .BR readahead () can be applied. .SH "CONFORMING TO" -The +The .BR readahead () system call is Linux specific, and its use should be avoided in portable applications. diff --git a/man2/readdir.2 b/man2/readdir.2 index 8756d9c89..b6e4f4e9b 100644 --- a/man2/readdir.2 +++ b/man2/readdir.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -59,7 +59,7 @@ pointed at by .I fd into the memory area pointed to by .IR dirp . -The parameter +The parameter .I count is ignored; at most one dirent structure is read. .PP diff --git a/man2/readlink.2 b/man2/readlink.2 index eacd5b917..db2360d60 100644 --- a/man2/readlink.2 +++ b/man2/readlink.2 @@ -111,7 +111,7 @@ Nowadays, the return type is declared as as (newly) required in POSIX.1-2001. .\" FIXME . In 2005-04-01, the return type was changed to the .\" the POSIX compliant 'size_t'. When this is actually released -.\" we should udate the above prototype and add a NOTE about the +.\" we should udate the above prototype and add a NOTE about the .\" variation across glibc versions. .\" See http://sourceware.org/bugzilla/show_bug.cg1?id=2450 .\" diff --git a/man2/readlinkat.2 b/man2/readlinkat.2 index e055bf48c..d07d2d4e7 100644 --- a/man2/readlinkat.2 +++ b/man2/readlinkat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,14 +18,14 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" .TH READLINKAT 2 2006-07-21 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME -readlinkat \- read value of a symbolic link relative to +readlinkat \- read value of a symbolic link relative to a directory file descriptor .SH SYNOPSIS .nf @@ -42,37 +42,37 @@ system call operates in exactly the same way as .BR readlink (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR readlink (2) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR readlink (2)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .SH "RETURN VALUE" On success, -.BR readlinkat () -returns 0. +.BR readlinkat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -81,7 +81,7 @@ The same errors that occur for .BR readlink (2) can also occur for .BR readlinkat (). -The following additional errors can occur for +The following additional errors can occur for .BR readlinkat (): .TP .B EBADF diff --git a/man2/readv.2 b/man2/readv.2 index 6ba22ca1e..061e16a80 100644 --- a/man2/readv.2 +++ b/man2/readv.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -103,8 +103,8 @@ The sum of the .I iov_len values overflows an .I ssize_t -value. Or, -the vector count \fIcount\fR is less than zero or greater than the +value. +Or, the vector count \fIcount\fR is less than zero or greater than the permitted maximum. .SH "CONFORMING TO" 4.4BSD (the @@ -117,7 +117,7 @@ and \fIint\fP as return type for these functions. .\" The readv/writev system calls were buggy before Linux 1.3.40. .\" (Says release.libc.) .SH "LINUX NOTES" -POSIX.1-2001 allows an implementation to place a limit on +POSIX.1-2001 allows an implementation to place a limit on the number of items that can be passed in .IR vector . An implementation can advertise its limit by defining @@ -130,16 +130,17 @@ On Linux, the limit advertised by these mechanisms is 1024, which is the true kernel limit. However, the glibc wrapper functions do some extra work if they detect that the underlying kernel system call failed because this -limit was exceeded. In the case of +limit was exceeded. +In the case of .BR readv () -the wrapper function allocates a temporary buffer large enough +the wrapper function allocates a temporary buffer large enough for all of the items specified by .IR vector , -passes that buffer in a call to +passes that buffer in a call to .BR read (), copies data from the buffer to the locations specified by the .I iov_base -fields of the elements of +fields of the elements of .IR vector , and then frees the buffer. The wrapper function for diff --git a/man2/reboot.2 b/man2/reboot.2 index 41529c5f0..175afc8b5 100644 --- a/man2/reboot.2 +++ b/man2/reboot.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" Modified, 27 May 2004, Michael Kerrisk @@ -46,7 +46,7 @@ system call: .sp .BI "int reboot(int " flag ); .SH DESCRIPTION -The +The .BR reboot () call reboots the system, or enables/disables the reboot keystroke (abbreviated CAD, since the default is Ctrl-Alt-Delete; @@ -123,7 +123,8 @@ anything at present (2.1.122), but the type of reboot can be determined by kernel command line arguments (`reboot=...') to be either warm or cold, and either hard or through the BIOS. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -135,14 +136,14 @@ Problem with getting userspace data under LINUX_REBOOT_CMD_RESTART2. Bad magic numbers or \fIflag\fP. .TP .B EPERM -The calling process has insufficient privilege to call +The calling process has insufficient privilege to call .BR reboot (); the .B CAP_SYS_BOOT capability is required. .SH "CONFORMING TO" .BR reboot () -is Linux specific, +is Linux specific, and should not be used in programs intended to be portable. .SH "SEE ALSO" .BR sync (2), diff --git a/man2/recv.2 b/man2/recv.2 index 723da156f..e16770787 100644 --- a/man2/recv.2 +++ b/man2/recv.2 @@ -49,7 +49,7 @@ recv, recvfrom, recvmsg \- receive a message from a socket .sp .BI "ssize_t recv(int " s ", void *" buf ", size_t " len ", int " flags ); .sp -.BI "ssize_t recvfrom(int " s ", void *" buf ", size_t " len ", int " flags , +.BI "ssize_t recvfrom(int " s ", void *" buf ", size_t " len ", int " flags , .BI " struct sockaddr *" from ", socklen_t *" fromlen ); .sp .BI "ssize_t recvmsg(int " s ", struct msghdr *" msg ", int " flags ); @@ -82,9 +82,9 @@ associated with and modified on return to indicate the actual size of the address stored there. .PP -The +The .BR recv () -call is normally used only on a +call is normally used only on a .I connected socket (see .BR connect (2)) @@ -92,10 +92,11 @@ and is identical to .BR recvfrom () with a NULL .I from -parameter. +parameter. .PP All three routines return the length of the message on successful -completion. If a message is too long to fit in the supplied buffer, excess +completion. +If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from. .PP @@ -110,16 +111,16 @@ The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested. .PP The -.BR select (2) +.BR select (2) or .BR poll (2) call may be used to determine when more data arrives. .PP The .I flags -argument to a +argument to a .BR recv () -call is formed by +call is formed by .IR OR 'ing one or more of the following values: .TP @@ -138,7 +139,8 @@ specifies that queued errors should be received from the socket error queue. The error is passed in an ancillary message with a type dependent on the protocol (for IPv4 .BR IP_RECVERR ). -The user should supply a buffer of sufficient size. See +The user should supply a buffer of sufficient size. +See .BR cmsg (3) and .BR ip (7) @@ -162,7 +164,7 @@ After an error has been passed, the pending socket error is regenerated based on the next queued error and will be passed on the next socket operation. -The error is supplied in a +The error is supplied in a .I sock_extended_err structure: .in +0.25i @@ -176,79 +178,85 @@ structure: struct sock_extended_err { u_int32_t ee_errno; /* error number */ - u_int8_t ee_origin; /* where the error originated */ + u_int8_t ee_origin; /* where the error originated */ u_int8_t ee_type; /* type */ u_int8_t ee_code; /* code */ u_int8_t ee_pad; u_int32_t ee_info; /* additional information */ - u_int32_t ee_data; /* other data */ - /* More data may follow */ + u_int32_t ee_data; /* other data */ + /* More data may follow */ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); .fi .in -0.25i .IP -.B ee_errno -contains the errno number of the queued error. +.B ee_errno +contains the errno number of the queued error. .B ee_origin -is the origin code of where the error originated. -The other fields are protocol specific. The macro -.B SOCK_EE_OFFENDER +is the origin code of where the error originated. +The other fields are protocol specific. +The macro +.B SOCK_EE_OFFENDER returns a pointer to the address of the network object where the error originated from given a pointer to the ancillary message. If this address is not known, the -.I sa_family -member of the -.B sockaddr -contains +.I sa_family +member of the +.B sockaddr +contains .B AF_UNSPEC -and the other fields of the -.B sockaddr -are undefined. The payload of the packet -that caused the error is passed as normal data. +and the other fields of the +.B sockaddr +are undefined. +The payload of the packet that caused the error is passed as normal data. .IP For local errors, no address is passed (this -can be checked with the -.I cmsg_len -member of the -.IR cmsghdr ). +can be checked with the +.I cmsg_len +member of the +.IR cmsghdr ). For error receives, -the -.B MSG_ERRQUEUE -is set in the -.IR msghdr . +the +.B MSG_ERRQUEUE +is set in the +.IR msghdr . After an error has been passed, the pending socket error is regenerated based on the next queued error and will be passed on the next socket operation. .TP .B MSG_OOB This flag requests receipt of out-of-band data that would not be received -in the normal data stream. Some protocols place expedited data +in the normal data stream. +Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. .TP .B MSG_PEEK -This flag causes the receive operation to return data from the beginning of the -receive queue without removing that data from the queue. Thus, a +This flag causes the receive operation to +return data from the beginning of the +receive queue without removing that data from the queue. +Thus, a subsequent receive call will return the same data. .TP .B MSG_TRUNC Return the real length of the packet, even when it was longer than -the passed buffer. Only valid for packet sockets. +the passed buffer. +Only valid for packet sockets. .TP .B MSG_WAITALL This flag requests that the operation block until the full request is -satisfied. However, the call may still return less data than requested if +satisfied. +However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. .PP The .BR recvmsg () -call uses a +call uses a .I msghdr -structure to minimize the number of directly supplied parameters. This -structure has the following form, as defined in +structure to minimize the number of directly supplied parameters. +This structure has the following form, as defined in .IR : .in +0.25i .nf @@ -282,13 +290,14 @@ The field .IR msg_control , which has length .IR msg_controllen , -points to a buffer for other protocol control related messages or -miscellaneous ancillary data. When +points to a buffer for other protocol control related messages or +miscellaneous ancillary data. +When .BR recvmsg () -is called, +is called, .I msg_controllen -should contain the length of the available buffer in -.IR msg_control ; +should contain the length of the available buffer in +.IR msg_control ; upon return from a successful call it will contain the length of the control message sequence. .PP @@ -306,11 +315,11 @@ struct cmsghdr { .fi .in -0.25i .PP -Ancillary data should only be accessed by the macros defined in +Ancillary data should only be accessed by the macros defined in .BR cmsg (3). .PP As an example, Linux uses this auxiliary data mechanism to pass extended -errors, IP options or file descriptors over Unix sockets. +errors, IP options or file descriptors over Unix sockets. .PP The .I msg_flags @@ -339,12 +348,14 @@ indicates that no data was received but an extended error from the socket error queue. .SH "RETURN VALUE" These calls return the number of bytes received, or \-1 -if an error occurred. The return value will be 0 when the +if an error occurred. +The return value will be 0 when the peer has performed an orderly shutdown. .SH ERRORS -These are some standard errors generated by the socket layer. Additional errors -may be generated and returned from the underlying protocol modules; see their -manual pages. +These are some standard errors generated by the socket layer. +Additional errors +may be generated and returned from the underlying protocol modules; +see their manual pages. .TP .B EAGAIN The socket is marked non-blocking and the receive operation @@ -369,12 +380,12 @@ The receive was interrupted by delivery of a signal before any data were available. .TP .B EINVAL -Invalid argument passed. +Invalid argument passed. .\" e.g., msg_namelen < 0 for recvmsg() or fromlen < 0 for recvfrom() .TP .B ENOMEM -Could not allocate memory for -.BR recvmsg (). +Could not allocate memory for +.BR recvmsg (). .TP .B ENOTCONN The socket is associated with a connection-oriented protocol @@ -420,7 +431,7 @@ field of the .I msghdr structure should be typed as .IR socklen_t , -but glibc currently (2.4) types it as +but glibc currently (2.4) types it as .IR size_t . .\" glibc bug raised 12 Mar 2006 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 index a997bdf68..e05e8aba9 100644 --- a/man2/remap_file_pages.2 +++ b/man2/remap_file_pages.2 @@ -51,7 +51,7 @@ Use .BR mmap () to create a mapping (which is initially linear). This mapping must be created with the -.B MAP_SHARED +.B MAP_SHARED flag. .TP \fB2.\fP @@ -97,12 +97,12 @@ and .I size should be multiples of the system page size. If they are not, then the kernel rounds -.I both -values +.I both +values .I down to the nearest multiple of the page size. -.\" This rounding is weird, and not consistent with the treatment of -.\" the analogous arguments for munmap()/mprotect() and for mlock(). +.\" This rounding is weird, and not consistent with the treatment of +.\" the analogous arguments for munmap()/mprotect() and for mlock(). .\" MTK, 14 Sep 2005 The @@ -113,8 +113,8 @@ The .I flags argument has the same meaning as for .BR mmap (), -but all flags other than -.B MAP_NONBLOCK +but all flags other than +.B MAP_NONBLOCK are ignored. .SH "RETURN VALUE" On success, @@ -132,8 +132,8 @@ system call appeared in Linux 2.5.46. .B EINVAL .I start does not refer to a valid mapping -created with the -.B MAP_SHARED +created with the +.B MAP_SHARED flag. .TP .B EINVAL diff --git a/man2/removexattr.2 b/man2/removexattr.2 index 8e3152b66..66b095e49 100644 --- a/man2/removexattr.2 +++ b/man2/removexattr.2 @@ -57,7 +57,7 @@ and associated with the given in the filesystem. .PP .BR lremovexattr () -is identical to +is identical to .BR removexattr (), except in the case of a symbolic link, where the extended attribute is removed from the link itself, not the file that it refers to. diff --git a/man2/rename.2 b/man2/rename.2 index 0c38d83d5..7d1b61edd 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -72,7 +72,7 @@ in place. .I oldpath can specify a directory. -In this case, +In this case, .I newpath must either not exist, or it must specify an empty directory. @@ -89,7 +89,8 @@ refers to a symbolic link the link is renamed; if .I newpath refers to a symbolic link the link will be overwritten. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -217,10 +218,13 @@ even if the same filesystem is mounted on both.) 4.3BSD, C89, C99, POSIX.1-2001. .SH BUGS On NFS filesystems, you can not assume that if the operation -failed the file was not renamed. If the server does the rename operation +failed the file was not renamed. +If the server does the rename operation and then crashes, the retransmitted RPC which will be processed when the -server is up again causes a failure. The application is expected to -deal with this. See +server is up again causes a failure. +The application is expected to +deal with this. +See .BR link (2) for a similar problem. .SH "SEE ALSO" diff --git a/man2/renameat.2 b/man2/renameat.2 index 2ff2e42d5..c82f0857e 100644 --- a/man2/renameat.2 +++ b/man2/renameat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,7 +31,7 @@ renameat \- rename a file relative to directory file descriptors .B #define _ATFILE_SOURCE .B #include .sp -.BI "int renameat(int " olddirfd ", const char *" oldpath , +.BI "int renameat(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath ); .fi .SH DESCRIPTION @@ -41,45 +41,45 @@ system call operates in exactly the same way as .BR rename (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I oldpath is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR olddirfd -(rather than relative to the current working directory of +.IR olddirfd +(rather than relative to the current working directory of the calling process, as is done by .BR rename (2) for a relative pathname). If .I oldpath -is relative and +is relative and .I olddirfd is the special value .BR AT_FDCWD , then .I oldpath -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR rename (2)). If .IR oldpath -is absolute, then -.I olddirfd +is absolute, then +.I olddirfd is ignored. The interpretation of .I newpath -is as for -.IR oldpath , +is as for +.IR oldpath , except that a relative pathname is interpreted relative to the directory referred to by the file descriptor .IR newdirfd . .SH "RETURN VALUE" On success, -.BR renameat () -returns 0. +.BR renameat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -88,7 +88,7 @@ The same errors that occur for .BR rename (2) can also occur for .BR renameat (). -The following additional errors can occur for +The following additional errors can occur for .BR renameat (): .TP .B EBADF diff --git a/man2/rmdir.2 b/man2/rmdir.2 index 2797249ae..d9881680a 100644 --- a/man2/rmdir.2 +++ b/man2/rmdir.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,8 @@ rmdir \- delete a directory .BR rmdir () deletes a directory, which must be empty. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -95,10 +96,10 @@ is not, in fact, a directory. .I pathname contains entries other than .IR . " and " .. " ;" -or, +or, .I pathname has -.IR .. +.IR .. as its final component. .TP .B EPERM @@ -106,8 +107,8 @@ The directory containing .I pathname has the sticky bit .RB ( S_ISVTX ) -set and the process's effective user ID is neither the user ID -of the file to be deleted nor that of the directory containing it, +set and the process's effective user ID is neither the user ID +of the file to be deleted nor that of the directory containing it, and the process is not privileged (Linux: does not have the .B CAP_FOWNER capability). diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 index 330ff3985..ed73019f8 100644 --- a/man2/sched_get_priority_max.2 +++ b/man2/sched_get_priority_max.2 @@ -43,24 +43,26 @@ returns the maximum priority value that can be used with the scheduling algorithm identified by \fIpolicy\fR. .BR sched_get_priority_min () returns the minimum priority value that can be used with the -scheduling algorithm identified by \fIpolicy\fR. Supported \fIpolicy\fR +scheduling algorithm identified by \fIpolicy\fR. +Supported \fIpolicy\fR values are -.IR SCHED_FIFO , +.IR SCHED_FIFO , .IR SCHED_RR , .IR SCHED_OTHER , -and +and .IR SCHED_BATCH . Further details about these policies can be found in .BR sched_setscheduler (2). Processes with numerically higher priority values are scheduled before -processes with numerically lower priority values. Thus, the value +processes with numerically lower priority values. +Thus, the value returned by \fBsched_get_priority_max\fR() will be greater than the value returned by \fBsched_get_priority_min\fR(). Linux allows the static priority value range 1 to 99 for \fISCHED_FIFO\fR and \fISCHED_RR\fR and the priority 0 for -\fISCHED_OTHER\fR and \fISCHED_BATCH\fP. +\fISCHED_OTHER\fR and \fISCHED_BATCH\fP. Scheduling priority ranges for the various policies are not alterable. diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 index c13c7bd22..11057b2b8 100644 --- a/man2/sched_rr_get_interval.2 +++ b/man2/sched_rr_get_interval.2 @@ -37,7 +37,7 @@ sched_rr_get_interval \- get the SCHED_RR interval for the named process .SH DESCRIPTION .BR sched_rr_get_interval () writes into the \fItimespec\fR structure pointed to by \fItp\fR the -round-robin time quantum for the process identified by \fIpid\fR. +round-robin time quantum for the process identified by \fIpid\fR. The \fItimespec\fR structure has the following form: @@ -53,12 +53,12 @@ struct timespec { If \fIpid\fR is zero, the time quantum for the calling process is written into *\fItp\fR. The identified process should be running under the -.I SCHED_RR +.I SCHED_RR scheduling policy. .\" The round-robin time quantum value is not alterable under Linux .\" 1.3.81. -.\" +.\" POSIX systems on which .BR sched_rr_get_interval () is available define @@ -95,7 +95,7 @@ The quantum can be controlled by adjusting the process's nice value (see Assigning a negative (i.e., high) nice value results in a longer quantum; assigning a positive (i.e., low) nice value results in a shorter quantum. The default quantum is 0.1 seconds; -the degree to which changing the nice value affects the +the degree to which changing the nice value affects the quantum has varied somewhat across kernel versions. .\" .SH BUGS .\" As of Linux 1.3.81 \fBsched_rr_get_interval\fR() returns with error diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2 index 76988e3c6..142ce14d0 100644 --- a/man2/sched_setaffinity.2 +++ b/man2/sched_setaffinity.2 @@ -26,7 +26,7 @@ .\" 2002-11-19 Robert Love - initial version .\" 2004-04-20 mtk - fixed description of return value .\" 2004-04-22 aeb - added glibc prototype history -.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread +.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread .\" migration and that CPU affinity is a per-thread attribute. .\" 2006-02-03 mtk -- Major rewrite .\" @@ -56,19 +56,19 @@ sched_setaffinity, sched_getaffinity, CPU_CLR, CPU_ISSET, CPU_SET, CPU_ZERO \ A process's CPU affinity mask determines the set of CPUs on which it is eligible to run. On a multiprocessor system, setting the CPU affinity mask -can be used to obtain performance benefits. +can be used to obtain performance benefits. For example, -by dedicating one CPU to a particular process -(i.e., setting the affinity mask of that process to specify a single CPU, -and setting the affinity mask of all other processes to exclude that CPU), +by dedicating one CPU to a particular process +(i.e., setting the affinity mask of that process to specify a single CPU, +and setting the affinity mask of all other processes to exclude that CPU), it is possible to ensure maximum execution speed for that process. Restricting a process to run on a single CPU also prevents -the performance cost caused by the cache invalidation that occurs -when a process ceases to execute on one CPU and then +the performance cost caused by the cache invalidation that occurs +when a process ceases to execute on one CPU and then recommences execution on a different CPU. -A CPU affinity mask is represented by the -.I cpu_set_t +A CPU affinity mask is represented by the +.I cpu_set_t structure, a "CPU set", pointed to by .IR mask . Four macros are provided to manipulate CPU sets. @@ -89,7 +89,7 @@ value of 0, the next CPU corresponds to a value of 1, and so on. The constant .B CPU_SETSIZE -(1024) specifies a value one greater than the maximum CPU +(1024) specifies a value one greater than the maximum CPU number that can be stored in a CPU set. .BR sched_setaffinity () @@ -117,11 +117,11 @@ then that process is migrated to one of the CPUs specified in .BR sched_getaffinity () writes the affinity mask of the process whose ID is .IR pid -into the +into the .I cpu_set_t structure pointed to by .IR mask . -The +The .I cpusetsize argument specifies the size (in bytes) of .IR mask . @@ -146,9 +146,9 @@ A supplied memory address was invalid. The affinity bitmask .I mask contains no processors that are physically on the system, -.\" The following can only (?) occur with the raw sched_getaffinity() +.\" The following can only (?) occur with the raw sched_getaffinity() .\" system call (MTK, 3 Feb 2006): -or +or .I cpusetsize is smaller than the size of the affinity mask used by the kernel. .TP @@ -175,28 +175,28 @@ The value returned from a call to can be passed in the argument .IR pid . -A child created via +A child created via .BR fork (2) inherits its parent's CPU affinity mask. The affinity mask is preserved across an .BR execve (2). This manual page describes the glibc interface for the CPU affinity calls. -The actual system call interface is slightly different, with the +The actual system call interface is slightly different, with the .I mask being typed as .IR "unsigned long *" , -reflecting that the fact that the underlying implementation of CPU +reflecting that the fact that the underlying implementation of CPU sets is a simple bitmask. -On success, the raw +On success, the raw .BR sched_getaffinity () -system call returns the size (in bytes) of the +system call returns the size (in bytes) of the .I cpumask_t -data type that is used internally by the kernel to +data type that is used internally by the kernel to represent the CPU set bitmask. .SH "HISTORY" The CPU affinity system calls were introduced in Linux kernel 2.5.8. -The library interfaces were introduced in glibc 2.3. +The library interfaces were introduced in glibc 2.3. Initially, the glibc interfaces included a .I cpusetsize argument. diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 index 54e12fe47..3308028f0 100644 --- a/man2/sched_setparam.2 +++ b/man2/sched_setparam.2 @@ -48,27 +48,31 @@ sched_setparam, sched_getparam \- set and get scheduling parameters .SH DESCRIPTION .BR sched_setparam () sets the scheduling parameters associated with the scheduling policy -for the process identified by \fIpid\fR. If \fIpid\fR is zero, then -the parameters of the current process are set. The interpretation of -the parameter \fIparam\fR depends on the scheduling +for the process identified by \fIpid\fR. +If \fIpid\fR is zero, then +the parameters of the current process are set. +The interpretation of +the parameter \fIparam\fR depends on the scheduling policy of the process identified by -.IR pid . -See +.IR pid . +See .BR sched_setscheduler (2) for a description of the scheduling policies supported under Linux. .BR sched_getparam () -retrieves the scheduling parameters for the -process identified by \fIpid\fR. If \fIpid\fR is zero, then the parameters -of the current process are retrieved. +retrieves the scheduling parameters for the +process identified by \fIpid\fR. +If \fIpid\fR is zero, then the parameters +of the current process are retrieved. .BR sched_setparam () checks the validity of \fIparam\fR for the scheduling policy of the -process. The parameter \fIparam->sched_priority\fR must lie within the +process. +The parameter \fIparam->sched_priority\fR must lie within the range given by \fBsched_get_priority_min\fR(2) and \fBsched_get_priority_max\fR(2). -For a discussion of the privileges and resource limits related to +For a discussion of the privileges and resource limits related to scheduling priority and policy, see .BR sched_setscheduler (2). diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 index 0bfab8861..228854d01 100644 --- a/man2/sched_setscheduler.2 +++ b/man2/sched_setscheduler.2 @@ -28,7 +28,7 @@ .\" revision .\" 1999-08-18 David A. Wheeler added Note. .\" Modified, 25 Jun 2002, Michael Kerrisk -.\" Corrected description of queue placement by sched_setparam() and +.\" Corrected description of queue placement by sched_setparam() and .\" sched_setscheduler() .\" A couple of grammar clean-ups .\" Modified 2004-05-27 by Michael Kerrisk @@ -57,14 +57,17 @@ set and get scheduling algorithm/parameters .SH DESCRIPTION .BR sched_setscheduler () sets both the scheduling policy and the associated parameters for the -process identified by \fIpid\fP. If \fIpid\fP equals zero, the -scheduler of the calling process will be set. The interpretation of -the parameter \fIparam\fP depends on the selected policy. Currently, the +process identified by \fIpid\fP. +If \fIpid\fP equals zero, the +scheduler of the calling process will be set. +The interpretation of +the parameter \fIparam\fP depends on the selected policy. +Currently, the following three scheduling policies are supported under Linux: -.IR SCHED_FIFO , +.IR SCHED_FIFO , .IR SCHED_RR , .IR SCHED_OTHER , -.\" In the 2.6 kernel sources, SCHED_OTHER is actually called +.\" In the 2.6 kernel sources, SCHED_OTHER is actually called .\" SCHED_NORMAL. and .IR SCHED_BATCH ; @@ -72,20 +75,26 @@ their respective semantics are described below. .BR sched_getscheduler () queries the scheduling policy currently applied to the process -identified by \fIpid\fP. If \fIpid\fP equals zero, the policy of the +identified by \fIpid\fP. +If \fIpid\fP equals zero, the policy of the calling process will be retrieved. .SS Scheduling Policies The scheduler is the kernel part that decides which runnable process -will be executed by the CPU next. The Linux scheduler offers three +will be executed by the CPU next. +The Linux scheduler offers three different scheduling policies, one for normal processes and two for -real-time applications. A static priority value \fIsched_priority\fP +real-time applications. +A static priority value \fIsched_priority\fP is assigned to each process and this value can be changed only via -system calls. Conceptually, the scheduler maintains a list of runnable +system calls. +Conceptually, the scheduler maintains a list of runnable processes for each possible \fIsched_priority\fP value, and -\fIsched_priority\fP can have a value in the range 0 to 99. In order +\fIsched_priority\fP can have a value in the range 0 to 99. +In order to determine the process that runs next, the Linux scheduler looks for the non-empty list with the highest static priority and takes the -process at the head of this list. The scheduling policy determines for +process at the head of this list. +The scheduling policy determines for each process, where it will be inserted into the list of processes with equal static priority and how it will move inside this list. @@ -95,12 +104,12 @@ policy used by most processes. \fISCHED_FIFO\fP and \fISCHED_RR\fP are intended for special time-critical applications that need precise control over the way in which runnable processes are selected for -execution. +execution. Processes scheduled with \fISCHED_OTHER\fP or \fISCHED_BATCH\fP must be assigned the static priority 0. Processes scheduled under \fISCHED_FIFO\fP or -\fISCHED_RR\fP can have a static priority in the range 1 to 99. +\fISCHED_RR\fP can have a static priority in the range 1 to 99. The system calls \fBsched_get_priority_min\fP() and \fBsched_get_priority_max\fP() can be used to find out the valid priority range for a scheduling policy in a portable way on all @@ -108,22 +117,26 @@ POSIX.1-2001 conforming systems. All scheduling is preemptive: If a process with a higher static priority gets ready to run, the current process will be preempted and -returned into its wait list. The scheduling policy only determines the +returned into its wait list. +The scheduling policy only determines the ordering within the list of runnable processes with equal static priority. .SS SCHED_FIFO: First In-First Out scheduling \fISCHED_FIFO\fP can only be used with static priorities higher than 0, which means that when a \fISCHED_FIFO\fP processes becomes runnable, it will always immediately preempt any currently running -\fISCHED_OTHER\fP or \fISCHED_BATCH\fP process. +\fISCHED_OTHER\fP or \fISCHED_BATCH\fP process. \fISCHED_FIFO\fP is a simple scheduling -algorithm without time slicing. For processes scheduled under the +algorithm without time slicing. +For processes scheduled under the \fISCHED_FIFO\fP policy, the following rules are applied: A \fISCHED_FIFO\fP process that has been preempted by another process of higher priority will stay at the head of the list for its priority and will resume execution as soon as all processes of higher priority are -blocked again. When a \fISCHED_FIFO\fP process becomes runnable, it -will be inserted at the end of the list for its priority. A call to +blocked again. +When a \fISCHED_FIFO\fP process becomes runnable, it +will be inserted at the end of the list for its priority. +A call to \fBsched_setscheduler\fP() or \fBsched_setparam\fP() will put the \fISCHED_FIFO\fP (or \fISCHED_RR\fP) process identified by \fIpid\fP at the start of the list if it was runnable. @@ -134,21 +147,27 @@ of the list.) .\" In 2.2.x and 2.4.x, the process is placed at the front of the queue .\" In 2.0.x, the Right Thing happened: the process went to the back -- MTK A process calling \fBsched_yield\fP() will be -put at the end of the list. No other events will move a process +put at the end of the list. +No other events will move a process scheduled under the \fISCHED_FIFO\fP policy in the wait list of -runnable processes with equal static priority. A \fISCHED_FIFO\fP +runnable processes with equal static priority. +A \fISCHED_FIFO\fP process runs until either it is blocked by an I/O request, it is preempted by a higher priority process, or it calls \fBsched_yield\fP(). .SS SCHED_RR: Round Robin scheduling -\fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP. Everything +\fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP. +Everything described above for \fISCHED_FIFO\fP also applies to \fISCHED_RR\fP, except that each process is only allowed to run for a maximum time -quantum. If a \fISCHED_RR\fP process has been running for a time +quantum. +If a \fISCHED_RR\fP process has been running for a time period equal to or longer than the time quantum, it will be put at the -end of the list for its priority. A \fISCHED_RR\fP process that has +end of the list for its priority. +A \fISCHED_RR\fP process that has been preempted by a higher priority process and subsequently resumes execution as a running process will complete the unexpired portion of -its round robin time quantum. The length of the time quantum can be +its round robin time quantum. +The length of the time quantum can be retrieved using \fBsched_rr_get_interval\fP(2). .\" On Linux 2.4, the length of the RR interval is influenced .\" by the process nice value -- MTK @@ -157,12 +176,15 @@ retrieved using \fBsched_rr_get_interval\fP(2). \fISCHED_OTHER\fP can only be used at static priority 0. \fISCHED_OTHER\fP is the standard Linux time-sharing scheduler that is intended for all processes that do not require special static priority -real-time mechanisms. The process to run is chosen from the static +real-time mechanisms. +The process to run is chosen from the static priority 0 list based on a dynamic priority that is determined only -inside this list. The dynamic priority is based on the nice level (set +inside this list. +The dynamic priority is based on the nice level (set by \fBnice\fP(2) or \fBsetpriority\fP(2)) and increased for each time quantum the process is ready to run, but denied to run by -the scheduler. This ensures fair progress among all \fISCHED_OTHER\fP +the scheduler. +This ensures fair progress among all \fISCHED_OTHER\fP processes. .SS SCHED_BATCH: Scheduling batch processes (Since Linux 2.6.16.) @@ -173,24 +195,24 @@ that the process is CPU-intensive. Consequently, the scheduler will apply a small scheduling penalty so that this process is mildly disfavoured in scheduling decisions. -.\" The following paragraph is drawn largely from the text that -.\" accompanied Ingo Molnar's patch for the implementation of +.\" The following paragraph is drawn largely from the text that +.\" accompanied Ingo Molnar's patch for the implementation of .\" SCHED_BATCH. This policy is useful for workloads that are non-interactive, -but do not want to lower their nice value, -and for workloads that want a deterministic scheduling policy without +but do not want to lower their nice value, +and for workloads that want a deterministic scheduling policy without interactivity causing extra preemptions (between the workload's tasks). .SS Privileges and resource limits .\" FIXME make some general statement about Unix implementations -.\" A process calling +.\" A process calling .\" .BR sched_setscheduler -.\" needs an effective user ID equal to the real user ID or effective +.\" needs an effective user ID equal to the real user ID or effective .\" user ID of the process identified by .\" .IR pid , .\" or it must be privileged (Linux: have the .\" .B CAP_SYS_NICE .\" capability). -.\" +.\" In Linux kernels before 2.6.12, only privileged .RB ( CAP_SYS_NICE ) processes can set a non-zero static priority. @@ -198,7 +220,7 @@ The only change that an unprivileged process can make is to set the .B SCHED_OTHER policy, and this can only be done if the effective user ID of the caller of .BR sched_setscheduler () -matches the real or effective user ID of the target process +matches the real or effective user ID of the target process (i.e., the process specified by .IR pid ) whose policy is being changed. @@ -209,21 +231,21 @@ resource limit defines a ceiling on an unprivileged process's priority for the .B SCHED_RR and -.BR SCHED_FIFO +.BR SCHED_FIFO policies. -If an unprivileged process has a non-zero +If an unprivileged process has a non-zero .B RLIMIT_RTPRIO -soft limit, then it can change its scheduling policy and priority, -subject to the restriction that the priority cannot be set to a -value higher than the +soft limit, then it can change its scheduling policy and priority, +subject to the restriction that the priority cannot be set to a +value higher than the .B RLIMIT_RTPRIO soft limit. -If the +If the .B RLIMIT_RTPRIO soft limit is 0, then the only permitted change is to lower the priority. -Subject to the same rules, -another unprivileged process can also make these changes, -as long as the effective user ID of the process making the change +Subject to the same rules, +another unprivileged process can also make these changes, +as long as the effective user ID of the process making the change matches the real or effective user ID of the target process. See .BR getrlimit (2) @@ -235,7 +257,8 @@ processes ignore this limit; as with older kernels, they can make arbitrary changes to scheduling policy and priority. .SS Response time A blocked high priority process waiting for the I/O has a certain -response time before it is scheduled again. The device driver writer +response time before it is scheduled again. +The device driver writer can greatly reduce this response time by using a "slow interrupt" interrupt handler. .\" as described in @@ -243,20 +266,21 @@ interrupt handler. .SS Miscellaneous Child processes inherit the scheduling algorithm and parameters across a .BR fork (). -The scheduling algorithm and parameters are preserved across +The scheduling algorithm and parameters are preserved across .BR execve (2). -Memory locking is usually needed for real-time processes to avoid +Memory locking is usually needed for real-time processes to avoid paging delays, this can be done with .BR mlock () -or +or .BR mlockall (). As a non-blocking end-less loop in a process scheduled under \fISCHED_FIFO\fP or \fISCHED_RR\fP will block all processes with lower priority forever, a software developer should always keep available on the console a shell scheduled under a higher static priority than the -tested application. This will allow an emergency kill of tested +tested application. +This will allow an emergency kill of tested real-time applications that do not block or terminate as expected. POSIX systems on which @@ -269,10 +293,10 @@ in . .SH "RETURN VALUE" On success, .BR sched_setscheduler () -returns zero. +returns zero. On success, .BR sched_getscheduler () -returns the policy for the process (a non-negative integer). +returns the policy for the process (a non-negative integer). On error, \-1 is returned, and .I errno is set appropriately. diff --git a/man2/sched_yield.2 b/man2/sched_yield.2 index 32a1114a0..9a3815733 100644 --- a/man2/sched_yield.2 +++ b/man2/sched_yield.2 @@ -36,7 +36,7 @@ sched_yield \- yield the processor \fBint sched_yield(void); .fi .SH DESCRIPTION -A process can relinquish the processor voluntarily without blocking by calling +A process can relinquish the processor voluntarily without blocking by calling .BR sched_yield (). The process will then be moved to the end of the queue for its static priority and a new process gets to run. diff --git a/man2/select.2 b/man2/select.2 index 451a2884a..00dbdc531 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,7 +37,7 @@ .\" .TH SELECT 2 2006-03-11 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME -select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- synchronous I/O multiplexing .SH SYNOPSIS .nf @@ -53,7 +53,7 @@ synchronous I/O multiplexing .br .B #include .sp -\fBint select(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, +\fBint select(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, fd_set *\fIexceptfds\fB, struct timeval *\fItimeout\fB); .sp .BI "void FD_CLR(int " fd ", fd_set *" set ); @@ -67,8 +67,8 @@ synchronous I/O multiplexing .B #define _XOPEN_SOURCE 600 .B #include .sp -\fBint pselect(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, - fd_set *\fIexceptfds\fB, const struct timespec *\fItimeout\fB, +\fBint pselect(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, + fd_set *\fIexceptfds\fB, const struct timespec *\fItimeout\fB, const sigset_t *\fIsigmask\fB); .fi .SH DESCRIPTION @@ -79,7 +79,7 @@ allow a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" for some class of I/O operation (e.g., input possible). A file descriptor is considered ready if it is possible to -perform the corresponding I/O operation (e.g., +perform the corresponding I/O operation (e.g., .BR read (2)) without blocking. .PP @@ -116,7 +116,7 @@ argument, and behaves as called with NULL .IR sigmask . .PP -Three independent sets of file descriptors are watched. +Three independent sets of file descriptors are watched. Those listed in .I readfds will be watched to see if characters become @@ -127,10 +127,11 @@ those in will be watched to see if a write will not block, and those in .I exceptfds -will be watched for exceptions. On exit, the sets are modified in place +will be watched for exceptions. +On exit, the sets are modified in place to indicate which file descriptors actually changed status. Each of the three file descriptor sets may be specified as NULL -if no file descriptors are to be watched for the corresponding class +if no file descriptors are to be watched for the corresponding class of events. .PP Four macros are provided to manipulate the sets. @@ -141,7 +142,7 @@ and .BR FD_CLR () respectively add and remove a given file descriptor from a set. .BR FD_ISSET () -tests to see if a file descriptor is part of the set; +tests to see if a file descriptor is part of the set; this is useful after .BR select () returns. @@ -152,9 +153,12 @@ is the highest-numbered file descriptor in any of the three sets, plus 1. .I timeout is an upper bound on the amount of time elapsed before .BR select () -returns. It may be zero, causing +returns. +It may be zero, causing .BR select () -to return immediately. (This is useful for polling.) If +to return immediately. +(This is useful for polling.) +If .I timeout is NULL (no timeout), .BR select () @@ -172,12 +176,12 @@ signal mask. .PP Other than the difference in the precision of the .I timeout -argument, the following +argument, the following .BR pselect () call: .nf - ready = pselect(nfds, &readfds, &writefds, &exceptfds, + ready = pselect(nfds, &readfds, &writefds, &exceptfds, timeout, &sigmask); .fi @@ -193,16 +197,17 @@ executing the following calls: sigprocmask(SIG_SETMASK, &origmask, NULL); .fi .PP -The reason that +The reason that .BR pselect () is needed is that if one wants to wait for either a signal or for a file descriptor to become ready, then -an atomic test is needed to prevent race conditions. +an atomic test is needed to prevent race conditions. (Suppose the signal handler sets a global flag and -returns. Then a test of this global flag followed by a call of +returns. +Then a test of this global flag followed by a call of .BR select () could hang indefinitely if the signal arrived just after the test -but just before the call. +but just before the call. By contrast, .BR pselect () allows one to first block signals, handle the signals that have come in, @@ -218,7 +223,7 @@ and look like .in +0.25i .nf -struct timeval { +struct timeval { long tv_sec; /* seconds */ long tv_usec; /* microseconds */ }; @@ -246,7 +251,7 @@ zero, and a non-NULL .I timeout as a fairly portable way to sleep with subsecond precision. .PP -On Linux, +On Linux, .BR select () modifies .I timeout @@ -258,7 +263,8 @@ This causes problems both when Linux code which reads is ported to other operating systems, and when code is ported to Linux that reuses a struct timeval for multiple .BR select ()s -in a loop without reinitializing it. Consider +in a loop without reinitializing it. +Consider .I timeout to be undefined after .BR select () @@ -288,7 +294,7 @@ rely on their contents after an error. .TP .B EBADF An invalid file descriptor was given in one of the sets. -(Perhaps a file descriptor that was already closed, +(Perhaps a file descriptor that was already closed, or one on which an error has occurred.) .TP .B EINTR @@ -310,7 +316,7 @@ unable to allocate memory for internal tables. #include int -main(void) +main(void) { fd_set rfds; struct timeval tv; @@ -339,36 +345,39 @@ main(void) } .fi .SH "CONFORMING TO" -.BR select () -conforms to POSIX.1-2001 and -4.4BSD +.BR select () +conforms to POSIX.1-2001 and +4.4BSD .RB ( select () -first appeared in 4.2BSD). Generally portable to/from +first appeared in 4.2BSD). +Generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including -System V variants). However, note that the System V variant typically +System V variants). +However, note that the System V variant typically sets the timeout variable before exit, but the BSD variant does not. .PP .BR pselect () is defined in POSIX.1g, and in POSIX.1-2001. .SH NOTES -An -.I fd_set -is a fixed size buffer. -Executing +An +.I fd_set +is a fixed size buffer. +Executing .BR FD_CLR () -or +or .BR FD_SET () with a value of .I fd that is negative or is equal to or larger than FD_SETSIZE will result -in undefined behavior. Moreover, POSIX requires +in undefined behavior. +Moreover, POSIX requires .I fd to be a valid file descriptor. Concerning the types involved, the classical situation is that the two fields of a -.I timeval +.I timeval structure are longs (as shown above), and the structure is defined in .IR . @@ -385,10 +394,10 @@ struct timeval { where the structure is defined in .I -and the data types -.I time_t -and -.I suseconds_t +and the data types +.I time_t +and +.I suseconds_t are defined in .IR . .LP @@ -425,26 +434,26 @@ was emulated in glibc (but see BUGS). .SH "LINUX NOTES" The Linux .BR pselect () -system call modifies its -.I timeout +system call modifies its +.I timeout argument. However, the glibc wrapper function hides this behaviour by using a local variable for the timeout argument that is passed to the system call. -Thus, the glibc +Thus, the glibc .BR pselect () function does not modify its timeout argument; this is the behaviour required by POSIX.1-2001. .SH BUGS Glibc 2.0 provided a version of .BR pselect () -that did not take a -.I sigmask +that did not take a +.I sigmask argument. Since version 2.1, glibc has provided an emulation of -.BR pselect () -that is implemented using +.BR pselect () +that is implemented using .BR sigprocmask (2) and .BR select (). @@ -453,19 +462,21 @@ This implementation remains vulnerable to the very race condition that was designed to prevent. On systems that lack .BR pselect () -reliable (and more portable) signal trapping can be achieved -using the self-pipe trick +reliable (and more portable) signal trapping can be achieved +using the self-pipe trick (where a signal handler writes a byte to a pipe whose other end -is monitored by +is monitored by .BR select () in the main program.) Under Linux, .BR select () may report a socket file descriptor as "ready for reading", while -nevertheless a subsequent read blocks. This could for example +nevertheless a subsequent read blocks. +This could for example happen when data has arrived but upon examination has wrong -checksum and is discarded. There may be other circumstances +checksum and is discarded. +There may be other circumstances in which a file descriptor is spuriously reported as ready. .\" Stevens discusses a case where accept can block after select .\" returns successfully because of an intervening RST from the client. diff --git a/man2/select_tut.2 b/man2/select_tut.2 index b830efe3c..dc746da98 100644 --- a/man2/select_tut.2 +++ b/man2/select_tut.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -24,11 +24,11 @@ .\" .\" Modified 5 June 2002, Michael Kerrisk .\" 2006-05-13, mtk, removed much material that is redundant with select.2 -.\" various other changes +.\" various other changes .\" .TH SELECT_TUT 2 2006-05-13 "Linux" "Linux Programmer's Manual" .SH NAME -select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- synchronous I/O multiplexing .SH SYNOPSIS .nf @@ -44,7 +44,7 @@ synchronous I/O multiplexing .br .B #include .sp -\fBint select(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, +\fBint select(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, fd_set *\fIexceptfds\fB, struct timeval *\fItimeout\fB); .sp .BI "void FD_CLR(int " fd ", fd_set *" set ); @@ -58,20 +58,23 @@ synchronous I/O multiplexing .B #define _XOPEN_SOURCE 600 .B #include .sp -\fBint pselect(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, - fd_set *\fIexceptfds\fB, const struct timespec *\fItimeout\fB, +\fBint pselect(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, + fd_set *\fIexceptfds\fB, const struct timespec *\fItimeout\fB, const sigset_t *\fIsigmask\fB); .fi .SH DESCRIPTION -\fBselect\fP() (or \fBpselect\fP()) is the pivot function of +\fBselect\fP() (or \fBpselect\fP()) is the pivot function of most C programs that -handle more than one simultaneous file descriptor (or socket handle) +handle more than one simultaneous file descriptor (or socket handle) in an efficient -manner. Its principal arguments are three arrays of file descriptors: -\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP. The way that +manner. +Its principal arguments are three arrays of file descriptors: +\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP. +The way that \fBselect\fP() is usually used is to block while waiting for a "change of -status" on one or more of the file descriptors. A "change of status" is +status" on one or more of the file descriptors. +A "change of status" is when more characters become available from the file descriptor, \fIor\fP when space becomes available within the kernel's internal buffers for more to be written to the file descriptor, \fIor\fP when a file @@ -85,7 +88,8 @@ The arrays of file descriptors are called \fIfile descriptor sets\fP. Each set is declared as type \fBfd_set\fP, and its contents can be altered with the macros \fBFD_CLR\fP(), \fBFD_ISSET\fP(), \fBFD_SET\fP(), and \fBFD_ZERO\fP(). \fBFD_ZERO\fP() is usually the first function to be used on -a newly declared set. Thereafter, the individual file descriptors that +a newly declared set. +Thereafter, the individual file descriptors that you are interested in can be added one by one with \fBFD_SET\fP(). \fBselect\fP() modifies the contents of the sets according to the rules described below; after calling \fBselect\fP() you can test if your file @@ -96,14 +100,15 @@ it is not. \fBFD_CLR\fP() removes a file descriptor from the set. .TP \fIreadfds\fP This set is watched to see if data is available for reading from any of -its file descriptors. After \fBselect\fP() has returned, \fIreadfds\fP will be +its file descriptors. +After \fBselect\fP() has returned, \fIreadfds\fP will be cleared of all file descriptors except for those file descriptors that are immediately available for reading with a \fBrecv\fP() (for sockets) or \fBread\fP() (for pipes, files, and sockets) call. .TP \fIwritefds\fP This set is watched to see if there is space to write data to any of -its file descriptors. +its file descriptors. After \fBselect\fP() has returned, \fIwritefds\fP will be cleared of all file descriptors except for those file descriptors that are immediately available for writing with a \fBsend\fP() (for sockets) or @@ -111,21 +116,29 @@ are immediately available for writing with a \fBsend\fP() (for sockets) or .TP \fIexceptfds\fP This set is watched for exceptions or errors on any of the file -descriptors. However, that is actually just a rumor. How you use -\fIexceptfds\fP is to watch for \fIout\-of\-band\fP (OOB) data. OOB data +descriptors. +However, that is actually just a rumor. +How you use +\fIexceptfds\fP is to watch for \fIout\-of\-band\fP (OOB) data. +OOB data is data sent on a socket using the \fBMSG_OOB\fP flag, and hence -\fIexceptfds\fP only really applies to sockets. See \fBrecv\fP(2) and -\fBsend\fP(2) about this. After \fBselect\fP() has returned, +\fIexceptfds\fP only really applies to sockets. +See \fBrecv\fP(2) and +\fBsend\fP(2) about this. +After \fBselect\fP() has returned, \fIexceptfds\fP will be cleared of all file descriptors except for those -descriptors that are available for reading OOB data. You can only ever +descriptors that are available for reading OOB data. +You can only ever read one byte of OOB data though (which is done with \fBrecv\fP()), and writing OOB data (done with \fBsend\fP()) can be done at any time and will -not block. Hence there is no need for a fourth set to check if a socket +not block. +Hence there is no need for a fourth set to check if a socket is available for writing OOB data. .TP \fInfds\fP This is an integer one more than the maximum of any file descriptor in -any of the sets. In other words, while you are busy adding file descriptors +any of the sets. +In other words, while you are busy adding file descriptors to your sets, you must calculate the maximum integer value of all of them, then increment this value by one, and then pass this as \fInfds\fP to \fBselect\fP(). @@ -133,10 +146,12 @@ them, then increment this value by one, and then pass this as \fInfds\fP to \fIutimeout\fP .RS This is the longest time \fBselect\fP() must wait before returning, even -if nothing interesting happened. If this value is passed as NULL, +if nothing interesting happened. +If this value is passed as NULL, then \fBselect\fP() blocks indefinitely waiting for an event. \fIutimeout\fP can be set to zero seconds, which causes \fBselect\fP() to -return immediately. The structure \fBstruct timeval\fP is defined as, +return immediately. +The structure \fBstruct timeval\fP is defined as, .PP .nf struct timeval { @@ -160,44 +175,57 @@ struct timespec { .RE .TP \fIsigmask\fP -This argument holds a set of signals to allow while performing a -\fBpselect\fP() call (see \fBsigaddset\fP(3) and \fBsigprocmask\fP(2)). +This argument holds a set of signals to allow while performing a +\fBpselect\fP() call (see \fBsigaddset\fP(3) and \fBsigprocmask\fP(2)). It can be passed as NULL, in which case it does not modify the set of allowed signals on -entry and exit to the function. It will then behave just like \fBselect\fP(). +entry and exit to the function. +It will then behave just like \fBselect\fP(). .SH COMBINING SIGNAL AND DATA EVENTS \fBpselect\fP() must be used if you are waiting for a signal as well as -data from a file descriptor. Programs that receive signals as events -normally use the signal handler only to raise a global flag. The global +data from a file descriptor. +Programs that receive signals as events +normally use the signal handler only to raise a global flag. +The global flag will indicate that the event must be processed in the main loop of -the program. A signal will cause the \fBselect\fP() (or \fBpselect\fP()) -call to return with \fIerrno\fP set to \fBEINTR\fP. This behavior is +the program. +A signal will cause the \fBselect\fP() (or \fBpselect\fP()) +call to return with \fIerrno\fP set to \fBEINTR\fP. +This behavior is essential so that signals can be processed in the main loop of the -program, otherwise \fBselect\fP() would block indefinitely. Now, somewhere -in the main loop will be a conditional to check the global flag. So we +program, otherwise \fBselect\fP() would block indefinitely. +Now, somewhere +in the main loop will be a conditional to check the global flag. +So we must ask: what if a signal arrives after the conditional, but before the \fBselect\fP() call? The answer is that \fBselect\fP() would block -indefinitely, even though an event is actually pending. This race -condition is solved by the \fBpselect\fP() call. This call can be used to +indefinitely, even though an event is actually pending. +This race +condition is solved by the \fBpselect\fP() call. +This call can be used to mask out signals that are not to be received except within the -\fBpselect\fP() call. For instance, let us say that the event in question -was the exit of a child process. Before the start of the main loop, we -would block \fBSIGCHLD\fP using \fBsigprocmask\fP(). Our \fBpselect\fP() -call would enable \fBSIGCHLD\fP by using the virgin signal mask. Our +\fBpselect\fP() call. +For instance, let us say that the event in question +was the exit of a child process. +Before the start of the main loop, we +would block \fBSIGCHLD\fP using \fBsigprocmask\fP(). +Our \fBpselect\fP() +call would enable \fBSIGCHLD\fP by using the virgin signal mask. +Our program would look like: .PP .nf int child_events = 0; -void -child_sig_handler(int x) +void +child_sig_handler(int x) { child_events++; signal(SIGCHLD, child_sig_handler); } -int -main(int argc, char **argv) +int +main(int argc, char **argv) { sigset_t sigmask, orig_sigmask; @@ -219,19 +247,22 @@ main(int argc, char **argv) .fi .SH PRACTICAL So what is the point of \fBselect\fP()? Can't I just read and write to my -descriptors whenever I want? +descriptors whenever I want? The point of \fBselect\fP() is that it watches multiple descriptors at the same time and properly puts the process to -sleep if there is no activity. It does this while enabling you to handle -multiple simultaneous pipes and sockets. Unix programmers often find +sleep if there is no activity. +It does this while enabling you to handle +multiple simultaneous pipes and sockets. +Unix programmers often find themselves in a position where they have to handle I/O from more than one -file descriptor where the data flow may be intermittent. If you were to +file descriptor where the data flow may be intermittent. +If you were to merely create a sequence of \fBread\fP() and \fBwrite\fP() calls, you would find that one of your calls may block waiting for data from/to a file descriptor, while another file descriptor is unused though available for data. \fBselect\fP() efficiently copes with this situation. -A simple example of the use of +A simple example of the use of .BR select () can be found in the .BR select (2) @@ -260,8 +291,8 @@ static int forward_port; #undef max #define max(x,y) ((x) > (y) ? (x) : (y)) -static int -listen_socket(int listen_port) +static int +listen_socket(int listen_port) { struct sockaddr_in a; int s; @@ -290,8 +321,8 @@ listen_socket(int listen_port) return s; } -static int -connect_socket(int connect_port, char *address) +static int +connect_socket(int connect_port, char *address) { struct sockaddr_in a; int s; @@ -338,8 +369,8 @@ connect_socket(int connect_port, char *address) #define BUF_SIZE 1024 -int -main(int argc, char **argv) +int +main(int argc, char **argv) { int h; int fd1 = \-1, fd2 = \-1; @@ -507,31 +538,41 @@ main(int argc, char **argv) .fi .PP The above program properly forwards most kinds of TCP connections -including OOB signal data transmitted by \fBtelnet\fP servers. It +including OOB signal data transmitted by \fBtelnet\fP servers. +It handles the tricky problem of having data flow in both directions -simultaneously. You might think it more efficient to use a \fBfork\fP() -call and devote a thread to each stream. This becomes more tricky than -you might suspect. Another idea is to set non-blocking I/O using an -\fBioctl\fP() call. This also has its problems because you end up having +simultaneously. +You might think it more efficient to use a \fBfork\fP() +call and devote a thread to each stream. +This becomes more tricky than +you might suspect. +Another idea is to set non-blocking I/O using an +\fBioctl\fP() call. +This also has its problems because you end up having to have inefficient timeouts. The program does not handle more than one simultaneous connection at a 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 +of buffers \(em one for each connection. +At the moment, new connections cause the current connection to be dropped. .SH SELECT LAW Many people who try to use \fBselect\fP() come across behavior that is difficult to understand and produces non-portable or borderline -results. For instance, the above program is carefully written not to +results. +For instance, the above program is carefully written not to block at any point, even though it does not set its file descriptors to -non-blocking mode at all (see \fBioctl\fP(2)). It is easy to introduce +non-blocking mode at all (see \fBioctl\fP(2)). +It is easy to introduce subtle errors that will remove the advantage of using \fBselect\fP(), hence I will present a list of essentials to watch for when using the \fBselect\fP() call. .TP \fB1.\fP -You should always try to use \fBselect\fP() without a timeout. Your program -should have nothing to do if there is no data available. Code that +You should always try to use \fBselect\fP() without a timeout. +Your program +should have nothing to do if there is no data available. +Code that depends on timeouts is not usually portable and is difficult to debug. .TP \fB2.\fP @@ -541,11 +582,12 @@ explained above. \fB3.\fP No file descriptor must be added to any set if you do not intend to check its result after the \fBselect\fP() call, and respond -appropriately. See next rule. +appropriately. +See next rule. .TP \fB4.\fP After \fBselect\fP() returns, all file descriptors in all sets -should be checked to see if they are ready. +should be checked to see if they are ready. .\" mtk, May 2006: the following isn't really true. .\" Any file descriptor that is available .\" for writing \fImust\fP be written to, and any file descriptor @@ -554,14 +596,18 @@ should be checked to see if they are ready. \fB5.\fP The functions \fBread\fP(), \fBrecv\fP(), \fBwrite\fP(), and \fBsend\fP() do \fInot\fP necessarily read/write the full amount of data -that you have requested. If they do read/write the full amount, its -because you have a low traffic load and a fast stream. This is not -always going to be the case. You should cope with the case of your +that you have requested. +If they do read/write the full amount, its +because you have a low traffic load and a fast stream. +This is not +always going to be the case. +You should cope with the case of your functions only managing to send or receive a single byte. .TP \fB6.\fP Never read/write only in single bytes at a time unless your are really -sure that you have a small amount of data to process. It is extremely +sure that you have a small amount of data to process. +It is extremely inefficient not to read/write as much data as you can buffer each time. The buffers in the example above are 1024 bytes although they could easily be made larger. @@ -569,15 +615,18 @@ easily be made larger. \fB7.\fP The functions \fBread\fP(), \fBrecv\fP(), \fBwrite\fP(), and \fBsend\fP() as well as the \fBselect\fP() call can return \-1 with -.I errno -set to \fBEINTR\fP, -or with +.I errno +set to \fBEINTR\fP, +or with .I errno set to \fBEAGAIN\fP (\fBEWOULDBLOCK\fP). These results must be properly managed (not done properly -above). If your program is not going to receive any signals then -it is unlikely you will get \fBEINTR\fP. If your program does not -set non-blocking I/O, you will not get \fBEAGAIN\fP. Nonetheless +above). +If your program is not going to receive any signals then +it is unlikely you will get \fBEINTR\fP. +If your program does not +set non-blocking I/O, you will not get \fBEAGAIN\fP. +Nonetheless you should still cope with these errors for completeness. .TP \fB8.\fP @@ -587,11 +636,11 @@ with a buffer length of zero. \fB9.\fP If the functions \fBread\fP(), \fBrecv\fP(), \fBwrite\fP(), and \fBsend\fP() fail -with errors other than those listed in \fB7.\fP, -or one of the input functions returns 0, indicating end of file, +with errors other than those listed in \fB7.\fP, +or one of the input functions returns 0, indicating end of file, then you should \fInot\fP pass that descriptor to .BR select () -again. +again. In the above example, I close the descriptor immediately, and then set it to \-1 to prevent it being included in a set. @@ -603,8 +652,10 @@ however does not modify its timeout structure. .TP \fB11.\fP I have heard that the Windows socket layer does not cope with OOB data -properly. It also does not cope with \fBselect\fP() calls when no file -descriptors are set at all. Having no file descriptors set is a useful +properly. +It also does not cope with \fBselect\fP() calls when no file +descriptors are set at all. +Having no file descriptors set is a useful way to sleep the process with sub-second precision by using the timeout. (See further on.) .SH USLEEP EMULATION @@ -624,35 +675,36 @@ This is only guaranteed to work on Unix systems, however. On success, \fBselect\fP() returns the total number of file descriptors still present in the file descriptor sets. -If \fBselect\fP() timed out, then +If \fBselect\fP() timed out, then the return value will be zero. The file descriptors set should be all -empty (but may not be on some systems). +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 +set appropriately. +In the case of an error, the returned sets and the timeout struct contents are undefined and should not be used. \fBpselect\fP() however never modifies \fIntimeout\fP. .SH NOTES Generally speaking, all operating systems that support sockets, also -support \fBselect\fP(). +support \fBselect\fP(). Many types of programs become extremely complicated without the use of -.BR select (). +.BR select (). \fBselect\fP() 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 +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 \fBselect\fP(), -and is somewhat more efficient when monitoring sparse +and is somewhat more efficient when monitoring sparse file descriptor sets. -It is nowadays widely available, +It is nowadays widely available, but historically was less portable than \fBselect\fP(). .PP -The Linux-specific +The Linux-specific .BR epoll (7) API provides an interface that is more efficient than .BR select (2) diff --git a/man2/semctl.2 b/man2/semctl.2 index e4dbcf2ba..5c6455273 100644 --- a/man2/semctl.2 +++ b/man2/semctl.2 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,7 +36,7 @@ .\" Added semid_ds and ipc_perm structure definitions .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. .\" -.TH SEMCTL 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" +.TH SEMCTL 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" .SH NAME semctl \- semaphore control operations .SH SYNOPSIS @@ -70,7 +70,7 @@ union semun { int val; /* Value for SETVAL */ struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ unsigned short *array; /* Array for GETALL, SETALL */ - struct seminfo *__buf; /* Buffer for IPC_INFO + struct seminfo *__buf; /* Buffer for IPC_INFO (Linux specific) */ }; .in -4n @@ -136,14 +136,14 @@ to the kernel data structure associated with this semaphore set, updating also its .I sem_ctime member. -The following members of the structure are updated: +The following members of the structure are updated: .IR sem_perm.uid , .IR sem_perm.gid , and (the least significant 9 bits of) .IR sem_perm.mode . The effective UID of the calling process must match the owner .RI ( sem_perm.uid ) -or creator +or creator .RI ( sem_perm.cuid ) of the semaphore set, or the caller must be privileged. The argument @@ -166,7 +166,7 @@ The argument is ignored. .TP .BR IPC_INFO " (Linux specific)" -Returns information about system-wide semaphore limits and +Returns information about system-wide semaphore limits and parameters in the structure pointed to by .IR arg.__buf . This structure is of type @@ -178,26 +178,26 @@ if the _GNU_SOURCE feature test macro is defined: .in +2n struct seminfo { - int semmap; /* # of entries in semaphore map; + int semmap; /* # of entries in semaphore map; unused */ int semmni; /* Max. # of semaphore sets */ - int semmns; /* Max. # of semaphores in all + int semmns; /* Max. # of semaphores in all semaphore sets */ - int semmnu; /* System-wide max. # of undo + int semmnu; /* System-wide max. # of undo structures; unused */ int semmsl; /* Max. # of semaphores in a set */ int semopm; /* Max. # of operations for semop() */ - int semume; /* Max. # of undo entries per + int semume; /* Max. # of undo entries per process; unused */ int semusz; /* size of struct sem_undo */ int semvmx; /* Maximum semaphore value */ - int semaem; /* Max. value that can be recorded for + int semaem; /* Max. value that can be recorded for semaphore adjustment (SEM_UNDO) */ }; .in -2n .fi -The +The .IR semmsl , .IR semmns , .IR semopm , @@ -206,7 +206,7 @@ and settings can be changed via .IR /proc/sys/kernel/sem ; see -.BR proc (5) +.BR proc (5) for details. .TP .BR SEM_INFO " (Linux specific)" @@ -214,18 +214,18 @@ Returns a .I seminfo structure containing the same information as for .BR IPC_INFO , -except that the following fields are returned with information +except that the following fields are returned with information about system resources consumed by semaphores: the .I semusz -field returns the number of semaphore sets that currently exist +field returns the number of semaphore sets that currently exist on the system; and the .I semaem -field returns the total number of semaphores in all semaphore sets +field returns the total number of semaphores in all semaphore sets on the system. .TP .BR SEM_STAT " (Linux specific)" -Returns a -.I semid_ds +Returns a +.I semid_ds structure as for .BR IPC_STAT . However, the @@ -366,11 +366,11 @@ the index of the highest used entry in the kernel's internal array recording information about all semaphore sets. (This information can be used with repeated -.B SEM_STAT +.B SEM_STAT operations to obtain information about all semaphore sets on the system.) .TP .B SEM_INFO -As for +As for .BR IPC_INFO . .TP .B SEM_STAT @@ -421,7 +421,7 @@ or .IR semid . Or: for a .B SEM_STAT -operation, the index value specified in +operation, the index value specified in .I semid referred to an array slot that is currently unused. .TP diff --git a/man2/semget.2 b/man2/semget.2 index 94a462f44..5ee8c0dcf 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -76,11 +76,11 @@ and a semaphore set already exists for .IR key , then .BR semget () -fails with +fails with .I errno set to .BR EEXIST . -(This is analogous to the effect of the combination +(This is analogous to the effect of the combination .B O_CREAT | O_EXCL for .BR open (2).) @@ -99,20 +99,20 @@ not meaningful for semaphores, and write permissions mean permission to alter semaphore values). .PP The values of the semaphores in a newly created set are indeterminate. -(POSIX.1-2001 is explicit on this point.) +(POSIX.1-2001 is explicit on this point.) Although Linux, like many other implementations, initialises the semaphore values to 0, a portable application cannot rely on this: it should explicitly initialise the semaphores to the desired values. -.\" In truth, every one of the many implementations that I've tested sets -.\" the values to zero, but I suppose there is/was some obscure +.\" In truth, every one of the many implementations that I've tested sets +.\" the values to zero, but I suppose there is/was some obscure .\" implementation out there that does not. .PP When creating a new semaphore set, .BR semget () initialises the set's associated data structure, .I semid_ds -(see +(see .BR semctl (2)), as follows: .IP @@ -256,7 +256,7 @@ would more clearly show its function. .LP The semaphores in a set are not initialised by .BR semget (). -.\" In fact they are initialised to zero on Linux, but POSIX.1-2001 +.\" In fact they are initialised to zero on Linux, but POSIX.1-2001 .\" does not specify this, and we can't portably rely on it. In order to initialise the semaphores, .BR semctl (2) diff --git a/man2/semop.2 b/man2/semop.2 index 9f0ba3065..a7dc48a94 100644 --- a/man2/semop.2 +++ b/man2/semop.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -29,7 +29,7 @@ .\" Added notes on /proc files .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() .\" -.TH SEMOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" +.TH SEMOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" .SH NAME semop, semtimedop \- semaphore operations .SH SYNOPSIS @@ -90,9 +90,9 @@ it will be automatically undone when the process terminates. .PP The set of operations contained in .I sops -is performed in -.IR "array order" , -and +is performed in +.IR "array order" , +and .IR atomically , that is, the operations are performed either as a complete unit, or not at all. @@ -247,7 +247,7 @@ set to The calling process catches a signal: the value of .I semncnt -is decremented and +is decremented and .BR semop () fails, with .I errno @@ -275,7 +275,7 @@ In addition, the is set to the current time. .PP .BR semtimedop () -behaves identically to +behaves identically to .BR semop () except that in those cases were the calling process would sleep, the duration of that sleep is limited by the amount of elapsed @@ -283,7 +283,8 @@ time specified by the .B timespec structure whose address is passed in the .I timeout -parameter. If the specified time limit has been reached, +parameter. +If the specified time limit has been reached, .BR semtimedop () fails with .I errno @@ -302,7 +303,7 @@ behaves exactly like .SH "RETURN VALUE" If successful .BR semop () -and +and .BR semtimedop () return 0; otherwise they return \-1 @@ -463,8 +464,8 @@ Linux adopts a third approach: decreasing the semaphore value as far as possible (i.e., to zero) and allowing process termination to proceed immediately. -In kernels 2.6.x, x <= 10, there is a bug that in some circumstances -prevents a process that is waiting for a semaphore value to become +In kernels 2.6.x, x <= 10, there is a bug that in some circumstances +prevents a process that is waiting for a semaphore value to become zero from being woken up when the value does actually become zero. This bug is fixed in kernel 2.6.11. .\" The bug report: diff --git a/man2/send.2 b/man2/send.2 index 3e6235bd9..ab743078c 100644 --- a/man2/send.2 +++ b/man2/send.2 @@ -63,7 +63,7 @@ are used to transmit a message to another socket. .PP The .BR send () -call may be used only when the socket is in a +call may be used only when the socket is in a .I connected state (so that the intended recipient is known). The only difference between @@ -96,9 +96,10 @@ and .I tolen are ignored (and the error EISCONN may be returned when they are not NULL and 0), and the error ENOTCONN is returned when the socket was -not actually connected. Otherwise, the address of the target is given by +not actually connected. +Otherwise, the address of the target is given by .I to -with +with .I tolen specifying its size. For @@ -137,7 +138,8 @@ Locally detected errors are indicated by a return value of \-1. When the message does not fit into the send buffer of the socket, .BR send () normally blocks, unless the socket has been placed in non-blocking I/O -mode. In non-blocking mode it would return +mode. +In non-blocking mode it would return .B EAGAIN in this case. The @@ -152,20 +154,24 @@ of zero or more of the following flags. .TP .BR MSG_CONFIRM " (Linux 2.3+ only)" Tell the link layer that forward progress happened: you got a successful -reply from the other side. If the link layer doesn't get this +reply from the other side. +If the link layer doesn't get this it will regularly reprobe the neighbour (e.g. via a unicast ARP). -Only valid on +Only valid on .B SOCK_DGRAM and .B SOCK_RAW -sockets and currently only implemented for IPv4 and IPv6. See +sockets and currently only implemented for IPv4 and IPv6. +See .BR arp (7) for details. .TP .B MSG_DONTROUTE -Don't use a gateway to send out the packet, only send to hosts on -directly connected networks. This is usually used only -by diagnostic or routing programs. This is only defined for protocol +Don't use a gateway to send out the packet, only send to hosts on +directly connected networks. +This is usually used only +by diagnostic or routing programs. +This is only defined for protocol families that route; packet sockets don't. .TP .B MSG_DONTWAIT @@ -191,17 +197,18 @@ with the difference that this flag can be set on a per-call basis. Since Linux 2.6, this flag is also supported for UDP sockets, and informs the kernel to package all of the data sent in calls with this flag set into a single datagram which is only transmitted when a call is performed -that does not specify this flag. -(See also the -.B UDP_CORK -socket option described in +that does not specify this flag. +(See also the +.B UDP_CORK +socket option described in .BR udp (7).) .TP .B MSG_NOSIGNAL -Requests not to send -.B SIGPIPE +Requests not to send +.B SIGPIPE on errors on stream oriented sockets when the other end breaks the -connection. The +connection. +The .B EPIPE error is still returned. .TP @@ -216,7 +223,8 @@ data. .PP The definition of the .I msghdr -structure follows. See +structure follows. +See .BR recv (2) and below for an exact description of its fields. .in +0.25i @@ -234,13 +242,14 @@ struct msghdr { .fi .in -0.25i .PP -You may send control information using the -.I msg_control -and -.I msg_controllen -members. The maximum control buffer length the kernel can process is limited +You may send control information using the +.I msg_control +and +.I msg_controllen +members. +The maximum control buffer length the kernel can process is limited per socket by the -.B net.core.optmem_max +.B net.core.optmem_max sysctl; see .BR socket (7). .\" Still to be documented: @@ -253,15 +262,17 @@ On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -These are some standard errors generated by the socket layer. Additional errors -may be generated and returned from the underlying protocol modules; see their -respective manual pages. +These are some standard errors generated by the socket layer. +Additional errors +may be generated and returned from the underlying protocol modules; +see their respective manual pages. .TP .B EACCES (For Unix domain sockets, which are identified by pathname) Write permission is denied on the destination socket file, or search permission is denied for one of the directories -the path prefix. (See +the path prefix. +(See .BR path_resolution (2).) .TP .BR EAGAIN " or " EWOULDBLOCK @@ -302,7 +313,8 @@ of the message to be sent made this impossible. The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. -(Normally, this does not occur in Linux. Packets are just silently dropped +(Normally, this does not occur in Linux. +Packets are just silently dropped when a device queue overflows.) .TP .B ENOMEM @@ -324,10 +336,10 @@ argument is inappropriate for the socket type. .B EPIPE The local end has been shut down on a connection oriented socket. In this case the process -will also receive a -.B SIGPIPE -unless -.B MSG_NOSIGNAL +will also receive a +.B SIGPIPE +unless +.B MSG_NOSIGNAL is set. .SH "CONFORMING TO" 4.4BSD, SVr4, POSIX.1-2001. @@ -339,7 +351,7 @@ and .B MSG_EOR flags. The -.B MSG_CONFIRM +.B MSG_CONFIRM flag is a Linux extension. .SH NOTES The prototypes given above follow the Single Unix Specification, @@ -361,7 +373,7 @@ field of the .I msghdr structure should be typed as .IR socklen_t , -but glibc currently (2.4) types it as +but glibc currently (2.4) types it as .IR size_t . .\" glibc bug raised 12 Mar 2006 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 diff --git a/man2/sendfile.2 b/man2/sendfile.2 index a5ce8d6e6..ad70a1f2d 100644 --- a/man2/sendfile.2 +++ b/man2/sendfile.2 @@ -12,7 +12,7 @@ .\" .\" 2005-03-31 Martin Pool mmap() improvements .\" -.TH SENDFILE 2 2004-12-17 "Linux Man Page" "Linux Programmer's Manual" +.TH SENDFILE 2 2004-12-17 "Linux Man Page" "Linux Programmer's Manual" .SH NAME sendfile \- transfer data between file descriptors .SH SYNOPSIS @@ -25,7 +25,7 @@ sendfile \- transfer data between file descriptors .\" .\" .B #include .\" .br -.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 +.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 .\" .br .\" .B #include .\" .br @@ -33,7 +33,7 @@ sendfile \- transfer data between file descriptors .\" .br .\" .B #include .\" .br -.\" .B /* No system prototype before glibc 2.1. */ +.\" .B /* No system prototype before glibc 2.1. */ .\" .br .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ .\" offset ", size_t" " count" ) @@ -56,14 +56,14 @@ should be a file descriptor opened for reading and .I out_fd should be a descriptor opened for writing. -If +If .I offset is not NULL, then it points to a variable holding the file offset from which .BR sendfile () will start reading data from .IR in_fd . -When +When .BR sendfile () returns, this variable will be set to the offset of the byte following the last byte that was read. @@ -71,9 +71,9 @@ If .I offset is not NULL, then .BR sendfile () -does not modify the current file offset of +does not modify the current file offset of .IR in_fd ; -otherwise the current file offset is adjusted to reflect +otherwise the current file offset is adjusted to reflect the number of bytes read from .IR in_fd . @@ -82,7 +82,7 @@ is the number of bytes to copy between the file descriptors. Presently (Linux 2.6.9): .IR in_fd , -must correspond to a file which supports +must correspond to a file which supports .BR mmap ()-like operations (i.e., it cannot be a socket); @@ -96,12 +96,12 @@ in the case where .BR sendfile () fails with EINVAL or ENOSYS. .SH NOTES -If you plan to use -.BR sendfile () +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 +.B TCP_CORK option, described in .BR tcp (7), to minimize the number of packets and to tune performance. @@ -114,7 +114,8 @@ changed the current offset of that file. .SH "RETURN VALUE" If the transfer was successful, the number of bytes written to .I out_fd -is returned. On error, \-1 is returned, and +is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -132,7 +133,7 @@ was not opened for writing. Bad address. .TP .B EINVAL -Descriptor is not valid or locked, or an +Descriptor is not valid or locked, or an .BR mmap ()-like operation is not available for .IR in_fd . @@ -151,9 +152,9 @@ The include file is present since glibc2.1. .SH "CONFORMING TO" Not specified in POSIX.1-2001, or other standards. -Other Unix systems implement +Other Unix systems implement .BR sendfile () -with different semantics and prototypes. +with different semantics and prototypes. It should not be used in portable programs. .SH "SEE ALSO" .BR open (2), diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2 index 081b494c3..fc3bf3f90 100644 --- a/man2/set_mempolicy.2 +++ b/man2/set_mempolicy.2 @@ -8,15 +8,15 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. -.\" +.\" .\" 2006-02-03, mtk, substantial wording changes and other improvements .\" .TH SET_MEMPOLICY 2 "2006-02-07" "SuSE Labs" "Linux Programmer's Manual" @@ -24,83 +24,86 @@ set_mempolicy \- set default NUMA memory policy for a process and its children. .SH SYNOPSIS .nf -.B "#include " +.B "#include " .sp -.BI "int set_mempolicy(int " policy ", unsigned long *" nodemask , +.BI "int set_mempolicy(int " policy ", unsigned long *" nodemask , .BI " unsigned long " maxnode ); .fi .SH DESCRIPTION .BR set_mempolicy () -sets the NUMA memory policy of the calling process to +sets the NUMA memory policy of the calling process to .IR policy . A NUMA machine has different memory controllers with different distances to specific CPUs. -The memory policy defines in which node memory is allocated for -the process. +The memory policy defines in which node memory is allocated for +the process. This system call defines the default policy for the process; -in addition a policy can be set for specific memory ranges using +in addition a policy can be set for specific memory ranges using .BR mbind (2). The policy is only applied when a new page is allocated -for the process. For anonymous memory this is when the page is first +for the process. +For anonymous memory this is when the page is first touched by the application. -Available policies are +Available policies are .BR MPOL_DEFAULT , .BR MPOL_BIND , .BR MPOL_INTERLEAVE , .BR MPOL_PREFERRED . -All policies except +All policies except .B MPOL_DEFAULT require the caller to specify the nodes to which the policy applies in the -.I nodemask +.I nodemask parameter. -.I nodemask -is pointer to a bit field of nodes that contains up to +.I nodemask +is pointer to a bit field of nodes that contains up to .I maxnode -bits. The bit field size is rounded to the next multiple of -.IR "sizeof(unsigned long)" , -but the kernel will only use bits up to +bits. +The bit field size is rounded to the next multiple of +.IR "sizeof(unsigned long)" , +but the kernel will only use bits up to .IR maxnode . -The +The .B MPOL_DEFAULT -policy is the default and means to allocate memory locally, -i.e., on the node of the CPU that triggered the allocation. -.I nodemask +policy is the default and means to allocate memory locally, +i.e., on the node of the CPU that triggered the allocation. +.I nodemask should be specified as NULL. The .B MPOL_BIND -policy is a strict policy that restricts memory allocation to the -nodes specified in +policy is a strict policy that restricts memory allocation to the +nodes specified in .IR nodemask . There won't be allocations on other nodes. .B MPOL_INTERLEAVE -interleaves allocations to the nodes specified in +interleaves allocations to the nodes specified in .IR nodemask . This optimizes for bandwidth instead of latency. -To be effective the memory area should be fairly large, +To be effective the memory area should be fairly large, at least 1MB or bigger. .B MPOL_PREFERRED -sets the preferred node for allocation. +sets the preferred node for allocation. The kernel will try to allocate in this -node first and fall back to other nodes if the preferred node is low on free -memory. Only the first node in the -.I nodemask -is used. -If no node is set in the mask, then the memory is allocated on +node first and fall back to other nodes if the preferred node is low on free +memory. +Only the first node in the +.I nodemask +is used. +If no node is set in the mask, then the memory is allocated on the node of the CPU that triggered the allocation allocation (like .BR MPOL_DEFAULT ). The memory policy is preserved across an .BR execve (2), and is inherited by child processes created using -.BR fork (2) -or +.BR fork (2) +or .BR clone (2). .SH NOTES Process policy is not remembered if the page is swapped out. @@ -109,7 +112,7 @@ On success, .BR set_mempolicy () returns 0; on error, \-1 is returned and -.I errno +.I errno is set to indicate the error. .\" .SH ERRORS .\" FIXME writeme -- no errors are listed on this page diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2 index 260265729..52e4acaa8 100644 --- a/man2/set_thread_area.2 +++ b/man2/set_thread_area.2 @@ -15,12 +15,13 @@ set_thread_area \- Set a Thread Local Storage (TLS) area .BI "int set_thread_area(struct user_desc *" u_info ); .SH "DESCRIPTION" .BR set_thread_area () -sets an entry in the current thread's Thread Local Storage (TLS) array. +sets an entry in the current thread's Thread Local Storage (TLS) array. The TLS array entry set by .BR set_thread_area () corresponds to the value of .I u_info->entry_number -passed in by the user. If this value is in bounds, +passed in by the user. +If this value is in bounds, .BR set_thread_area () copies the TLS descriptor pointed to by .I u_info @@ -30,9 +31,10 @@ When .BR set_thread_area () is passed an .I entry_number -of \-1, it uses a free TLS entry. If +of \-1, it uses a free TLS entry. +If .BR set_thread_area () -finds a free TLS entry, the value of +finds a free TLS entry, the value of .I u_info->entry_number is set upon return to show which entry was changed. .SH "RETURN VALUE" diff --git a/man2/set_tid_address.2 b/man2/set_tid_address.2 index d3c540a45..8f75f8690 100644 --- a/man2/set_tid_address.2 +++ b/man2/set_tid_address.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -54,7 +54,7 @@ If a process is started using .BR clone (2) with the .B CLONE_CHILD_CLEARTID -flag, +flag, .I clear_child_tid is set to .IR child_tidptr , @@ -73,7 +73,8 @@ is set, and the process exits, and the process was sharing memory with other processes or threads, then 0 is written at this address, and a .I futex(child_tidptr, FUTEX_WAKE, 1, NULL, NULL, 0); -call is done. (That is, wake a single process waiting on this futex.) +call is done. +(That is, wake a single process waiting on this futex.) Errors are ignored. .SH "RETURN VALUE" .BR set_tid_address () diff --git a/man2/seteuid.2 b/man2/seteuid.2 index 8d59fc822..2210c35e3 100644 --- a/man2/seteuid.2 +++ b/man2/seteuid.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,7 +48,8 @@ with "group" instead of "user". .\" .I euid .\" equals \-1, nothing is changed. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -71,14 +72,14 @@ and is not the real user (group) ID, the effective user (group) ID, or the saved set-user-ID (saved set-group-ID). .SH NOTES -Setting the effective user (group) ID to the +Setting the effective user (group) ID to the saved set-user-ID (saved set-group-ID) is possible since Linux 1.1.37 (1.1.38). On an arbitrary system one should check _POSIX_SAVED_IDS. .LP Under libc4, libc5 and glibc2.0 .BI seteuid( euid ) -is equivalent to +is equivalent to .BI setreuid(\-1, " euid" ) and hence may change the saved set-user-ID. Under glibc2.1 it is equivalent to diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 index 2523b6216..ef381d45a 100644 --- a/man2/setfsgid.2 +++ b/man2/setfsgid.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,9 +38,11 @@ setfsgid \- set group identity used for file system checks The system call .BR setfsgid () sets the group ID that the Linux kernel uses to check for all accesses -to the file system. Normally, the value of +to the file system. +Normally, the value of .I fsgid -will shadow the value of the effective group ID. In fact, whenever the +will shadow the value of the effective group ID. +In fact, whenever the effective group ID is changed, .I fsgid will also be changed to the new value of the effective group ID. @@ -64,16 +66,18 @@ saved set-group-ID, or the current value of .SH "RETURN VALUE" On success, the previous value of .I fsgid -is returned. On error, the current value of +is returned. +On error, the current value of .I fsgid is returned. .SH "CONFORMING TO" .BR setfsgid () -is Linux specific and should not be used in programs intended +is Linux specific and should not be used in programs intended to be portable. It is present since Linux 1.1.44 and in libc since libc 4.7.6. .SH BUGS -No error messages of any kind are returned to the caller. At the very +No error messages of any kind are returned to the caller. +At the very least, .B EPERM should be returned when the call fails (because the caller lacks the diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 index 6b14ac692..c0f671ac6 100644 --- a/man2/setfsuid.2 +++ b/man2/setfsuid.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,9 +38,11 @@ setfsuid \- set user identity used for file system checks The system call .BR setfsuid () sets the user ID that the Linux kernel uses to check for all accesses -to the file system. Normally, the value of +to the file system. +Normally, the value of .I fsuid -will shadow the value of the effective user ID. In fact, whenever the +will shadow the value of the effective user ID. +In fact, whenever the effective user ID is changed, .I fsuid will also be changed to the new value of the effective user ID. @@ -64,16 +66,18 @@ the current value of .SH "RETURN VALUE" On success, the previous value of .I fsuid -is returned. On error, the current value of +is returned. +On error, the current value of .I fsuid is returned. .SH "CONFORMING TO" .BR setfsuid () -is Linux specific and should not be used in programs intended +is Linux specific and should not be used in programs intended to be portable. It is present since Linux 1.1.44 and in libc since libc 4.7.6. .SH BUGS -No error messages of any kind are returned to the caller. At the very +No error messages of any kind are returned to the caller. +At the very least, .B EPERM should be returned when the call fails (because the caller lacks the diff --git a/man2/setgid.2 b/man2/setgid.2 index b54a6c2f1..22d6fb42b 100644 --- a/man2/setgid.2 +++ b/man2/setgid.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,11 +16,11 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. .\" Modified 1997-01-31 by Eric S. Raymond .\" Modified 2002-03-09 by aeb .\" @@ -35,10 +35,11 @@ setgid \- set group identity .BI "int setgid(gid_t " gid ); .SH DESCRIPTION .BR setgid () -sets the effective group ID of the current process. If the caller is the +sets the effective group ID of the current process. +If the caller is the superuser, the real GID and saved set-group-ID are also set. -Under Linux, +Under Linux, .BR setgid () is implemented like the POSIX version with the _POSIX_SAVED_IDS feature. This allows a set-group-ID program that is not set-user-ID-root @@ -46,7 +47,8 @@ to drop all of its group privileges, do some un-privileged work, and then re-engage the original effective group ID in a secure manner. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man2/setpgid.2 b/man2/setpgid.2 index 73ba501ba..771291785 100644 --- a/man2/setpgid.2 +++ b/man2/setpgid.2 @@ -61,13 +61,16 @@ to .IR pgid . If .I pid -is zero, the process ID of the current process is used. If +is zero, the process ID of the current process is used. +If .I pgid is zero, the process ID of the process specified by .I pid -is used. If \fBsetpgid\fP() is used to move a process from one process +is used. +If \fBsetpgid\fP() is used to move a process from one process group to another (as is done by some shells when creating pipelines), -both process groups must be part of the same session. In this case, +both process groups must be part of the same session. +In this case, the \fIpgid\fP specifies an existing process group to be joined and the session ID of that group must match the session ID of the joining process. @@ -96,7 +99,8 @@ group as the terminal are foreground and may read, while others will block with a signal if they attempt to read. These calls are thus used by programs such as .BR csh (1) -to create process groups in implementing job control. The +to create process groups in implementing job control. +The .B TIOCGPGRP and .B TIOCSPGRP @@ -105,7 +109,8 @@ calls described in are used to get/set the process group of the control terminal. If a session has a controlling terminal, CLOCAL is not set and a hangup -occurs, then the session leader is sent a SIGHUP. If the session leader +occurs, then the session leader is sent a SIGHUP. +If the session leader exits, the SIGHUP signal will be sent to each process in the foreground process group of the controlling terminal. @@ -116,9 +121,10 @@ in the newly-orphaned process group. .SH "RETURN VALUE" On success, .BR setpgid () -and +and .BR setpgrp () -return zero. On error, \-1 is returned, and +return zero. +On error, \-1 is returned, and .I errno is set appropriately. @@ -144,9 +150,9 @@ is less than 0 (\fBsetpgid\fP(), \fBsetpgrp\fP()). .TP .B EPERM -An attempt was made to move a process into a process group in a -different session, or to change the process -group ID of one of the children of the calling process and the +An attempt was made to move a process into a process group in a +different session, or to change the process +group ID of one of the children of the calling process and the child was in a different session, or to change the process group ID of a session leader (\fBsetpgid\fP(), \fBsetpgrp\fP()). @@ -173,7 +179,7 @@ The function .BR getpgid () conforms to SVr4. .SH NOTES -A child created via +A child created via .BR fork (2) inherits its parent's process group ID. The process group ID is preserved across an diff --git a/man2/setresuid.2 b/man2/setresuid.2 index 13e747618..d99e4b1bc 100644 --- a/man2/setresuid.2 +++ b/man2/setresuid.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,7 +33,7 @@ setresuid, setresgid \- set real, effective and saved user or group ID .sp .BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid ); .br -.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); +.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); .SH DESCRIPTION .BR setresuid () sets the real user ID, the effective user ID, and the @@ -42,27 +42,28 @@ saved set-user-ID of the current process. Unprivileged user processes may change the real UID, effective UID, and saved set-user-ID, each to one of: -the current real UID, the current effective UID or the +the current real UID, the current effective UID or the current saved set-user-ID. Privileged processes (on Linux, those having the CAP_SETUID capability) -may set the real UID, effective UID, and +may set the real UID, effective UID, and saved set-user-ID to arbitrary values. If one of the parameters equals \-1, the corresponding value is not changed. Regardless of what changes are made to the real UID, effective UID, -and saved set-user-ID, the file system UID is always set to the same +and saved set-user-ID, the file system UID is always set to the same value as the (possibly new) effective UID. Completely analogously, .BR setresgid () -sets the real GID, effective GID, and saved set-group-ID -of the current process (and always modifies the file system GID +sets the real GID, effective GID, and saved set-group-ID +of the current process (and always modifies the file system GID to be the same as the effective GID), with the same restrictions for non-privileged processes. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -76,7 +77,7 @@ bring that user ID over its NPROC rlimit. The calling process is not privileged (did not have the CAP_SETUID capability) and tried to change the IDs to values that are not permitted. .SH "CONFORMING TO" -These calls are non-standard; +These calls are non-standard; they also appear on HP-UX and some of the BSDs. .SH HISTORY This system call was first introduced in HP-UX. diff --git a/man2/setreuid.2 b/man2/setreuid.2 index 35222d2b9..d723a1024 100644 --- a/man2/setreuid.2 +++ b/man2/setreuid.2 @@ -68,7 +68,7 @@ saved set-user-ID. Linux: Unprivileged users may only set the real user ID to the real user ID or the effective user ID. -Linux: If the real user ID is set or the effective user ID is set to a value +Linux: If the real user ID is set or the effective user ID is set to a value not equal to the previous real user ID, the saved set-user-ID will be set to the new effective user ID. @@ -77,7 +77,8 @@ Completely analogously, sets real and effective group ID's of the current process, and all of the above holds with "group" instead of "user". .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -87,8 +88,8 @@ The current process is not privileged (Linux: does not have the .B CAP_SETUID capability in the case of -.BR setreuid (), -or the +.BR setreuid (), +or the .B CAP_SETGID capability in the case of .BR setregid ()) @@ -98,7 +99,7 @@ or (ii) setting one to the value of the other or (iii) setting the effective user (group) ID to the value of the saved set-user-ID (saved set-group-ID) was specified. .SH NOTES -Setting the effective user (group) ID to the +Setting the effective user (group) ID to the saved set-user-ID (saved set-group-ID) is possible since Linux 1.1.37 (1.1.38). .SH "CONFORMING TO" diff --git a/man2/setsid.2 b/man2/setsid.2 index a2f267aad..d0f4ea3d6 100644 --- a/man2/setsid.2 +++ b/man2/setsid.2 @@ -37,11 +37,14 @@ setsid \- creates a session and sets the process group ID .ad b .SH DESCRIPTION \fBsetsid\fP() creates a new session if the calling process is not a -process group leader. The calling process is the leader of the new +process group leader. +The calling process is the leader of the new session, the process group leader of the new process group, and has no -controlling tty. The process group ID and session ID of the calling -process are set to the PID of the calling process. The calling process -will be the only process in this new process group and in this new session. +controlling tty. +The process group ID and session ID of the calling +process are set to the PID of the calling process. +The calling process will be the only process in +this new process group and in this new session. .SH "RETURN VALUE" The session ID of the calling process. .SH ERRORS @@ -49,24 +52,27 @@ On error, \-1 is returned, and .I errno is set. The only error which can happen is -EPERM. It is returned when the process group ID of any process -equals the PID of the calling process. Thus, in particular, +EPERM. +It is returned when the process group ID of any process +equals the PID of the calling process. +Thus, in particular, .BR setsid () fails if the calling process is already a process group leader. .SH NOTES -A child created via +A child created via .BR fork (2) inherits its parent's session ID. The session ID is preserved across an .BR execve (2). A process group leader is a process with process group ID equal -to its PID. In order to be sure that +to its PID. +In order to be sure that .BR setsid () -will succeed, -.BR fork () -and -.BR exit (), +will succeed, +.BR fork () +and +.BR exit (), and have the child do .BR setsid (). .SH "CONFORMING TO" diff --git a/man2/setuid.2 b/man2/setuid.2 index 017c981b1..80cbc3e66 100644 --- a/man2/setuid.2 +++ b/man2/setuid.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,11 +16,11 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. .\" Changes inspired by patch from Richard Kettlewell .\" , aeb 970616. .\" Modified, 27 May 2004, Michael Kerrisk @@ -40,7 +40,7 @@ sets the effective user ID of the current process. If the effective UID of the caller is root, the real UID and saved set-user-ID are also set. .PP -Under Linux, +Under Linux, .BR setuid () is implemented like the POSIX version with the _POSIX_SAVED_IDS feature. This allows a set-user-ID (other than root) program to drop all of its user @@ -48,22 +48,24 @@ privileges, do some un-privileged work, and then re-engage the original effective user ID in a secure manner. .PP If the user is root or the program is set-user-ID-root, special care must be -taken. The +taken. +The .BR setuid () function checks the effective user ID of the caller and if it is the superuser, all process related user ID's are set to -.IR uid . +.IR uid . After this has occurred, it is impossible for the program to regain root privileges. .PP Thus, a set-user-ID-root program wishing to temporarily drop root privileges, assume the identity of a non-root user, and then regain -root privileges afterwards cannot use +root privileges afterwards cannot use .BR setuid (). You can accomplish this with the (non-POSIX, BSD) call .BR seteuid (). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -71,7 +73,7 @@ is set appropriately. .B EAGAIN The .I uid -does not match the current uid and +does not match the current uid and .I uid brings process over it's NPROC rlimit. .TP @@ -82,13 +84,14 @@ capability) and .I uid does not match the real UID or saved set-user-ID of the calling process. .SH "CONFORMING TO" -SVr4, POSIX.1-2001. +SVr4, POSIX.1-2001. Not quite compatible with the 4.4BSD call, which -sets all of the real, saved, and effective user IDs. +sets all of the real, saved, and effective user IDs. .\" SVr4 documents an additional EINVAL error condition. .SH "LINUX-SPECIFIC REMARKS" Linux has the concept of filesystem user ID, normally equal to the -effective user ID. The +effective user ID. +The .BR setuid () call also sets the filesystem user ID of the current process. See diff --git a/man2/setup.2 b/man2/setup.2 index f4bfac6a2..701a92a68 100644 --- a/man2/setup.2 +++ b/man2/setup.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man2/setxattr.2 b/man2/setxattr.2 index 74f8c5fd2..43acdf09e 100644 --- a/man2/setxattr.2 +++ b/man2/setxattr.2 @@ -68,7 +68,7 @@ of the must be specified. .PP .BR lsetxattr () -is identical to +is identical to .BR setxattr (), except in the case of a symbolic link, where the extended attribute is set on the link itself, not the file that it refers to. diff --git a/man2/shmctl.2 b/man2/shmctl.2 index d0a8eb611..923110b7b 100644 --- a/man2/shmctl.2 +++ b/man2/shmctl.2 @@ -33,7 +33,7 @@ .\" Language and formatting clean-ups .\" Updated shmid_ds structure definitions .\" Added information on SHM_DEST and SHM_LOCKED flags -.\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK +.\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK .\" since kernel 2.6.9 .\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes .\" 2005-04-25, mtk -- noted aberrant Linux behaviour w.r.t. new @@ -152,11 +152,11 @@ The caller \fImust\fP ensure that a segment is eventually destroyed; otherwise its pages that were faulted in will remain in memory or swap. .TP .BR IPC_INFO " (Linux specific)" -Returns information about system-wide shared memory limits and +Returns information about system-wide shared memory limits and parameters in the structure pointed to by .IR buf . This structure is of type -.IR shminfo +.IR shminfo (thus, a cast is required), defined in .I @@ -168,29 +168,29 @@ struct shminfo { unsigned long shmmax; /* Max. segment size */ unsigned long shmmin; /* Min. segment size; always 1 */ unsigned long shmmni; /* Max. # of segments */ - unsigned long shmseg; /* Max. # of segments that a + unsigned long shmseg; /* Max. # of segments that a process can attach; unused */ - unsigned long shmall; /* Max. # of pages of shared + unsigned long shmall; /* Max. # of pages of shared memory, system-wide */ }; .in -2n .fi -The +The .IR shmmni , .IR shmmax , and .I shmall settings can be changed via -.I /proc +.I /proc files of the same name; see -.BR proc (5) +.BR proc (5) for details. .TP .BR SHM_INFO " (Linux specific)" Returns a .I shm_info -structure whose fields contain information +structure whose fields contain information about system resources consumed by shared memory. This structure is defined in .I @@ -199,13 +199,13 @@ if the _GNU_SOURCE feature test macro is defined: .in +2n struct shm_info { - int used_ids; /* # of currently existing + int used_ids; /* # of currently existing segments */ - unsigned long shm_tot; /* Total number of shared + unsigned long shm_tot; /* Total number of shared memory pages */ - unsigned long shm_rss; /* # of resident shared + unsigned long shm_rss; /* # of resident shared memory pages */ - unsigned long shm_swp; /* # of swapped shared + unsigned long shm_swp; /* # of swapped shared memory pages */ unsigned long swap_attempts; /* Unused since Linux 2.4 */ unsigned long swap_successes; /* Unused since Linux 2.4 */ @@ -214,8 +214,8 @@ struct shm_info { .fi .TP .BR SHM_STAT " (Linux specific)" -Returns a -.I shmid_ds +Returns a +.I shmid_ds structure as for .BR IPC_STAT . However, the @@ -229,7 +229,8 @@ memory segment with the following \fIcmd\fP values: .br .TP 12 .BR SHM_LOCK " (Linux specific)" -Prevent swapping of the shared memory segment. The caller must fault in +Prevent swapping of the shared memory segment. +The caller must fault in any pages that are required to be present after locking is enabled. If a segment has been locked, then the (non-standard) .BR SHM_LOCKED @@ -247,7 +248,7 @@ could employ .B SHM_LOCK and .BR SHM_UNLOCK . -Since kernel 2.6.10, an unprivileged process can employ these operations +Since kernel 2.6.10, an unprivileged process can employ these operations if its effective UID matches the owner or creator UID of the segment, and (for .BR SHM_LOCK ) @@ -255,25 +256,25 @@ the amount of memory to be locked falls within the .BR RLIMIT_MEMLOCK resource limit (see .BR setrlimit (2)). -.\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could +.\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could .\" be applied to a segment, regardless of ownership of the segment. -.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed +.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed .\" in 2.6.10. MTK, May 2005 .SH "RETURN VALUE" A successful .B IPC_INFO -or +or .B SHM_INFO operation returns the index of the highest used entry in the kernel's internal array recording information about all shared memory segments. (This information can be used with repeated -.B SHM_STAT -operations to obtain information about all shared memory segments +.B SHM_STAT +operations to obtain information about all shared memory segments on the system.) A successful .B SHM_STAT -operation returns the identifier of the shared memory segment +operation returns the identifier of the shared memory segment whose index was given in .IR shmid . Other operations return 0 on success. @@ -310,14 +311,14 @@ isn't accessible. is not a valid command. Or: for a .B SHM_STAT -operation, the index value specified in +operation, the index value specified in .I shmid referred to an array slot that is currently unused. .TP .B ENOMEM (In kernels since 2.6.9), .B SHM_LOCK -was specified and the size of the to-be-locked segment would mean +was specified and the size of the to-be-locked segment would mean that the total bytes in locked shared memory segments would exceed the limit for the real user ID of the calling process. This limit is defined by the @@ -365,7 +366,7 @@ program to provide information on allocated resources. In the future these may modified or moved to a /proc file system interface. -Linux permits a process to attach +Linux permits a process to attach .RB ( shmat ()) a shared memory segment that has already been marked for deletion using @@ -374,12 +375,13 @@ This feature is not available on other Unix implementations; portable applications should avoid relying on it. Various fields in a \fIstruct shmid_ds\fP were shorts under Linux 2.2 -and have become longs under Linux 2.4. To take advantage of this, +and have become longs under Linux 2.4. +To take advantage of this, a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an IPC_64 flag in .IR cmd .) .SH "CONFORMING TO" -SVr4, POSIX.1-2001. +SVr4, POSIX.1-2001. .\" SVr4 documents additional error conditions EINVAL, .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents .\" an EIDRM error condition. diff --git a/man2/shmget.2 b/man2/shmget.2 index cc86dca25..3e772fd2e 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -77,11 +77,11 @@ and a shared memory segment already exists for .IR key , then .BR shmget () -fails with +fails with .I errno set to .BR EEXIST . -(This is analogous to the effect of the combination +(This is analogous to the effect of the combination .B O_CREAT | O_EXCL for .BR open (2).) @@ -91,15 +91,16 @@ The value is composed of: .TP 12 .B IPC_CREAT -to create a new segment. If this flag is not used, then +to create a new segment. +If this flag is not used, then .BR shmget () -will find the segment associated with \fIkey\fP and check to see if +will find the segment associated with \fIkey\fP and check to see if the user has permission to access the segment. .TP .B IPC_EXCL -used with \fBIPC_CREAT\fP to ensure failure if the segment already exists. +used with \fBIPC_CREAT\fP to ensure failure if the segment already exists. .TP -.I mode_flags +.I mode_flags (least significant 9 bits) specifying the permissions granted to the owner, group, and world. These bits have the same format, and the same @@ -110,7 +111,7 @@ argument of Presently, the execute permissions are not used by the system. .TP .BR SHM_HUGETLB " (since Linux 2.6)" -Allocate the segment using "huge pages." +Allocate the segment using "huge pages." See the kernel source file .I Documentation/vm/hugetlbpage.txt for further information. @@ -120,14 +121,14 @@ This flag serves the same purpose as the .BR mmap (2) .B MAP_NORESERVE flag. -Do not reserve swap space for this segment. +Do not reserve swap space for this segment. When swap space is reserved, one has the guarantee that it is possible to modify the segment. When swap space is not reserved one might get SIGSEGV upon a write if no physical memory is available. See also the discussion of the file .I /proc/sys/vm/overcommit_memory -in +in .BR proc (5). .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also .\" specified. @@ -197,7 +198,7 @@ On failure, is set to one of the following: .TP 12 .B EACCES -The user does not have permission to access the +The user does not have permission to access the shared memory segment, and does not have the .B CAP_IPC_OWNER capability. @@ -285,7 +286,7 @@ number of shared memory segments The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more clearly show its function. .SH "CONFORMING TO" -SVr4, POSIX.1-2001. +SVr4, POSIX.1-2001. .\" SVr4 documents an additional error condition EEXIST. .SH LINUX NOTES Until version 2.3.30 Linux would return EIDRM for a diff --git a/man2/shmop.2 b/man2/shmop.2 index 4f9223bf4..88094794e 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -175,8 +175,8 @@ all attached shared memory segments are detached from the process. .SH "RETURN VALUE" On success .BR shmat () -returns the address of the attached shared memory segment; on error -.I (void *) \-1 +returns the address of the attached shared memory segment; on error +.I (void *) \-1 is returned, and .I errno is set to indicate the cause of the error. @@ -226,7 +226,7 @@ is set as follows: .TP .B EINVAL There is no shared memory segment attached at -.IR shmaddr ; +.IR shmaddr ; or, .\" The following since 2.6.17-rc1: .I shmaddr @@ -252,7 +252,7 @@ many other implementations do not support it. The following system parameter affects .BR shmat (): .TP 11 -.\" FIXME A good explanation of the rationale for the existence +.\" FIXME A good explanation of the rationale for the existence .\" of SHMLBA would be useful here .B SHMLBA Segment low boundary address multiple. @@ -269,10 +269,10 @@ The implementation places no intrinsic limit on the per\-process maximum number of shared memory segments .RB ( SHMSEG ). .SH "CONFORMING TO" -SVr4, POSIX.1-2001. +SVr4, POSIX.1-2001. .\" SVr4 documents an additional error condition EMFILE. -In SVID 3 (or perhaps earlier) +In SVID 3 (or perhaps earlier) the type of the \fIshmaddr\fP argument was changed from .I "char *" into diff --git a/man2/shutdown.2 b/man2/shutdown.2 index 6d7595337..ca8d12292 100644 --- a/man2/shutdown.2 +++ b/man2/shutdown.2 @@ -48,21 +48,25 @@ The call causes all or part of a full-duplex connection on the socket associated with .I s -to be shut down. If +to be shut down. +If .I how is .BR SHUT_RD , -further receptions will be disallowed. If +further receptions will be disallowed. +If .I how is .BR SHUT_WR , -further transmissions will be disallowed. If +further transmissions will be disallowed. +If .I how is .BR SHUT_RDWR , further receptions and transmissions will be disallowed. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man2/sigaction.2 b/man2/sigaction.2 index f0d89d4b1..53239087e 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,7 +46,7 @@ sigaction \- examine and change a signal action .SH SYNOPSIS .nf .B #include -.sp +.sp .BI "int sigaction(int " signum ", const struct sigaction *" act , .BI " struct sigaction *" oldact ); .fi @@ -106,7 +106,7 @@ specifies the action to be associated with .I signum and may be .B SIG_DFL -for the default action, +for the default action, .B SIG_IGN to ignore this signal, or a pointer to a signal handling function. This function receives the signal number as its only argument. @@ -114,7 +114,7 @@ This function receives the signal number as its only argument. If .B SA_SIGINFO is specified in -.IR sa_flags , +.IR sa_flags , then .I sa_sigaction (instead of @@ -130,14 +130,16 @@ as its second argument and a pointer to a .PP .I sa_mask gives a mask of signals which should be blocked during execution of -the signal handler. In addition, the signal which triggered the handler +the signal handler. +In addition, the signal which triggered the handler will be blocked, unless the .B SA_NODEFER flag is used. .PP .I sa_flags specifies a set of flags which modify the behaviour of the signal handling -process. It is formed by the bitwise OR of zero or more of the following: +process. +It is formed by the bitwise OR of zero or more of the following: .RS .TP .B SA_NOCLDSTOP @@ -173,7 +175,7 @@ has been called. is an obsolete, non-standard synonym for this flag. .TP .BR SA_ONSTACK -Call the signal handler on an alternate signal stack provided by +Call the signal handler on an alternate signal stack provided by .BR sigaltstack (2). If an alternate stack is not available, the default stack will be used. .TP @@ -188,7 +190,8 @@ handler. is an obsolete, non-standard synonym for this flag. .TP .B SA_SIGINFO -The signal handler takes 3 arguments, not one. In this case, +The signal handler takes 3 arguments, not one. +In this case, .I sa_sigaction should be set instead of .IR sa_handler . @@ -234,7 +237,7 @@ POSIX.1b signals and .B SIGCHLD fill in .IR si_pid " and " si_uid . -.BR +.BR .B SIGCHLD also fills in .IR si_status ", " si_utime " and " si_stime . @@ -243,9 +246,9 @@ are specified by the sender of the POSIX.1b signal. .\" See .\" .BR sigqueue (2) .\" for more details. -.BR SIGILL , +.BR SIGILL , .BR SIGFPE , -.BR SIGSEGV , +.BR SIGSEGV , and .B SIGBUS fill in @@ -256,8 +259,9 @@ fills in .IR si_band " and " si_fd . .I si_code -indicates why this signal was sent. It is a value, not a bitmask. The -values which are possible for any signal are listed in this table: +indicates why this signal was sent. +It is a value, not a bitmask. +The values which are possible for any signal are listed in this table: .TS tab(:) allbox; c s @@ -273,7 +277,7 @@ SI_ASYNCIO:AIO completed SI_SIGIO:queued SIGIO SI_TKILL:tkill() or tgkill() (since Linux 2.4.19) .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented -.\" It appears to have been an idea that was tried during 2.5.6 +.\" It appears to have been an idea that was tried during 2.5.6 .\" through to 2.5.24 and then was backed out. .TE @@ -370,7 +374,8 @@ returns 0 on success and \-1 on error. points to memory which is not a valid part of the process address space. .TP .B EINVAL -An invalid signal was specified. This will also be generated if an attempt +An invalid signal was specified. +This will also be generated if an attempt is made to change the action for .BR SIGKILL " or " SIGSTOP ", " which cannot be caught or ignored. @@ -434,7 +439,8 @@ flag is compatible with the SVr4 flag of the same name. The .B SA_NODEFER flag is compatible with the SVr4 flag of the same name under kernels -1.3.9 and newer. On older kernels the Linux implementation +1.3.9 and newer. +On older kernels the Linux implementation allowed the receipt of any signal, not just the one we are installing (effectively overriding any .I sa_mask @@ -447,10 +453,11 @@ settings). .PP .BR sigaction () can be called with a null second argument to query the current signal -handler. It can also be used to check whether a given signal is valid for +handler. +It can also be used to check whether a given signal is valid for the current machine by calling it with null second and third arguments. .PP -It is not possible to block +It is not possible to block .BR SIGKILL " or " SIGSTOP (by specifying them in .IR sa_mask ). @@ -464,12 +471,12 @@ In kernels up to and including 2.6.13, specifying .B SA_NODEFER in .I sa_flags -preventing not only the delivered signal from being masked during +preventing not only the delivered signal from being masked during execution of the handler, but also the signals specified in .IR sa_mask . This bug is was fixed in kernel 2.6.14. .SH "CONFORMING TO" -POSIX.1-2001, SVr4. +POSIX.1-2001, SVr4. .\" SVr4 does not document the EINTR condition. .SH UNDOCUMENTED Before the introduction of diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index f34d5d81e..8f7cf2223 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -29,7 +29,8 @@ sigaltstack \- set and/or get signal stack context .SH DESCRIPTION \fBsigaltstack\fP() allows a process to define a new alternate signal stack and/or retrieve the state of an existing -alternate signal stack. An alternate signal stack is used during the +alternate signal stack. +An alternate signal stack is used during the execution of a signal handler if the establishment of that handler (see .BR sigaction (2)) requested it. @@ -78,12 +79,13 @@ to cover the usual size requirements for an alternate signal stack, and the constant \fBMINSIGSTKSZ\fP defines the minimum size required to execute a signal handler. -When a signal handler is invoked on the alternate stack, -the kernel automatically aligns the address given in \fIss.ss_sp\fP +When a signal handler is invoked on the alternate stack, +the kernel automatically aligns the address given in \fIss.ss_sp\fP to a suitable address boundary for the underlying hardware architecture. To disable an existing stack, specify \fIss.ss_flags\fP -as \fBSS_DISABLE\fP. In this case, the remaining fields +as \fBSS_DISABLE\fP. +In this case, the remaining fields in \fIss\fP are ignored. If \fIoss\fP is not NULL, then it is used to return information about @@ -94,8 +96,8 @@ address and size of that stack. The \fIoss.ss_flags\fP may return either of the following values: .TP .B SS_ONSTACK -The process is currently executing on the alternate -signal stack. (Note that it is not possible +The process is currently executing on the alternate signal stack. +(Note that it is not possible to change the alternate signal stack if the process is currently executing on it.) .TP @@ -125,10 +127,10 @@ on the current alternate signal stack). .SH NOTES The most common usage of an alternate signal stack is to handle the .B SIGSEGV -signal that is generated if the space available for the -normal process stack is exhausted: in this case, a signal handler for -.B SIGSEGV -cannot be invoked on the process stack; if we wish to handle it, +signal that is generated if the space available for the +normal process stack is exhausted: in this case, a signal handler for +.B SIGSEGV +cannot be invoked on the process stack; if we wish to handle it, we must use an alternate signal stack. The following code segment demonstrates the use of \fBsigaltstack\fP(): @@ -177,7 +179,8 @@ signal stack. For backwards compatibility, glibc also provides \fBsigstack\fP(). All new applications should be written using \fBsigaltstack\fP(). .SH HISTORY -4.2BSD had a \fIsigstack\fP() system call. It used a slightly +4.2BSD had a \fIsigstack\fP() 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 "CONFORMING TO" diff --git a/man2/signal.2 b/man2/signal.2 index 6b915dea9..5bd7b7f85 100644 --- a/man2/signal.2 +++ b/man2/signal.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,12 +18,12 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" Modified 2004-11-19, mtk: -.\" added pointer to sigaction.2 for details of ignoring SIGCHLD +.\" Modified 2004-11-19, mtk: +.\" added pointer to sigaction.2 for details of ignoring SIGCHLD .\" .TH SIGNAL 2 2000-04-28 "Linux 2.2" "Linux Programmer's Manual" .SH NAME @@ -92,21 +92,24 @@ If one on a libc5 system includes .B "" instead of .B "" -then +then .BR signal () is redefined as .B __bsd_signal -and signal has the BSD semantics. This is not recommended. +and signal has the BSD semantics. +This is not recommended. If one on a glibc2 system defines a feature test macro such as .B _XOPEN_SOURCE or uses a separate .B sysv_signal -function, one obtains classical behaviour. This is not recommended. +function, one obtains classical behaviour. +This is not recommended. Trying to change the semantics of this call using -defines and includes is not a good idea. It is better to avoid +defines and includes is not a good idea. +It is better to avoid .BR signal () altogether, and use .BR sigaction (2) @@ -117,11 +120,12 @@ The effects of this call in a multi-threaded process are unspecified. The routine .I handler must be very careful, since processing elsewhere was interrupted -at some arbitrary point. POSIX has the concept of "safe function". +at some arbitrary point. +POSIX has the concept of "safe function". If a signal interrupts an unsafe function, and .I handler -calls an unsafe function, then the behavior is undefined. Safe -functions are listed explicitly in the various standards. +calls an unsafe function, then the behavior is undefined. +Safe functions are listed explicitly in the various standards. The POSIX.1-2003 list is _Exit() diff --git a/man2/sigpending.2 b/man2/sigpending.2 index c0dcfbd0b..09ce6af08 100644 --- a/man2/sigpending.2 +++ b/man2/sigpending.2 @@ -1,5 +1,5 @@ .\" Copyright (c) 2005 Michael Kerrisk -.\" based on earlier work by faith@cs.unc.edu and +.\" based on earlier work by faith@cs.unc.edu and .\" Mike Battersby .\" .\" Permission is granted to make and distribute verbatim copies of this @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -29,7 +29,7 @@ sigpending \- examine pending signals .SH SYNOPSIS .B #include -.sp +.sp .BI "int sigpending(sigset_t *" set ); .SH DESCRIPTION .PP @@ -56,7 +56,7 @@ POSIX.1-2001. In versions of glibc up to and including 2.2.1, there is a bug in the wrapper function for .BR sigpending () -which means that information about pending real-time signals +which means that information about pending real-time signals is not correctly returned. .SH "SEE ALSO" .BR kill (2), diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2 index 7b1966774..cf0028a26 100644 --- a/man2/sigprocmask.2 +++ b/man2/sigprocmask.2 @@ -1,5 +1,5 @@ .\" Copyright (c) 2005 Michael Kerrisk -.\" based on earlier work by faith@cs.unc.edu and +.\" based on earlier work by faith@cs.unc.edu and .\" Mike Battersby .\" .\" Permission is granted to make and distribute verbatim copies of this @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -29,7 +29,7 @@ sigprocmask \- examine and change blocked signals .SH SYNOPSIS .B #include -.sp +.sp .BI "int sigprocmask(int " how ", const sigset_t *" set , .BI "sigset_t *" oldset ); .SH DESCRIPTION @@ -48,8 +48,8 @@ argument. .B SIG_UNBLOCK The signals in .I set -are removed from the current set of blocked signals. It is legal to -attempt to unblock a signal which is not blocked. +are removed from the current set of blocked signals. +It is legal to attempt to unblock a signal which is not blocked. .TP .B SIG_SETMASK The set of blocked signals is set to the argument @@ -67,7 +67,7 @@ is NULL, then the signal mask is unchanged (i.e., .I how is ignored), but the current value of the signal mask is nevertheless returned in -.IR oldset +.IR oldset (it is not NULL). The use of @@ -83,16 +83,16 @@ The value specified in .I how was invalid. .SH NOTES -It is not possible to block +It is not possible to block .BR SIGKILL " or " SIGSTOP . Attempts to do so are silently ignored. .PP If .BR SIGBUS , -.BR SIGFPE , +.BR SIGFPE , .BR SIGILL , or -.BR SIGSEGV +.BR SIGSEGV are generated while they are blocked, the result is undefined, unless the signal was generated by the diff --git a/man2/sigqueue.2 b/man2/sigqueue.2 index f4a8a53f0..d68009b30 100644 --- a/man2/sigqueue.2 +++ b/man2/sigqueue.2 @@ -8,12 +8,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,7 +35,7 @@ to the process whose PID is given in .IR pid . The permissions required to send a signal are the same as for .BR kill (2). -As with +As with .BR kill (2), the null signal (0) can be used to check if a process with a given PID exists. @@ -60,7 +60,7 @@ flag to .BR sigaction (2), then it can obtain this data via the .I si_value -field of the +field of the .I siginfo_t structure passed as the second argument to the handler. Furthermore, the @@ -68,7 +68,7 @@ Furthermore, the field of that structure will be set to .BR SI_QUEUE . .SH "RETURN VALUE" -On success, +On success, .BR sigqueue () returns 0, indicating that the signal was successfully queued to the receiving process. diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 index 7d4eab66c..10c0460c6 100644 --- a/man2/sigreturn.2 +++ b/man2/sigreturn.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,7 +35,8 @@ call to is inserted into the stack frame so that the signal handler will call .BR sigreturn () -upon return. This inserted call to +upon return. +This inserted call to .BR sigreturn () cleans up the stack so that the process can restart from where it was interrupted by the signal. @@ -45,9 +46,11 @@ never returns. .SH WARNING The .BR sigreturn () -call is used by the kernel to implement signal handlers. It should +call is used by the kernel to implement signal handlers. +It should .B never -be called directly. Better yet, the specific use of the +be called directly. +Better yet, the specific use of the .I __unused argument varies depending on the architecture. .SH "CONFORMING TO" diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 index a643c6615..ae1422ffe 100644 --- a/man2/sigsuspend.2 +++ b/man2/sigsuspend.2 @@ -1,5 +1,5 @@ .\" Copyright (c) 2005 Michael Kerrisk -.\" based on earlier work by faith@cs.unc.edu and +.\" based on earlier work by faith@cs.unc.edu and .\" Mike Battersby .\" .\" Permission is granted to make and distribute verbatim copies of this @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,7 +34,7 @@ sigsuspend \- wait for a signal .SH DESCRIPTION .BR sigsuspend () temporarily replaces the signal mask of the calling process with the -mask given by +mask given by .I mask and then suspends the process until delivery of a signal whose action is to invoke a signal handler or to terminate a process. @@ -66,11 +66,11 @@ points to memory which is not a valid part of the process address space. The call was interrupted by a signal. .SH NOTES .PP -Normally, +Normally, .BR sigsuspend () is used in conjunction with .BR sigprocmask () -in order to prevent delivery of a signal during the execution of a +in order to prevent delivery of a signal during the execution of a critical code section. The caller first blocks the signals with .BR sigprocmask (). diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 index 4b2904a15..bc2b6aed7 100644 --- a/man2/sigwaitinfo.2 +++ b/man2/sigwaitinfo.2 @@ -117,14 +117,14 @@ via a prior call to .BR sigprocmask () (so that the default disposition for these signals does not occur if they are delivered between successive calls to -.BR sigwaitinfo () +.BR sigwaitinfo () or .BR sigtimedwait ()) and does not establish handlers for these signals. -In a multithreaded program, -the signal should be blocked in all threads to prevent +In a multithreaded program, +the signal should be blocked in all threads to prevent the signal being delivered to a thread other than the one calling -.BR sigwaitinfo () +.BR sigwaitinfo () or .BR sigtimedwait ()). .PP diff --git a/man2/socket.2 b/man2/socket.2 index 03926949d..2d8168050 100644 --- a/man2/socket.2 +++ b/man2/socket.2 @@ -54,7 +54,8 @@ creates an endpoint for communication and returns a descriptor. The .I domain parameter specifies a communication domain; this selects the protocol -family which will be used for communication. These families are defined in +family which will be used for communication. +These families are defined in .IR . The currently understood formats include: .TS @@ -117,12 +118,13 @@ T} .PP The socket has the indicated .IR type , -which specifies the communication semantics. Currently defined types +which specifies the communication semantics. +Currently defined types are: .TP .B SOCK_STREAM Provides sequenced, reliable, two-way, connection-based byte streams. -An out-of-band data transmission mechanism may be supported. +An out-of-band data transmission mechanism may be supported. .TP .B SOCK_DGRAM Supports datagrams (connectionless, unreliable messages of a fixed @@ -131,7 +133,7 @@ maximum length). .B SOCK_SEQPACKET Provides a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer is -required to read an entire packet with each read system call. +required to read an entire packet with each read system call. .TP .B SOCK_RAW Provides raw network protocol access. @@ -141,24 +143,25 @@ Provides a reliable datagram layer that does not guarantee ordering. .TP .B SOCK_PACKET Obsolete and should not be used in new programs; -see +see .BR packet (7). .PP -Some socket types may not be implemented by all protocol families; for example, +Some socket types may not be implemented by all protocol families; +for example, .B SOCK_SEQPACKET -is not implemented for +is not implemented for .BR AF_INET . .PP The .I protocol -specifies a particular protocol to be used with the socket. Normally only -a single protocol exists to support a particular socket type within a given -protocol family, in which case +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +socket type within a given protocol family, in which case .I protocol can be specified as 0. However, it is possible that many protocols may exist, in -which case a particular protocol must be specified in this manner. The -protocol number to use is specific to the \*(lqcommunication domain\*(rq +which case a particular protocol must be specified in this manner. +The protocol number to use is specific to the \*(lqcommunication domain\*(rq in which communication is to take place; see .BR protocols (5). See @@ -167,36 +170,43 @@ on how to map protocol name strings to protocol numbers. .PP Sockets of type .B SOCK_STREAM -are full-duplex byte streams, similar to pipes. They do not preserve -record boundaries. A stream socket must be in +are full-duplex byte streams, similar to pipes. +They do not preserve +record boundaries. +A stream socket must be in a .I connected -state before any data may be sent or received on it. A connection to +state before any data may be sent or received on it. +A connection to another socket is created with a .BR connect (2) -call. Once connected, data may be transferred using +call. +Once connected, data may be transferred using .BR read (2) and .BR write (2) -calls or some variant of the +calls or some variant of the .BR send (2) and .BR recv (2) -calls. When a session has been completed a +calls. +When a session has been completed a .BR close (2) -may be performed. Out-of-band data may also be transmitted as described in +may be performed. +Out-of-band data may also be transmitted as described in .BR send (2) and received as described in .BR recv (2). .PP The communications protocols which implement a .B SOCK_STREAM -ensure that data is not lost or duplicated. If a piece of data for which +ensure that data is not lost or duplicated. +If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered to be dead. When -.B SO_KEEPALIVE +.B SO_KEEPALIVE is enabled on the socket the protocol checks in a protocol-specific manner if the other end is still alive. A @@ -207,11 +217,12 @@ which do not handle the signal, to exit. .B SOCK_SEQPACKET sockets employ the same system calls as .B SOCK_STREAM -sockets. The only difference is that +sockets. +The only difference is that .BR read (2) calls will return only the amount of data requested, and any data remaining in the arriving packet will be discarded. -Also all message boundaries in incoming datagrams are preserved. +Also all message boundaries in incoming datagrams are preserved. .PP .B SOCK_DGRAM and @@ -225,23 +236,24 @@ which returns the next datagram along with the address of its sender. .PP .B SOCK_PACKET is an obsolete socket type to receive raw packets directly from the -device driver. Use +device driver. +Use .BR packet (7) instead. .PP -An +An .BR fcntl (2) -.B F_SETOWN +.B F_SETOWN operation can be used to specify a process or process group to receive a .B SIGURG -signal when the out-of-band data arrives or -.B SIGPIPE -signal when a -.B SOCK_STREAM -connection breaks unexpectedly. -This operation may also be used to set the process or process group +signal when the out-of-band data arrives or +.B SIGPIPE +signal when a +.B SOCK_STREAM +connection breaks unexpectedly. +This operation may also be used to set the process or process group that receives the I/O and asynchronous notification of I/O events via -.BR SIGIO . +.BR SIGIO . Using .B F_SETOWN is equivalent to an @@ -255,15 +267,16 @@ argument. When the network signals an error condition to the protocol module (e.g., using a ICMP message for IP) the pending error flag is set for the socket. The next operation on this socket will return the error code of the pending -error. For some protocols it is possible to enable a per-socket error queue +error. +For some protocols it is possible to enable a per-socket error queue to retrieve detailed information about the error; see -.B IP_RECVERR +.B IP_RECVERR in .BR ip (7) . .PP The operation of sockets is controlled by socket level .IR options . -These options are defined in +These options are defined in .IR . The functions .BR setsockopt (2) @@ -294,7 +307,8 @@ Process file table overflow. The system limit on the total number of open files has been reached. .TP .BR ENOBUFS " or " ENOMEM -Insufficient memory is available. The socket cannot be +Insufficient memory is available. +The socket cannot be created until sufficient resources are freed. .TP .B EPROTONOSUPPORT @@ -305,13 +319,15 @@ Other errors may be generated by the underlying protocol modules. .SH "CONFORMING TO" 4.4BSD, POSIX.1-2001. .BR socket () -appeared in 4.2BSD. It is generally portable to/from +appeared in 4.2BSD. +It is generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System V variants). .SH NOTE The manifest constants used under 4.x BSD for protocol families are PF_UNIX, PF_INET, etc., while AF_UNIX etc. are used for address -families. However, already the BSD man page promises: "The protocol +families. +However, already the BSD man page promises: "The protocol family generally is the same as the address family", and subsequent standards use AF_* everywhere. .SH BUGS diff --git a/man2/socketpair.2 b/man2/socketpair.2 index 096a05dd6..e9afdda3d 100644 --- a/man2/socketpair.2 +++ b/man2/socketpair.2 @@ -61,7 +61,8 @@ and .IR sv [1]. The two sockets are indistinguishable. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -93,7 +94,7 @@ function call appeared in 4.2BSD. It is generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System V variants). .SH NOTES -On Linux, the only supported domain for this call is +On Linux, the only supported domain for this call is .BR AF_UNIX (or synonymously, .BR AF_LOCAL ). diff --git a/man2/splice.2 b/man2/splice.2 index fd1876228..defc55016 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,13 +31,13 @@ splice \- splice data to/from a pipe .B #define _GNU_SOURCE .B #include -.BI "long splice(int " fd_in ", off_t *" off_in ", int " fd_out , +.BI "long splice(int " fd_in ", off_t *" off_in ", int " fd_out , .BI " off_t *" off_out ", size_t " len \ ", unsigned int " flags ); .fi .SH DESCRIPTION .BR splice () -moves data between two file descriptors +moves data between two file descriptors without copying between kernel address space and user address space. It transfers up to .I len @@ -45,32 +45,32 @@ bytes of data from the file descriptor .I fd_in to the file descriptor .IR fd_out , -where one of the descriptors must refer to a pipe. +where one of the descriptors must refer to a pipe. If .I fd_in refers to a pipe, then -.I off_in +.I off_in must be NULL. If -.I fd_in +.I fd_in does not refer to a pipe and .I off_in -is NULL, then bytes are read from +is NULL, then bytes are read from .I fd_in starting from the current file offset, and the current file offset is adjusted appropriately. If -.I fd_in +.I fd_in does not refer to a pipe and .I off_in -is not NULL, then +is not NULL, then .I off_in must point to a buffer which specifies the starting offset from which bytes will be read from .IR fd_in ; in this case, the current file offset of -.IR fd_in +.IR fd_in is not changed. Analogous statements apply for .I out_fd @@ -83,15 +83,15 @@ argument is a bit mask that is composed by ORing together zero or more of the following values: .TP 1.9i .B SPLICE_F_MOVE -Attempt to move pages instead of copying. +Attempt to move pages instead of copying. This is only a hint to the kernel: -pages may still be copied if the kernel cannot move the +pages may still be copied if the kernel cannot move the pages from the pipe, or if the pipe buffers don't refer to full pages. .TP .B SPLICE_F_NONBLOCK Do not block on I/O. -This makes the splice pipe operations non-blocking, but +This makes the splice pipe operations non-blocking, but .BR splice () may nevertheless block because the file descriptors that are spliced to/from may block (unless they have the @@ -101,7 +101,7 @@ flag set). .B SPLICE_F_MORE More data will be coming in a subsequent splice. This is a helpful hint when -the +the .I fd_out refers to a socket (see also the description of .B MSG_MORE @@ -121,13 +121,13 @@ see Upon successful completion, .BR splice () returns the number of bytes -spliced to or from the pipe. -A return value of 0 means that there was no data to transfer, -and it would not make sense to block, because there are no -writers connected to the write end of the pipe referred to by +spliced to or from the pipe. +A return value of 0 means that there was no data to transfer, +and it would not make sense to block, because there are no +writers connected to the write end of the pipe referred to by .IR fd_in . -On error, +On error, .BR splice () returns \-1 and .I errno @@ -135,21 +135,21 @@ is set to indicate the error. .SH ERRORS .TP .B EBADF -One or both file descriptors are not valid, +One or both file descriptors are not valid, or do not have proper read-write mode. .TP .B EINVAL Target file system doesn't support splicing; -neither of the descriptors refers to a pipe; or +neither of the descriptors refers to a pipe; or offset given for non-seekable device. .TP .B ENOMEM Out of memory. .TP .B ESPIPE -Either +Either .I off_in -or +or .I off_out was not NULL, but the corresponding file descriptor refers to a pipe. .SH HISTORY @@ -162,9 +162,9 @@ The three system calls .BR vmsplice (2), and .BR tee (2)), -provide userspace programs with full control over an arbitrary +provide userspace programs with full control over an arbitrary kernel buffer, implemented within the kernel using the same type -of buffer that is used for a pipe. +of buffer that is used for a pipe. In overview, these system calls perform the following tasks: .TP 1.2i .BR splice () @@ -174,37 +174,37 @@ or from one buffer to another. .BR tee () "copies" the data from one buffer to another. .TP -.BR vmsplice () +.BR vmsplice () "copies" data from user space into the buffer. .PP Though we talk of copying, actual copies are generally avoided. -The kernel does this by implementing a pipe buffer as a set +The kernel does this by implementing a pipe buffer as a set of reference-counted pointers to pages of kernel memory. -The kernel creates "copies" of pages in a buffer by creating new -pointers (for the output buffer) referring to the pages, -and increasing the reference counts for the pages: +The kernel creates "copies" of pages in a buffer by creating new +pointers (for the output buffer) referring to the pages, +and increasing the reference counts for the pages: only pointers are copied, not the pages of the buffer. .\" -.\" Linus: Now, imagine using the above in a media server, for example. -.\" Let's say that a year or two has passed, so that the video drivers -.\" have been updated to be able to do the splice thing, and what can +.\" Linus: Now, imagine using the above in a media server, for example. +.\" Let's say that a year or two has passed, so that the video drivers +.\" have been updated to be able to do the splice thing, and what can .\" you do? You can: -.\" +.\" .\" - splice from the (mpeg or whatever - let's just assume that the video .\" input is either digital or does the encoding on its own - like they .\" pretty much all do) video input into a pipe (remember: no copies - the -.\" video input will just DMA directly into memory, and splice will just +.\" video input will just DMA directly into memory, and splice will just .\" set up the pages in the pipe buffer) .\" - tee that pipe to split it up .\" - splice one end to a file (ie "save the compressed stream to disk") -.\" - splice the other end to a real-time video decoder window for your +.\" - splice the other end to a real-time video decoder window for your .\" real-time viewing pleasure. .\" -.\" Linus: Now, the advantage of splice()/tee() is that you can -.\" do zero-copy movement of data, and unlike sendfile() you can -.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more -.\" than just sending the data to somebody else: you can duplicate -.\" the data and choose to forward it to two or more different +.\" Linus: Now, the advantage of splice()/tee() is that you can +.\" do zero-copy movement of data, and unlike sendfile() you can +.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more +.\" than just sending the data to somebody else: you can duplicate +.\" the data and choose to forward it to two or more different .\" users - for things like logging etc). .\" .SH EXAMPLE diff --git a/man2/stat.2 b/man2/stat.2 index d07fa584e..01168b6cc 100644 --- a/man2/stat.2 +++ b/man2/stat.2 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,7 +33,7 @@ .\" Modified 1999-07-06 by aeb & Albert Cahalan .\" Modified 2000-01-07 by aeb .\" Modified 2004-06-23 by Michael Kerrisk -.\" +.\" .TH STAT 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual" .SH NAME stat, fstat, lstat \- get file status @@ -54,7 +54,7 @@ stat, fstat, lstat \- get file status These functions return information about a file. No permissions are required on the file itself, but \(em in the case of .BR stat () -and +and .BR lstat () \(em execute (search) permission is required on all of the directories in @@ -62,7 +62,7 @@ execute (search) permission is required on all of the directories in that lead to the file. .PP .BR stat () -stats the file pointed to by +stats the file pointed to by .I path and fills in .IR buf . @@ -115,8 +115,8 @@ field describes the device that this file (inode) represents. The .I st_size -field gives the size of the file (if it is a regular -file or a symbolic link) in bytes. +field gives the size of the file (if it is a regular +file or a symbolic link) in bytes. The size of a symlink is the length of the pathname it contains, without a trailing null byte. @@ -137,7 +137,8 @@ Not all of the Linux filesystems implement all of the time fields. Some file system types allow mounting in such a way that file accesses do not cause an update of the .I st_atime -field. (See `noatime' in +field. +(See `noatime' in .BR mount (8).) The field @@ -262,15 +263,16 @@ 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 +For most files under the .I /proc directory, .BR stat () does not return the file size in the -.I st_size +.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 +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -320,13 +322,14 @@ Use of the .I st_blocks and .I st_blksize -fields may be less portable. (They were introduced in BSD. -The interpretation differs between -systems, and possibly on a single system when NFS mounts are involved.) +fields may be less portable. +(They were introduced in BSD. +The interpretation differs between systems, +and possibly on a single system when NFS mounts are involved.) .LP POSIX does not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX bits, but instead demands the use of -the macros S_ISDIR(), etc. +the macros S_ISDIR(), etc. The S_ISLNK and S_ISSOCK macros are not in POSIX.1-1996, but both are present in POSIX.1-2001; the former is from SVID 4, the latter from SUSv2. diff --git a/man2/statfs.2 b/man2/statfs.2 index e30b45659..ab1374e3a 100644 --- a/man2/statfs.2 +++ b/man2/statfs.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -115,7 +115,8 @@ Fields that are undefined for a particular file system are set to 0. returns the same information about an open file referenced by descriptor .IR fd . .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -181,16 +182,17 @@ The Linux was inspired by the 4.4BSD one (but they do not use the same structure). .SH NOTES -The kernel has system calls -.BR statfs (), -.BR fstatfs (), +The kernel has system calls +.BR statfs (), +.BR fstatfs (), .BR statfs64 (), and .BR fstatfs64 () to support this library call. Some systems only have , other systems also have -, where the former includes the latter. So it seems +, where the former includes the latter. +So it seems including the former is the best choice. LSB has deprecated the library calls diff --git a/man2/statvfs.2 b/man2/statvfs.2 index 58f7b38c1..4631025f4 100644 --- a/man2/statvfs.2 +++ b/man2/statvfs.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -55,7 +55,7 @@ struct statvfs { fsfilcnt_t f_files; /* # inodes */ fsfilcnt_t f_ffree; /* # free inodes */ fsfilcnt_t f_favail; /* # free inodes for non-root */ - unsigned long f_fsid; /* file system ID */ + unsigned long f_fsid; /* file system ID */ unsigned long f_flag; /* mount flags */ unsigned long f_namemax; /* maximum filename length */ }; @@ -90,7 +90,8 @@ have meaningful values on all filesystems. returns the same information about an open file referenced by descriptor .IR fd . .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -152,7 +153,7 @@ Some values were too large to be represented in the returned struct. .SH "CONFORMING TO" POSIX.1-2001 .SH NOTES -The Linux kernel has system calls +The Linux kernel has system calls .BR statfs () and .BR fstatfs () diff --git a/man2/stime.2 b/man2/stime.2 index ce7f02017..bc7ae5b54 100644 --- a/man2/stime.2 +++ b/man2/stime.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,11 +37,13 @@ stime \- set time .sp .BI "int stime(time_t *" t ); .SH DESCRIPTION -\fBstime\fP() sets the system's idea of the time and date. Time, pointed +\fBstime\fP() sets the system's idea of the time and date. +Time, pointed to by \fIt\fP, is measured in seconds from 00:00:00 GMT January 1, 1970. \fBstime\fP() may only be executed by the superuser. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man2/swapon.2 b/man2/swapon.2 index 4d3d846b3..d114487ea 100644 --- a/man2/swapon.2 +++ b/man2/swapon.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -96,13 +96,14 @@ pages are allocated on a round-robin basis between them. As of Linux 1.3.6, the kernel usually follows these rules, but there are exceptions. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP .B EBUSY -(for +(for .BR swapon ()) The specified .I path @@ -115,7 +116,7 @@ exists, but refers neither to a regular file nor to a block device; or, for .BR swapon (), the indicated path does not contain a valid swap signature; -or, for +or, for .BR swapoff (), .I path is not currently a swap area. @@ -125,7 +126,7 @@ The system limit on the total number of open files has been reached. .TP .B ENOENT The file -.I path +.I path does not exist. .TP .B ENOMEM diff --git a/man2/symlink.2 b/man2/symlink.2 index 1d5841aad..e5488d6f1 100644 --- a/man2/symlink.2 +++ b/man2/symlink.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -69,7 +69,8 @@ exists it will .I not be overwritten. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -137,7 +138,7 @@ file (unless it also has other hard links). If this behaviour is not desired, use .BR link (). .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error codes EDQUOT and ENOSYS. .\" See .\" .BR open (2) diff --git a/man2/symlinkat.2 b/man2/symlinkat.2 index 85379242a..87929a897 100644 --- a/man2/symlinkat.2 +++ b/man2/symlinkat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,37 +41,37 @@ system call operates in exactly the same way as .BR symlink (2), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I newpath is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR newdirfd -(rather than relative to the current working directory of +.IR newdirfd +(rather than relative to the current working directory of the calling process, as is done by .BR symlink (2) for a relative pathname). If .I newpath -is relative and +is relative and .I newdirfd is the special value .BR AT_FDCWD , then .I newpath -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR symlink (2)). If .IR newpath -is absolute, then -.I newdirfd +is absolute, then +.I newdirfd is ignored. .SH "RETURN VALUE" On success, -.BR symlinkat () -returns 0. +.BR symlinkat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -80,7 +80,7 @@ The same errors that occur for .BR symlink (2) can also occur for .BR symlinkat (). -The following additional errors can occur for +The following additional errors can occur for .BR symlinkat (): .TP .B EBADF diff --git a/man2/sync.2 b/man2/sync.2 index 76095b92d..3b34a821d 100644 --- a/man2/sync.2 +++ b/man2/sync.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -54,8 +54,9 @@ However, since version 1.3.20 Linux does actually wait. large caches.) .SH NOTES Since glibc 2.2.2 the Linux prototype is as listed above, -following the various standards. In libc4, libc5, and glibc up to 2.2.1 -it was "int sync(void)", and +following the various standards. +In libc4, libc5, and glibc up to 2.2.1 +it was "int sync(void)", and .BR sync () always returned 0. .SH "SEE ALSO" diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index e1402848d..4252cb763 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,11 +19,11 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" 2006-07-05 Initial creation, Michael Kerrisk based on +.\" 2006-07-05 Initial creation, Michael Kerrisk based on .\" Andrew Morton's comments in fs/sync.c .\" .TH SYNC_FILE_RANGE 2 2006-07-05 "Linux 2.6.17" "Linux Programmer's Manual" @@ -34,7 +34,7 @@ sync_file_range \- sync a file segment with disk .B #define _GNU_SOURCE .B #include -.BI "void sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes , +.BI "void sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes , .BI " unsigned int " flags ); .fi .SH DESCRIPTION @@ -44,22 +44,22 @@ file descriptor .I fd with disk. -.I offset +.I offset is the starting byte of the file range to be synchronised. -.I nbytes +.I nbytes specifies the length of the range to be synchronised, in bytes; if .I nbytes -is zero, then all bytes from +is zero, then all bytes from .I offset through to the end of file are synchronised. Synchronisation is in units of the system page size: -.I offset +.I offset is rounded down to a page boundary; -.I (offset+nbytes-1) +.I (offset+nbytes-1) is rounded up to a page boundary. -The -.I flags +The +.I flags bit-mask argument can include any of the following values: .TP .B SYNC_FILE_RANGE_WAIT_BEFORE @@ -79,51 +79,52 @@ Specifying .I flags as 0 is permitted, as a no-op. .SH NOTES -None of these operations write out the file's metadata. +None of these operations write out the file's metadata. Therefore, unless the application is strictly performing overwrites of -already-instantiated disk blocks, +already-instantiated disk blocks, there are no guarantees that the data will be available after a crash. -.B SYNC_FILE_RANGE_WAIT_BEFORE -and -.B SYNC_FILE_RANGE_WAIT_AFTER +.B SYNC_FILE_RANGE_WAIT_BEFORE +and +.B SYNC_FILE_RANGE_WAIT_AFTER will detect any -I/O errors or -.B ENOSPC +I/O errors or +.B ENOSPC conditions and will return these to the caller. -Useful combinations of the -.I flags +Useful combinations of the +.I flags bits are: .TP .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE Ensures that all pages -in the specified range which were dirty when -.BR sync_file_range () +in the specified range which were dirty when +.BR sync_file_range () was called are placed -under write-out. +under write-out. This is a start-write-for-data-integrity operation. .TP .B SYNC_FILE_RANGE_WRITE Start write-out of all dirty pages in the specified range which -are not presently under write-out. This is an asynchronous flush-to-disk -operation. +are not presently under write-out. +This is an asynchronous flush-to-disk +operation. This is not suitable for data integrity operations. .TP .BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER ) Wait for -completion of write-out of all pages in the specified range. -This can be used after an earlier -SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE +completion of write-out of all pages in the specified range. +This can be used after an earlier +SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE operation to wait for completion of that operation, and obtain its result. .TP .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER -This is a traditional -.BR fdatasync (2) +This is a traditional +.BR fdatasync (2) operation. It is a write-for-data-integrity operation that will ensure that all pages in the specified range which were dirty when -.BR sync_file_range() +.BR sync_file_range() was called are committed to disk. .SH ERRORS .TP @@ -136,7 +137,7 @@ I/O error. .TP .B EINVAL .I flags -specifies an invalid bit; or +specifies an invalid bit; or .I offset or .I nbytes @@ -150,13 +151,13 @@ Out of disk space. .TP .B ESPIPE .I fd -refers to something other than a regular file, a block device, +refers to something other than a regular file, a block device, a directory, or a symbolic link. -.\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)? -.\" (In userspace at least) it isn't possible to obtain a file descriptor +.\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)? +.\" (In userspace at least) it isn't possible to obtain a file descriptor .\" for a symbolic link. .SH "CONFORMING TO" -This system call is Linux specific, and should be avoided +This system call is Linux specific, and should be avoided in portable programs. .SH VERSIONS .BR sync_file_range () diff --git a/man2/syscalls.2 b/man2/syscalls.2 index 11d28b38f..44460f959 100644 --- a/man2/syscalls.2 +++ b/man2/syscalls.2 @@ -29,7 +29,8 @@ none \- list of all system calls Linux 2.4 system calls. .SH DESCRIPTION The system call is the fundamental interface between an application -and the Linux kernel. As of Linux 2.4.17, there are 1100 system calls +and the Linux kernel. +As of Linux 2.4.17, there are 1100 system calls listed in .IR /usr/src/linux/include/asm-*/unistd.h . This man page lists those that are common to most platforms. @@ -258,9 +259,11 @@ and .BR ulimit (3) exist as library routines. The slot for phys is in use since 2.1.116 for umount; -phys will never be implemented. The getpmsg and putpmsg calls are for +phys will never be implemented. +The getpmsg and putpmsg calls are for kernels patched to support streams, and may never be in the standard -kernel. The security call is for future use. +kernel. +The security call is for future use. Roughly speaking, the code belonging to the system call with number __NR_xxx defined in @@ -271,7 +274,8 @@ can be found in the kernel source in the routine .IR /usr/src/linux/arch/i386/kernel/entry.S .) There are many exceptions, however, mostly because older system calls were superseded by newer ones, -and this has been treated somewhat unsystematically. On platforms with +and this has been treated somewhat unsystematically. +On platforms with proprietary OS emulation, such as parisc, sparc, sparc64 and alpha, there are many additional system calls; mips64 also contains a full set of 32-bit system calls. @@ -294,11 +298,13 @@ It is different with and .IR mmap . These use five or more parameters, and caused problems the way -parameter passing on the i386 used to be set up. Thus, while +parameter passing on the i386 used to be set up. +Thus, while other architectures have sys_select() and sys_mmap() corresponding to __NR_select and __NR_mmap, on i386 one finds old_select() and old_mmap() (routines that use a pointer to a -parameter block) instead. These days passing five parameters +parameter block) instead. +These days passing five parameters is not a problem any more, and there is a __NR__newselect (used by libc 6) that corresponds directly to sys_select() and similarly __NR_mmap2. @@ -313,10 +319,12 @@ On many platforms, including i386, socket calls are all multiplexed through socketcall() and System V IPC calls through ipc(). On newer platforms that only have 64-bit file access and 32-bit uids -(e.g. alpha, ia64, s390x) there are no *64 or *32 calls. Where the *64 +(e.g. alpha, ia64, s390x) there are no *64 or *32 calls. +Where the *64 and *32 calls exist, the other versions are obsolete. -The chown and lchown system calls were swapped in 2.1.81. The *64 and +The chown and lchown system calls were swapped in 2.1.81. +The *64 and *32 calls were added for kernel 2.4, as were the new versions of getrlimit and mmap, and the new calls pivot_root, mincore, madvise, security, gettid and readahead. diff --git a/man2/sysctl.2 b/man2/sysctl.2 index 044975296..7a27d4c2e 100644 --- a/man2/sysctl.2 +++ b/man2/sysctl.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,8 +46,10 @@ sysctl \- read/write system parameters .SH DESCRIPTION The .BR _sysctl () -call reads and/or writes kernel parameters. For example, the hostname, -or the maximum number of open files. The argument has the form +call reads and/or writes kernel parameters. +For example, the hostname, +or the maximum number of open files. +The argument has the form .PP .nf struct __sysctl_args { @@ -76,7 +78,7 @@ _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, + struct __sysctl_args args = { name, nlen, oldval, oldlenp, newval, newlen }; return _sysctl(&args); } @@ -102,7 +104,8 @@ main(void) .SH "RETURN VALUE" Upon successful completion, .BR _sysctl () -returns 0. Otherwise, a value of \-1 is returned and +returns 0. +Otherwise, a value of \-1 is returned and .I errno is set to indicate the error. .SH ERRORS @@ -129,8 +132,10 @@ This call is Linux specific, and should not be used in programs intended to be portable. A .BR sysctl () -call has been present in Linux since version 1.3.57. It originated in -4.4BSD. Only Linux has the +call has been present in Linux since version 1.3.57. +It originated in +4.4BSD. +Only Linux has the .I /proc/sys mirror, and the object naming schemes differ between Linux and 4.4BSD, but the declaration of the diff --git a/man2/sysfs.2 b/man2/sysfs.2 index fced6d4e5..501cad68b 100644 --- a/man2/sysfs.2 +++ b/man2/sysfs.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,7 +34,8 @@ sysfs \- get file system type information .SH DESCRIPTION .BR sysfs () returns information about the file system types currently present in -the kernel. The specific form of the +the kernel. +The specific form of the .BR sysfs () call and the information returned depends on the .I option @@ -48,7 +49,8 @@ into a file-system type index. .B 2 Translate the file-system type index .I fs_index -into a null-terminated file-system identifier string. This string will +into a null-terminated file-system identifier string. +This string will be written to the buffer pointed to by .IR buf . Make sure that diff --git a/man2/sysinfo.2 b/man2/sysinfo.2 index 1760ca94a..a1934d960 100644 --- a/man2/sysinfo.2 +++ b/man2/sysinfo.2 @@ -68,12 +68,14 @@ struct sysinfo { and the sizes are given as multiples of \fImem_unit\fP bytes. .BR sysinfo () -provides a simple way of getting overall system statistics. This is more +provides a simple way of getting overall system statistics. +This is more portable than reading \fI/dev/kmem\fP. -For an example of its use, see +For an example of its use, see .BR intro (2). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -85,9 +87,9 @@ This function is Linux specific, and should not be used in programs intended to be portable. .sp The Linux kernel has a -.BR sysinfo () +.BR sysinfo () system call since 0.98.pl6. -Linux libc contains a +Linux libc contains a .BR sysinfo () routine since 5.3.5, and glibc has one since 1.90. diff --git a/man2/syslog.2 b/man2/syslog.2 index e688ab2ec..f637ee9d7 100644 --- a/man2/syslog.2 +++ b/man2/syslog.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,14 +16,14 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Written 11 June 1995 by Andries Brouwer .TH SYSLOG 2 2001-11-25 "Linux 1.2.9" "Linux Programmer's Manual" .SH NAME -syslog, klogctl \- read and/or clear kernel message ring buffer; +syslog, klogctl \- read and/or clear kernel message ring buffer; set console_loglevel .SH SYNOPSIS .nf @@ -94,8 +94,10 @@ The call .BR syslog () .RI (2, buf , len ) waits until this kernel log buffer is nonempty, and then reads -at most \fIlen\fP bytes into the buffer \fIbuf\fP. It returns -the number of bytes read. Bytes read from the log disappear from +at most \fIlen\fP bytes into the buffer \fIbuf\fP. +It returns +the number of bytes read. +Bytes read from the log disappear from the log buffer: the information can only be read once. This is the function executed by the kernel when a user program reads @@ -137,10 +139,12 @@ The calls with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only) or 7 (all except debugging messages), respectively. -Every text line in a message has its own loglevel. This level is +Every text line in a message has its own loglevel. +This level is DEFAULT_MESSAGE_LOGLEVEL \- 1 (6) unless the line starts with where \fId\fP is a digit in the range 1-7, in which case the level -is \fId\fP. The conventional meaning of the loglevel is defined in +is \fId\fP. +The conventional meaning of the loglevel is defined in .I as follows: @@ -155,7 +159,8 @@ as follows: #define KERN_DEBUG "<7>" /* debug-level messages */ .fi .SH "RETURN VALUE" -In case of error, \-1 is returned, and \fIerrno\fP is set. Otherwise, +In case of error, \-1 is returned, and \fIerrno\fP is set. +Otherwise, for \fItype\fP equal to 2, 3 or 4, \fBsyslog\fP() returns the number of bytes read, and otherwise 0. .SH ERRORS diff --git a/man2/tee.2 b/man2/tee.2 index 3a793ce46..38b3ccb88 100644 --- a/man2/tee.2 +++ b/man2/tee.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,8 +38,8 @@ tee \- duplicating pipe content .\" Example programs http://brick.kernel.dk/snaps .\" .\" -.\" add a "tee(in, out1, out2)" system call that duplicates the pages -.\" (again, incrementing their reference count, not copying the data) from +.\" add a "tee(in, out1, out2)" system call that duplicates the pages +.\" (again, incrementing their reference count, not copying the data) from .\" one pipe to two other pipes. .BR tee () duplicates up to @@ -49,8 +49,8 @@ bytes of data from the pipe referred to by the file descriptor to the pipe referred to by the file descriptor .IR fd_out . It does not consume the data that is duplicated from -.IR fd_in ; -therefore, that data can be copied by a subsequent +.IR fd_in ; +therefore, that data can be copied by a subsequent .BR splice (2). .I flags @@ -60,18 +60,18 @@ and .BR vmsplice (2): .TP 1.9i .B SPLICE_F_MOVE -Currently has no effect for +Currently has no effect for .BR tee (); see .BR splice (2). .TP .B SPLICE_F_NONBLOCK -Do not block on I/O; see -.BR splice (2) +Do not block on I/O; see +.BR splice (2) for further details. .TP .B SPLICE_F_MORE -Currently has no effect for +Currently has no effect for .BR tee (), but may be implemented in the future; see .BR splice (2). @@ -85,19 +85,19 @@ see Upon successful completion, .BR tee () returns the number of bytes that were duplicated between the input -and output. -A return value of 0 means that there was no data to transfer, -and it would not make sense to block, because there are no -writers connected to the write end of the pipe referred to by +and output. +A return value of 0 means that there was no data to transfer, +and it would not make sense to block, because there are no +writers connected to the write end of the pipe referred to by .IR fd_in . -On error, +On error, .BR tee () returns \-1 and .I errno is set to indicate the error. .SH ERRORS -.TP +.TP .B EINVAL .I fd_in or @@ -117,14 +117,14 @@ copies the data between the two pipes. In reality no real data copying takes place though: under the covers, .BR tee () -assigns data in the output by merely grabbing +assigns data in the output by merely grabbing a reference to the input. .SH EXAMPLE The following example implements a basic .BR tee (1) program using the .BR tee (2) -system call. +system call. .nf #define _GNU_SOURCE diff --git a/man2/time.2 b/man2/time.2 index fc1517cbd..0d7032927 100644 --- a/man2/time.2 +++ b/man2/time.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -57,10 +57,11 @@ POSIX.1 defines as a value to be interpreted as the number of seconds between a specified time and the Epoch, according to a formula for conversion from UTC equivalent to conversion on the naive basis that leap -seconds are ignored and all years divisible by 4 are leap years. This -value is not the same as the actual number of seconds between the time +seconds are ignored and all years divisible by 4 are leap years. +This value is not the same as the actual number of seconds between the time and the Epoch, because of leap seconds and because clocks are not -required to be synchronised to a standard reference. The intention is +required to be synchronised to a standard reference. +The intention is that the interpretation of seconds since the Epoch values be consistent; see POSIX.1 Annex B 2.2.2 for further rationale. .SH "CONFORMING TO" diff --git a/man2/times.2 b/man2/times.2 index c1480aaeb..f17a70f95 100644 --- a/man2/times.2 +++ b/man2/times.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -93,7 +93,8 @@ is added in at the moment .BR wait (2) or .BR waitpid (2) -returns their process ID. In particular, times of grandchildren +returns their process ID. +In particular, times of grandchildren that the children did not wait for are never seen. .LP All times reported are in clock ticks. @@ -116,7 +117,8 @@ sysconf(_SC_CLK_TCK); .RE In POSIX-1996 the symbol CLK_TCK (defined in .IR ) -is mentioned as obsolescent. It is obsolete now. +is mentioned as obsolescent. +It is obsolete now. .PP In Linux kernel versions before 2.6.9, if the disposition of @@ -160,7 +162,8 @@ SVr1-3 returns .I long and the struct members are of type .I time_t -although they store clock ticks, not seconds since the epoch. V7 used +although they store clock ticks, not seconds since the epoch. +V7 used .I long for the struct members, because it had no type .I time_t diff --git a/man2/tkill.2 b/man2/tkill.2 index ecc0be9e4..43e927f22 100644 --- a/man2/tkill.2 +++ b/man2/tkill.2 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -56,13 +56,15 @@ by its unique TID. .PP The \fBtgkill\fP() call improves on \fBtkill\fP() by allowing the caller to specify the thread group ID of the thread to be signalled, protecting -against TID reuse. If the tgid is specified as \-1, \fBtgkill\fP() degenerates +against TID reuse. +If the tgid is specified as \-1, \fBtgkill\fP() degenerates into \fBtkill\fP(). .PP These are the raw system call interfaces, meant for internal thread library use. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and \fIerrno\fP +On success, zero is returned. +On error, \-1 is returned, and \fIerrno\fP is set appropriately. .SH ERRORS .TP @@ -70,7 +72,8 @@ is set appropriately. An invalid TID or signal was specified. .TP .B EPERM -Permission denied. For the required permissions, see +Permission denied. +For the required permissions, see .BR kill (2). .TP .B ESRCH diff --git a/man2/truncate.2 b/man2/truncate.2 index 6ab7ab605..fee104346 100644 --- a/man2/truncate.2 +++ b/man2/truncate.2 @@ -62,17 +62,17 @@ to be truncated to a size of precisely .I length bytes. .LP -If the file previously was larger than this size, the extra data is lost. +If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes ('\\0'). .LP The file offset is not changed. .LP -If the size changed, then the st_ctime and st_mtime fields +If the size changed, then the st_ctime and st_mtime fields (respectively, time of last status change and time of last modification; see .BR stat (2)) -for the file are updated, +for the file are updated, and the set-user-ID and set-group-ID permission bits may be cleared. .LP With @@ -81,7 +81,8 @@ the file must be open for writing; with .BR truncate (), the file must be writable. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -188,11 +189,11 @@ exceeds the file length .BR truncate () is not specified at all in such an environment): either returning an error, or extending the file. -Like most Unix implementations, Linux follows the XSI requirement -when dealing with native file systems. +Like most Unix implementations, Linux follows the XSI requirement +when dealing with native file systems. However, some non-native file systems do not permit .BR truncate () -and +and .BR ftruncate () to be used to extend a file beyond its current length: a notable example on Linux is VFAT. diff --git a/man2/umask.2 b/man2/umask.2 index 8253e375c..993d3c3c5 100644 --- a/man2/umask.2 +++ b/man2/umask.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,8 +40,8 @@ umask \- set file mode creation mask .BI "mode_t umask(mode_t " mask ); .SH DESCRIPTION .BR umask () -sets the calling process's file mode creation mask (umask) to -.I mask +sets the calling process's file mode creation mask (umask) to +.I mask & 0777. The umask is used by @@ -57,7 +57,7 @@ the \fImode\fR argument to and .BR mkdir (2). -The constants that should be used to specify +The constants that should be used to specify .I mask are described under .BR stat (2). @@ -67,7 +67,7 @@ S_IWGRP\ |\ S_IWOTH (octal 022). In the usual case where the .I mode -argument to +argument to .BR open (2) is specified as: .nf diff --git a/man2/uname.2 b/man2/uname.2 index 21af4c14c..4e66b7b1e 100644 --- a/man2/uname.2 +++ b/man2/uname.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,8 +31,8 @@ uname \- get name and information about current kernel .BR uname () returns system information in the structure pointed to by .IR buf . -The -.I utsname +The +.I utsname struct is defined in .IR : .in +0.5i @@ -55,7 +55,8 @@ The length of the arrays in a .I struct utsname is unspecified; the fields are terminated by a null byte ('\\0'). .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -74,12 +75,14 @@ The member (the NIS or YP domain name) is a GNU extension. .SH NOTES This is a system call, and the operating system presumably knows -its name, release and version. It also knows what hardware it runs on. +its name, release and version. +It also knows what hardware it runs on. So, four of the fields of the struct are meaningful. On the other hand, the field \fInodename\fP is meaningless: it gives the name of the present machine in some undefined network, but typically machines are in more than one network -and have several names. Moreover, the kernel has no way of knowing +and have several names. +Moreover, the kernel has no way of knowing about such things, so it has to be told what to answer here. The same holds for the additional \fIdomainname\fP field. .LP @@ -92,17 +95,22 @@ Note that there is no standard that says that the hostname set by is the same string as the \fInodename\fP field of the struct returned by .BR uname () (indeed, some systems allow a 256-byte hostname and an 8-byte nodename), -but this is true on Linux. The same holds for +but this is true on Linux. +The same holds for .BR setdomainname (2) and the \fIdomainname\fP field. .LP -The length of the fields in the struct varies. Some operating systems -or libraries use a hardcoded 9 or 33 or 65 or 257. Other systems use -SYS_NMLN or _SYS_NMLN or UTSLEN or _UTSNAME_LENGTH. Clearly, it is a bad +The length of the fields in the struct varies. +Some operating systems +or libraries use a hardcoded 9 or 33 or 65 or 257. +Other systems use +SYS_NMLN or _SYS_NMLN or UTSLEN or _UTSNAME_LENGTH. +Clearly, it is a bad idea to use any of these constants; just use sizeof(...). Often 257 is chosen in order to have room for an internet hostname. .LP -There have been three Linux system calls \fIuname\fP(). The first one +There have been three Linux system calls \fIuname\fP(). +The first one used length 9, the second one used 65, the third one also uses 65 but adds the \fIdomainname\fP field. .LP diff --git a/man2/unlink.2 b/man2/unlink.2 index 5a71afb62..fbf4cca54 100644 --- a/man2/unlink.2 +++ b/man2/unlink.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,8 @@ unlink \- delete a name and possibly the file it refers to .BI "int unlink(const char *" pathname ); .SH DESCRIPTION .BR unlink () -deletes a name from the filesystem. If that name was the +deletes a name from the filesystem. +If that name was the last link to a file and no processes have the file open the file is deleted and the space it was using is made available for reuse. @@ -134,7 +135,7 @@ capability). .I pathname refers to a file on a read-only filesystem. .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error .\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK. .SH BUGS diff --git a/man2/unlinkat.2 b/man2/unlinkat.2 index ce44f1841..a06298018 100644 --- a/man2/unlinkat.2 +++ b/man2/unlinkat.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,7 @@ The .BR unlinkat () system call operates in exactly the same way as either .BR unlink (2) -or +or .BR rmdir (2) (depending on whether or not .I flags @@ -47,27 +47,27 @@ includes the flag) except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR unlink (2) and .BR rmdir (2) for a relative pathname). -If the pathname given in +If the pathname given in .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , then .I pathname -is interpreted relative to the current working +is interpreted relative to the current working directory of the calling process (like .BR unlink (2) and @@ -75,13 +75,13 @@ and If the pathname given in .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .I flags is a bit mask that can either be specified as 0, or by ORing -together flag values that control the operation of +together flag values that control the operation of .BR unlinkat (). Currently only one such flags is defined: .TP @@ -92,17 +92,17 @@ performs the equivalent of .BR unlink (2) on .IR pathname . -If the +If the .B AT_REMOVEDIR flag is specified, then -performs the equivalent of +performs the equivalent of .BR rmdir (2) on .IR pathname . .SH "RETURN VALUE" On success, -.BR unlinkat () -returns 0. +.BR unlinkat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -113,7 +113,7 @@ and .BR rmdir (2) can also occur for .BR unlinkat (). -The following additional errors can occur for +The following additional errors can occur for .BR unlinkat (): .TP .B EBADF diff --git a/man2/unshare.2 b/man2/unshare.2 index bf8557173..d81fa2fc1 100644 --- a/man2/unshare.2 +++ b/man2/unshare.2 @@ -3,16 +3,16 @@ .\" Licensed under the GPL .\" .\" Patch Justification: -.\" unshare system call is needed to implement, using PAM, -.\" per-security_context and/or per-user namespace to provide -.\" polyinstantiated directories. Using unshare and bind mounts, a -.\" PAM module can create private namespace with appropriate -.\" directories(based on user's security context) bind mounted on -.\" public directories such as /tmp, thus providing an instance of -.\" /tmp that is based on user's security context. Without the -.\" unshare system call, namespace separation can only be achieved -.\" by clone, which would require porting and maintaining all commands -.\" such as login, and su, that establish a user session. +.\" unshare system call is needed to implement, using PAM, +.\" per-security_context and/or per-user namespace to provide +.\" polyinstantiated directories. Using unshare and bind mounts, a +.\" PAM module can create private namespace with appropriate +.\" directories(based on user's security context) bind mounted on +.\" public directories such as /tmp, thus providing an instance of +.\" /tmp that is based on user's security context. Without the +.\" unshare system call, namespace separation can only be achieved +.\" by clone, which would require porting and maintaining all commands +.\" such as login, and su, that establish a user session. .\" .TH UNSHARE 2 2005-03-10 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME @@ -24,27 +24,27 @@ unshare \- disassociate parts of the process execution context .BI "int unshare(int " flags ); .fi .SH DESCRIPTION -.BR unshare () +.BR unshare () allows a process to disassociate parts of its execution -context that are currently being shared with other processes. -Part of the execution context, such as the namespace, is shared -implicitly when a new process is created using +context that are currently being shared with other processes. +Part of the execution context, such as the namespace, is shared +implicitly when a new process is created using .BR fork (2) or -.BR vfork (2), +.BR vfork (2), while other parts, such as virtual memory, may be -shared by explicit request when creating a process using +shared by explicit request when creating a process using .BR clone (2). -The main use of +The main use of .BR unshare () is to allow a process to control its shared execution context without creating a new process. -The -.I flags -argument is a bit mask that specifies which parts of -the execution context should be unshared. +The +.I flags +argument is a bit mask that specifies which parts of +the execution context should be unshared. This argument is specified by ORing together zero or more of the following constants: .TP @@ -53,16 +53,16 @@ Reverse the effect of the .BR clone (2) .B CLONE_FILES flag. -Unshare the file descriptor table, so that the calling process +Unshare the file descriptor table, so that the calling process no longer shares its file descriptors with any other process. .TP .B CLONE_FS Reverse the effect of the .BR clone (2) -.B CLONE_FS +.B CLONE_FS flag. -Unshare file system attributes, so that the calling process -no longer shares its root directory, current directory, +Unshare file system attributes, so that the calling process +no longer shares its root directory, current directory, or umask attributes with any other process. .BR chroot (2), .BR chdir (2), @@ -71,11 +71,11 @@ or .TP .B CLONE_NEWNS .\" These flag name are inconsistent: -.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, +.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, .\" CLONE_FS, and CLONE_FILES reverse the action of the clone() .\" flags of the same name. -This flag has the -.I same +This flag has the +.I same effect as the .BR clone (2) .B CLONE_NEWNS @@ -88,8 +88,8 @@ as well. .\" As at 2.6.16, the following forced implications also apply, .\" although the relevant flags are not yet implemented. .\" If CLONE_THREAD is set force CLONE_VM. -.\" If CLONE_VM is set, force CLONE_SIGHAND. -.\" If CLONE_SIGHAND is set and signals are also being shared +.\" If CLONE_VM is set, force CLONE_SIGHAND. +.\" If CLONE_SIGHAND is set and signals are also being shared .\" (i.e., current->signal->count > 1), force CLONE_THREAD. .\" .\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented. @@ -105,25 +105,26 @@ as well. .\" and can be reversed using this .\" .BR unshare () .\" flag.) -.\" Unshare virtual memory, so that the calling process no +.\" Unshare virtual memory, so that the calling process no .\" longer shares its virtual address space with any other process. .PP -If +If .I flags is specified as zero, then .BR unshare () is a no-op; no changes are made to the calling process's execution context. .SH RETURN VALUE -On success, zero returned. On failure, \-1 is returned and -.I errno +On success, zero returned. +On failure, \-1 is returned and +.I errno is set to indicate the error. .SH ERRORS .TP .B EPERM .I flags specified -.B CLONE_NEWNS +.B CLONE_NEWNS but the calling process was not privileged (did not have the .B CAP_SYS_ADMIN capability). @@ -144,13 +145,13 @@ The .BR unshare () system call was added to Linux in kernel 2.6.16. -Not all of the process attributes that can be shared when +Not all of the process attributes that can be shared when a new process is created using .BR clone (2) can be unshared using .BR unshare (). In particular, as at kernel 2.6.16, -.BR unshare () +.BR unshare () does not implement flags that reverse the effects of .BR CLONE_SIGHAND , .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND @@ -180,7 +181,7 @@ Such functionality may be added in the future, if required. .\"applications using unshare. .\" .SH SEE ALSO -.BR clone (2), -.BR fork (2), -.BR vfork (2), +.BR clone (2), +.BR fork (2), +.BR vfork (2), Documentation/unshare.txt diff --git a/man2/uselib.2 b/man2/uselib.2 index 95c778a91..763a50f45 100644 --- a/man2/uselib.2 +++ b/man2/uselib.2 @@ -38,11 +38,14 @@ uselib \- load shared library .SH DESCRIPTION The system call \fBuselib\fP() serves to load a shared library to be used by the calling process. -It is given a pathname. The address where to load is found -in the library itself. The library can have any recognized +It is given a pathname. +The address where to load is found +in the library itself. +The library can have any recognized binary format. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man2/ustat.2 b/man2/ustat.2 index eb4d1a869..316972ff7 100644 --- a/man2/ustat.2 +++ b/man2/ustat.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -61,7 +61,8 @@ always be filled with null bytes ('\\0'). .SH "RETURN VALUE" On success, zero is returned and the ustat structure pointed to by .I ubuf -will be filled in. On error, \-1 is returned, and +will be filled in. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -80,7 +81,7 @@ The mounted file system referenced by does not support this operation, or any version of Linux before 1.3.16. .SH "CONFORMING TO" -SVr4. +SVr4. .\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR .\" but has no ENOSYS condition. .SH NOTES @@ -91,10 +92,10 @@ All new programs should use instead. .SH "HP-UX NOTES" The HP-UX version of the -.I ustat +.I ustat structure has an additional field, .IR f_blksize , -that is unknown elsewhere. +that is unknown elsewhere. HP-UX warns: For some file systems, the number of free inodes does not change. Such file systems will return \-1 in the field diff --git a/man2/utime.2 b/man2/utime.2 index f7afb7ca2..c814da793 100644 --- a/man2/utime.2 +++ b/man2/utime.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,7 +49,7 @@ changes the access and modification times of the inode specified by .I filename to the .IR actime " and " modtime -fields of +fields of .I buf respectively. @@ -104,7 +104,8 @@ struct timeval { .fi .RE .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -152,7 +153,7 @@ On the other hand, POSIX.1-2001 is buggy in its error description for .BR utimes (). .SH "CONFORMING TO" .BR utime (): -SVr4, POSIX.1-2001. +SVr4, POSIX.1-2001. .\" SVr4 documents additional error conditions EFAULT, .\" EINTR, ELOOP, EMULTIHOP, ENAMETOOLONG, ENOLINK, ENOLINK, ENOTDIR. .br diff --git a/man2/vfork.2 b/man2/vfork.2 index dc045351c..0ae5e628d 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,8 +40,8 @@ function has the same effect as .BR fork (), except that the behaviour is undefined if the process created by .BR vfork () -either modifies any data other than a variable of type -.I pid_t +either modifies any data other than a variable of type +.I pid_t used to store the return value from .BR vfork (), or returns from the function in which @@ -63,12 +63,13 @@ For details and return value and errors, see is a special case of .BR clone (2). It is used to create new processes without copying the page tables of -the parent process. It may be useful in performance sensitive applications +the parent process. +It may be useful in performance sensitive applications where a child will be created which then immediately issues an .BR execve () . .PP .BR vfork () -differs from +differs from .BR fork () in that the parent is suspended until the child makes a call to .BR execve (2) @@ -76,13 +77,14 @@ or .BR _exit (2). The child shares all memory with its parent, including the stack, until .BR execve () -is issued by the child. The child must not return from the -current function or call +is issued by the child. +The child must not return from the current function or call .BR exit (), but may call .BR _exit (). .PP -Signal handlers are inherited, but not shared. Signals to the parent +Signal handlers are inherited, but not shared. +Signals to the parent arrive after the child releases the parent's memory. .SH "HISTORIC DESCRIPTION" Under Linux, @@ -96,13 +98,15 @@ However, in the bad old days a would require making a complete copy of the caller's data space, often needlessly, since usually immediately afterwards an .BR exec () -is done. Thus, for greater efficiency, BSD introduced the +is done. +Thus, for greater efficiency, BSD introduced the .BR vfork () system call, that did not fully copy the address space of the parent process, but borrowed the parent's memory and thread of control until a call to .BR execve () -or an exit occurred. The parent process was suspended while the +or an exit occurred. +The parent process was suspended while the child was using its resources. The use of .BR vfork () @@ -113,7 +117,8 @@ held in a register. It is rather unfortunate that Linux revived this spectre from the past. The BSD manpage states: "This system call will be eliminated when proper system sharing mechanisms -are implemented. Users should not depend on the memory sharing semantics of +are implemented. +Users should not depend on the memory sharing semantics of .BR vfork () as it will, in that case, be made synonymous to .BR fork ().\c @@ -146,19 +151,20 @@ but NetBSD introduced it again, cf. http://www.netbsd.org/Documentation/kernel/vfork.html . In Linux, it has been equivalent to .BR fork () -until 2.2.0-pre6 or so. Since 2.2.0-pre9 (on i386, somewhat later on -other architectures) it is an independent system call. Support was -added in glibc 2.0.112. +until 2.2.0-pre6 or so. +Since 2.2.0-pre9 (on i386, somewhat later on +other architectures) it is an independent system call. +Support was added in glibc 2.0.112. .SH "CONFORMING TO" 4.3BSD, POSIX.1-2001. -.\" FIXME Mar 07: in the draft of the next POSIX revision, the spec for +.\" FIXME Mar 07: in the draft of the next POSIX revision, the spec for .\" vfork() has been removed. The requirements put on .BR vfork () by the standards are weaker than those put on .BR fork (), -so an implementation where the two are synonymous -is compliant. In particular, the programmer cannot +so an implementation where the two are synonymous is compliant. +In particular, the programmer cannot rely on the parent remaining blocked until a call of .BR execve () or @@ -168,10 +174,10 @@ and cannot rely on any specific behaviour w.r.t. shared memory. .SH "LINUX NOTES" Fork handlers established using .BR pthread_atfork (3) -are not called when a multithreaded program employing +are not called when a multithreaded program employing the NPTL threading library calls .BR vfork (). -Fork handlers are called in this case in a program using the +Fork handlers are called in this case in a program using the LinuxThreads threading library. (See .BR pthreads (7) diff --git a/man2/vhangup.2 b/man2/vhangup.2 index 38b417376..b9ece0073 100644 --- a/man2/vhangup.2 +++ b/man2/vhangup.2 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" Modified, 27 May 2004, Michael Kerrisk @@ -33,16 +33,18 @@ vhangup \- virtually hangup the current tty .B int vhangup(void); .SH DESCRIPTION .BR vhangup () -simulates a hangup on the current terminal. This call arranges for other +simulates a hangup on the current terminal. +This call arranges for other users to have a \*(lqclean\*(rq tty at login time. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP .B EPERM -The calling process has insufficient privilege to call +The calling process has insufficient privilege to call .BR vhangup (); the .B CAP_SYS_TTY_CONFIG diff --git a/man2/vm86.2 b/man2/vm86.2 index 529afe69b..af2035d6e 100644 --- a/man2/vm86.2 +++ b/man2/vm86.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,20 +35,23 @@ vm86old, vm86 \- enter virtual 8086 mode .SH DESCRIPTION The system call .BR vm86 () -was introduced in Linux 0.97p2. In Linux 2.1.15 and 2.0.28 it was renamed to +was introduced in Linux 0.97p2. +In Linux 2.1.15 and 2.0.28 it was renamed to .BR vm86old (), and a new .BR vm86 () -was introduced. The definition of `struct vm86_struct' was changed +was introduced. +The definition of `struct vm86_struct' was changed in 1.1.8 and 1.1.9. .LP These calls cause the process to enter VM86 mode (virtual-8086 in Intel -literature), and are used by +literature), and are used by .BR dosemu . .PP VM86 mode is an emulation of real mode within a protected mode task. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS @@ -62,7 +65,8 @@ This return value indicates the call is not implemented on the present architecture. .TP .B EPERM -Saved kernel stack exists. (This is a kernel sanity check; the saved +Saved kernel stack exists. +(This is a kernel sanity check; the saved stack should only exist within vm86 mode itself.) .SH "CONFORMING TO" This call is specific to Linux on Intel processors, and should not be diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 index aa272301b..662730876 100644 --- a/man2/vmsplice.2 +++ b/man2/vmsplice.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,26 +32,26 @@ vmsplice \- splice user pages into a pipe .B #include .B #include -.BI "long vmsplice(int " fd ", const struct iovec *" iov , +.BI "long vmsplice(int " fd ", const struct iovec *" iov , .BI " unsigned long " nr_segs ", unsigned int " flags ); .fi .SH DESCRIPTION -.\" Linus: vmsplice() system call to basically do a "write to -.\" the buffer", but using the reference counting and VM traversal -.\" to actually fill the buffer. This means that the user needs to -.\" be careful not to re-use the user-space buffer it spliced into -.\" the kernel-space one (contrast this to "write()", which copies -.\" the actual data, and you can thus re-use the buffer immediately -.\" after a successful write), but that is often easy to do. +.\" Linus: vmsplice() system call to basically do a "write to +.\" the buffer", but using the reference counting and VM traversal +.\" to actually fill the buffer. This means that the user needs to +.\" be careful not to re-use the user-space buffer it spliced into +.\" the kernel-space one (contrast this to "write()", which copies +.\" the actual data, and you can thus re-use the buffer immediately +.\" after a successful write), but that is often easy to do. The .BR vmsplice () system call maps .I nr_segs ranges of user memory described by .I iov -into a pipe. +into a pipe. The file descriptor -.I fd +.I fd must refer to a pipe. The pointer @@ -84,21 +84,21 @@ see .B SPLICE_F_NONBLOCK .\" Not used for vmsplice .\" May be in the future -- therefore EAGAIN -Do not block on I/O; see -.BR splice (2) +Do not block on I/O; see +.BR splice (2) for further details. .TP .B SPLICE_F_MORE -Currently has no effect for +Currently has no effect for .BR vmsplice (), but may be implemented in the future; see .BR splice (2). .TP .B SPLICE_F_GIFT -The user pages are a gift to the kernel. -The application may not modify this memory ever, +The user pages are a gift to the kernel. +The application may not modify this memory ever, .\" FIXME Explain the following line in a little more detail: -or page cache and on-disk data may differ. +or page cache and on-disk data may differ. Gifting pages to the kernel means that a subsequent .BR splice () .B SPLICE_F_MOVE @@ -112,8 +112,8 @@ Data must also be properly page aligned, both in memory and length. .SH RETURN VALUE Upon successful completion, .BR vmsplice () -returns the number of bytes transferred to the pipe. -On error, +returns the number of bytes transferred to the pipe. +On error, .BR vmplice () returns \-1 and .I errno @@ -127,7 +127,7 @@ either not valid, or doesn't refer to a pipe. .B EINVAL .I nr_segs is 0 or greater than -.BR IOV_MAX; +.BR IOV_MAX; or memory not aligned if .B SPLICE_F_GIFT set. @@ -137,7 +137,7 @@ Out of memory. .SH NOTES .BR vmsplice () follows the other vectorized read/write type functions when it comes to -limitations on number of segments being passed in. +limitations on number of segments being passed in. This limit is .B IOV_MAX as defined in diff --git a/man2/wait.2 b/man2/wait.2 index b73e4def3..5c9b41500 100644 --- a/man2/wait.2 +++ b/man2/wait.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -79,7 +79,7 @@ are not automatically restarted using the flag of .BR sigaction (2)). In the remainder of this page, a child whose state has changed -and which has not yet been waited upon by one of these system +and which has not yet been waited upon by one of these system calls is termed .IR waitable . .SS "wait() and waitpid()" @@ -148,7 +148,7 @@ also return if a stopped child has been resumed by delivery of .PP (For Linux-only options, see below.) .PP -The +The .B WUNTRACED and .B WCONTINUED @@ -199,7 +199,8 @@ returns true if the child process was terminated by a signal. .TP .BI WTERMSIG( status ) returns the number of the signal that caused the child process to -terminate. This macro should only be employed if +terminate. +This macro should only be employed if .B WIFSIGNALED returned true. .TP @@ -220,8 +221,8 @@ or when the child is being traced (see .BR ptrace (2)). .TP .BI WSTOPSIG( status ) -returns the number of the signal which caused the child to stop. This -macro should only be employed if +returns the number of the signal which caused the child to stop. +This macro should only be employed if .B WIFSTOPPED returned true. .TP @@ -297,7 +298,7 @@ Either the exit status of the child, as given to (or .BR exit (3)), or the signal that caused the child to terminate, stop, or continue. -The +The .I si_code field can be used to determine how to interpret this field. .IP \fIsi_code\fP @@ -325,7 +326,7 @@ the state of the structure pointed to by .I infop is unspecified. -.\" POSIX.1-2001 leaves this possibility unspecified; most +.\" POSIX.1-2001 leaves this possibility unspecified; most .\" implementations (including Linux) zero out the structure .\" in this case, but at at least one implementation (AIX 5.1) .\" does not -- MTK Nov 04 @@ -349,7 +350,7 @@ was specified and no child(ren) specified by has yet changed state, then 0 is returned. .BR waitid (): -returns 0 on success or +returns 0 on success or if .B WNOHANG was specified and no child(ren) specified by @@ -362,15 +363,15 @@ Each of these calls sets to an appropriate value in the case of an error. .SH ERRORS .TP -.BR ECHILD -(for +.BR ECHILD +(for .BR wait ()) The calling process does not have any unwaited-for children. .TP -.BR ECHILD -(for -.BR waitpid () -or +.BR ECHILD +(for +.BR waitpid () +or .BR waitid ()) The process specified by .I pid @@ -382,7 +383,8 @@ and .RB ( waitid ()) does not exist or is not a child of the calling process. (This can happen for one's own child if the action for SIGCHLD -is set to SIG_IGN. See also the LINUX NOTES section about threads.) +is set to SIG_IGN. +See also the LINUX NOTES section about threads.) .TP .B EINTR .B WNOHANG @@ -410,13 +412,13 @@ which automatically performs a wait to remove the zombies. POSIX.1-2001 specifies that if the disposition of .B SIGCHLD -is set to +is set to .B SIG_IGN -or the +or the .B SA_NOCLDWAIT flag is set for .BR SIGCHLD -(see +(see .BR sigaction (2)), then children that terminate do not become zombies and a call to .BR wait () @@ -434,8 +436,8 @@ unspecified.) Linux 2.6 conforms to this specification. However, Linux 2.4 (and earlier) does not: if a -.BR wait () -or +.BR wait () +or .BR waitpid () call is made while .B SIGCHLD @@ -445,7 +447,8 @@ were not being ignored, that is, the call blocks until the next child terminates and then returns the process ID and status of that child. .SH "LINUX NOTES" In the Linux kernel, a kernel-scheduled thread is not a distinct -construct from a process. Instead, a thread is simply a process +construct from a process. +Instead, a thread is simply a process that is created using the Linux-unique .BR clone (2) system call; other routines such as the portable @@ -468,9 +471,9 @@ they cannot be used with .TP .B __WCLONE .\" since 0.99pl10 -Wait for "clone" children only. If omitted then wait -for "non-clone" children only. (A "clone" child is one -which delivers no signal, or a signal other than +Wait for "clone" children only. +If omitted then wait for "non-clone" children only. +(A "clone" child is one which delivers no signal, or a signal other than .B SIGCHLD to its parent upon termination.) This option is ignored if @@ -485,20 +488,21 @@ type ("clone" or "non-clone"). .B __WNOTHREAD .\" since patch-2.4.0-test8 (Since Linux 2.4) Do not wait for children of other threads in -the same thread group. This was the default before Linux 2.4. +the same thread group. +This was the default before Linux 2.4. .SH EXAMPLE .\" fork.2 refers to this example program. -The following program demonstrates the use of -.BR fork(2) -and +The following program demonstrates the use of +.BR fork(2) +and .BR waitpid (2). The program creates a child process. -If no command-line argument is supplied to the program, -then the child suspends its execution using +If no command-line argument is supplied to the program, +then the child suspends its execution using .BR pause (2), to allow the user to send signals to the child. Otherwise, if a command-line argument is supplied, -then the child exits immediately, +then the child exits immediately, using the integer supplied on the command line as the exit status. The parent process executes a loop that monitors the child using .BR waitpid (2), diff --git a/man2/wait4.2 b/man2/wait4.2 index 8c64967a0..ee92f85f4 100644 --- a/man2/wait4.2 +++ b/man2/wait4.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -28,7 +28,7 @@ .\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. .\" Modified Tue Jul 7 12:26:42 1998 by aeb - changed return value wait3 .\" Modified 2004-11-11, Michael Kerrisk -.\" Rewrote much of this page, and removed much duplicated text, +.\" Rewrote much of this page, and removed much duplicated text, .\" replacing with pointers to wait.2 .\" .TH WAIT4 2 2004-11-11 "Linux" "Linux Programmer's Manual" @@ -36,7 +36,7 @@ wait3, wait4 \- wait for process to change state, BSD style .SH SYNOPSIS .nf -.B #define _BSD_SOURCE +.B #define _BSD_SOURCE /* Or #define _XOPEN_SOURCE 500 for wait3() */ .B #include .B #include diff --git a/man2/write.2 b/man2/write.2 index 01675c91d..bf430072d 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,12 +46,14 @@ bytes to the file referenced by the file descriptor from the buffer starting at .IR buf . POSIX requires that a \fBread\fP() which can be proved to occur after a -\fBwrite\fP() has returned returns the new data. Note that not all file +\fBwrite\fP() has returned returns the new data. +Note that not all file systems are POSIX conforming. .SH "RETURN VALUE" On success, the number of bytes written are returned (zero indicates -nothing was written). On error, \-1 is returned, and \fIerrno\fP is set -appropriately. +nothing was written). +On error, \-1 is returned, and \fIerrno\fP is set +appropriately. If \fIcount\fP is zero and .I fd @@ -63,7 +65,7 @@ If no errors are detected, If \fIcount\fP is zero and .I fd -refers to a file other than a regular file, +refers to a file other than a regular file, the results are not specified. .SH ERRORS .TP @@ -91,7 +93,7 @@ The call was interrupted by a signal before any data was written. .B EINVAL .I fd is attached to an object which is unsuitable for writing; -or the file was opened with the +or the file was opened with the .B O_DIRECT flag, and either the address specified in .IR buf , @@ -109,8 +111,8 @@ has no room for the data. .TP .B EPIPE .I fd -is connected to a pipe or socket whose reading end is closed. When this -happens the writing process will also receive a +is connected to a pipe or socket whose reading end is closed. +When this happens the writing process will also receive a .B SIGPIPE signal. (Thus, the write return value is seen only if the program @@ -119,12 +121,12 @@ catches, blocks or ignores this signal.) Other errors may occur, depending on the object connected to .IR fd . .SH "CONFORMING TO" -SVr4, 4.3BSD, POSIX.1-2001. +SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. Under SVr4 a write may be interrupted and return EINTR at any point, -not just before any data is written. +not just before any data is written. .SH NOTES A successful return from .BR write () diff --git a/man3/INFINITY.3 b/man3/INFINITY.3 index fd9ae3556..2d7cb62a7 100644 --- a/man3/INFINITY.3 +++ b/man3/INFINITY.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -47,12 +47,15 @@ expands to a float constant representing positive infinity. The macro .B NAN expands to a float constant representing a quiet NaN -(when supported). A +(when supported). +A .I quiet NaN is a NaN ("not-a-number") that does not raise exceptions -when it is used in arithmetic. The opposite is a +when it is used in arithmetic. +The opposite is a .I signalling -NaN. See IEC 60559:1989. +NaN. +See IEC 60559:1989. The macros .BR HUGE_VAL , diff --git a/man3/MB_LEN_MAX.3 b/man3/MB_LEN_MAX.3 index f24d7ee62..8bfc3fd39 100644 --- a/man3/MB_LEN_MAX.3 +++ b/man3/MB_LEN_MAX.3 @@ -33,7 +33,8 @@ The entities .B MB_LEN_MAX and .B sizeof(wchar_t) -are totally unrelated. In the GNU libc, +are totally unrelated. +In the GNU libc, .B MB_LEN_MAX is typically 6 while .B sizeof(wchar_t) diff --git a/man3/__setfpucw.3 b/man3/__setfpucw.3 index 775380107..93f30d1f5 100644 --- a/man3/__setfpucw.3 +++ b/man3/__setfpucw.3 @@ -11,19 +11,19 @@ __setfpucw \- set fpu control word on i386 architecture (obsolete) .SH DESCRIPTION .BR __setfpucw () transfers -.I control_word -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. +.I control_word +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 +.br \- rounding to nearest -.br +.br \- exceptions on overflow, zero divide and NaN .SH AVAILABILITY As of glibc 2.1 this function does not exist anymore. @@ -36,7 +36,7 @@ and the floating point environment, like .IR fegetenv , .IR feholdexcept , .IR fesetenv , -.IR feupdateenv +.IR feupdateenv and fpu exception handling, like .IR feclearexcept , .IR fegetexceptflag , diff --git a/man3/a64l.3 b/man3/a64l.3 index fe3a5daad..3058de9be 100644 --- a/man3/a64l.3 +++ b/man3/a64l.3 @@ -5,7 +5,7 @@ .\" .TH A64L 3 2002-02-15 "" "Linux Programmer's Manual" .SH NAME -a64l, l64a \- convert between long and base-64 +a64l, l64a \- convert between long and base-64 .SH SYNOPSIS .B #include .sp @@ -49,7 +49,8 @@ The behaviour of .BR l64a () is undefined when .I value -is negative. If +is negative. +If .I value is zero, it returns an empty string. .LP diff --git a/man3/abort.3 b/man3/abort.3 index 5ac85ffc4..5af3b5e2b 100644 --- a/man3/abort.3 +++ b/man3/abort.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/abs.3 b/man3/abs.3 index f567a5891..94d1e8264 100644 --- a/man3/abs.3 +++ b/man3/abs.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,15 +48,16 @@ abs, labs, llabs, imaxabs \- compute the absolute value of an integer .fi .SH DESCRIPTION The \fBabs\fP() function computes the absolute value of the integer -argument \fIj\fP. The \fBlabs\fP(), \fBllabs\fP() and \fBimaxabs\fP() +argument \fIj\fP. +The \fBlabs\fP(), \fBllabs\fP() and \fBimaxabs\fP() functions compute the absolute value of the argument \fIj\fP of the appropriate integer type for the function. .SH "RETURN VALUE" Returns the absolute value of the integer argument, of the appropriate integer type for the function. .SH "CONFORMING TO" -SVr4, POSIX.1-2001, 4.3BSD, C99. -.\" POSIX.1 (1996 edition) only requires the \fBabs\fP() function. +SVr4, POSIX.1-2001, 4.3BSD, C99. +.\" POSIX.1 (1996 edition) only requires the \fBabs\fP() function. C89 only includes the \fBabs\fP() and \fBlabs\fP() functions; the functions \fBllabs\fP() and \fBimaxabs\fP() were added in C99. @@ -65,15 +66,16 @@ Trying to take the absolute value of the most negative integer is not defined. .PP The \fBllabs\fP() function is included in glibc since version 2.0, but -is not in libc5 or libc4. The \fBimaxabs\fP() function is included in +is not in libc5 or libc4. +The \fBimaxabs\fP() function is included in glibc since version 2.1.1. .PP For \fBllabs\fP() to be declared, it may be necessary to define \fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the version of glibc) before including any standard headers. .PP -GCC handles \fBabs\fP() and \fBlabs\fP() as builtin functions. GCC -3.0 also handles \fBllabs\fP() and \fBimaxabs\fP() as builtins. +GCC handles \fBabs\fP() and \fBlabs\fP() as builtin functions. +GCC 3.0 also handles \fBllabs\fP() and \fBimaxabs\fP() as builtins. .SH "SEE ALSO" .BR cabs (3), .BR ceil (3), diff --git a/man3/acos.3 b/man3/acos.3 index f24e2f1b1..e72a0bcec 100644 --- a/man3/acos.3 +++ b/man3/acos.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -54,7 +54,7 @@ value is mathematically defined to be between 0 and PI (inclusive). \fIx\fP is out of range. .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89, C99. -The +The .I float and .I "long double" diff --git a/man3/acosh.3 b/man3/acosh.3 index cc0695bf8..972493854 100644 --- a/man3/acosh.3 +++ b/man3/acosh.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,15 +38,15 @@ acosh, acoshf, acoshl \- inverse hyperbolic cosine function .BI "double acosh(double " x ); .br .BI "float acoshf(float " x ); -.br +.br .BI "long double acoshl(long double " x ); .sp .fi Link with \-lm. .SH DESCRIPTION -The \fBacosh\fP() function calculates the inverse hyperbolic cosine of -\fIx\fP; that is the value whose hyperbolic cosine is \fIx\fP. If \fIx\fP -is less than 1.0, \fBacosh\fP() returns not-a-number (NaN) and \fIerrno\fP +The \fBacosh\fP() function calculates the inverse hyperbolic cosine of +\fIx\fP; that is the value whose hyperbolic cosine is \fIx\fP. If \fIx\fP +is less than 1.0, \fBacosh\fP() returns not-a-number (NaN) and \fIerrno\fP is set. .SH ERRORS .TP @@ -54,7 +54,7 @@ is set. \fIx\fP is out of range. .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/addseverity.3 b/man3/addseverity.3 index 792e08e30..2108594e0 100644 --- a/man3/addseverity.3 +++ b/man3/addseverity.3 @@ -19,11 +19,13 @@ addseverity \- introduce new severity classes This function allows the introduction of new severity classes which can be addressed by the .I severity -parameter of the +parameter of the .BR fmtmsg (3) -function. By default that latter function only knows how to +function. +By default that latter function only knows how to print messages for severity 0-4 (with strings (none), HALT, -ERROR, WARNING, INFO). This call attaches the given string +ERROR, WARNING, INFO). +This call attaches the given string .I s to the given value .IR severity . @@ -33,22 +35,25 @@ is NULL, the severity class with the numeric value .I severity is removed. It is not possible to overwrite or remove one of the default -severity classes. The severity value must be nonnegative. +severity classes. +The severity value must be nonnegative. .SH "RETURN VALUE" Upon success, the value .B MM_OK -is returned. Upon error, the return value is +is returned. +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 NOTE -New severity classes can also be added by setting the environment variable +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 -.BR fmtmsg () -function is. It is available on System V +although the +.BR fmtmsg () +function is. +It is available on System V systems. .SH "SEE ALSO" .BR fmtmsg (3), diff --git a/man3/adjtime.3 b/man3/adjtime.3 index 622539ff8..09a4a4ed4 100644 --- a/man3/adjtime.3 +++ b/man3/adjtime.3 @@ -48,8 +48,8 @@ struct timeval { If the adjustment in .I delta is positive, then the system clock is speeded up by some -small percentage (i.e., by adding a small -amount of time to the clock value in each second) until the adjustment +small percentage (i.e., by adding a small +amount of time to the clock value in each second) until the adjustment has been completed. If the adjustment in .I delta @@ -57,18 +57,18 @@ is negative, then the clock is slowed down in a similar fashion. If a clock adjustment from an earlier .BR adjtime () -call is already in progress +call is already in progress at the time of a later .BR adjtime () call, and .I delta -is not NULL for the later call, then the earlier adjustment is stopped, +is not NULL for the later call, then the earlier adjustment is stopped, but any already completed part of that adjustment is not undone. If .I olddelta -is not NULL, then the buffer that it points to is used to return -the amount of time remaining from any previous adjustment that +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 NOTES The adjustment that @@ -86,13 +86,13 @@ by abrupt positive or negative jumps in the system time. is intended to be used to make small adjustments to the system time. Most systems impose a limit on the adjustment that can be specified in .IR delta . -In the glibc implementation, -.I delta +In the glibc implementation, +.I delta must be less than or equal to (INT_MAX / 1000000 - 2) -and greater than or equal to (INT_MIN / 1000000 + 2) +and greater than or equal to (INT_MIN / 1000000 + 2) (respectively 2145 and -2145 seconds on x86). .SH "RETURN VALUE" -On success, +On success, .BR adjtime () returns 0. On failure, \-1 is returned, and .I errno @@ -100,8 +100,8 @@ is set to indicate the error. .SH ERRORS .TP .B EINVAL -The adjustment in -.I delta +The adjustment in +.I delta is outside the permitted range. .TP .B EPERM @@ -114,15 +114,15 @@ capability is required. .SH BUGS Currently, if .I delta -is specified as NULL, +is specified as NULL, no valid information about the outstanding clock adjustment is returned in .IR olddelta . -(In this circumstance, +(In this circumstance, .BR adjtime () should return the outstanding clock adjustment, without changing it.) This is the result of a kernel limitation. .\" FIXME . -.\" A kernel bug report has been submitted; check later to see if +.\" A kernel bug report has been submitted; check later to see if .\" things are resolved. .\" http://bugzilla.kernel.org/show_bug.cgi?id=6761 .SH "SEE ALSO" diff --git a/man3/aio_cancel.3 b/man3/aio_cancel.3 index 61991e94e..48a947581 100644 --- a/man3/aio_cancel.3 +++ b/man3/aio_cancel.3 @@ -36,7 +36,8 @@ for the file descriptor .IR fd . If .I aiocbp -is NULL, all such requests are cancelled. Otherwise, only the request +is NULL, all such requests are cancelled. +Otherwise, only the request described by the control block pointed to by .I aiocbp is cancelled. @@ -57,7 +58,8 @@ Which operations are cancelable is implementation-defined. .\" FreeBSD: not those on raw disk devices. .SH "RETURN VALUE" This function returns AIO_CANCELED if all requests were successfully -cancelled. It returns AIO_NOTCANCELED when at least one of the +cancelled. +It returns AIO_NOTCANCELED when at least one of the requests specified was not cancelled because it was in progress. In this case one may check the status of individual requests using .BR aio_error (3). diff --git a/man3/aio_error.3 b/man3/aio_error.3 index 4665a5861..e69e0dce4 100644 --- a/man3/aio_error.3 +++ b/man3/aio_error.3 @@ -36,7 +36,8 @@ with control block pointed to by .IR aiocbp . .SH "RETURN VALUE" This function returns EINPROGRESS if the request has not been -completed yet. It returns ECANCELED if the request was cancelled. +completed yet. +It returns ECANCELED if the request was cancelled. It returns 0 if the request completed successfully. Otherwise an error value is returned, the same value that would have been stored in the diff --git a/man3/aio_read.3 b/man3/aio_read.3 index bb0eab7de..81372327d 100644 --- a/man3/aio_read.3 +++ b/man3/aio_read.3 @@ -36,17 +36,20 @@ with fd, buf, count given by .IR aiocbp->aio_fildes , .IR aiocbp->aio_buf , .IR aiocbp->aio_nbytes , -respectively. The return status n can be retrieved upon completion using +respectively. +The return status n can be retrieved upon completion using .BR aio_return (3). .LP The data is read starting at the absolute file offset .IR aiocbp->aio_offset , -regardless of the current file position. After this request, +regardless of the current file position. +After this request, the value of the current file position is unspecified. .LP The "asynchronous" means that this call returns as soon as the request has been enqueued; the read may or may not have completed -when the call returns. One tests for completion using +when the call returns. +One tests for completion using .BR aio_error (3). .LP If _POSIX_PRIORITIZED_IO is defined, and this file supports it, @@ -60,10 +63,12 @@ is ignored. .LP No data is read from a regular file beyond its maximum offset. .SH "RETURN VALUE" -On success, 0 is returned. On error the request is not enqueued, \-1 +On success, 0 is returned. +On error the request is not enqueued, \-1 is returned, and .I errno -is set appropriately. If an error is first detected later, it will +is set appropriately. +If an error is first detected later, it will be reported via .BR aio_return (3) (returns status \-1) and @@ -101,7 +106,8 @@ is in progress. The buffer area being read into .\" or the control block of the operation must not be accessed during the operation or undefined results may -occur. The memory areas involved must remain valid. +occur. +The memory areas involved must remain valid. .SH "CONFORMING TO" POSIX.1-2001 .SH "SEE ALSO" diff --git a/man3/aio_write.3 b/man3/aio_write.3 index c543a20fa..828dfab6c 100644 --- a/man3/aio_write.3 +++ b/man3/aio_write.3 @@ -36,7 +36,8 @@ with fd, buf, count given by .IR aiocbp->aio_fildes , .IR aiocbp->aio_buf , .IR aiocbp->aio_nbytes , -respectively. The return status n can be retrieved upon completion using +respectively. +The return status n can be retrieved upon completion using .BR aio_return (3). .LP If O_APPEND is not set, the data is written starting at the @@ -48,7 +49,8 @@ After this request, the value of the current file position is unspecified. .LP The "asynchronous" means that this call returns as soon as the request has been enqueued; the write may or may not have completed -when the call returns. One tests for completion using +when the call returns. +One tests for completion using .BR aio_error (3). .LP If _POSIX_PRIORITIZED_IO is defined, and this file supports it, @@ -62,10 +64,12 @@ is ignored. .LP No data is written to a regular file beyond its maximum offset. .SH "RETURN VALUE" -On success, 0 is returned. On error the request is not enqueued, \-1 +On success, 0 is returned. +On error the request is not enqueued, \-1 is returned, and .I errno -is set appropriately. If an error is first detected later, it will +is set appropriately. +If an error is first detected later, it will be reported via .BR aio_return (3) (returns status \-1) and @@ -102,7 +106,8 @@ is in progress. The buffer area being written out .\" or the control block of the operation must not be accessed during the operation or undefined results may -occur. The memory areas involved must remain valid. +occur. +The memory areas involved must remain valid. .SH "CONFORMING TO" POSIX.1-2001 .SH "SEE ALSO" diff --git a/man3/alloca.3 b/man3/alloca.3 index 67d9668fb..a9f3f6515 100644 --- a/man3/alloca.3 +++ b/man3/alloca.3 @@ -47,7 +47,8 @@ The .BR alloca () function allocates .I size -bytes of space in the stack frame of the caller. This temporary space is +bytes of space in the stack frame of the caller. +This temporary space is automatically freed when the function that called .BR alloca () returns to its caller. @@ -59,17 +60,20 @@ If the allocation causes stack overflow, program behaviour is undefined. .SH "CONFORMING TO" There is evidence that the .BR alloca () -function appeared in 32v, pwb, pwb.2, 3bsd, and 4bsd. There is a man page -for it in 4.3BSD. Linux uses the GNU version. +function appeared in 32v, pwb, pwb.2, 3bsd, and 4bsd. +There is a man page for it in 4.3BSD. +Linux uses the GNU version. This function is not in POSIX.1-2001. .SH "NOTES ON THE GNU VERSION" Normally, .B gcc translates calls to .BR alloca () -by inlined code. This is not done when either the \-ansi or -the \-fno\-builtin option is given. But beware! By default -the glibc version of +by inlined code. +This is not done when either the \-ansi or +the \-fno\-builtin option is given. +But beware! +By default the glibc version of .I includes .I @@ -89,8 +93,10 @@ Thus, there is no NULL error return. .SH BUGS The .BR alloca () -function is machine and compiler dependent. On many systems -its implementation is buggy. Its use is discouraged. +function is machine and compiler dependent. +On many systems +its implementation is buggy. +Its use is discouraged. .LP On many systems .BR alloca () diff --git a/man3/argz_add.3 b/man3/argz_add.3 index af0089e13..57d7f5849 100644 --- a/man3/argz_add.3 +++ b/man3/argz_add.3 @@ -1,7 +1,7 @@ .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) .\" Distributed under GPL .\" based on the description in glibc source and infopages -.\" +.\" .\" Corrections and additions, aeb .TH ARGZ_ADD 3 .SH NAME @@ -110,7 +110,7 @@ will be increased by .IR buf_len .) .LP .BR argz_count () -counts the number of strings, that is, +counts the number of strings, that is, the number of null bytes ('\\0'), in .RI ( argz , argz_len ). .LP @@ -173,17 +173,21 @@ is NULL, then will inserted at the end. .LP .BR argz_next () -is a function to step trough the argz vector. If +is a function to step trough the argz vector. +If .I entry -is NULL, the first entry is returned. Otherwise, the entry -following is returned. It returns NULL if there is no following entry. +is NULL, the first entry is returned. +Otherwise, the entry +following is returned. +It returns NULL if there is no following entry. .LP .BR argz_replace () replaces each occurrence of .I str with .IR with , -reallocating argz as necessary. If +reallocating argz as necessary. +If .I replace_count is non-NULL, .RI * replace_count @@ -202,6 +206,7 @@ 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. +These functions are a GNU extension. +Handle with care. .SH "SEE ALSO" .BR envz (3) diff --git a/man3/asin.3 b/man3/asin.3 index f5025a0c3..3d8c8a4cb 100644 --- a/man3/asin.3 +++ b/man3/asin.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,7 +39,7 @@ asin, asinf, asinl \- arc sine function .br .BI "float asinf(float " x ); .br -.BI "long double asinl(long double " x ); +.BI "long double asinl(long double " x ); .fi .sp Link with \-lm. @@ -57,7 +57,7 @@ value is mathematically defined to be between \-PI/2 and PI/2 \fIx\fP is out of range. .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89, C99. -The +The .I float and .I "long double" diff --git a/man3/asinh.3 b/man3/asinh.3 index e19393f50..4079ec945 100644 --- a/man3/asinh.3 +++ b/man3/asinh.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,16 +39,16 @@ asinh, asinhf, asinhl \- inverse hyperbolic sine function .br .BI "float asinhf(float " x ); .br -.BI "long double asinhl(long double " x ); +.BI "long double asinhl(long double " x ); .fi .sp Link with \-lm. .SH DESCRIPTION -The \fBasinh\fP() function calculates the inverse hyperbolic sine of +The \fBasinh\fP() function calculates the inverse hyperbolic sine of \fIx\fP; that is the value whose hyperbolic sine is \fIx\fP. .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/asprintf.3 b/man3/asprintf.3 index 9e228ec85..55a4d193f 100644 --- a/man3/asprintf.3 +++ b/man3/asprintf.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/assert.3 b/man3/assert.3 index 3ed53716f..ecd168d42 100644 --- a/man3/assert.3 +++ b/man3/assert.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -49,7 +49,8 @@ if is false (i.e., compares equal to zero). .LP The purpose of this macro is to help the programmer find bugs in -his program. The message "assertion failed in file foo.c, function +his program. +The message "assertion failed in file foo.c, function do_bar(), line 1287" is of no help at all to a user. .SH "RETURN VALUE" No value is returned. @@ -67,7 +68,8 @@ it may have any scalar type. is implemented as a macro; if the expression tested has side-effects, program behaviour will be different depending on whether .B NDEBUG -is defined. This may create Heisenbugs which go away when debugging +is defined. +This may create Heisenbugs which go away when debugging is turned on. .SH "SEE ALSO" .BR abort (3), diff --git a/man3/assert_perror.3 b/man3/assert_perror.3 index 8892e618c..f8c039119 100644 --- a/man3/assert_perror.3 +++ b/man3/assert_perror.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,7 +48,8 @@ by calling .BR abort () if .I errnum -is non-zero. The message contains the filename, function name and +is non-zero. +The message contains the filename, function name and line number of the macro call, and the output of .IR strerror(errnum) . .SH "RETURN VALUE" @@ -61,7 +62,8 @@ his program, things that cannot happen unless there was a coding mistake. However, with system or library calls the situation is rather different, and error returns can happen, and will happen, and should be tested for. Not by an assert, where the test goes away when NDEBUG is defined, -but by proper error handling code. Never use this macro. +but by proper error handling code. +Never use this macro. .SH "SEE ALSO" .BR abort (3), .BR assert (3), diff --git a/man3/atan.3 b/man3/atan.3 index 97cedd465..9771e0387 100644 --- a/man3/atan.3 +++ b/man3/atan.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,7 +37,7 @@ atan, atanf, atanl \- arc tangent function .sp .BI "double atan(double " x ); .br -.BI "float atanf(float " x ); +.BI "float atanf(float " x ); .br .BI "long double atanl( long double " x ); .sp @@ -52,7 +52,7 @@ value is mathematically defined to be between \-PI/2 and PI/2 (inclusive). .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/atan2.3 b/man3/atan2.3 index 4389d9964..68e9aa034 100644 --- a/man3/atan2.3 +++ b/man3/atan2.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,7 +40,7 @@ atan2, atan2f, atan2l \- arc tangent function of two variables .BI "float atan2f(float " y ", float " x ); .br .BI "long double atan2l(long double " y ", long double " x ); -.sp +.sp .fi Link with \-lm. .SH DESCRIPTION @@ -53,7 +53,7 @@ The \fBatan2\fP() function returns the result in radians, which is between \-PI and PI (inclusive). .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/atanh.3 b/man3/atanh.3 index 4fc3c5867..5fee932f6 100644 --- a/man3/atanh.3 +++ b/man3/atanh.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,13 +40,13 @@ atanh, atanhf, atanhl \- inverse hyperbolic tangent function .BI "float atanhf(float " x ); .br .BI "long double atanhl(long double " x ); -.sp +.sp .fi Link with \-lm. .SH DESCRIPTION -The \fBatanh\fP() function calculates the inverse hyperbolic tangent of +The \fBatanh\fP() function calculates the inverse hyperbolic tangent of \fIx\fP; that is the value whose hyperbolic tangent is \fIx\fP. If the -absolute value of \fIx\fP is greater than 1.0, \fBatanh\fP() returns +absolute value of \fIx\fP is greater than 1.0, \fBatanh\fP() returns not-a-number (NaN) and \fIerrno\fP is set. .SH ERRORS .TP @@ -54,7 +54,7 @@ not-a-number (NaN) and \fIerrno\fP is set. \fIx\fP is out of range. .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/atexit.3 b/man3/atexit.3 index 7fa1ed9e0..995d1f061 100644 --- a/man3/atexit.3 +++ b/man3/atexit.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,11 +50,11 @@ such functions to be registered. The actual limit supported by an implementation can be obtained using .BR sysconf (3). .LP -When a child process is created via +When a child process is created via .BR fork (), it inherits copies of its parents registrations. -Upon a successful call to one of the -.BR exec () +Upon a successful call to one of the +.BR exec () functions, all registrations are removed. .SH "RETURN VALUE" @@ -66,13 +66,13 @@ it returns a non-zero value. #include #include -void -bye(void) +void +bye(void) { printf("That was all, folks\en"); } -int +int main(void) { long a; diff --git a/man3/atof.3 b/man3/atof.3 index 1c35265ca..a8641109e 100644 --- a/man3/atof.3 +++ b/man3/atof.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,7 +37,8 @@ atof \- convert a string to a double .fi .SH DESCRIPTION The \fBatof\fP() function converts the initial portion of the string -pointed to by \fInptr\fP to double. The behaviour is the same as +pointed to by \fInptr\fP to double. +The behaviour is the same as .sp .RS .B strtod(nptr, (char **) NULL); diff --git a/man3/atoi.3 b/man3/atoi.3 index 40f492742..eadaac17f 100644 --- a/man3/atoi.3 +++ b/man3/atoi.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -62,7 +62,7 @@ string to their return type of \fIlong\fP or \fIlong long\fP. .SH "RETURN VALUE" The converted value. .SH "CONFORMING TO" -SVr4, POSIX.1-2001, 4.3BSD, C99. +SVr4, POSIX.1-2001, 4.3BSD, C99. C89 and POSIX.1-1996 include the functions \fBatoi\fP() and \fBatol\fP() only. .BR atoq (3) @@ -70,8 +70,8 @@ is a GNU extension. .SH NOTES The non-standard \fBatoq\fP() function is not present in libc 4.6.27 or glibc 2, but is present in libc5 and libc 4.7 (though only as an -inline function in \fB\fP until libc 5.4.44). The -\fBatoll\fP() function is present in glibc 2 since version 2.0.2, but +inline function in \fB\fP until libc 5.4.44). +The \fBatoll\fP() function is present in glibc 2 since version 2.0.2, but not in libc4 or libc5. .SH "SEE ALSO" .BR atof (3), diff --git a/man3/basename.3 b/man3/basename.3 index b400ac813..2e1ec7964 100644 --- a/man3/basename.3 +++ b/man3/basename.3 @@ -8,12 +8,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -39,16 +39,16 @@ The functions .BR dirname () and .BR basename () -break a null-terminated pathname string into directory -and filename components. -In the usual case, +break a null-terminated pathname string into directory +and filename components. +In the usual case, .BR dirname () returns the string up to, but not including, the final '/', and .BR basename () returns the component following the final '/'. Trailing '/' characters are not counted as part of the pathname. .PP -If +If .I path does not contain a slash, .BR dirname () @@ -56,14 +56,14 @@ returns the string "." while .BR basename () returns a copy of .IR path . -If +If .I path is the string "/", then both .BR dirname () -and +and .BR basename () return the string "/". -If +If .I path is a NULL pointer or points to an empty string, then both .BR dirname () @@ -73,17 +73,17 @@ return the string ".". .PP Concatenating the string returned by .BR dirname (), -a "/", and the string returned by +a "/", and the string returned by .BR basename () yields a complete pathname. .PP -Both +Both .BR dirname () and .BR basename () -may modify the contents of -.IR path , -so it may be desirable to pass a copy when calling one of +may modify the contents of +.IR path , +so it may be desirable to pass a copy when calling one of these functions. .PP These functions may return pointers to statically allocated memory @@ -96,14 +96,14 @@ should not be modified or freed until the pointer returned by the function is no longer required. .PP The following list of examples (taken from SUSv2) -shows the strings returned by +shows the strings returned by .BR dirname () and .BR basename () for different paths: .sp .nf -.B +.B path dirname basename "/usr/lib" "/usr" "lib" "/usr/" "/" "usr" @@ -126,7 +126,7 @@ printf("dirname=%s, basename=%s\\n", dname, bname); .fi .RE .SH "RETURN VALUE" -Both +Both .BR dirname () and .BR basename () diff --git a/man3/bcmp.3 b/man3/bcmp.3 index e22be4ec2..f120f9706 100644 --- a/man3/bcmp.3 +++ b/man3/bcmp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,18 +44,20 @@ and .I s2 of length .I n -each. If they are equal, and in particular if +each. +If they are equal, and in particular if .I n is zero, .BR bcmp () -returns 0. Otherwise it returns a non-zero result. +returns 0. +Otherwise it returns a non-zero result. .SH "RETURN VALUE" The .BR bcmp () function returns 0 if the byte sequences are equal, otherwise a non-zero result is returned. .SH "CONFORMING TO" -4.3BSD. +4.3BSD. This function is deprecated (marked as LEGACY in POSIX.1-2001): use .BR memcmp () in new programs. diff --git a/man3/bcopy.3 b/man3/bcopy.3 index 8a255ad12..f82ff92a6 100644 --- a/man3/bcopy.3 +++ b/man3/bcopy.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,12 +50,13 @@ The result is correct, even when both areas overlap. .SH "RETURN VALUE" None. .SH "CONFORMING TO" -4.3BSD. +4.3BSD. This function is deprecated (marked as LEGACY in POSIX.1-2001): use .BR memcpy () or .BR memmove () -in new programs. Note that the first two parameters +in new programs. +Note that the first two parameters are interchanged for .BR memcpy () and diff --git a/man3/bindresvport.3 b/man3/bindresvport.3 index d2d94416f..daa6b78cf 100644 --- a/man3/bindresvport.3 +++ b/man3/bindresvport.3 @@ -1,7 +1,7 @@ .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) .\" .\" @(#)bindresvport.3n 2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI -.TH BINDRESVPORT 3 1987-11-22 +.TH BINDRESVPORT 3 1987-11-22 .SH NAME bindresvport \- bind a socket to a privileged IP port .SH SYNOPSIS diff --git a/man3/bsearch.3 b/man3/bsearch.3 index 5bf559146..4714da6ba 100644 --- a/man3/bsearch.3 +++ b/man3/bsearch.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,11 +41,13 @@ bsearch \- binary search of a sorted array .SH DESCRIPTION The \fBbsearch\fP() function searches an array of \fInmemb\fP objects, the initial member of which is pointed to by \fIbase\fP, for a member -that matches the object pointed to by \fIkey\fP. The size of each member +that matches the object pointed to by \fIkey\fP. +The size of each member of the array is specified by \fIsize\fP. .PP The contents of the array should be in ascending sorted order according -to the comparison function referenced by \fIcompar\fP. The \fIcompar\fP +to the comparison function referenced by \fIcompar\fP. +The \fIcompar\fP routine is expected to have two arguments which point to the \fIkey\fP object and to an array member, in that order, and should return an integer less than, equal to, or greater than zero if the \fIkey\fP object is found, @@ -53,7 +55,8 @@ respectively, to be less than, to match, or be greater than the array member. .SH "RETURN VALUE" The \fBbsearch\fP() function returns a pointer to a matching member of the -array, or NULL if no match is found. If there are multiple elements that +array, or NULL if no match is found. +If there are multiple elements that match the key, the element returned is unspecified. .SH EXAMPLE The example below first sorts an array of structures using @@ -77,16 +80,16 @@ struct mi { #define nr_of_months (sizeof(months)/sizeof(months[0])) -static int -compmi(const void *m1, const void *m2) +static int +compmi(const void *m1, const void *m2) { struct mi *mi1 = (struct mi *) m1; struct mi *mi2 = (struct mi *) m2; return strcmp(mi1\->name, mi2\->name); } -int -main(int argc, char **argv) +int +main(int argc, char **argv) { int i; diff --git a/man3/bstring.3 b/man3/bstring.3 index e5940782b..6883ca6ce 100644 --- a/man3/bstring.3 +++ b/man3/bstring.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -29,7 +29,7 @@ .\" Modified 2002-01-20, Walter Harms .TH BSTRING 3 2002-01-20 "" "Linux Programmer's Manual" .SH NAME -bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, +bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, memmove, memset \- byte string operations .SH SYNOPSIS .nf @@ -62,7 +62,8 @@ memmove, memset \- byte string operations .fi .SH DESCRIPTION The byte string functions perform operations on strings (byte arrays) -that are not necessarily null-terminated. See the individual man pages +that are not necessarily null-terminated. +See the individual man pages for descriptions of each function. .SH NOTE The functions @@ -70,7 +71,8 @@ The functions .BR bcopy () and .BR bzero () -are obsolete. Use +are obsolete. +Use .BR memcmp (), .BR memcpy () and diff --git a/man3/btowc.3 b/man3/btowc.3 index 0922815f3..c25caa89b 100644 --- a/man3/btowc.3 +++ b/man3/btowc.3 @@ -21,13 +21,16 @@ btowc \- convert single byte to wide character .BI "wint_t btowc(int " c ); .fi .SH DESCRIPTION -The \fBbtowc\fP() function converts \fIc\fP, interpreted as a multibyte sequence +The \fBbtowc\fP() function converts \fIc\fP, +interpreted as a multibyte sequence of length 1, starting in the initial shift state, to a wide character and -returns it. If \fIc\fP is EOF or not a valid multibyte sequence of length 1, +returns it. +If \fIc\fP is EOF or not a valid multibyte sequence of length 1, the \fBbtowc\fP() function returns WEOF. .SH "RETURN VALUE" -The \fBbtowc\fP() function returns the wide character converted from the single -byte \fIc\fP. If \fIc\fP is EOF or not a valid multibyte sequence of length 1, +The \fBbtowc\fP() function returns the wide character +converted from the single byte \fIc\fP. +If \fIc\fP is EOF or not a valid multibyte sequence of length 1, it returns WEOF. .SH "CONFORMING TO" C99, POSIX.1-2001. @@ -37,6 +40,8 @@ C99, POSIX.1-2001. The behaviour of \fBbtowc\fP() depends on the LC_CTYPE category of the current locale. .PP -This function should never be used. It does not work for encodings which have +This function should never be used. +It does not work for encodings which have state, and unnecessarily treats single bytes differently from multibyte -sequences. Use the function \fBmbtowc\fP() instead. +sequences. +Use the function \fBmbtowc\fP() instead. diff --git a/man3/btree.3 b/man3/btree.3 index 015ca628b..c60e80bb4 100644 --- a/man3/btree.3 +++ b/man3/btree.3 @@ -31,7 +31,7 @@ .\" .\" @(#)btree.3 8.4 (Berkeley) 8/18/94 .\" -.TH BTREE 3 1994-08-18 +.TH BTREE 3 1994-08-18 .\".UC 7 .SH NAME btree \- btree database access method @@ -184,7 +184,7 @@ done. .TP lorder The byte order for integers in the stored database metadata. -The number should represent the order as an integer; for example, +The number should represent the order as an integer; for example, big endian order would be the number 4,321. If .I lorder @@ -227,7 +227,7 @@ Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 (March 1977), 11-26. .sp -.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , +.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , D.E. Knuth, 1968, pp 471-480. .SH BUGS Only big and little endian byte order is supported. diff --git a/man3/byteorder.3 b/man3/byteorder.3 index 19cad889b..b25fa61bb 100644 --- a/man3/byteorder.3 +++ b/man3/byteorder.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -56,15 +56,15 @@ from network byte order to host byte order. The \fBntohs\fP() function converts the unsigned short integer \fInetshort\fP from network byte order to host byte order. .PP -On the i80x86 the host byte order is Least Significant Byte first, -whereas the network byte order, as used on the Internet, is Most +On the i80x86 the host byte order is Least Significant Byte first, +whereas the network byte order, as used on the Internet, is Most Significant Byte first. .SH "CONFORMING TO" POSIX.1-2001. -Some systems require the inclusion of -.I -instead of +Some systems require the inclusion of +.I +instead of .IR . .SH "SEE ALSO" .BR gethostbyname (3), diff --git a/man3/bzero.3 b/man3/bzero.3 index 77321c987..c7f3555d9 100644 --- a/man3/bzero.3 +++ b/man3/bzero.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,10 +46,10 @@ to zero (bytes containing '\\0'). .SH "RETURN VALUE" None. .SH "CONFORMING TO" -4.3BSD. +4.3BSD. This function is deprecated (marked as LEGACY in POSIX.1-2001): use .BR memset () -in new programs. +in new programs. .SH "SEE ALSO" .BR memset (3), .BR swab (3) diff --git a/man3/cabs.3 b/man3/cabs.3 index 8ca94528d..9363bf2c7 100644 --- a/man3/cabs.3 +++ b/man3/cabs.3 @@ -3,7 +3,7 @@ .\" .TH CABS 3 2002-07-28 "" "complex math routines" .SH NAME -cabs, cabsf, cabsl \- absolute value of a complex number +cabs, cabsf, cabsl \- absolute value of a complex number .SH SYNOPSIS .B #include .sp @@ -15,10 +15,10 @@ cabs, cabsf, cabsl \- absolute value of a complex number .sp Link with \-lm. .SH DESCRIPTION -The -.BR cabs () +The +.BR cabs () function returns the absolute value of the complex number z. The -result is a real number. +result is a real number. .SH NOTE The function is actually an alias for hypot(a,b) = sqrt(a*a+b*b). .SH "CONFORMING TO" diff --git a/man3/cabsf.3 b/man3/cabsf.3 index ba441dbab..e50ac96b7 100644 --- a/man3/cabsf.3 +++ b/man3/cabsf.3 @@ -1 +1 @@ -.so man3/cabs.3 +.so man3/cabs.3 diff --git a/man3/cabsl.3 b/man3/cabsl.3 index ba441dbab..e50ac96b7 100644 --- a/man3/cabsl.3 +++ b/man3/cabsl.3 @@ -1 +1 @@ -.so man3/cabs.3 +.so man3/cabs.3 diff --git a/man3/cacos.3 b/man3/cacos.3 index 8c224a4b4..7dc55ef34 100644 --- a/man3/cacos.3 +++ b/man3/cacos.3 @@ -7,16 +7,16 @@ cacos, cacosf, cacosl \- complex arc cosine .SH SYNOPSIS .B #include .sp -.BI "double complex cacos(double complex " z ); +.BI "double complex cacos(double complex " z ); .br -.BI "float complex cacosf(float complex " z ); +.BI "float complex cacosf(float complex " z ); .br -.BI "long double complex cacosl(long double complex " z ); +.BI "long double complex cacosl(long double complex " z ); .sp Link with \-lm. .SH DESCRIPTION -The -.BR cacos () +The +.BR cacos () function calculates the complex acos(). If y = cacos(z), then z = ccos(y). The real part of y is chosen in the interval [0,pi]. diff --git a/man3/cacosh.3 b/man3/cacosh.3 index 5bf7a62fc..318c62917 100644 --- a/man3/cacosh.3 +++ b/man3/cacosh.3 @@ -7,7 +7,7 @@ cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine .SH SYNOPSIS .B #include .sp -.BI "double complex cacosh(double complex " z ); +.BI "double complex cacosh(double complex " z ); .br .BI "float complex cacoshf(float complex " z ); .br @@ -15,7 +15,7 @@ cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine .sp Link with \-lm. .SH DESCRIPTION -The +The .BR cacosh () function calculates the complex acosh(). If y = cacosh(z), then z = ccosh(y). diff --git a/man3/cacoshf.3 b/man3/cacoshf.3 index 5853c95f1..c89c010f2 100644 --- a/man3/cacoshf.3 +++ b/man3/cacoshf.3 @@ -1 +1 @@ -.so man3/cacosh.3 +.so man3/cacosh.3 diff --git a/man3/cacoshl.3 b/man3/cacoshl.3 index 5853c95f1..c89c010f2 100644 --- a/man3/cacoshl.3 +++ b/man3/cacoshl.3 @@ -1 +1 @@ -.so man3/cacosh.3 +.so man3/cacosh.3 diff --git a/man3/cargf.3 b/man3/cargf.3 index c049a27d1..c181aa420 100644 --- a/man3/cargf.3 +++ b/man3/cargf.3 @@ -1 +1 @@ -.so man3/carg.3 +.so man3/carg.3 diff --git a/man3/cargl.3 b/man3/cargl.3 index c049a27d1..c181aa420 100644 --- a/man3/cargl.3 +++ b/man3/cargl.3 @@ -1 +1 @@ -.so man3/carg.3 +.so man3/carg.3 diff --git a/man3/casin.3 b/man3/casin.3 index eb1b060c3..f56f06cd7 100644 --- a/man3/casin.3 +++ b/man3/casin.3 @@ -3,20 +3,20 @@ .\" .TH CASIN 3 2002-07-28 "" "complex math routines" .SH NAME -casin, casinf, casinl \- complex arc sine +casin, casinf, casinl \- complex arc sine .SH SYNOPSIS .B #include .sp -.BI "double complex casin(double complex " z ); +.BI "double complex casin(double complex " z ); .br -.BI "float complex casinf(float complex " z ); +.BI "float complex casinf(float complex " z ); .br -.BI "long double complex casinl(long double complex " z ); +.BI "long double complex casinl(long double complex " z ); .sp Link with \-lm. .SH DESCRIPTION -The -.BR casin () +The +.BR casin () function calculates the complex asin(). If y = casin(z), then z = csin(y). The real part of y is chosen in the interval [\-pi/2,pi/2]. diff --git a/man3/casinf.3 b/man3/casinf.3 index 3418b5b76..582875fae 100644 --- a/man3/casinf.3 +++ b/man3/casinf.3 @@ -1 +1 @@ -.so man3/casin.3 +.so man3/casin.3 diff --git a/man3/casinh.3 b/man3/casinh.3 index d19b5ad25..3266ded32 100644 --- a/man3/casinh.3 +++ b/man3/casinh.3 @@ -7,7 +7,7 @@ casinh, casinhf, casinhl \- complex arc sine hyperbolic .SH SYNOPSIS .B #include .sp -.BI "double complex casinh(double complex " z ); +.BI "double complex casinh(double complex " z ); .br .BI "float complex casinhf(float complex " z ); .br @@ -15,7 +15,7 @@ casinh, casinhf, casinhl \- complex arc sine hyperbolic .sp Link with \-lm. .SH DESCRIPTION -The +The .BR casinh () function calculates the complex asinh(). If y = casinh(z), then z = csinh(y). diff --git a/man3/casinhf.3 b/man3/casinhf.3 index f8b022ca1..c2eada89d 100644 --- a/man3/casinhf.3 +++ b/man3/casinhf.3 @@ -1 +1 @@ -.so man3/casinh.3 +.so man3/casinh.3 diff --git a/man3/casinhl.3 b/man3/casinhl.3 index f8b022ca1..c2eada89d 100644 --- a/man3/casinhl.3 +++ b/man3/casinhl.3 @@ -1 +1 @@ -.so man3/casinh.3 +.so man3/casinh.3 diff --git a/man3/casinl.3 b/man3/casinl.3 index 3418b5b76..582875fae 100644 --- a/man3/casinl.3 +++ b/man3/casinl.3 @@ -1 +1 @@ -.so man3/casin.3 +.so man3/casin.3 diff --git a/man3/catan.3 b/man3/catan.3 index 19df57ec7..5e4afd745 100644 --- a/man3/catan.3 +++ b/man3/catan.3 @@ -3,15 +3,15 @@ .\" .TH CATAN 3 2002-07-28 "" "complex math routines" .SH NAME -catan, catanf, catanl \- complex arc tangents +catan, catanf, catanl \- complex arc tangents .SH SYNOPSIS .B #include .sp -.BI "double complex catan(double complex " z ); +.BI "double complex catan(double complex " z ); .br -.BI "float complex catanf(float complex " z ); +.BI "float complex catanf(float complex " z ); .br -.BI "long double complex catanl(long double complex " z ); +.BI "long double complex catanl(long double complex " z ); .sp Link with \-lm. .SH DESCRIPTION diff --git a/man3/catanf.3 b/man3/catanf.3 index 854de1390..d1e25223d 100644 --- a/man3/catanf.3 +++ b/man3/catanf.3 @@ -1 +1 @@ -.so man3/catan.3 +.so man3/catan.3 diff --git a/man3/catanh.3 b/man3/catanh.3 index 04505d279..7884bab2a 100644 --- a/man3/catanh.3 +++ b/man3/catanh.3 @@ -7,7 +7,7 @@ catanh, catanhf, catanhl \- complex arc tangents hyperbolic .SH SYNOPSIS .B #include .sp -.BI "double complex catanh(double complex " z ); +.BI "double complex catanh(double complex " z ); .br .BI "float complex catanhf(float complex " z ); .br @@ -15,8 +15,8 @@ catanh, catanhf, catanhl \- complex arc tangents hyperbolic .sp Link with \-lm. .SH DESCRIPTION -The -.BR catanh () +The +.BR catanh () function calculates the complex atanh(). If y = catanh(z), then z = ctanh(y). The imaginary part of y is chosen in the interval [\-pi/2,pi/2]. diff --git a/man3/catanhf.3 b/man3/catanhf.3 index 6c61e7cee..23f22a4a8 100644 --- a/man3/catanhf.3 +++ b/man3/catanhf.3 @@ -1 +1 @@ -.so man3/catanh.3 +.so man3/catanh.3 diff --git a/man3/catanhl.3 b/man3/catanhl.3 index 6c61e7cee..23f22a4a8 100644 --- a/man3/catanhl.3 +++ b/man3/catanhl.3 @@ -1 +1 @@ -.so man3/catanh.3 +.so man3/catanh.3 diff --git a/man3/catanl.3 b/man3/catanl.3 index 854de1390..d1e25223d 100644 --- a/man3/catanl.3 +++ b/man3/catanl.3 @@ -1 +1 @@ -.so man3/catan.3 +.so man3/catan.3 diff --git a/man3/catgets.3 b/man3/catgets.3 index 7ea040391..a3f7c3c7b 100644 --- a/man3/catgets.3 +++ b/man3/catgets.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,12 +16,12 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Updated, aeb, 980809 -.TH CATGETS 3 1998-08-09 +.TH CATGETS 3 1998-08-09 .SH NAME catgets \- get message from a message catalog .SH SYNOPSIS @@ -29,7 +29,7 @@ catgets \- get message from a message catalog .B #include .BI "char *catgets(nl_catd " catalog ", int " set_number \ -", int " message_number , +", int " message_number , .BI " const char *" message ); .fi .SH DESCRIPTION @@ -48,9 +48,11 @@ The fourth argument .I message points to a default message string which will be returned by .BR catgets () -if the identified message catalog is not currently available. The +if the identified message catalog is not currently available. +The message-text is contained in an internal buffer area and should be copied by -the application if it is to be saved or modified. The return string is +the application if it is to be saved or modified. +The return string is always terminated with a null byte. .SH "RETURN VALUE" .LP diff --git a/man3/catopen.3 b/man3/catopen.3 index 92e9a5da8..a688b665f 100644 --- a/man3/catopen.3 +++ b/man3/catopen.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,9 +36,9 @@ catopen, catclose \- open/close a message catalog The function .BR catopen () opens a message catalog and returns a catalog descriptor. -The descriptor remains valid until -.BR catclose () -or +The descriptor remains valid until +.BR catclose () +or .BR exec (). If a file descriptor is used to implement catalog descriptors then the FD_CLOEXEC flag will be set. @@ -112,7 +112,8 @@ on success. On failure, it returns (nl_catd) \-1 and sets .I errno -to indicate the error. The possible error values include all +to indicate the error. +The possible error values include all possible values for the .BR open () call. @@ -143,8 +144,8 @@ The default path varies, but usually looks at a number of places below These functions are available for Linux since libc 4.4.4c. In the case of linux libc4 and libc5, the catalog descriptor .I nl_catd -is a -.BR mmap ()'ed +is a +.BR mmap ()'ed area of memory and not a file descriptor. The .I flag diff --git a/man3/cbrt.3 b/man3/cbrt.3 index 5904b5172..6e628bc25 100644 --- a/man3/cbrt.3 +++ b/man3/cbrt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/ccos.3 b/man3/ccos.3 index 816dea660..169a5fea3 100644 --- a/man3/ccos.3 +++ b/man3/ccos.3 @@ -15,7 +15,7 @@ ccos, ccosf, ccosl \- complex cosine function .sp Link with \-lm. .SH DESCRIPTION -The complex cosine function ccos(z) is defined as (exp(i*z)+exp(\-i*z))/2. +The complex cosine function ccos(z) is defined as (exp(i*z)+exp(\-i*z))/2. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/ccosf.3 b/man3/ccosf.3 index a9811b00d..b4323ffa4 100644 --- a/man3/ccosf.3 +++ b/man3/ccosf.3 @@ -1 +1 @@ -.so man3/ccos.3 +.so man3/ccos.3 diff --git a/man3/ccosh.3 b/man3/ccosh.3 index f64ac1bdc..eb5c8787e 100644 --- a/man3/ccosh.3 +++ b/man3/ccosh.3 @@ -16,7 +16,7 @@ ccosh, ccoshf, ccoshl \- complex hyperbolic cosine Link with \-lm. .SH DESCRIPTION The complex hyperbolic cosine function ccosh(z) is defined as -(exp(z)+exp(\-z))/2. +(exp(z)+exp(\-z))/2. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/ccoshf.3 b/man3/ccoshf.3 index eaf3be5db..a777fbf7f 100644 --- a/man3/ccoshf.3 +++ b/man3/ccoshf.3 @@ -1 +1 @@ -.so man3/ccosh.3 +.so man3/ccosh.3 diff --git a/man3/ccoshl.3 b/man3/ccoshl.3 index eaf3be5db..a777fbf7f 100644 --- a/man3/ccoshl.3 +++ b/man3/ccoshl.3 @@ -1 +1 @@ -.so man3/ccosh.3 +.so man3/ccosh.3 diff --git a/man3/ccosl.3 b/man3/ccosl.3 index a9811b00d..b4323ffa4 100644 --- a/man3/ccosl.3 +++ b/man3/ccosl.3 @@ -1 +1 @@ -.so man3/ccos.3 +.so man3/ccos.3 diff --git a/man3/ceil.3 b/man3/ceil.3 index f51859123..75ff0e3c5 100644 --- a/man3/ceil.3 +++ b/man3/ceil.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,13 +16,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .TH CEIL 3 2001-05-31 "" "Linux Programmer's Manual" .SH NAME -ceil, ceilf, ceill \- ceiling function: smallest integral value not +ceil, ceilf, ceill \- ceiling function: smallest integral value not less than argument .SH SYNOPSIS .nf @@ -39,7 +39,8 @@ Link with \-lm. .SH DESCRIPTION These functions round \fIx\fP up to the nearest integer. .SH "RETURN VALUE" -The rounded integer value. If \fIx\fP is integral or infinite, +The rounded integer value. +If \fIx\fP is integral or infinite, \fIx\fP itself is returned. .SH ERRORS No errors other than EDOM and ERANGE can occur. diff --git a/man3/cerf.3 b/man3/cerf.3 index ae82d1881..152ff0820 100644 --- a/man3/cerf.3 +++ b/man3/cerf.3 @@ -21,12 +21,12 @@ cerf, cerff, cerfl, cerfc, cerfcf, cerfcl \- complex error function .sp Link with \-lm. .SH DESCRIPTION -The function -.BR cerf () +The function +.BR cerf () is the complex version of the error function. erf(z) = 2/sqrt(pi) * integral from 0 to z of exp(\-t*t) dt. The function -.BR cerfc () +.BR cerfc () is defined as cerfc(z) = 1\-cerf(z). .\" must check 1/sqrt(2*pi) ? .SH "CONFORMING TO" diff --git a/man3/cerfc.3 b/man3/cerfc.3 index ec1ee79a0..57fb417c7 100644 --- a/man3/cerfc.3 +++ b/man3/cerfc.3 @@ -1 +1 @@ -.so man3/cerf.3 +.so man3/cerf.3 diff --git a/man3/cerfcf.3 b/man3/cerfcf.3 index ec1ee79a0..57fb417c7 100644 --- a/man3/cerfcf.3 +++ b/man3/cerfcf.3 @@ -1 +1 @@ -.so man3/cerf.3 +.so man3/cerf.3 diff --git a/man3/cerfcl.3 b/man3/cerfcl.3 index ec1ee79a0..57fb417c7 100644 --- a/man3/cerfcl.3 +++ b/man3/cerfcl.3 @@ -1 +1 @@ -.so man3/cerf.3 +.so man3/cerf.3 diff --git a/man3/cerff.3 b/man3/cerff.3 index ec1ee79a0..57fb417c7 100644 --- a/man3/cerff.3 +++ b/man3/cerff.3 @@ -1 +1 @@ -.so man3/cerf.3 +.so man3/cerf.3 diff --git a/man3/cerfl.3 b/man3/cerfl.3 index ec1ee79a0..57fb417c7 100644 --- a/man3/cerfl.3 +++ b/man3/cerfl.3 @@ -1 +1 @@ -.so man3/cerf.3 +.so man3/cerf.3 diff --git a/man3/cexp2.3 b/man3/cexp2.3 index 737b1ed00..11341dcd7 100644 --- a/man3/cexp2.3 +++ b/man3/cexp2.3 @@ -15,11 +15,11 @@ cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number .sp Link with \-lm. .SH DESCRIPTION -The function returns 2 raised to the power of z. +The function returns 2 raised to the power of z. .SH "CONFORMING TO" These function names are reserved for future use in C99. .SH AVAILABILITY -Not yet in glibc, as at version 2.4. +Not yet in glibc, as at version 2.4. .\" But reserved in NAMESPACE. .SH "SEE ALSO" .BR cabs (3), diff --git a/man3/cexp2f.3 b/man3/cexp2f.3 index 19660179c..759ad34ce 100644 --- a/man3/cexp2f.3 +++ b/man3/cexp2f.3 @@ -1 +1 @@ -.so man3/cexp2.3 +.so man3/cexp2.3 diff --git a/man3/cexp2l.3 b/man3/cexp2l.3 index 19660179c..759ad34ce 100644 --- a/man3/cexp2l.3 +++ b/man3/cexp2l.3 @@ -1 +1 @@ -.so man3/cexp2.3 +.so man3/cexp2.3 diff --git a/man3/cexpf.3 b/man3/cexpf.3 index 1c19767f8..794d70711 100644 --- a/man3/cexpf.3 +++ b/man3/cexpf.3 @@ -1 +1 @@ -.so man3/cexp.3 +.so man3/cexp.3 diff --git a/man3/cexpl.3 b/man3/cexpl.3 index 1c19767f8..794d70711 100644 --- a/man3/cexpl.3 +++ b/man3/cexpl.3 @@ -1 +1 @@ -.so man3/cexp.3 +.so man3/cexp.3 diff --git a/man3/cfree.3 b/man3/cfree.3 index 7b137cc50..ee468316e 100644 --- a/man3/cfree.3 +++ b/man3/cfree.3 @@ -41,7 +41,8 @@ cfree \- free allocated memory .BI "void cfree(void *" ptr ", size_t " nelem ", size_t " elsize ); .fi .SH DESCRIPTION -This function should never be used. Use +This function should never be used. +Use .BR free (3) instead. .SS "1-arg cfree" @@ -80,7 +81,8 @@ Answer: use .BR free (). .LP An SCO manual writes: "The cfree routine is provided for compliance -to the iBCSe2 standard and simply calls free. The num and size +to the iBCSe2 standard and simply calls free. +The num and size arguments to cfree are not used." .SH "RETURN VALUE" The SunOS version of @@ -93,7 +95,7 @@ In case of error, is set to EINVAL: the value of .I ptr was not a pointer to a block previously allocated by -one of the routines in the +one of the routines in the .BR malloc (3) family. .SH "CONFORMING TO" diff --git a/man3/cimag.3 b/man3/cimag.3 index 901864e71..ca40f16f1 100644 --- a/man3/cimag.3 +++ b/man3/cimag.3 @@ -7,7 +7,7 @@ cimag, cimagf, cimagl \- get imaginary part of a complex number .SH SYNOPSIS .B #include .sp -.BI "double cimag(double complex " z ");" +.BI "double cimag(double complex " z ");" .br .BI "float cimagf(float complex " z ");" .br @@ -15,13 +15,13 @@ cimag, cimagf, cimagl \- get imaginary part of a complex number .sp Link with \-lm. .SH DESCRIPTION -The +The .BR cimag () function returns the imaginary part of the complex number z. .LP One has z = creal(z) + I*cimag(z). .SH NOTE -gcc also supports __imag__. That is a GNU extension. +gcc also supports __imag__. That is a GNU extension. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/cimagf.3 b/man3/cimagf.3 index d582faa0d..e806455ae 100644 --- a/man3/cimagf.3 +++ b/man3/cimagf.3 @@ -1 +1 @@ -.so man3/cimag.3 +.so man3/cimag.3 diff --git a/man3/cimagl.3 b/man3/cimagl.3 index d582faa0d..e806455ae 100644 --- a/man3/cimagl.3 +++ b/man3/cimagl.3 @@ -1 +1 @@ -.so man3/cimag.3 +.so man3/cimag.3 diff --git a/man3/clearenv.3 b/man3/clearenv.3 index 1167e2a11..a12345af0 100644 --- a/man3/clearenv.3 +++ b/man3/clearenv.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,17 +41,19 @@ value on failure. .\" Most versions of Unix return -1 on error, or do not even have errors. .\" Glibc info and the Watcom C library document "a non-zero value". .SH AVAILABILITY -Not in libc4, libc5. In glibc since glibc 2.0. +Not in libc4, libc5. +In glibc since glibc 2.0. .SH "CONFORMING TO" Various Unix variants (DG/UX, HP-UX, QNX, ...). POSIX.9 (bindings for FORTRAN77). POSIX.1-1996 did not accept \fBclearenv\fP() and \fIputenv\fP(), but changed its mind and scheduled these functions for some -later issue of this standard (cf. B.4.6.1). +later issue of this standard (cf. B.4.6.1). However, POSIX.1-2001 only adds \fIputenv\fP(), and rejected \fBclearenv\fP(). .SH NOTES -Used in security-conscious applications. If it is unavailable +Used in security-conscious applications. +If it is unavailable the assignment .RS .nf diff --git a/man3/clock.3 b/man3/clock.3 index 197750235..93f83fbb4 100644 --- a/man3/clock.3 +++ b/man3/clock.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -43,7 +43,7 @@ The value returned is the CPU time used so far as a to get the number of seconds used, divide by .BR CLOCKS_PER_SEC . If the processor time used is not available or its value cannot -be represented, the function returns the value (clock_t)\-1. +be represented, the function returns the value (clock_t)\-1. .SH "CONFORMING TO" C89, C99, POSIX.1-2001. POSIX requires that CLOCKS_PER_SEC equals 1000000 independent @@ -54,12 +54,13 @@ subtract the value returned from a call to .BR clock () at the start of the program to get maximum portability. .PP -Note that the time can wrap around. On a 32bit system where +Note that the time can wrap around. +On a 32bit system where CLOCKS_PER_SEC equals 1000000 this function will return the same value approximately every 72 minutes. .PP On several other implementations, -the value returned by +the value returned by .BR clock () also includes the times of any children whose status has been collected via @@ -74,7 +75,7 @@ value returned by .\" explicit prohibition. -- MTK The .BR times () -function, which explicitly returns (separate) information about the +function, which explicitly returns (separate) information about the caller and its children, may be preferable. .SH "SEE ALSO" .BR getrusage (2), diff --git a/man3/clock_getres.3 b/man3/clock_getres.3 index 848b08277..33e4e0837 100644 --- a/man3/clock_getres.3 +++ b/man3/clock_getres.3 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -72,7 +72,7 @@ and arguments are .B timespec structs, as specified in -.IR : +.IR : .sp .nf struct timespec { @@ -83,7 +83,7 @@ long tv_nsec; /* nanoseconds */ }; .fi .PP -The +The .I clk_id argument is the identifier of the particular clock on which to act. A clock may be system-wide and hence visible for all processes, or @@ -96,7 +96,8 @@ Its time represents seconds and nanoseconds since the Epoch. When its time is changed, timers for a relative interval are unaffected, but timers for an absolute point in time are affected. .LP -More clocks may be implemented. The interpretation of the +More clocks may be implemented. +The interpretation of the corresponding time values and the effect on timers is unspecified. .LP Sufficiently recent versions of GNU libc and the Linux kernel @@ -130,7 +131,7 @@ is set appropriately). points outside the accessible address space. .TP .B EINVAL -The +The .I clk_id specified is not supported on this system. .TP @@ -154,11 +155,13 @@ if a process is migrated to another CPU. .PP If the CPUs in an SMP system have different clock sources then there is no way to maintain a correlation between the timer registers since -each CPU will run at a slightly different frequency. If that is the case then +each CPU will run at a slightly different frequency. +If that is the case then .I clock_getcpuclockid(0) will return .B ENOENT -to signify this condition. The two clocks will then only be useful if it +to signify this condition. +The two clocks will then only be useful if it can be ensured that a process stays on a certain CPU. .PP The processors in an SMP system do not start all at exactly the same @@ -166,7 +169,8 @@ time and therefore the timer registers are typically running at an offset. Some architectures include code that attempts to limit these offsets on bootup. However, the code cannot guarantee to accurately tune the offsets. Glibc contains no provisions to deal with these offsets (unlike the Linux -Kernel). Typically these offsets are small and therefore the effects may be +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 diff --git a/man3/clog.3 b/man3/clog.3 index 56ad97665..7eaa39097 100644 --- a/man3/clog.3 +++ b/man3/clog.3 @@ -17,15 +17,15 @@ Link with \-lm. .SH DESCRIPTION The logarithm clog() is the inverse function of the exponential cexp(). Thus, if y = clog(z), then z = cexp(y). -The imaginary part of -.I y +The imaginary part of +.I y is chosen in the interval [\-pi,pi]. .LP One has clog(z) = log(cabs(z))+I*carg(z). .LP -Note that -.I z -close to zero will cause an overflow. +Note that +.I z +close to zero will cause an overflow. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/clog10.3 b/man3/clog10.3 index 46e751fc5..b67080d4d 100644 --- a/man3/clog10.3 +++ b/man3/clog10.3 @@ -17,18 +17,18 @@ clog10, clog10f, clog10l \- base-10 logarithm of a complex number .sp Link with \-lm. .SH DESCRIPTION -The call +The call .I clog10(z) is equivalent to .IR clog(z)/log(10) . -The other functions perform the same task for +The other functions perform the same task for .I float -and +and .IR "long double" . -Note that -.I z -close to zero will cause an overflow. +Note that +.I z +close to zero will cause an overflow. .SH "CONFORMING TO" This function is a GNU extension. It is reserved for future use in C99. diff --git a/man3/clog10f.3 b/man3/clog10f.3 index fc825a73e..5840d54d0 100644 --- a/man3/clog10f.3 +++ b/man3/clog10f.3 @@ -1 +1 @@ -.so man3/clog10.3 +.so man3/clog10.3 diff --git a/man3/clog10l.3 b/man3/clog10l.3 index fc825a73e..5840d54d0 100644 --- a/man3/clog10l.3 +++ b/man3/clog10l.3 @@ -1 +1 @@ -.so man3/clog10.3 +.so man3/clog10.3 diff --git a/man3/clog2.3 b/man3/clog2.3 index ceefc6d2d..df6fdbc33 100644 --- a/man3/clog2.3 +++ b/man3/clog2.3 @@ -15,19 +15,19 @@ clog2, clog2f, clog2l \- base-2 logarithm of a complex number .\" .sp .\" Link with \-lm. .SH DESCRIPTION -The call +The call .I clog2(z) is equivalent to .IR clog(z)/log(2) . -The other functions perform the same task for +The other functions perform the same task for .I float -and +and .IR "long double" . -Note that -.I z -close to zero will cause an overflow. +Note that +.I z +close to zero will cause an overflow. .SH "CONFORMING TO" These function names are reserved for future use in C99. .SH AVAILABILITY diff --git a/man3/clog2f.3 b/man3/clog2f.3 index e487cb182..23d683416 100644 --- a/man3/clog2f.3 +++ b/man3/clog2f.3 @@ -1 +1 @@ -.so man3/clog2.3 +.so man3/clog2.3 diff --git a/man3/clog2l.3 b/man3/clog2l.3 index e487cb182..23d683416 100644 --- a/man3/clog2l.3 +++ b/man3/clog2l.3 @@ -1 +1 @@ -.so man3/clog2.3 +.so man3/clog2.3 diff --git a/man3/clogf.3 b/man3/clogf.3 index 478e02b4d..3cd9533b3 100644 --- a/man3/clogf.3 +++ b/man3/clogf.3 @@ -1 +1 @@ -.so man3/clog.3 +.so man3/clog.3 diff --git a/man3/clogl.3 b/man3/clogl.3 index 478e02b4d..3cd9533b3 100644 --- a/man3/clogl.3 +++ b/man3/clogl.3 @@ -1 +1 @@ -.so man3/clog.3 +.so man3/clog.3 diff --git a/man3/closedir.3 b/man3/closedir.3 index 1b4ef55ba..17e96ffd0 100644 --- a/man3/closedir.3 +++ b/man3/closedir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/cmsg.3 b/man3/cmsg.3 index 1fe5dda28..579340235 100644 --- a/man3/cmsg.3 +++ b/man3/cmsg.3 @@ -4,7 +4,7 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ -.TH CMSG 3 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.TH CMSG 3 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data .SH SYNOPSIS @@ -20,7 +20,7 @@ CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data .br .BI "size_t CMSG_LEN(size_t " length ); .br -.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); +.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); .sp .nf struct cmsghdr { @@ -33,121 +33,127 @@ struct cmsghdr { .SH DESCRIPTION These macros are used to create and access control messages (also called ancillary data) that are not a part of the socket payload. -This control information may -include the interface the packet was received on, various rarely used header +This control information may +include the interface the packet was received on, various rarely used header fields, an extended error description, a set of file descriptors or Unix -credentials. For instance, control messages can be used to send -additional header fields such as IP options. -Ancillary data is sent by calling +credentials. +For instance, control messages can be used to send +additional header fields such as IP options. +Ancillary data is sent by calling .BR sendmsg (2) and received by calling .BR recvmsg (2). -See their manual pages for more information. +See their manual pages for more information. .PP -Ancillary data is a sequence of -.I struct cmsghdr -structures with appended data. This sequence should only be accessed -using the macros described in this manual page and never directly. -See the specific protocol man pages for the available control message types. -The maximum ancillary buffer size allowed per socket can be set using the +Ancillary data is a sequence of +.I struct cmsghdr +structures with appended data. +This sequence should only be accessed +using the macros described in this manual page and never directly. +See the specific protocol man pages for the available control message types. +The maximum ancillary buffer size allowed per socket can be set using the .B net.core.optmem_max sysctl; see -.BR socket (7). +.BR socket (7). .PP .BR CMSG_FIRSTHDR () -returns a pointer to the first -.B cmsghdr +returns a pointer to the first +.B cmsghdr in the ancillary -data buffer associated with the passed +data buffer associated with the passed .BR msghdr . .PP .BR CMSG_NXTHDR () -returns the next valid -.B cmsghdr -after the passed -.BR cmsghdr . +returns the next valid +.B cmsghdr +after the passed +.BR cmsghdr . It returns NULL when there isn't enough space left in the buffer. .PP .BR CMSG_ALIGN (), -given a length, returns it including the required alignment. This is a +given a length, returns it including the required alignment. +This is a constant expression. .PP .BR CMSG_SPACE () -returns the number of bytes an ancillary element with payload of the -passed data length occupies. +returns the number of bytes an ancillary element with payload of the +passed data length occupies. This is a constant expression. .PP .B CMSG_DATA -returns a pointer to the data portion of a -.BR cmsghdr . +returns a pointer to the data portion of a +.BR cmsghdr . .PP .B CMSG_LEN -returns the value to store in the +returns the value to store in the .I cmsg_len -member of the -.B cmsghdr +member of the +.B cmsghdr structure, taking into account any necessary -alignment. It takes the data length as an argument. This is a constant -expression. +alignment. +It takes the data length as an argument. +This is a constant +expression. .PP -To create ancillary data, first initialize the +To create ancillary data, first initialize the .I msg_controllen -member of the -.B msghdr -with the length of the control message buffer. Use +member of the +.B msghdr +with the length of the control message buffer. +Use .BR CMSG_FIRSTHDR () -on the -.B msghdr +on the +.B msghdr to get the first control message and .B CMSG_NEXTHDR to get all subsequent ones. In each control message, initialize .I cmsg_len -(with -.BR CMSG_LEN ), -the other -.B cmsghdr -header fields, and the data portion using +(with +.BR CMSG_LEN ), +the other +.B cmsghdr +header fields, and the data portion using .BR CMSG_DATA . -Finally, the -.I msg_controllen -field of the -.B msghdr -should be set to the sum of the +Finally, the +.I msg_controllen +field of the +.B msghdr +should be set to the sum of the .BR CMSG_SPACE () -of the length of -all control messages in the buffer. -For more information on the +of the length of +all control messages in the buffer. +For more information on the .BR msghdr , see -.BR recvmsg (2). +.BR recvmsg (2). .PP When the control message buffer is too short to store all messages, the -.B MSG_CTRUNC -flag is set in the -.I msg_flags -member of the +.B MSG_CTRUNC +flag is set in the +.I msg_flags +member of the .BR msghdr . .SH EXAMPLE -This code looks for the -.B IP_TTL +This code looks for the +.B IP_TTL option in a received ancillary buffer: .PP .RS .nf -struct msghdr msgh; +struct msghdr msgh; struct cmsghdr *cmsg; int *ttlptr; int received_ttl; -/* Receive auxiliary data in msgh */ -for (cmsg = CMSG_FIRSTHDR(&msgh); - cmsg != NULL; +/* Receive auxiliary data in msgh */ +for (cmsg = CMSG_FIRSTHDR(&msgh); + cmsg != NULL; cmsg = CMSG_NXTHDR(&msgh,cmsg)) { - if (cmsg->cmsg_level == IPPROTO_IP - && cmsg->cmsg_type == IP_TTL) { + if (cmsg->cmsg_level == IPPROTO_IP + && cmsg->cmsg_type == IP_TTL) { ttlptr = (int *) CMSG_DATA(cmsg); - received_ttl = *ttlptr; + received_ttl = *ttlptr; break; } } @@ -155,12 +161,12 @@ if (cmsg == NULL) { /* * Error: IP_TTL not enabled or small buffer * or I/O error. - */ -} + */ +} .fi .RE .PP -The code below passes an array of file descriptors over a Unix socket using +The code below passes an array of file descriptors over a Unix socket using .BR SCM_RIGHTS : .PP .RS @@ -168,44 +174,45 @@ The code below passes an array of file descriptors over a Unix socket using .ta 8n 16n 32n struct msghdr msg = {0}; struct cmsghdr *cmsg; -int myfds[NUM_FD]; /* Contains the file descriptors to pass. */ +int myfds[NUM_FD]; /* Contains the file descriptors to pass. */ char buf[CMSG_SPACE(sizeof myfds)]; /* ancillary data buffer */ int *fdptr; -msg.msg_control = buf; +msg.msg_control = buf; msg.msg_controllen = sizeof buf; -cmsg = CMSG_FIRSTHDR(&msg); +cmsg = CMSG_FIRSTHDR(&msg); cmsg->cmsg_level = SOL_SOCKET; cmsg->cmsg_type = SCM_RIGHTS; -cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD); -/* Initialize the payload: */ -fdptr = (int *)CMSG_DATA(cmsg); -memcpy(fdptr, myfds, NUM_FD * sizeof(int)); -/* Sum of the length of all control messages in the buffer: */ +cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD); +/* Initialize the payload: */ +fdptr = (int *)CMSG_DATA(cmsg); +memcpy(fdptr, myfds, NUM_FD * sizeof(int)); +/* Sum of the length of all control messages in the buffer: */ msg.msg_controllen = cmsg->cmsg_len; .ta .fi .RE .SH NOTES For portability, ancillary data should be accessed only using the macros -described here. +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_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. +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. +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 70d5f0e96..d35547bfa 100644 --- a/man3/confstr.3 +++ b/man3/confstr.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,14 +16,14 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. .\" Modified Sat Jul 24 19:53:02 1993 by Rik Faith (faith@cs.unc.edu) -.\" FIXME Many more values for 'name' are supported, some of which +.\" FIXME Many more values for 'name' are supported, some of which .\" are documented under 'info confstr'. -.\" See for the rest. +.\" See for the rest. .\" These should all be added to this page. .\" See also the POSIX.1-2001 specification of confstr() .TH CONFSTR 3 1993-04-17 "GNU" "Linux Programmer's Manual" @@ -64,7 +64,7 @@ be found. .PP If .I buf -is not NULL and +is not NULL and .I len is not zero, .BR confstr () @@ -90,7 +90,7 @@ If .I name is a valid configuration variable, .BR confstr () -returns the number of bytes (including the terminating null byte) +returns the number of bytes (including the terminating null byte) that would be required to hold the entire value of that variable. This value may be greater than .IR len , @@ -99,8 +99,8 @@ which means that the value in is truncated. If -.I name -is a valid configuration variable, +.I name +is a valid configuration variable, but that variable does not have a value, then .BR confstr () returns 0. @@ -110,11 +110,11 @@ does not correspond to a valid configuration variable, .BR confstr () returns 0, and .I errno -is set to +is set to .BR EINVAL . .SH ERRORS .TP -.BR EINVAL +.BR EINVAL If the value of .I name is invalid. diff --git a/man3/conj.3 b/man3/conj.3 index 5835e0e3e..906019ac8 100644 --- a/man3/conj.3 +++ b/man3/conj.3 @@ -7,16 +7,16 @@ conj, conjf, conjl \- calculate the complex conjugate .SH SYNOPSIS .B #include .sp -.BI "double complex conj(double complex " z ); +.BI "double complex conj(double complex " z ); .br -.BI "float complex conjf(float complex " z ); +.BI "float complex conjf(float complex " z ); .br -.BI "long double complex conjl(long double complex " z ); +.BI "long double complex conjl(long double complex " z ); .sp Link with \-lm. .SH DESCRIPTION -The -.BR conj () +The +.BR conj () function returns the complex conjugate value of z. That is the value obtained by changing the sign of the imaginary part. .LP diff --git a/man3/conjf.3 b/man3/conjf.3 index babfc4a0f..ef6093f70 100644 --- a/man3/conjf.3 +++ b/man3/conjf.3 @@ -1 +1 @@ -.so man3/conj.3 +.so man3/conj.3 diff --git a/man3/conjl.3 b/man3/conjl.3 index babfc4a0f..ef6093f70 100644 --- a/man3/conjl.3 +++ b/man3/conjl.3 @@ -1 +1 @@ -.so man3/conj.3 +.so man3/conj.3 diff --git a/man3/copysign.3 b/man3/copysign.3 index 1fa6c1a87..170cb4657 100644 --- a/man3/copysign.3 +++ b/man3/copysign.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/cos.3 b/man3/cos.3 index 5559e1fc6..224f852a9 100644 --- a/man3/cos.3 +++ b/man3/cos.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,7 +49,7 @@ given in radians. The \fBcos\fP() function returns a value between \-1 and 1. .SH "CONFORMING TO" SVr4, 4.3BSD, C99. -The +The .I float and .I "long double" diff --git a/man3/cosh.3 b/man3/cosh.3 index ddf2b27fb..942d42fc8 100644 --- a/man3/cosh.3 +++ b/man3/cosh.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,13 +45,13 @@ cosh, coshf, coshl \- hyperbolic cosine function .sp Link with \-lm. .SH DESCRIPTION -The \fBcosh\fP() function returns the hyperbolic cosine of \fIx\fP, which +The \fBcosh\fP() function returns the hyperbolic cosine of \fIx\fP, which is defined mathematically as (exp(x) + exp(\-x)) / 2. .SH "CONFORMING TO" SVr4, POSIX, 4.3BSD, C99. -The -.I float -and the +The +.I float +and the .I "long double" variants are C99 requirements. .SH "SEE ALSO" diff --git a/man3/cpowf.3 b/man3/cpowf.3 index 91e516d15..7577fcdf1 100644 --- a/man3/cpowf.3 +++ b/man3/cpowf.3 @@ -1 +1 @@ -.so man3/cpow.3 +.so man3/cpow.3 diff --git a/man3/cpowl.3 b/man3/cpowl.3 index 91e516d15..7577fcdf1 100644 --- a/man3/cpowl.3 +++ b/man3/cpowl.3 @@ -1 +1 @@ -.so man3/cpow.3 +.so man3/cpow.3 diff --git a/man3/cproj.3 b/man3/cproj.3 index 84c76d624..2a7e2e909 100644 --- a/man3/cproj.3 +++ b/man3/cproj.3 @@ -15,7 +15,7 @@ cproj, cprojf, cprojl \- project into Riemann Sphere .sp Link with \-lm. .SH DESCRIPTION -This function projects a point in the plane onto the surface of a +This function projects a point in the plane onto the surface of a Riemann Sphere, the one-point compactification of the complex plane. Each finite point z projects to z itself. Every complex infinite value is projected to a single infinite value, diff --git a/man3/cprojf.3 b/man3/cprojf.3 index dc33dea33..0a3f31c6d 100644 --- a/man3/cprojf.3 +++ b/man3/cprojf.3 @@ -1 +1 @@ -.so man3/cproj.3 +.so man3/cproj.3 diff --git a/man3/cprojl.3 b/man3/cprojl.3 index dc33dea33..0a3f31c6d 100644 --- a/man3/cprojl.3 +++ b/man3/cprojl.3 @@ -1 +1 @@ -.so man3/cproj.3 +.so man3/cproj.3 diff --git a/man3/creal.3 b/man3/creal.3 index 8267c24b9..6dd6db1b7 100644 --- a/man3/creal.3 +++ b/man3/creal.3 @@ -15,13 +15,13 @@ creal, crealf, creall \- get real part of a complex number .sp Link with \-lm. .SH DESCRIPTION -The +The .BR creal () function returns the real part of the complex number z. .LP One has z = creal(z) + I*cimag(z). .SH NOTE -The gcc supports also __real__. That is a GNU extension. +The gcc supports also __real__. That is a GNU extension. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/crealf.3 b/man3/crealf.3 index 409b15707..4289f71de 100644 --- a/man3/crealf.3 +++ b/man3/crealf.3 @@ -1 +1 @@ -.so man3/creal.3 +.so man3/creal.3 diff --git a/man3/creall.3 b/man3/creall.3 index 409b15707..4289f71de 100644 --- a/man3/creall.3 +++ b/man3/creall.3 @@ -1 +1 @@ -.so man3/creal.3 +.so man3/creal.3 diff --git a/man3/crypt.3 b/man3/crypt.3 index d010baea5..92b97d1a1 100644 --- a/man3/crypt.3 +++ b/man3/crypt.3 @@ -22,7 +22,7 @@ .\" .\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away .\" -.\" TO DO: This manual page should go more into detail how DES is perturbed, +.\" TO DO: This manual page should go more into detail how DES is perturbed, .\" which string will be encrypted, and what determines the repetition factor. .\" Is a simple repetition using ECB used, or something more advanced? I hope .\" the presented explanations are at least better than nothing, but by no @@ -42,7 +42,8 @@ crypt \- password and data encryption .BI "char *crypt(const char *" key ", const char *" salt ); .SH DESCRIPTION .BR crypt () -is the password encryption function. It is based on the Data Encryption +is the password encryption function. +It is based on the Data Encryption Standard algorithm with variations intended (among other things) to discourage use of hardware implementations of a key search. .PP @@ -51,27 +52,34 @@ is a user's typed password. .PP .I salt is a two-character string chosen from the set -[\fBa\fP\(en\fBzA\fP\(en\fBZ0\fP\(en\fB9./\fP]. This string is used to +[\fBa\fP\(en\fBzA\fP\(en\fBZ0\fP\(en\fB9./\fP]. +This string is used to perturb the algorithm in one of 4096 different ways. .PP By taking the lowest 7 bits of each of the first eight characters of the .IR key , -a 56-bit key is obtained. This 56-bit key is used to encrypt repeatedly a -constant string (usually a string consisting of all zeros). The returned +a 56-bit key is obtained. +This 56-bit key is used to encrypt repeatedly a +constant string (usually a string consisting of all zeros). +The returned value points to the encrypted password, a series of 13 printable ASCII -characters (the first two characters represent the salt itself). The -return value points to static data whose content is overwritten by each -call. +characters (the first two characters represent the salt itself). +The return value points to static data whose content is +overwritten by each call. .PP Warning: The key space consists of .if t 2\s-2\u56\s0\d .if n 2**56 -equal 7.2e16 possible values. Exhaustive searches of this key space are -possible using massively parallel computers. Software, such as +equal 7.2e16 possible values. +Exhaustive searches of this key space are +possible using massively parallel computers. +Software, such as .BR crack (1), is available which will search the portion of this key space that is -generally used by humans for passwords. Hence, password selection should, -at minimum, avoid common words and names. The use of a +generally used by humans for passwords. +Hence, password selection should, +at minimum, avoid common words and names. +The use of a .BR passwd (1) program that checks for crackable passwords during the selection process is recommended. @@ -79,7 +87,8 @@ recommended. The DES algorithm itself has a few quirks which make the use of the .BR crypt (3) interface a very poor choice for anything other than password -authentication. If you are planning on using the +authentication. +If you are planning on using the .BR crypt (3) interface for a cryptography project, don't do it: get a good book on encryption and one of the widely available DES libraries. @@ -89,7 +98,7 @@ On error, NULL is returned. .SH ERRORS .TP .B ENOSYS -The +The .BR crypt () function was not implemented, probably because of U.S.A. export restrictions. .\" This level of detail is not necessary in this man page. . . @@ -136,11 +145,11 @@ then instead of using the DES machine, the glibc crypt function uses an MD5-based algorithm, and outputs up to 34 bytes, namely "$1$$", where "" stands for the up to 8 characters following "$1$" in the salt, -and "" is a further 22 characters. -The characters in "" and "" are drawn from the set +and "" is a further 22 characters. +The characters in "" and "" are drawn from the set [\fBa\fP\(en\fBzA\fP\(en\fBZ0\fP\(en\fB9./\fP]. -The entire -.I key +The entire +.I key is significant here (instead of only the first 8 bytes). .LP diff --git a/man3/csin.3 b/man3/csin.3 index 5e6f5a22b..d4695d2d6 100644 --- a/man3/csin.3 +++ b/man3/csin.3 @@ -15,7 +15,7 @@ csin, csinf, csinl \- complex sine function .sp Link with \-lm. .SH DESCRIPTION -The complex sine function csin(z) is defined as (exp(i*z)\-exp(\-i*z))/(2*i). +The complex sine function csin(z) is defined as (exp(i*z)\-exp(\-i*z))/(2*i). .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/csinf.3 b/man3/csinf.3 index a5fe0e010..1ed2a3e7f 100644 --- a/man3/csinf.3 +++ b/man3/csinf.3 @@ -1 +1 @@ -.so man3/csin.3 +.so man3/csin.3 diff --git a/man3/csinh.3 b/man3/csinh.3 index 01c154e1b..4dea6c124 100644 --- a/man3/csinh.3 +++ b/man3/csinh.3 @@ -16,7 +16,7 @@ csinh, csinhf, csinhl \- complex hyperbolic sine Link with \-lm. .SH DESCRIPTION The complex hyperbolic sine function sinh(z) is defined as -(exp(z)\-exp(\-z))/2. +(exp(z)\-exp(\-z))/2. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/csinhf.3 b/man3/csinhf.3 index e6a49a65f..9f6d66f92 100644 --- a/man3/csinhf.3 +++ b/man3/csinhf.3 @@ -1 +1 @@ -.so man3/csinh.3 +.so man3/csinh.3 diff --git a/man3/csinhl.3 b/man3/csinhl.3 index e6a49a65f..9f6d66f92 100644 --- a/man3/csinhl.3 +++ b/man3/csinhl.3 @@ -1 +1 @@ -.so man3/csinh.3 +.so man3/csinh.3 diff --git a/man3/csinl.3 b/man3/csinl.3 index a5fe0e010..1ed2a3e7f 100644 --- a/man3/csinl.3 +++ b/man3/csinl.3 @@ -1 +1 @@ -.so man3/csin.3 +.so man3/csin.3 diff --git a/man3/ctanf.3 b/man3/ctanf.3 index 47e122864..c0f4a6607 100644 --- a/man3/ctanf.3 +++ b/man3/ctanf.3 @@ -1 +1 @@ -.so man3/ctan.3 +.so man3/ctan.3 diff --git a/man3/ctanhf.3 b/man3/ctanhf.3 index 1c6e2c28e..49b92172b 100644 --- a/man3/ctanhf.3 +++ b/man3/ctanhf.3 @@ -1 +1 @@ -.so man3/ctanh.3 +.so man3/ctanh.3 diff --git a/man3/ctanhl.3 b/man3/ctanhl.3 index 1c6e2c28e..49b92172b 100644 --- a/man3/ctanhl.3 +++ b/man3/ctanhl.3 @@ -1 +1 @@ -.so man3/ctanh.3 +.so man3/ctanh.3 diff --git a/man3/ctanl.3 b/man3/ctanl.3 index 47e122864..c0f4a6607 100644 --- a/man3/ctanl.3 +++ b/man3/ctanl.3 @@ -1 +1 @@ -.so man3/ctan.3 +.so man3/ctan.3 diff --git a/man3/ctermid.3 b/man3/ctermid.3 index 11804f042..9f3c24fd9 100644 --- a/man3/ctermid.3 +++ b/man3/ctermid.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -32,8 +32,8 @@ ctermid \- get controlling terminal name .fi .SH DESCRIPTION .BR ctermid () -returns a string which is the pathname for the current -controlling terminal for this process. +returns a string which is the pathname for the current +controlling terminal for this process. If .I s is NULL, diff --git a/man3/ctime.3 b/man3/ctime.3 index a6860d6f9..9bf5cea5e 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -89,11 +89,11 @@ struct tm { The members of the \fItm\fP structure are: .TP .I tm_sec -The number of seconds after the minute, normally in the range 0 to 59, +The number of seconds after the minute, normally in the range 0 to 59, but can be up to 60 to allow for leap seconds. .TP .I tm_min -The number of minutes after the hour, in the range 0 to 59. +The number of minutes after the hour, in the range 0 to 59. .TP .I tm_hour The number of hours past midnight, in the range 0 to 23. @@ -115,7 +115,8 @@ The number of days since January 1, in the range 0 to 365. .TP .I tm_isdst A flag that indicates whether daylight saving time is in effect at the -time described. The value is positive if daylight saving time is in +time described. +The value is positive if daylight saving time is in effect, zero if it is not, and negative if the information is not available. .PP @@ -130,20 +131,25 @@ It converts the calendar time \fIt\fP into a string of the form .RE .sp The abbreviations for the days of the week are `Sun', `Mon', `Tue', `Wed', -`Thu', `Fri', and `Sat'. The abbreviations for the months are `Jan', +`Thu', `Fri', and `Sat'. +The abbreviations for the months are `Jan', `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and -`Dec'. The return value points to a statically allocated string which +`Dec'. +The return value points to a statically allocated string which might be overwritten by subsequent calls to any of the date and time -functions. The function also sets the external variable \fItzname\fP (see +functions. +The function also sets the external variable \fItzname\fP (see .BR tzset (3)) with information about the current time zone. The re-entrant version \fBctime_r\fP() does the same, but stores the -string in a user-supplied buffer of length at least 26. It need not +string in a user-supplied buffer of length at least 26. +It need not set \fItzname\fP. .PP The \fBgmtime\fP() function converts the calendar time \fItimep\fP to broken-down time representation, expressed in Coordinated Universal Time -(UTC). It may return NULL when the year does not fit into an integer. +(UTC). +It may return NULL when the year does not fit into an integer. The return value points to a statically allocated struct which might be overwritten by subsequent calls to any of the date and time functions. The \fBgmtime_r\fP() function does the same, but stores the data in a @@ -151,9 +157,10 @@ user-supplied struct. .PP The \fBlocaltime\fP() function converts the calendar time \fItimep\fP to broken-time representation, expressed relative to the user's specified -time zone. The function acts as if it called +time zone. +The function acts as if it called .BR tzset (3) -and sets the external variables \fItzname\fP with +and sets the external variables \fItzname\fP with information about the current time zone, \fItimezone\fP with the difference between Coordinated Universal Time (UTC) and local standard time in seconds, and \fIdaylight\fP to a non-zero value if daylight savings @@ -161,24 +168,27 @@ time rules apply during some part of the year. The return value points to a statically allocated struct which might be overwritten by subsequent calls to any of the date and time functions. The \fBlocaltime_r\fP() function does the same, but stores the data in a -user-supplied struct. It need not set \fItzname\fP. +user-supplied struct. +It need not set \fItzname\fP. .PP The \fBasctime\fP() function converts the broken-down time value \fItm\fP into a string with the same format as \fBctime\fP(). -The return value points to a statically allocated string which might be +The return value points to a statically allocated string which might be overwritten by subsequent calls to any of the date and time functions. The \fBasctime_r\fP() function does the same, but stores the string in a user-supplied buffer of length at least 26. .PP The \fBmktime\fP() function converts a broken-down time structure, expressed -as local time, to calendar time representation. The function ignores +as local time, to calendar time representation. +The function ignores the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP and recomputes them from the other information in the broken-down time structure. If structure members are outside their legal interval, they will be normalized (so that, e.g., 40 October is changed into 9 November). Calling \fBmktime\fP() also sets the external variable \fItzname\fP with -information about the current time zone. If the specified broken-down +information about the current time zone. +If the specified broken-down time cannot be represented as calendar time (seconds since the epoch), \fBmktime\fP() returns a value of (time_t)(\-1) and does not alter the \fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure. @@ -220,12 +230,12 @@ 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. +POSIX.1-2001. C89 and C99 specify .BR asctime (), .BR ctime (), .BR gmtime (), -.BR localtime (), +.BR localtime (), and .BR mktime () .SH "SEE ALSO" diff --git a/man3/daemon.3 b/man3/daemon.3 index a59911e96..d10c4dfe4 100644 --- a/man3/daemon.3 +++ b/man3/daemon.3 @@ -70,7 +70,7 @@ returns \-1 and sets the global variable .I errno to any of the errors specified for the library functions .BR fork (2) -and +and .BR setsid (2). .SH "SEE ALSO" .BR fork (2), @@ -79,7 +79,8 @@ and The glibc implementation can also return \-1 when .I /dev/null exists but is not a character device with the expected -major and minor numbers. In this case +major and minor numbers. +In this case .I errno need not be set. .SH CONFORMING TO diff --git a/man3/dbopen.3 b/man3/dbopen.3 index 95f240861..139d46728 100644 --- a/man3/dbopen.3 +++ b/man3/dbopen.3 @@ -31,7 +31,7 @@ .\" .\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 .\" -.TH DBOPEN 3 1994-01-02 +.TH DBOPEN 3 1994-01-02 .UC 7 .SH NAME dbopen \- database access methods @@ -42,7 +42,7 @@ dbopen \- database access methods .B #include .BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ -", DBTYPE " type , +", DBTYPE " type , .BI " const void *" openinfo ); .fi .SH DESCRIPTION diff --git a/man3/des_crypt.3 b/man3/des_crypt.3 index 30221f175..81e37967a 100644 --- a/man3/des_crypt.3 +++ b/man3/des_crypt.3 @@ -9,7 +9,7 @@ .\" .TH DES_CRYPT 3 "6 October 1987" .SH NAME -des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast +des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast DES encryption .SH SYNOPSIS .nf @@ -53,10 +53,12 @@ mode, which chains together successive blocks. .SM CBC mode protects against insertions, deletions and -substitutions of blocks. Also, regularities in the clear text will +substitutions of blocks. +Also, regularities in the clear text will not appear in the cipher text. .LP -Here is how to use these routines. The first parameter, +Here is how to use these routines. +The first parameter, .IR key , is the 8-byte encryption key with parity. To set the key's parity, which for @@ -65,16 +67,19 @@ is in the low bit of each byte, use .BR des_setparity (). The second parameter, .IR data , -contains the data to be encrypted or decrypted. The +contains the data to be encrypted or decrypted. +The third parameter, .IR datalen , is the length in bytes of .IR data , -which must be a multiple of 8. The fourth parameter, +which must be a multiple of 8. +The fourth parameter, .IR mode , is formed by .SM OR\s0'ing -together some things. For the encryption direction 'or' in either +together some things. +For the encryption direction 'or' in either .SM DES_ENCRYPT or .SM DES_DECRYPT\s0. @@ -93,7 +98,8 @@ For the parameter .I ivec is the 8-byte initialization -vector for the chaining. It is updated to the next initialization +vector for the chaining. +It is updated to the next initialization vector upon return. .SH "SEE ALSO" .BR des (1), @@ -130,5 +136,6 @@ is false only for the first two statuses. These routines are present in libc 4.6.27 and later, and in glibc 2.1 and later. .SH "CONFORMING TO" -4.3BSD. Not in POSIX.1-2001. +4.3BSD. +Not in POSIX.1-2001. diff --git a/man3/difftime.3 b/man3/difftime.3 index 4da5792df..6005d0a36 100644 --- a/man3/difftime.3 +++ b/man3/difftime.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,8 +43,8 @@ elapsed since the Epoch .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99 .SH NOTES -On a POSIX system, -.I time_t +On a POSIX system, +.I time_t is an arithmetic type, and one could just define .RS @@ -55,8 +55,8 @@ define .fi .RE when the possible overflow in the subtraction is not a concern. -On other systems, the data type -.I time_t +On other systems, the data type +.I time_t might use some other encoding where subtraction doesn't work directly. .SH "CONFORMING TO" diff --git a/man3/dirfd.3 b/man3/dirfd.3 index 71bffeb70..0141e61fa 100644 --- a/man3/dirfd.3 +++ b/man3/dirfd.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -58,7 +58,7 @@ is defined. 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 +This function is under consideration for inclusion in a future version of POSIX.1. .SH "SEE ALSO" .BR open (2), diff --git a/man3/div.3 b/man3/div.3 index 2e431b992..499d48107 100644 --- a/man3/div.3 +++ b/man3/div.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,7 +31,7 @@ .\" .TH DIV 3 2003-11-01 "" "Linux Programmer's Manual" .SH NAME -div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of +div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of an integer division .SH SYNOPSIS .nf @@ -48,16 +48,16 @@ an integer division .BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator ); .fi .SH DESCRIPTION -The \fBdiv\fP() function computes the value +The \fBdiv\fP() function computes the value \fInumerator\fP/\fIdenominator\fP and -returns the quotient and remainder in a structure +returns the quotient and remainder in a structure named \fIdiv_t\fP that contains two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP. The quotient is rounded towards zero. The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP. .LP The \fBldiv\fP() and \fBlldiv\fP() and \fBimaxdiv\fP() functions do the same, -dividing numbers of the indicated type and +dividing numbers of the indicated type and returning the result in a structure of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP of the same type as the function arguments. @@ -71,9 +71,9 @@ After the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The functions -.BR lldiv () -and +The functions +.BR lldiv () +and .BR imaxdiv () were added in C99. .SH "SEE ALSO" diff --git a/man3/dl_iterate_phdr.3 b/man3/dl_iterate_phdr.3 index c04de5bf2..914a641bd 100644 --- a/man3/dl_iterate_phdr.3 +++ b/man3/dl_iterate_phdr.3 @@ -141,9 +141,9 @@ in virtual memory using the formula: addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr; .fi .SH EXAMPLE -The following program displays a list of pathnames of the +The following program displays a list of pathnames of the shared objects it has loaded. -For each shared object, the program lists the virtual addresses +For each shared object, the program lists the virtual addresses at which the object's ELF segments are loaded. .nf diff --git a/man3/dlopen.3 b/man3/dlopen.3 index 90aa72cf6..5c6ff8c2f 100644 --- a/man3/dlopen.3 +++ b/man3/dlopen.3 @@ -56,10 +56,10 @@ implement the interface to the dynamic linking loader. The function .BR dlerror () returns a human readable string describing the most recent error -that occurred from -.BR dlopen (), -.BR dlsym () -or +that occurred from +.BR dlopen (), +.BR dlsym () +or .BR dlclose () since the last call to .BR dlerror () . @@ -92,7 +92,7 @@ If the environment variable .BR LD_LIBRARY_PATH is defined to contain a colon-separated list of directories, then these are searched. -(As a security measure this variable is ignored for set-user-ID and +(As a security measure this variable is ignored for set-user-ID and set-group-ID programs.) .IP o (ELF only) If the executable file for the calling program @@ -107,21 +107,22 @@ is checked to see whether it contains an entry for .IR filename . .IP o The directories -.I /lib -and -.I /usr/lib +.I /lib +and +.I /usr/lib are searched (in that order). .PP If the library has dependencies on other shared libraries, then these are also automatically loaded by the dynamic linker -using the same rules. (This process may occur recursively, +using the same rules. +(This process may occur recursively, if those libraries in turn have dependencies, and so on.) .PP One of the following two values must be included in .IR flag : .TP .B RTLD_LAZY -Perform lazy binding. +Perform lazy binding. Only resolve symbols as the code that references them is executed. If the symbol is never referenced, then it is never resolved. (Lazy binding is only performed for function references; @@ -134,7 +135,8 @@ If this value is specified, or the environment variable is set to a non-empty string, all undefined symbols in the library are resolved before .BR dlopen () -returns. If this cannot be done, an error is returned. +returns. +If this cannot be done, an error is returned. .PP Zero of more of the following values may also be ORed in .IR flag : @@ -142,9 +144,9 @@ Zero of more of the following values may also be ORed in .B RTLD_GLOBAL The symbols defined by this library will be made available for symbol resolution of subsequently loaded libraries. -.TP +.TP .B RTLD_LOCAL -This is the converse of +This is the converse of .BR RTLD_GLOBAL , and the default if neither flag is specified. Symbols defined in this library are not made available to resolve @@ -154,7 +156,7 @@ references in subsequently loaded libraries. Do not unload the library during .BR dlclose (). Consequently, the library's static variables are not reinitialised -if the library is reloaded with +if the library is reloaded with .BR dlopen () at a later time. This flag is not specified in POSIX.1-2001. @@ -165,23 +167,23 @@ Don't load the library. This can be used to test if the library is already resident .RB ( dlopen () returns NULL if it is not, or the library's handle if it is resident). -This flag can also be used to promote the flags on a library +This flag can also be used to promote the flags on a library that is already loaded. For example, a library that was previously loaded with .B RTLD_LOCAL -can be re-opened with +can be re-opened with .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . This flag is not specified in POSIX.1-2001. .\" (But it is present on Solaris.) .\" .TP .BR RTLD_DEEPBIND " (since glibc 2.3.4)" -.\" Inimitably described by UD in +.\" Inimitably described by UD in .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. -Place the lookup scope of the symbols in this -library ahead of the global scope. -This means that a self-contained library will use -its own symbols in preference to global symbols with the same name +Place the lookup scope of the symbols in this +library ahead of the global scope. +This means that a self-contained library will use +its own symbols in preference to global symbols with the same name contained in libraries that have already been loaded. This flag is not specified in POSIX.1-2001. .PP @@ -192,14 +194,14 @@ When given to .BR dlsym (), this handle causes a search for a symbol in the main program, followed by all shared libraries loaded at program startup, -and then all shared libraries loaded by +and then all shared libraries loaded by .BR dlopen () with the flag .BR RTLD_GLOBAL . .PP External references in the library are resolved using the libraries in that library's dependency list and any other libraries previously -opened with the +opened with the .B RTLD_GLOBAL flag. If the executable was linked with the flag "\-rdynamic" @@ -209,15 +211,18 @@ to resolve references in a dynamically loaded library. .PP If the same library is loaded again with .BR dlopen (), -the same file handle is returned. The dl library maintains reference +the same file handle is returned. +The dl library maintains reference counts for library handles, so a dynamic library is not deallocated until .BR dlclose () has been called on it as many times as .BR dlopen () -has succeeded on it. The +has succeeded on it. +The .B _init -routine, if present, is only called once. But a subsequent call with +routine, if present, is only called once. +But a subsequent call with .B RTLD_NOW may force symbol resolution for a library earlier loaded with .BR RTLD_LAZY . @@ -228,11 +233,12 @@ fails for any reason, it returns NULL. .SS "dlsym" The function .BR dlsym () -takes a "handle" of a dynamic library returned by +takes a "handle" of a dynamic library returned by .BR dlopen () and the null-terminated symbol name, returning the address where that symbol is -loaded into memory. If the symbol is not found, in the specified +loaded into memory. +If the symbol is not found, in the specified library or any of the libraries that were automatically loaded by .BR dlopen () when that library was loaded, @@ -259,9 +265,11 @@ There are two special pseudo-handles, and .BR RTLD_NEXT . The former will find the first occurrence of the desired symbol -using the default library search order. The latter +using the default library search order. +The latter will find the next occurrence of a function in the search order -after the current library. This allows one to provide a wrapper +after the current library. +This allows one to provide a wrapper around a function in another shared library. .SS "dlclose" The function @@ -283,7 +291,8 @@ If a dynamic library exports a routine named .BR _init , then that code is executed after the loading, before .BR dlopen () -returns. If the dynamic library exports a routine named +returns. +If the dynamic library exports a routine named .BR _fini , then that routine is called just before the library is unloaded. In case you need to avoid linking against the system startup files, @@ -294,7 +303,8 @@ Using these routines, or the gcc .B \-nostartfiles or .B \-nostdlib -options, is not recommended. Their use may result in undesired behavior, +options, is not recommended. +Their use may result in undesired behavior, since the constructor/destructor routines will not be executed (unless special measures are taken). .\" void _init(void) __attribute__((constructor)); @@ -304,7 +314,8 @@ Instead, libraries should export routines using the .BR __attribute__((constructor)) and .BR __attribute__((destructor)) -function attributes. See the gcc info pages for information on these. +function attributes. +See the gcc info pages for information on these. Constructor routines are executed before .BR dlopen () returns, and destructor routines are executed before @@ -325,7 +336,8 @@ Glibc adds two functions not described by POSIX, with prototypes The function .BR dladdr () takes a function pointer and tries to resolve name -and file where it is located. Information is stored in the +and file where it is located. +Information is stored in the Dl_info structure: .sp .nf @@ -355,8 +367,8 @@ Load the math library, and print the cosine of 2.0: #include #include -int -main(int argc, char **argv) +int +main(int argc, char **argv) { void *handle; double (*cosine)(double); @@ -405,26 +417,28 @@ 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 +.\" should not be modified. +.\" Some systems give the prototype as .\" .sp .\" .in +5 .\" .B "const char *dlerror(void);" .\" .in -Since glibc 2.2.3, +Since glibc 2.2.3, .BR atexit (3) -can be used to register an exit handler that is automatically +can be used to register an exit handler that is automatically called when a library is unloaded. .SH HISTORY -The dlopen interface standard comes from SunOS. That system also has -.BR dladdr (), -but not +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 (), +POSIX.1-2001 describes +.BR dlclose (), +.BR dlerror (), +.BR dlopen (), and .BR dlsym (). .SH "SEE ALSO" diff --git a/man3/dprintf.3 b/man3/dprintf.3 index 9d75da13f..e17cc6b91 100644 --- a/man3/dprintf.3 +++ b/man3/dprintf.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/drand48.3 b/man3/drand48.3 index edae9a3c3..47e7e7e6c 100644 --- a/man3/drand48.3 +++ b/man3/drand48.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -67,11 +67,12 @@ integers uniformly distributed between \-2^31 and 2^31. .PP The \fBsrand48\fP(), \fBseed48\fP() and \fBlcong48\fP() functions are initialization functions, one of which should be called before using -\fBdrand48\fP(), \fBlrand48\fP() or \fBmrand48\fP(). The functions +\fBdrand48\fP(), \fBlrand48\fP() or \fBmrand48\fP(). +The functions \fBerand48\fP(), \fBnrand48\fP() and \fBjrand48\fP() do not require an initialization function to be called first. .PP -All the functions work by generating a sequence of 48-bit integers, +All the functions work by generating a sequence of 48-bit integers, \fIXi\fP, according to the linear congruential formula: .sp .nf @@ -98,26 +99,32 @@ be returned, is copied from the high-order bits of \fIXi\fP and transformed into the returned value. .PP The functions \fBdrand48\fP(), \fBlrand48\fP() and \fBmrand48\fP() store -the last 48-bit \fIXi\fP generated in an internal buffer. The functions +the last 48-bit \fIXi\fP generated in an internal buffer. +The functions \fBerand48\fP(), \fBnrand48\fP() and \fBjrand48\fP() require the calling program to provide storage for the successive \fIXi\fP values in the array -argument \fIxsubi\fP. The functions are initialized by placing the initial +argument \fIxsubi\fP. +The functions are initialized by placing the initial value of \fIXi\fP into the array before calling the function for the first time. .PP The initializer function \fBsrand48\fP() sets the high order 32-bits of -\fIXi\fP to the argument \fIseedval\fP. The low order 16-bits are set +\fIXi\fP to the argument \fIseedval\fP. +The low order 16-bits are set to the arbitrary value 0x330E. .PP The initializer function \fBseed48\fP() sets the value of \fIXi\fP to -the 48-bit value specified in the array argument \fIseed16v\fP. The +the 48-bit value specified in the array argument \fIseed16v\fP. +The previous value of \fIXi\fP is copied into an internal buffer and a pointer to this buffer is returned by \fBseed48\fP(). .PP The initialization function \fBlcong48\fP() allows the user to specify -initial values for \fIXi\fP, \fIa\fP and \fIc\fP. Array argument +initial values for \fIXi\fP, \fIa\fP and \fIc\fP. +Array argument elements \fIparam[0-2]\fP specify \fIXi\fP, \fIparam[3-5]\fP specify -\fIa\fP, and \fIparam[6]\fP specifies \fIc\fP. After \fBlcong48\fP() +\fIa\fP, and \fIparam[6]\fP specifies \fIc\fP. +After \fBlcong48\fP() has been called, a subsequent call to either \fBsrand48\fP() or \fBseed48\fP() will restore the standard values of \fIa\fP and \fIc\fP. .SH "CONFORMING TO" diff --git a/man3/drand48_r.3 b/man3/drand48_r.3 index 9a6bd5524..68e14b07a 100644 --- a/man3/drand48_r.3 +++ b/man3/drand48_r.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -24,7 +24,7 @@ .\" .TH DRAND48_R 3 2004-10-31 "GNU" "Linux Programmer's Manual" .SH NAME -drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, +drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, srand48_r, seed48_r, lcong48_r \- generate uniformly distributed pseudo-random numbers reentrantly .SH SYNOPSIS @@ -39,7 +39,7 @@ srand48_r, seed48_r, lcong48_r .sp .BI "int lrand48_r(struct drand48_data *" buffer ", long int *" result ); .sp -.BI "int nrand48_r(unsigned short int " xsubi[3] "," +.BI "int nrand48_r(unsigned short int " xsubi[3] "," .br .BI " struct drand48_data *"buffer ", long int *" result ");" .sp @@ -51,7 +51,7 @@ srand48_r, seed48_r, lcong48_r .sp .BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");" .sp -.BI "int seed48_r(unsigned short int " seed16v[3] "," +.BI "int seed48_r(unsigned short int " seed16v[3] "," .br .BI " struct drand48_data *" buffer ");" .sp diff --git a/man3/dysize.3 b/man3/dysize.3 index dec17b887..d77c242de 100644 --- a/man3/dysize.3 +++ b/man3/dysize.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,7 +44,8 @@ also found in .SH "CONFORMING TO" This function occurs in SunOS 4.x. .SH NOTES -This is a compatibility function only. Don't use it in new programs. +This is a compatibility function only. +Don't use it in new programs. The SCO version of this function had a year-2000 problem. .SH "SEE ALSO" .BR strftime (3), diff --git a/man3/ecvt.3 b/man3/ecvt.3 index a1d0061ec..99258b877 100644 --- a/man3/ecvt.3 +++ b/man3/ecvt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,28 +42,33 @@ ecvt, fcvt \- convert a floating-point number to a string The \fBecvt\fP() function converts \fInumber\fP to a null-terminated string of \fIndigits\fP digits (where \fIndigits\fP is reduced to an system-specific limit determined by the precision of a double), -and returns a pointer to the string. The high-order digit is non-zero, -unless +and returns a pointer to the string. +The high-order digit is non-zero, unless .I number -is zero. The low order digit is rounded. +is zero. +The low order digit is rounded. The string itself does not contain a decimal point; however, the position of the decimal point relative to the start of the string -is stored in *\fIdecpt\fP. A negative value for *\fIdecpt\fP means that -the decimal point is to the left of the start of the string. If the sign of +is stored in *\fIdecpt\fP. +A negative value for *\fIdecpt\fP means that +the decimal point is to the left of the start of the string. +If the sign of \fInumber\fP is negative, *\fIsign\fP is set to a non-zero value, otherwise -it's set to 0. If +it's set to 0. +If .I number is zero, it is unspecified whether *\fIdecpt\fP is 0 or 1. .PP The \fBfcvt\fP() function is identical to \fBecvt\fP(), except that \fIndigits\fP specifies the number of digits after the decimal point. .SH "RETURN VALUE" -Both the \fBecvt\fP() and \fBfcvt\fP() functions return a pointer to a +Both the \fBecvt\fP() and \fBfcvt\fP() functions return a pointer to a static string containing the ASCII representation of \fInumber\fP. The static string is overwritten by each call to \fBecvt\fP() or \fBfcvt\fP(). .SH NOTES -These functions are obsolete. Instead, +These functions are obsolete. +Instead, .BR sprintf () is recommended. Linux libc4 and libc5 specified the type of diff --git a/man3/ecvt_r.3 b/man3/ecvt_r.3 index 524f5bbd6..fdcffbb3d 100644 --- a/man3/ecvt_r.3 +++ b/man3/ecvt_r.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -69,7 +69,8 @@ and .SH "RETURN VALUE" These functions return 0 on success, and \-1 otherwise. .SH NOTES -These functions are obsolete. Instead, +These functions are obsolete. +Instead, .BR sprintf () is recommended. .SH "CONFORMING TO" diff --git a/man3/encrypt.3 b/man3/encrypt.3 index ba5e52bda..b3c0458ad 100644 --- a/man3/encrypt.3 +++ b/man3/encrypt.3 @@ -49,31 +49,36 @@ encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages Each of these requires linking with .BR \-lcrypt . .SH DESCRIPTION -These functions encrypt and decrypt 64-bit messages. The +These functions encrypt and decrypt 64-bit messages. +The .BR setkey () function sets the key used by .BR encrypt (). The .I key parameter used here is an array of 64 bytes, each of which has -numerical value 1 or 0. The bytes key[n] where n=8*i-1 are ignored, +numerical value 1 or 0. +The bytes key[n] where n=8*i-1 are ignored, so that the effective key length is 56 bits. .PP -The -.BR encrypt () +The +.BR encrypt () function modifies the passed buffer, encoding if .I edflag -is 0, and decoding if 1 is being passed. Like the key parameter also +is 0, and decoding if 1 is being passed. +Like the key parameter also .I block is a bit vector representation of the actual value that is encoded. The result is returned in that same vector. .PP These two functions are not reentrant, that is, the key data is -kept in static storage. The functions +kept in static storage. +The functions .BR setkey_r () and .BR encrypt_r () -are the reentrant versions. They use the following +are the reentrant versions. +They use the following structure to hold the key data: .RS .nf @@ -109,17 +114,18 @@ The function is not provided. .SH EXAMPLE You need to link with libcrypt to compile this example with glibc2.2. To do useful work the key[] and txt[] arrays must be filled with a -useful bit pattern. Note that the header unconditionally -gives the prototypes for -.BR setkey () -and +useful bit pattern. +Note that the header unconditionally +gives the prototypes for +.BR setkey () +and .BR encrypt (). .sp .nf #include int -main(void) +main(void) { char key[64]; /* bit pattern for key */ char txt[64]; /* bit pattern for messages */ diff --git a/man3/envz_add.3 b/man3/envz_add.3 index 7da54cd05..c350eeb17 100644 --- a/man3/envz_add.3 +++ b/man3/envz_add.3 @@ -1,7 +1,7 @@ .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) .\" Distributed under GPL .\" based on the description in glibc source and infopages -.\" +.\" .\" Corrections and additions, aeb .TH ENVZ_ADD 3 .SH NAME @@ -40,8 +40,10 @@ An argz vector is a pointer to a character buffer together with a length, see .BR argz_add (3). An envz vector is a special argz vector, namely one where the strings -have the form "name=value". Everything after the first '=' is considered -to be the value. If there is no '=', the value is taken to be NULL. +have the form "name=value". +Everything after the first '=' is considered +to be the value. +If there is no '=', the value is taken to be NULL. (While the value in case of a trailing '=' is the empty string "".) .LP These functions are for handling envz vectors. @@ -134,6 +136,7 @@ main(int argc, char *argv[], char *envp[]) } .fi .SH "CONFORMING TO" -These functions are a GNU extension. Handle with care. +These functions are a GNU extension. +Handle with care. .SH "SEE ALSO" .BR argz (3) diff --git a/man3/erf.3 b/man3/erf.3 index 46e37c864..1aeb83030 100644 --- a/man3/erf.3 +++ b/man3/erf.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -30,7 +30,7 @@ .\" .TH ERF 3 2002-07-27 "BSD" "Linux Programmer's Manual" .SH NAME -erf, erff, erfl, erfc, erfcf, erfcl \- error function and +erf, erff, erfl, erfc, erfcf, erfcl \- error function and complementary error function .SH SYNOPSIS .nf @@ -60,7 +60,7 @@ The \fBerfc\fP() function returns the complementary error function of \fIx\fP, that is 1.0 \- erf(x). .SH "CONFORMING TO" SVr4, 4.3BSD, C99. -The +The .I float and .I "long double" diff --git a/man3/err.3 b/man3/err.3 index 33d024ad3..5d3963061 100644 --- a/man3/err.3 +++ b/man3/err.3 @@ -85,7 +85,7 @@ The .Fn verr , .Fn warn , and -.Fn vwarn +.Fn vwarn functions append an error message obtained from .Xr strerror 3 based on a code or the global variable diff --git a/man3/errno.3 b/man3/errno.3 index 07cfd9f0d..e75fb4ce7 100644 --- a/man3/errno.3 +++ b/man3/errno.3 @@ -35,7 +35,7 @@ errno \- number of last error .\".sp .\".BI "extern int " errno ; .SH DESCRIPTION -The +The .I header file defines the integer variable .BR errno , @@ -57,19 +57,20 @@ may be a macro. \fBerrno\fR is thread-local; setting it in one thread does not affect its value in any other thread. Valid error numbers are all non-zero; \fBerrno\fR is never set to zero -by any library function. All the error names specified by POSIX.1 +by any library function. +All the error names specified by POSIX.1 must have distinct values, with the exception of .B EAGAIN -and +and .BR EWOULDBLOCK , which may be the same. -.\" The following is now +.\" The following is now .\" POSIX.1 (2001 edition) lists the following symbolic error names. Of .\" these, \fBEDOM\fR and \fBERANGE\fR are in the ISO C standard. ISO C .\" Amendment 1 defines the additional error number \fBEILSEQ\fR for .\" coding errors in multibyte or wide characters. -.\" +.\" Below is a list of the symbolic error names that are defined on Linux. Some of these are marked .IR POSIX.1 , @@ -94,7 +95,7 @@ Address not available (POSIX.1) Address family not supported (POSIX.1) .TP .BR EAGAIN -Resource temporarily unavailable (may be the same value as +Resource temporarily unavailable (may be the same value as .BR EWOULDBLOCK ) (POSIX.1) .TP @@ -330,7 +331,7 @@ No space left on device (POSIX.1) .BR ENOSR No STREAM resources (POSIX.1 (XSI STREAMS option)) .TP -.BR ENOSTR +.BR ENOSTR Not a STREAM (POSIX.1 (XSI STREAMS option)) .TP .BR ENOSYS @@ -434,8 +435,8 @@ Streams pipe error Timer expired (POSIX.1 (XSI STREAMS option)) .sp -(POSIX.1 says "STREAM -.BR ioctl () +(POSIX.1 says "STREAM +.BR ioctl () timeout") .TP .BR ETIMEDOUT @@ -456,7 +457,7 @@ Too many users .TP .BR EWOULDBLOCK Operation would block (may be same value as -.BR EAGAIN ) +.BR EAGAIN ) (POSIX.1) .TP .BR EXDEV @@ -499,7 +500,7 @@ if (somecall() == \-1) { It was common in traditional C to declare .I errno manually -(i.e., +(i.e., .IR "extern int errno" ) instead of including .IR . diff --git a/man3/error.3 b/man3/error.3 index 6508760ff..7de381527 100644 --- a/man3/error.3 +++ b/man3/error.3 @@ -34,7 +34,7 @@ error_print_progname \- glibc error reporting functions \fBconst char *\fIformat, \fB...); \fBvoid error_at_line(int \fIstatus, \fBint \fIerrnum, \ -\fBconst char *\fIfilename, +\fBconst char *\fIfilename, \fBunsigned int \fIlinenum, \ \fBconst char *\fIformat, \fB...); @@ -45,35 +45,35 @@ error_print_progname \- glibc error reporting functions \fBextern void (* \fIerror_print_progname\fB) (void); .fi .SH DESCRIPTION -\fBerror\fP() is a general error reporting function. +\fBerror\fP() is a general error reporting function. It flushes .IR stdout , -and then outputs to -.I stderr -the program name, a colon and a space, the message specified by the -.BR printf (3)-style +and then outputs to +.I stderr +the program name, a colon and a space, the message specified by the +.BR printf (3)-style format string \fIformat\fP, and, if \fIerrnum\fP is non-zero, a second colon and a space followed by the string given by -\fBperror(\fIerrnum\fB)\fR. +\fBperror(\fIerrnum\fB)\fR. Any arguments required for -.I format -should follow +.I format +should follow .I format in the argument list. The output is terminated by a newline character. -The program name printed by +The program name printed by .BR error () is the value of the global variable .BR program_invocation_name (3). -.IR program_invocation_name +.IR program_invocation_name initially has the same value as .IR main ()'s .IR argv[0] . The value of this variable can be modified to change the output of .BR error (). -If \fIstatus\fP has a non-zero value, then +If \fIstatus\fP has a non-zero value, then .BR error () calls .BR exit (3) @@ -84,28 +84,28 @@ except for the addition of the arguments .I filename and .IR linenum . -The output produced is as for +The output produced is as for .BR error (), except that after the program name are written: a colon, the value of .IR filename , -a colon, and the value of +a colon, and the value of .IR linenum . The preprocessor values \fB__LINE__\fP and -\fB__FILE__\fP may be useful when calling \fBerror_at_line\fP(), +\fB__FILE__\fP may be useful when calling \fBerror_at_line\fP(), but other values can also be used. For example, these arguments could refer to a location in an input file. -If the global variable \fIerror_one_per_line\fP is set non-zero, +If the global variable \fIerror_one_per_line\fP is set non-zero, a sequence of -\fBerror_at_line\fP() calls with the +\fBerror_at_line\fP() calls with the same value of \fIfilename\fP and \fIlinenum\fP will result in only -one message (the first) being output. +one message (the first) being output. -The global variable \fIerror_message_count\fP counts the number of +The global variable \fIerror_message_count\fP counts the number of messages that have been output by \fBerror\fP() and \fBerror_at_line\fP(). -If the global variable \fIerror_print_progname\fP +If the global variable \fIerror_print_progname\fP is assigned the address of a function (i.e., is not NULL), then that function is called instead of prefixing the message with the program name and colon. diff --git a/man3/ether_aton.3 b/man3/ether_aton.3 index 486e686ea..a6d01ab9e 100644 --- a/man3/ether_aton.3 +++ b/man3/ether_aton.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -30,7 +30,7 @@ .\" .TH ETHER_ATON 3 2002-07-20 "BSD" "Linux Programmer's Manual" .SH NAME -ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, +ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines .SH SYNOPSIS .nf @@ -51,7 +51,7 @@ ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines .br .BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf ); .sp -.BI "struct ether_addr *ether_aton_r(const char *" asc , +.BI "struct ether_addr *ether_aton_r(const char *" asc , .BI " struct ether_addr *" addr ); .fi .SH DESCRIPTION @@ -68,7 +68,7 @@ The string is returned in a statically allocated buffer, which subsequent calls will overwrite. .PP The \fBether_ntohost\fP() function maps an Ethernet address to the -corresponding hostname in +corresponding hostname in .I /etc/ethers and returns non-zero if it cannot be found. .PP diff --git a/man3/exec.3 b/man3/exec.3 index f23275732..74be7162a 100644 --- a/man3/exec.3 +++ b/man3/exec.3 @@ -59,7 +59,8 @@ execl, execlp, execle, execv, execvp \- execute a file The .BR exec () family of functions replaces the current process image with a new process -image. The functions described in this manual page are front-ends for the +image. +The functions described in this manual page are front-ends for the function .BR execve (2). (See the manual page for @@ -84,7 +85,8 @@ functions can be thought of as Together they describe a list of one or more pointers to null-terminated strings that represent the argument list available to the executed program. The first argument, by convention, should point to the filename associated -with the file being executed. The list of arguments +with the file being executed. +The list of arguments .I must be terminated by a NULL pointer, and, since these are variadic functions, this pointer must be cast @@ -95,9 +97,10 @@ The and .BR execvp () functions provide an array of pointers to null-terminated strings that -represent the argument list available to the new program. The first -argument, by convention, should point to the filename associated with the -file being executed. The array of pointers +represent the argument list available to the new program. +The first argument, by convention, should point to the filename +associated with the file being executed. +The array of pointers .I must be terminated by a NULL pointer. .PP @@ -106,10 +109,11 @@ The function also specifies the environment of the executed process by following the NULL pointer that terminates the list of arguments in the parameter list or the -pointer to the argv array with an additional parameter. This additional +pointer to the argv array with an additional parameter. +This additional parameter is an array of pointers to null-terminated strings and .I must -be terminated by a NULL pointer. +be terminated by a NULL pointer. The other functions take the environment for the new process image from the external variable .I environ @@ -122,19 +126,22 @@ The functions and .BR execvp () will duplicate the actions of the shell in searching for an executable file -if the specified filename does not contain a slash (/) character. The -search path is the path specified in the environment by the +if the specified filename does not contain a slash (/) character. +The search path is the path specified in the environment by the .B PATH -variable. If this variable isn't specified, the default path -``:/bin:/usr/bin'' is used. In addition, certain +variable. +If this variable isn't specified, the default path +``:/bin:/usr/bin'' is used. +In addition, certain errors are treated specially. .PP If permission is denied for a file (the attempted .BR execve () returned .BR EACCES ), -these functions will continue searching the rest of the search path. If no -other file is found, however, they will return with the global variable +these functions will continue searching the rest of the search path. +If no other file is found, however, +they will return with the global variable .I errno set to .BR EACCES . @@ -144,11 +151,13 @@ If the header of a file isn't recognized (the attempted returned .BR ENOEXEC ), these functions will execute the shell with the path of the file as its -first argument. (If this attempt fails, no further searching is done.) +first argument. +(If this attempt fails, no further searching is done.) .SH "RETURN VALUE" If any of the .BR exec () -functions returns, an error will have occurred. The return value is \-1, +functions returns, an error will have occurred. +The return value is \-1, and the global variable .I errno will be set to indicate the error. @@ -173,7 +182,8 @@ directory listed after .I /bin and .IR /usr/bin , -as an anti-Trojan-horse measure. Linux uses here the +as an anti-Trojan-horse measure. +Linux uses here the traditional "current directory first" default path. .PP The behavior of @@ -182,8 +192,10 @@ and .BR execvp () when errors occur while attempting to execute the file is historic practice, but has not traditionally been documented and is not specified by -the POSIX standard. BSD (and possibly other systems) do an automatic -sleep and retry if ETXTBSY is encountered. Linux treats it as a hard +the POSIX standard. +BSD (and possibly other systems) do an automatic +sleep and retry if ETXTBSY is encountered. +Linux treats it as a hard error and returns immediately. .PP Traditionally, the functions @@ -194,7 +206,8 @@ ignored all errors except for the ones described above and .B ENOMEM and .BR E2BIG , -upon which they returned. They now return if any error other than the ones +upon which they returned. +They now return if any error other than the ones described above occurs. .SH "CONFORMING TO" POSIX.1-2001. diff --git a/man3/exit.3 b/man3/exit.3 index 2a7870f91..743dc7c11 100644 --- a/man3/exit.3 +++ b/man3/exit.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -63,17 +63,23 @@ calls either \fBexit\fP() or \fBlongjmp\fP(). .LP The use of EXIT_SUCCESS and EXIT_FAILURE is slightly more portable (to non-Unix environments) than that of 0 and some non-zero value -like 1 or \-1. In particular, VMS uses a different convention. +like 1 or \-1. +In particular, VMS uses a different convention. .LP BSD has attempted to standardize exit codes; see the file .IR . .LP After \fBexit\fP(), the exit status must be transmitted to the -parent process. There are three cases. If the parent has set +parent process. +There are three cases. +If the parent has set SA_NOCLDWAIT, or has set the SIGCHLD handler to SIG_IGN, the -status is discarded. If the parent was waiting on the child -it is notified of the exit status. In both cases the exiting -process dies immediately. If the parent has not indicated that +status is discarded. +If the parent was waiting on the child +it is notified of the exit status. +In both cases the exiting +process dies immediately. +If the parent has not indicated that it is not interested in the exit status, but is not waiting, the exiting process turns into a "zombie" process (which is nothing but a container for the single byte representing @@ -81,7 +87,8 @@ the exit status) so that the parent can learn the exit status when it later calls one of the \fIwait\fP() functions. .LP If the implementation supports the SIGCHLD signal, this signal -is sent to the parent. If the parent has set SA_NOCLDWAIT, +is sent to the parent. +If the parent has set SA_NOCLDWAIT, it is undefined whether a SIGCHLD signal is sent. .LP If the process is a session leader and its controlling terminal diff --git a/man3/exp.3 b/man3/exp.3 index 195d0bbf7..ead2d8e3b 100644 --- a/man3/exp.3 +++ b/man3/exp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,7 +49,7 @@ The \fBexp\fP() function returns the value of e (the base of natural logarithms) raised to the power of \fIx\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99, POSIX.1-2001. -The +The .I float and .I "long double" diff --git a/man3/exp10.3 b/man3/exp10.3 index 8c59f9ee8..1caa89197 100644 --- a/man3/exp10.3 +++ b/man3/exp10.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/exp2.3 b/man3/exp2.3 index a79c1f1d9..d2031320a 100644 --- a/man3/exp2.3 +++ b/man3/exp2.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,7 +49,7 @@ The \fBexp2\fP() function returns the value of 2 raised to the power of \fIx\fP. .SH "CONFORMING TO" SVr4, POSIX.1-2001, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/expm1.3 b/man3/expm1.3 index 2e323ac65..abfdffc23 100644 --- a/man3/expm1.3 +++ b/man3/expm1.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,7 +46,7 @@ zero\(ema case where `exp (\fIx\fP) \- 1' would be inaccurate due to subtraction of two numbers that are nearly equal. .SH "CONFORMING TO" BSD, C99. -The +The .I float and .I "long double" diff --git a/man3/fabs.3 b/man3/fabs.3 index e528b8b0f..87f3e169f 100644 --- a/man3/fabs.3 +++ b/man3/fabs.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/fclose.3 b/man3/fclose.3 index 465a9e151..a85f331f1 100644 --- a/man3/fclose.3 +++ b/man3/fclose.3 @@ -55,11 +55,13 @@ function will flush the stream pointed to by .BR fflush (3)) and close the underlying file descriptor. .SH "RETURN VALUE" -Upon successful completion 0 is returned. Otherwise, +Upon successful completion 0 is returned. +Otherwise, .B EOF is returned and the global variable .I errno -is set to indicate the error. In either case any further access +is set to indicate the error. +In either case any further access (including another call to .BR fclose ()) to the stream results in undefined behaviour. @@ -87,7 +89,8 @@ or Note that .BR fclose () only flushes the user space buffers provided by the -C library. To ensure that the data is physically stored +C library. +To ensure that the data is physically stored on disk the kernel buffers must be flushed too, e.g. with .BR sync (2) or diff --git a/man3/fcloseall.3 b/man3/fcloseall.3 index f300951de..c26e206e4 100644 --- a/man3/fcloseall.3 +++ b/man3/fcloseall.3 @@ -39,8 +39,8 @@ and are also closed. .SH "RETURN VALUE" This function returns 0 if all files were successfully closed; -on error, -.B EOF +on error, +.B EOF is returned. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/fenv.3 b/man3/fenv.3 index c3632a943..d6a9b6fdb 100644 --- a/man3/fenv.3 +++ b/man3/fenv.3 @@ -94,7 +94,8 @@ of the corresponding exception, and if so then defines the corresponding bit(s), so that one can call exception handling functions e.g. using the integer argument .BR FE_OVERFLOW | FE_UNDERFLOW . -Other exceptions may be supported. The macro +Other exceptions may be supported. +The macro .B FE_ALL_EXCEPT is the bitwise OR of all bits corresponding to supported exceptions. .PP @@ -173,7 +174,8 @@ The .BR feholdexcept () function does the same, then clears all exception flags, and sets a non-stop (continue on exceptions) mode, -if available. It returns zero when successful. +if available. +It returns zero when successful. .LP The .BR fesetenv () @@ -209,7 +211,8 @@ These functions return zero on success and non-zero if an error occurred. If possible, the GNU C Library defines a macro .B FE_NOMASK_ENV which represents an environment where every exception raised causes a -trap to occur. You can test for this macro using +trap to occur. +You can test for this macro using .BR #ifdef . It is only defined if .B _GNU_SOURCE diff --git a/man3/ferror.3 b/man3/ferror.3 index ec014fbd3..6faed8253 100644 --- a/man3/ferror.3 +++ b/man3/ferror.3 @@ -62,7 +62,8 @@ The function .BR feof () tests the end-of-file indicator for the stream pointed to by .IR stream , -returning non-zero if it is set. The end-of-file indicator can only be +returning non-zero if it is set. +The end-of-file indicator can only be cleared by the function .BR clearerr (). .PP @@ -70,8 +71,8 @@ The function .BR ferror () tests the error indicator for the stream pointed to by .IR stream , -returning non-zero if it is set. The error indicator can only be reset by -the +returning non-zero if it is set. +The error indicator can only be reset by the .BR clearerr () function. .PP diff --git a/man3/fexecve.3 b/man3/fexecve.3 index 4e1d5081a..3321ad86d 100644 --- a/man3/fexecve.3 +++ b/man3/fexecve.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,10 +33,10 @@ fexecve \- execute program specified via file descriptor .fi .SH DESCRIPTION .BR fexecve () -performs the same task as -.BR execve (2), +performs the same task as +.BR execve (2), with the difference that the file to be executed -is specified via a file descriptor, +is specified via a file descriptor, .IR fd , rather than via a pathname. .SH "RETURN VALUE" @@ -47,13 +47,13 @@ On error, the function returns, with a result value of \-1 is returned, and .I errno is set appropriately. .SH ERRORS -Errors are as for +Errors are as for .BR execve (2), with the following additions: .TP .B EINVAL .I fd -is not a valid file descriptor, or +is not a valid file descriptor, or .I argv is NULL, or .I envp diff --git a/man3/fflush.3 b/man3/fflush.3 index 39644b496..fcbe4648e 100644 --- a/man3/fflush.3 +++ b/man3/fflush.3 @@ -52,8 +52,8 @@ The function .BR fflush () forces a write of all user-space buffered data for the given output or update .I stream -via the stream's underlying write function. The open status of the stream -is unaffected. +via the stream's underlying write function. +The open status of the stream is unaffected. .PP If the .I stream @@ -66,7 +66,8 @@ open output streams. For a non-locking counterpart, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -Upon successful completion 0 is returned. Otherwise, +Upon successful completion 0 is returned. +Otherwise, .B EOF is returned and the global variable .I errno diff --git a/man3/ffs.3 b/man3/ffs.3 index 539b0dc59..2c2d7d99d 100644 --- a/man3/ffs.3 +++ b/man3/ffs.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -27,7 +27,7 @@ .\" Modified Sat Jul 24 19:39:35 1993 by Rik Faith (faith@cs.unc.edu) .\" .\" Modified 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) -.\" +.\" .TH FFS 3 2003-08-05 "GNU" "Linux Programmer's Manual" .SH NAME ffs \- find first bit set in a word diff --git a/man3/fgetgrent.3 b/man3/fgetgrent.3 index 4c21287bb..16f8ff961 100644 --- a/man3/fgetgrent.3 +++ b/man3/fgetgrent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,9 +38,10 @@ fgetgrent \- get group file entry .fi .SH DESCRIPTION The \fBfgetgrent\fP() function returns a pointer to a structure containing -the group information from the file \fIstream\fP. The first time it is called -it returns the first entry; thereafter, it returns successive entries. The -file \fIstream\fP must have the same format as \fI/etc/group\fP. +the group information from the file \fIstream\fP. +The first time it is called +it returns the first entry; thereafter, it returns successive entries. +The file \fIstream\fP must have the same format as \fI/etc/group\fP. .PP The \fIgroup\fP structure is defined in \fI\fP as follows: .sp @@ -57,7 +58,7 @@ struct group { .fi .RE .SH "RETURN VALUE" -The \fBfgetgrent\fP() function returns the group information structure, +The \fBfgetgrent\fP() function returns the group information structure, or NULL if there are no more entries or an error occurs. .SH ERRORS .TP diff --git a/man3/fgetpwent.3 b/man3/fgetpwent.3 index ed3d60123..7bb85878b 100644 --- a/man3/fgetpwent.3 +++ b/man3/fgetpwent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,9 +41,10 @@ fgetpwent \- get password file entry .fi .SH DESCRIPTION The \fBfgetpwent\fP() function returns a pointer to a structure containing -the broken out fields of a line in the file \fIstream\fP. The first time -it is called it returns the first entry; thereafter, it returns successive -entries. The file \fIstream\fP must have the same format as +the broken out fields of a line in the file \fIstream\fP. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +The file \fIstream\fP must have the same format as \fI/etc/passwd\fP. .PP The \fIpasswd\fP structure is defined in \fI\fP as follows: @@ -62,7 +63,7 @@ struct passwd { .fi .in -0.5i .SH "RETURN VALUE" -The \fBfgetpwent\fP() function returns the passwd structure, or NULL if +The \fBfgetpwent\fP() function returns the passwd structure, or NULL if there are no more entries or an error occurs. .SH ERRORS .TP diff --git a/man3/fgetwc.3 b/man3/fgetwc.3 index dbf3469ca..9c001139d 100644 --- a/man3/fgetwc.3 +++ b/man3/fgetwc.3 @@ -26,15 +26,18 @@ fgetwc, getwc \- read a wide character from a FILE stream .BI "wint_t getwc(FILE *" stream ); .fi .SH DESCRIPTION -The \fBfgetwc\fP() function is the wide-character equivalent of the \fBfgetc\fP() -function. It reads a wide character from \fIstream\fP and returns it. If -the end of stream is reached, or if \fIferror(stream)\fP becomes true, -it returns WEOF. If a wide character conversion error occurs, it sets +The \fBfgetwc\fP() function is the wide-character equivalent +of the \fBfgetc\fP() function. +It reads a wide character from \fIstream\fP and returns it. +If the end of stream is reached, or if \fIferror(stream)\fP becomes true, +it returns WEOF. +If a wide character conversion error occurs, it sets \fIerrno\fP to \fBEILSEQ\fP and returns WEOF. .PP The \fBgetwc\fP() function or macro functions identically to \fBfgetwc\fP(). It may be implemented as a macro, and may evaluate its argument -more than once. There is no reason ever to use it. +more than once. +There is no reason ever to use it. .PP For non-locking counterparts, see .BR unlocked_stdio (3). @@ -53,10 +56,10 @@ C99, POSIX.1-2001. The behaviour of \fBfgetwc\fP() depends on the LC_CTYPE category of the current locale. .PP -In the absence of additional information passed to the +In the absence of additional information passed to the .BR fopen () call, it is -reasonable to expect that \fBfgetwc\fP() +reasonable to expect that \fBfgetwc\fP() will actually read a multibyte sequence from the stream and then convert it to a wide character. .SH "SEE ALSO" diff --git a/man3/fgetws.3 b/man3/fgetws.3 index 299cd92ea..a5d4bc434 100644 --- a/man3/fgetws.3 +++ b/man3/fgetws.3 @@ -22,11 +22,14 @@ fgetws \- read a wide character string from a FILE stream .BI "wchar_t *fgetws(wchar_t *" ws ", int " n ", FILE *" stream ); .fi .SH DESCRIPTION -The \fBfgetws\fP() function is the wide-character equivalent of the \fBfgets\fP() -function. It reads a string of at most \fIn-1\fP wide characters into the +The \fBfgetws\fP() function is the wide-character equivalent +of the \fBfgets\fP() function. +It reads a string of at most \fIn-1\fP wide characters into the wide-character array pointed to by \fIws\fP, and adds a terminating L'\\0' -character. It stops reading wide characters after it has encountered and -stored a newline wide character. It also stops when end of stream is reached. +character. +It stops reading wide characters after it has encountered and +stored a newline wide character. +It also stops when end of stream is reached. .PP The programmer must ensure that there is room for at least \fIn\fP wide characters at \fIws\fP. @@ -34,7 +37,8 @@ characters at \fIws\fP. For a non-locking counterpart, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -The \fBfgetws\fP() function, if successful, returns \fIws\fP. If end of stream +The \fBfgetws\fP() function, if successful, returns \fIws\fP. +If end of stream was already reached or if an error occurred, it returns NULL. .SH "CONFORMING TO" C99, POSIX.1-2001. @@ -42,7 +46,7 @@ C99, POSIX.1-2001. The behaviour of \fBfgetws\fP() depends on the LC_CTYPE category of the current locale. .PP -In the absence of additional information passed to the +In the absence of additional information passed to the .BR fopen () call, it is reasonable to expect that \fBfgetws\fP() will actually read a multibyte string diff --git a/man3/finite.3 b/man3/finite.3 index 208ee3cbf..8ae016dce 100644 --- a/man3/finite.3 +++ b/man3/finite.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -64,7 +64,8 @@ The functions return 1 if \fIx\fP is plus infinity, \-1 is \fIx\fP is minus infinity, and 0 otherwise. .SH NOTE -Note that these functions are obsolete. C99 defines macros +Note that these functions are obsolete. +C99 defines macros isfinite(), isinf() and isnan() (for all types) replacing them. Further note that the C99 isinf() has weaker guarantees on the return value. See diff --git a/man3/flockfile.3 b/man3/flockfile.3 index 9e63b6858..2e2506b5d 100644 --- a/man3/flockfile.3 +++ b/man3/flockfile.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,7 +34,8 @@ flockfile, ftrylockfile, funlockfile \- lock FILE for stdio .BI "void funlockfile(FILE *" filehandle ); .fi .SH DESCRIPTION -The stdio functions are thread-safe. This is achieved by assigning +The stdio functions are thread-safe. +This is achieved by assigning to each FILE object a lockcount and (if the lockcount is non-zero) an owning thread. For each library call, these functions wait until the FILE object @@ -48,15 +49,18 @@ and .BR lockf (3).) .LP All this is invisible to the C-programmer, but there may be two -reasons to wish for more detailed control. On the one hand, maybe +reasons to wish for more detailed control. +On the one hand, maybe a series of I/O actions by one thread belongs together, and should not be interrupted by the I/O of some other thread. On the other hand, maybe the locking overhead should be avoided for greater efficiency. .LP To this end, a thread can explicitly lock the FILE object, -then do its series of I/O actions, then unlock. This prevents -other threads from coming in between. If the reason for doing +then do its series of I/O actions, then unlock. +This prevents +other threads from coming in between. +If the reason for doing this was to achieve greater efficiency, one does the I/O with the non-locking versions of the stdio functions: with \fIgetc_unlocked\fP() and \fIputc_unlocked\fP() instead of @@ -70,7 +74,8 @@ the lockcount. The \fBfunlockfile\fP() function decrements the lock count. .LP The \fBftrylockfile\fP() function is a non-blocking version -of \fBflockfile\fP(). It does nothing in case some other thread +of \fBflockfile\fP(). +It does nothing in case some other thread owns *\fIfilehandle\fP, and it obtains ownership and increments the lockcount otherwise. .SH "RETURN VALUE" @@ -80,7 +85,8 @@ The \fBftrylockfile\fP() function returns zero for success None. .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 +is defined. +They are in libc since libc 5.1.1 and in glibc since glibc 2.0. .SH "CONFORMING TO" POSIX.1-2001. diff --git a/man3/floor.3 b/man3/floor.3 index 1520b840e..9b9fefac2 100644 --- a/man3/floor.3 +++ b/man3/floor.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,8 @@ Link with \-lm. .SH DESCRIPTION These functions round \fIx\fP down to the nearest integer. .SH "RETURN VALUE" -The rounded integer value. If \fIx\fP is integral or infinite, +The rounded integer value. +If \fIx\fP is integral or infinite, \fIx\fP itself is returned. .SH ERRORS No errors other than EDOM and ERANGE can occur. diff --git a/man3/fma.3 b/man3/fma.3 index 239be66ec..671e6f177 100644 --- a/man3/fma.3 +++ b/man3/fma.3 @@ -19,7 +19,7 @@ fma, fmaf, fmal \- floating-point multiply and add .sp Compile with \-std=c99; link with \-lm. .SH DESCRIPTION -The +The .BR fma () function computes .IR x " * " y " + " z . diff --git a/man3/fmax.3 b/man3/fmax.3 index f85bf2825..98989e489 100644 --- a/man3/fmax.3 +++ b/man3/fmax.3 @@ -3,7 +3,7 @@ .\" .TH FMAX 3 2002-07-28 "" "math routines" .SH NAME -fmax, fmaxf, fmaxl \- find maximum value +fmax, fmaxf, fmaxl \- find maximum value .SH SYNOPSIS .B #include .sp diff --git a/man3/fmemopen.3 b/man3/fmemopen.3 index d28aaaeb8..acc6ec790 100644 --- a/man3/fmemopen.3 +++ b/man3/fmemopen.3 @@ -19,9 +19,9 @@ The .BR fmemopen () function opens a stream that permits the access specified by .IR mode . -The stream allows I/O to be performed on the string or memory buffer +The stream allows I/O to be performed on the string or memory buffer pointed to by -.IR buf . +.IR buf . This buffer must be at least .I size bytes long. @@ -32,55 +32,55 @@ is the same as for .BR fopen (3) . If .I mode -specifies an append mode, then the initial file position is set to +specifies an append mode, then the initial file position is set to location of the first null byte ('\\0') in the buffer; otherwise the initial file position is set to the start of the buffer. .PP -When a stream that has been opened for writing is flushed +When a stream that has been opened for writing is flushed .RB ( fflush (3)) or closed .RB ( fclose (3)), a null byte is written at the end of the buffer if there is space. -The caller should ensure that an extra byte is available in the +The caller should ensure that an extra byte is available in the buffer (and that .IR size counts that byte) -to allow for this. +to allow for this. Attempts to write more than .I size bytes to the buffer result in an error. -(By default, such errors will only be visible when the +(By default, such errors will only be visible when the .I stdio buffer is flushed. -Disabling buffering with +Disabling buffering with .I setbuf(fp,\ NULL) may be useful to detect errors at the time of an output operation. -Alternatively, the caller can explicitly set +Alternatively, the caller can explicitly set .I buf as the stdio stream buffer, at the same time informing stdio -of the buffer's size, using +of the buffer's size, using .IR "setbuffer(fp, buf, size)" .) .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995 .\" and .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html .PP -In a stream opened for reading, -null bytes ('\\0') in the buffer do not cause read +In a stream opened for reading, +null bytes ('\\0') in the buffer do not cause read operations to return an end-of-file indication. A read from the buffer will only indicate end-of-file -when the file pointer advances +when the file pointer advances .I size bytes past the start of the buffer. .PP -If -.I buf +If +.I buf is specified as NULL, then .BR fmemopen () dynamically allocates a buffer .I size -bytes long. +bytes long. This is useful for an application that wants to write data to a temporary buffer and then read it back again. The buffer is automatically freed when the stream is closed. @@ -91,58 +91,58 @@ below). The .BR open_memstream () -opens a stream for writing to a buffer. +opens a stream for writing to a buffer. The buffer -is dynamically allocated (as with +is dynamically allocated (as with .BR malloc (3)), and automatically grows as required. After closing the stream, the caller should .BR free (3) this buffer. -When the stream is closed +When the stream is closed .RB ( fclose (3)) -or flushed +or flushed .RB ( fflush (3)), the locations pointed to by -.I ptr -and +.I ptr +and .I sizeloc are updated to contain, respectively, a pointer to the buffer and the -current size of the buffer. -These values remain valid only as long as the caller -performs no further output on the stream. -If further output is performed, then the stream +current size of the buffer. +These values remain valid only as long as the caller +performs no further output on the stream. +If further output is performed, then the stream must again be flushed before trying to access these variables. -A null byte is maintained at the end of the buffer. -This byte is -.I not -included in the size value stored at +A null byte is maintained at the end of the buffer. +This byte is +.I not +included in the size value stored at .IR sizeloc . -.\" +.\" .\" FIXME The glibc info doc has text like the following, but it appears .\" not to be true: http://sourceware.org/bugzilla/show_bug.cgi?id=1996 .\" The stream's file position can be changed with -.\" .BR fseek (3) -.\" or +.\" .BR fseek (3) +.\" or .\" .BR fseeko (3). .\" Moving the file position past the end .\" of the data already written fills the intervening space with .\" zeroes. .SH "RETURN VALUE" -Upon successful completion -.BR fmemopen () +Upon successful completion +.BR fmemopen () and .BR open_memstream () return a -.B FILE -pointer. +.B FILE +pointer. Otherwise, NULL is returned and the global variable -.I errno +.I errno is set to indicate the error. .SH "EXAMPLE" -The program below uses +The program below uses .BR fmemopen () to open an input buffer, and .BR open_memstream () @@ -162,7 +162,7 @@ size=11; ptr=1 529 1849 #include #include -int +int main(int argc, char *argv[]) { FILE *out, *in; diff --git a/man3/fmod.3 b/man3/fmod.3 index 5f6f15836..670b5aee1 100644 --- a/man3/fmod.3 +++ b/man3/fmod.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -56,7 +56,7 @@ when the function fails and \fIerrno\fP is set. The denominator \fIy\fP is zero. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/fmtmsg.3 b/man3/fmtmsg.3 index 312ae556c..b5a447b7f 100644 --- a/man3/fmtmsg.3 +++ b/man3/fmtmsg.3 @@ -1,7 +1,7 @@ .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) .\" Distributed under GPL .\" adapted glibc info page -.\" +.\" .\" This should run as 'Guru Meditation' (amiga joke :) .\" The function is quite complex an deserves an example .\" @@ -23,7 +23,8 @@ fmtmsg \- print formatted error messages This function displays a message described by its parameters on the device(s) specified in the .I classification -parameter. For messages written to +parameter. +For messages written to .IR stderr , the format depends on the .B MSGVERB @@ -31,9 +32,10 @@ environment variable. .LP The .I label -parameter identifies the source of the message. The string must consist +parameter identifies the source of the message. +The string must consist of two colon separated parts where the first part has not more -than 10 and the second part not more than 14 characters. +than 10 and the second part not more than 14 characters. .LP The .I text @@ -47,11 +49,13 @@ If it is printed, it is prefixed by "TO FIX: ". The .I tag parameter is a reference to the online documentation where more -information can be found. It should contain the +information can be found. +It should contain the .I label value and a unique identification number. .SS "Dummy parameters" -Each of the parameters can have a dummy value. The dummy classification value +Each of the parameters can have a dummy value. +The dummy classification value .B MM_NULLMC (0L) does not specify any output, so nothing is printed. The dummy severity value @@ -67,10 +71,10 @@ are synonyms for ((char *) 0), the empty string, and is a synonym for .BR NO_SEV . .SS "The classification parameter" -The -.I classification +The +.I classification parameter is the sum of values describing 4 types of information. -.br +.br .sp The first value defines the output channel. .TP 12n @@ -114,8 +118,8 @@ It is a recoverable error. .B MM_NRECOV It is a non-recoverable error. .SS "The severity parameter" -The -.I severity +The +.I severity parameter can take one of the following values: .TP 12n .B MM_NOSEV @@ -133,13 +137,14 @@ This value is printed as WARNING. .B MM_INFO This value is printed as INFO. .PP -The numeric values are between 0 and 4. Using +The numeric values are between 0 and 4. +Using .BR addseverity () or the environment variable .B SEV_LEVEL you can add more levels and strings to print. .SH ENVIRONMENT -The environment variable +The environment variable .B MSGVERB ("message verbosity") can be used to suppress parts of the output to @@ -154,10 +159,11 @@ The environment variable .B SEV_LEVEL can be used to introduce new severity levels. By default, only the five severity levels described -above are available. Any other numeric value would make -.BR fmtmsg () +above are available. +Any other numeric value would make +.BR fmtmsg () print nothing. -If the user puts +If the user puts .B SEV_LEVEL with a format like .sp @@ -165,7 +171,7 @@ with a format like SEV_LEVEL=[description[:description[:...]]] .RE .sp -in the environment of the process before the first call to +in the environment of the process before the first call to .BR fmtmsg (), where each description is of the form .sp @@ -181,13 +187,15 @@ such a level occurs. .LP The severity-keyword part is not used by .BR fmtmsg () -but it has to be present. -The level part is a string representation of a number. +but it has to be present. +The level part is a string representation of a number. The numeric value must be a number greater than 4. -This value must be used in the severity parameter of +This value must be used in the severity parameter of .BR fmtmsg () -to select this class. It is not possible to overwrite -any of the predefined classes. The printstring +to select this class. +It is not possible to overwrite +any of the predefined classes. +The printstring is the string printed when a message of this class is processed by .BR fmtmsg (). .SH "RETURN VALUES" @@ -229,13 +237,13 @@ vpfmt(), lfmt(), and vlfmt()", and will be removed later. #include #include -int -main(void) +int +main(void) { long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; int err; err = fmtmsg(class, "util-linux:mount", MM_ERROR, - "unknown mount option", "See mount(8).", + "unknown mount option", "See mount(8).", "util-linux:mount:017"); switch(err) { case MM_OK: diff --git a/man3/fnmatch.3 b/man3/fnmatch.3 index deb723890..36a1f1c34 100644 --- a/man3/fnmatch.3 +++ b/man3/fnmatch.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -55,7 +55,7 @@ If this flag is set, match a slash in .I string only with a slash in .I pattern -and not by an asterisk (*) or a question mark (?) metacharacter, +and not by an asterisk (*) or a question mark (?) metacharacter, nor by a bracket expression ([]) containing a slash. .TP .B FNM_PERIOD @@ -66,7 +66,7 @@ has to be matched exactly by a period in A period is considered to be leading if it is the first character in .IR string , or if both -.B FNM_PATHNAME +.B FNM_PATHNAME is set and the period immediately follows a slash. .TP .B FNM_FILE_NAME @@ -76,7 +76,8 @@ This is a GNU synonym for \fBFNM_PATHNAME\fR. If this flag (a GNU extension) is set, the pattern is considered to be matched if it matches an initial segment of .I string -which is followed by a slash. This flag is mainly for the internal +which is followed by a slash. +This flag is mainly for the internal use of glibc and is only implemented in certain cases. .TP .B FNM_CASEFOLD @@ -90,7 +91,7 @@ matches .B FNM_NOMATCH if there is no match or another non-zero value if there is an error. .SH "CONFORMING TO" -POSIX.2. +POSIX.2. The .BR FNM_FILE_NAME ", " FNM_LEADING_DIR ", and " FNM_CASEFOLD flags are GNU extensions. diff --git a/man3/fopen.3 b/man3/fopen.3 index a82ecc1ed..6a08e9dc5 100644 --- a/man3/fopen.3 +++ b/man3/fopen.3 @@ -63,29 +63,31 @@ points to a string beginning with one of the following sequences (Additional characters may follow these sequences.): .TP .B r -Open text file for reading. The stream is positioned at the beginning of -the file. +Open text file for reading. +The stream is positioned at the beginning of the file. .TP .B r+ -Open for reading and writing. The stream is positioned at the beginning of -the file. +Open for reading and writing. +The stream is positioned at the beginning of the file. .TP .B w -Truncate file to zero length or create text file for writing. The stream -is positioned at the beginning of the file. +Truncate file to zero length or create text file for writing. +The stream is positioned at the beginning of the file. .TP .B w+ -Open for reading and writing. The file is created if it does not exist, -otherwise it is truncated. The stream is positioned at the beginning of +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +The stream is positioned at the beginning of the file. .TP .B a -Open for appending (writing at end of file). The file is created -if it does not exist. The stream is positioned at the end of the file. +Open for appending (writing at end of file). +The file is created if it does not exist. +The stream is positioned at the end of the file. .TP .B a+ -Open for reading and appending (writing at end of file). The file -is created if it does not exist. +Open for reading and appending (writing at end of file). +The file is created if it does not exist. The initial file position for reading is at the beginning of the file, but output is always appended to the end of the file. .PP @@ -93,7 +95,8 @@ The .I mode string can also include the letter ``b'' either as a last character or as a character between the characters in any of the two-character strings -described above. This is strictly for compatibility with C89 +described above. +This is strictly for compatibility with C89 and has no effect; the ``b'' is ignored on all POSIX conforming systems, including Linux. (Other systems may treat text files and binary files differently, @@ -116,8 +119,8 @@ under Linux) to put an .BR fseek () or .BR fgetpos () -operation between write and read operations on such a stream. This -operation may be an apparent no-op (as in \fIfseek(..., 0L, +operation between write and read operations on such a stream. +This operation may be an apparent no-op (as in \fIfseek(..., 0L, SEEK_CUR)\fR called for its synchronizing side effect. .PP Opening a file in append mode (\fBa\fR as the first character of @@ -156,11 +159,14 @@ function opens the file whose name is the string pointed to by .I path and associates the stream pointed to by .I stream -with it. The original stream (if it exists) is closed. The +with it. +The original stream (if it exists) is closed. +The .I mode argument is used just as in the .BR fopen () -function. The primary use of the +function. +The primary use of the .BR freopen () function is to change the file associated with a standard text stream .IR "" ( stderr ", " stdin ", or " stdout ). @@ -172,7 +178,7 @@ and .BR freopen () return a .I FILE -pointer. +pointer. Otherwise, NULL is returned and the global variable .I errno is set to indicate the error. @@ -226,7 +232,7 @@ The .BR fopen () and .BR freopen () -functions conform to C89. +functions conform to C89. The .BR fdopen () function conforms to POSIX.1-1990. @@ -235,17 +241,17 @@ The GNU C library allows the following extensions for the string specified in .IR mode : .TP .BR c " (since glibc 2.3.3)" -Do not make the open operation, +Do not make the open operation, or subsequent read and write operations, thread cancellation points. .TP .BR m " (since glibc 2.3)" -Attempt to access the file using +Attempt to access the file using .BR mmap (2), -rather than I/O system calls +rather than I/O system calls .RB ( read (2), .BR write (2)). -Currently, +Currently, .\" As at glibc 2.4: use of .BR mmap (2) @@ -254,7 +260,7 @@ is only attempted for a file opened for reading. .B x .\" Since glibc 2.0? Open the file exclusively -(like the +(like the .B O_EXCL flag of .BR open (2)). diff --git a/man3/fpathconf.3 b/man3/fpathconf.3 index 5c0807c75..569929ca9 100644 --- a/man3/fpathconf.3 +++ b/man3/fpathconf.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -60,7 +60,8 @@ equal to one of the following constants returns the following configuration options: .TP .B _PC_LINK_MAX -returns the maximum number of links to the file. If +returns the maximum number of links to the file. +If .I filedes or .I path @@ -100,7 +101,8 @@ returns the maximum length of a relative pathname when .I path or .I filedes -is the current working directory. The corresponding macro is +is the current working directory. +The corresponding macro is .BR _POSIX_PATH_MAX . .TP .B _PC_PIPE_BUF @@ -114,18 +116,21 @@ must refer to a FIFO. The corresponding macro is .B _PC_CHOWN_RESTRICTED returns non-zero if the .BR chown (2) -call may not be used on this file. If +call may not be used on this file. +If .I filedes or .I path refer to a directory, then this applies to all files in that -directory. The corresponding macro is +directory. +The corresponding macro is .BR _POSIX_CHOWN_RESTRICTED . .TP .B _PC_NO_TRUNC returns non-zero if accessing filenames longer than .B _POSIX_NAME_MAX -generates an error. The corresponding macro is +generates an error. +The corresponding macro is .BR _POSIX_NO_TRUNC . .TP .B _PC_VDISABLE @@ -135,10 +140,12 @@ or .I path must refer to a terminal. .SH "RETURN VALUE" -The limit is returned, if one exists. If the system does not have a +The limit is returned, if one exists. +If the system does not have a limit for the requested resource, \-1 is returned, and .I errno -is unchanged. If there is an error, \-1 is returned, and +is unchanged. +If there is an error, \-1 is returned, and .I errno is set to reflect the nature of the error. .SH "CONFORMING TO" diff --git a/man3/fpclassify.3 b/man3/fpclassify.3 index 1bf991c75..2a1e8221e 100644 --- a/man3/fpclassify.3 +++ b/man3/fpclassify.3 @@ -25,11 +25,11 @@ Compile with \-std=c99; link with \-lm. .SH DESCRIPTION Floating point numbers can have special values, such as infinite or NaN. With the macro -.BI fpclassify( x ) +.BI fpclassify( x ) you can find out what type .I x is. The macro takes any floating-point expression as argument. -The result is one of the following values: +The result is one of the following values: .TP FP_NAN .I x @@ -38,7 +38,7 @@ is "Not a Number". FP_INFINITE .I x is either plus or minus infinity. -.TP +.TP FP_ZERO .I x is zero. diff --git a/man3/fpurge.3 b/man3/fpurge.3 index fb6ea3f5b..5a94cc5ff 100644 --- a/man3/fpurge.3 +++ b/man3/fpurge.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/fputwc.3 b/man3/fputwc.3 index 67b658611..37c31dff2 100644 --- a/man3/fputwc.3 +++ b/man3/fputwc.3 @@ -25,14 +25,18 @@ fputwc \- write a wide character to a FILE stream .fi .SH DESCRIPTION The \fBfputwc\fP() function is the wide-character equivalent of the \fBfputc\fP() -function. It writes the wide character \fIwc\fP to \fIstream\fP. If -\fIferror(stream)\fP becomes true, it returns WEOF. If a wide character +function. +It writes the wide character \fIwc\fP to \fIstream\fP. +If +\fIferror(stream)\fP becomes true, it returns WEOF. +If a wide character conversion error occurs, it sets \fIerrno\fP to \fBEILSEQ\fP and returns WEOF. Otherwise it returns \fIwc\fP. .PP The \fBputwc\fP() function or macro functions identically to \fBfputwc\fP(). It may be implemented as a macro, and may evaluate its argument -more than once. There is no reason ever to use it. +more than once. +There is no reason ever to use it. .PP For non-locking counterparts, see .BR unlocked_stdio (3). @@ -50,7 +54,7 @@ C99, POSIX.1-2001. The behaviour of \fBfputwc\fP() depends on the LC_CTYPE category of the current locale. .PP -In the absence of additional information passed to the +In the absence of additional information passed to the .BR fopen () call, it is reasonable to expect that \fBfputwc\fP() will actually write the multibyte diff --git a/man3/fputws.3 b/man3/fputws.3 index 2c66e357f..1363f80b7 100644 --- a/man3/fputws.3 +++ b/man3/fputws.3 @@ -21,8 +21,9 @@ fputws \- write a wide character string to a FILE stream .BI "int fputws(const wchar_t *" ws ", FILE *" stream ); .fi .SH DESCRIPTION -The \fBfputws\fP() function is the wide-character equivalent of the \fBfputs\fP() -function. It writes the wide character string starting at \fIws\fP, up to but +The \fBfputws\fP() function is the wide-character equivalent of +the \fBfputs\fP() function. +It writes the wide character string starting at \fIws\fP, up to but not including the terminating L'\\0' character, to \fIstream\fP. .PP For a non-locking counterpart, see @@ -36,7 +37,7 @@ C99, POSIX.1-2001. The behaviour of \fBfputws\fP() depends on the LC_CTYPE category of the current locale. .PP -In the absence of additional information passed to the +In the absence of additional information passed to the .BR fopen () call, it is reasonable to expect that \fBfputws\fP() will actually write the multibyte diff --git a/man3/fread.3 b/man3/fread.3 index cd044ee06..f45e9d20e 100644 --- a/man3/fread.3 +++ b/man3/fread.3 @@ -83,7 +83,8 @@ For non-locking counterparts, see and .BR fwrite () return the number of items successfully read or written (i.e., not the -number of characters). If an error occurs, or the end-of-file is +number of characters). +If an error occurs, or the end-of-file is reached, the return value is a short item count (or zero). .PP .BR fread () diff --git a/man3/frexp.3 b/man3/frexp.3 index 72a2730db..65964e2e0 100644 --- a/man3/frexp.3 +++ b/man3/frexp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,15 +48,16 @@ Link with \-lm. The \fBfrexp\fP() function is used to split the number \fIx\fP into a normalized fraction and an exponent which is stored in \fIexp\fP. .SH "RETURN VALUE" -The \fBfrexp\fP() function returns the normalized fraction. -If the argument \fIx\fP is not zero, -the normalized fraction is \fIx\fP times a power of two, +The \fBfrexp\fP() function returns the normalized fraction. +If the argument \fIx\fP is not zero, +the normalized fraction is \fIx\fP times a power of two, and its absolute value is always in the range 1/2 (inclusive) to -1 (exclusive). If \fIx\fP is zero, then the normalized fraction is +1 (exclusive). +If \fIx\fP is zero, then the normalized fraction is zero and zero is stored in \fIexp\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/fseek.3 b/man3/fseek.3 index 2ef26539b..9800b80ee 100644 --- a/man3/fseek.3 +++ b/man3/fseek.3 @@ -69,7 +69,8 @@ is set to or .BR SEEK_END , the offset is relative to the start of the file, the current position -indicator, or end-of-file, respectively. A successful call to the +indicator, or end-of-file, respectively. +A successful call to the .BR fseek () function clears the end-of-file indicator for the stream and undoes any effects of the @@ -86,7 +87,8 @@ The .BR rewind () function sets the file position indicator for the stream pointed to by .I stream -to the beginning of the file. It is equivalent to: +to the beginning of the file. +It is equivalent to: .PP .RS (void)fseek(stream, 0L, SEEK_SET) @@ -115,15 +117,17 @@ portably reposition a text stream. .SH "RETURN VALUE" The .BR rewind () -function returns no value. Upon successful completion, +function returns no value. +Upon successful completion, .BR fgetpos (), .BR fseek (), .BR fsetpos () return 0, and .BR ftell () -returns the current offset. Otherwise, \-1 is returned and -.I errno +returns the current offset. +Otherwise, \-1 is returned and +.I errno is set to indicate the error. .SH ERRORS .TP @@ -135,7 +139,7 @@ specified is not a seekable stream. .B EINVAL The .I whence -argument to +argument to .BR fseek () was not .BR SEEK_SET , @@ -147,7 +151,7 @@ The functions .BR fgetpos (), .BR fseek (), .BR fsetpos (), -and +and .BR ftell () may also fail and set .I errno @@ -155,7 +159,7 @@ for any of the errors specified for the routines .BR fflush (3), .BR fstat (2), .BR lseek (2), -and +and .BR malloc (3). .SH "CONFORMING TO" C89, C99. diff --git a/man3/fseeko.3 b/man3/fseeko.3 index 98d52b0f5..94845f97f 100644 --- a/man3/fseeko.3 +++ b/man3/fseeko.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -30,7 +30,7 @@ fseeko, ftello \- seek to or report file position .BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence ); .sp .BI "off_t ftello(FILE *" stream ); -.BI +.BI .fi .SH DESCRIPTION The \fBfseeko\fP() and \fBftello\fP() functions are identical to @@ -54,7 +54,7 @@ On successful completion, returns 0, while .BR ftello () returns the current offset. -Otherwise, \-1 is returned and +Otherwise, \-1 is returned and .I errno is set to indicate the error. .SH ERRORS @@ -62,7 +62,7 @@ See the ERRORS in .BR fseek (3). .SH NOTES These functions are found on System V-like systems. -They are not present in libc4, libc5, glibc 2.0 +They are not present in libc4, libc5, glibc 2.0 but are available since glibc 2.1. .SH "CONFORMING TO" SUSv2, POSIX.1-2001. diff --git a/man3/ftime.3 b/man3/ftime.3 index cd6f3d557..e6e8e4063 100644 --- a/man3/ftime.3 +++ b/man3/ftime.3 @@ -62,7 +62,9 @@ fields are undefined. .SH "RETURN VALUE" This function always returns 0. .SH BUGS -This function is obsolete. Don't use it. If the time in seconds +This function is obsolete. +Don't use it. +If the time in seconds suffices, .BR time (2) can be used; diff --git a/man3/ftok.3 b/man3/ftok.3 index 4410917cb..a8b18f0fd 100644 --- a/man3/ftok.3 +++ b/man3/ftok.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -24,7 +24,7 @@ .\" Changed data type of proj_id; minor fixes .\" aeb: further fixes; added notes. .\" -.TH FTOK 3 2001-11-28 "Linux 2.4" "Linux Programmer's Manual" +.TH FTOK 3 2001-11-28 "Linux 2.4" "Linux Programmer's Manual" .SH NAME ftok \- convert a pathname and a project identifier to a System V IPC key .SH SYNOPSIS @@ -55,12 +55,14 @@ or The resulting value is the same for all pathnames that name the same file, when the same value of .I proj_id -is used. The value returned should be different when the +is used. +The value returned should be different when the (simultaneously existing) files or the project IDs differ. .SH "RETURN VALUE" On success the generated .B key_t -value is returned. On failure \-1 is returned, with +value is returned. +On failure \-1 is returned, with .I errno indicating the error as for the .BR stat (2) @@ -76,7 +78,8 @@ Today .I proj_id is an .IR int , -but still only 8 bits are used. Typical usage has an ASCII character +but still only 8 bits are used. +Typical usage has an ASCII character .IR proj_id , that is why the behaviour is said to be undefined when .I proj_id @@ -84,7 +87,8 @@ is zero. .LP Of course no guarantee can be given that the resulting .B key_t -is unique. Typically, a best effort attempt combines the given +is unique. +Typically, a best effort attempt combines the given .I proj_id byte, the lower 16 bits of the i\-node number, and the lower 8 bits of the device number into a 32\-bit result. diff --git a/man3/fts.3 b/man3/fts.3 index b2cf728cb..f87767b9c 100644 --- a/man3/fts.3 +++ b/man3/fts.3 @@ -42,7 +42,7 @@ .Nm fts_read , .Nm fts_children , .Nm fts_set , -.Nm fts_close +.Nm fts_close .Nd traverse a file hierarchy .Sh SYNOPSIS .Fd #include @@ -244,7 +244,7 @@ or .Fn fts_read functions, with its .Fa fts_info -field set to +field set to .Dv FTS_DNR , .Dv FTS_ERR or @@ -476,7 +476,7 @@ fields of the structures may .Em never be used in this comparison. -If the +If the .Fa fts_info field is set to .Dv FTS_NS diff --git a/man3/ftw.3 b/man3/ftw.3 index 5896bf74b..54c72b17d 100644 --- a/man3/ftw.3 +++ b/man3/ftw.3 @@ -25,7 +25,7 @@ .\" .\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) .\" 2006-05-24, Justin Pryzby -.\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE"; +.\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE"; .\" 2006-05-24, Justin Pryzby and .\" Michael Kerrisk .\" reorganized and rewrote much of the page @@ -38,35 +38,35 @@ ftw, nftw \- file tree walk .nf .B #include .sp -.BI "int ftw(const char *" dirpath , -.BR " int (*" fn ") (const char *" fpath ", const struct stat *" sb , +.BI "int ftw(const char *" dirpath , +.BR " int (*" fn ") (const char *" fpath ", const struct stat *" sb , .BI " int " typeflag ), .BI " int " nopenfd ); .sp .B #define _XOPEN_SOURCE 500 .B #include .sp -.BI "int nftw(const char *" dirpath , -.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , +.BI "int nftw(const char *" dirpath , +.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , .BI " int " typeflag ", struct FTW *" ftwbuf ), .BI " int " nopenfd ", int " flags ); .fi .SH DESCRIPTION -\fBftw\fP() walks through the directory tree that is +\fBftw\fP() walks through the directory tree that is located under the directory \fIdirpath\fP, and calls \fIfn\fP() once for each entry in the tree. -By default, directories are handled before the files and +By default, directories are handled before the files and subdirectories they contain (pre-order traversal). -To avoid using up all of the calling process's file descriptors, -\fInopenfd\fP specifies the maximum number of directories that -\fBftw\fP() will hold open simultaneously. +To avoid using up all of the calling process's file descriptors, +\fInopenfd\fP specifies the maximum number of directories that +\fBftw\fP() will hold open simultaneously. When the search depth exceeds this, \fBftw\fP() will become slower because directories have to be closed and reopened. \fBftw\fP() uses at most one file descriptor for each level in the directory tree. -For each entry found in the tree, +For each entry found in the tree, .BR ftw () calls \fIfn\fP() with three arguments: @@ -74,17 +74,17 @@ calls .IR sb , and .IR typeflag . -.IR fpath +.IR fpath is the pathname of the entry relative to .IR dirpath . -.IR sb +.IR sb is a pointer to the -.IR stat -structure returned by a call to -.BR stat (2) -for +.IR stat +structure returned by a call to +.BR stat (2) +for .IR fpath . -.IR typeflag +.IR typeflag is an integer that has one of the following values: .TP .B FTW_F @@ -100,15 +100,15 @@ is a directory. is a directory which can't be read. .TP .B FTW_NS -The -.BR stat (2) -call failed on +The +.BR stat (2) +call failed on .IR fpath , which is not a symbolic link. .sp -If +If .I fpath -is a symbolic link and +is a symbolic link and .BR stat (2) failed, POSIX.1-2001 states that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below) @@ -116,16 +116,16 @@ is passed in .IR typeflag . .PP To stop the tree walk, \fIfn\fP() returns a non-zero value; this -value will become the return value of \fBftw\fP(). +value will become the return value of \fBftw\fP(). As long as \fIfn\fP() returns 0, -\fBftw\fP() will continue either until it has traversed the entire tree, -in which case it will return zero, +\fBftw\fP() will continue either until it has traversed the entire tree, +in which case it will return zero, or until it encounters an error (such as a .BR malloc (3) failure), in which case it will return \-1. .PP Because \fBftw\fP() uses dynamic data structures, the only safe way to -exit out of a tree walk is to return a non-zero value from \fIfn\fP(). +exit out of a tree walk is to return a non-zero value from \fIfn\fP(). To allow a signal to terminate the walk without causing a memory leak, have the handler set a global flag that is checked by \fIfn\fP(). \fIDon't\fP use \fBlongjmp\fP(3) unless the program is going to terminate. @@ -134,7 +134,7 @@ The function \fBnftw\fP() is the same as \fBftw\fP(), except that it has one additional argument, \fIflags\fP, and calls \fIfn\fP() with one more argument, \fIftwbuf\fP. -This \fIflags\fP argument is formed by ORing zero or more of the +This \fIflags\fP argument is formed by ORing zero or more of the following flags: .TP .BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" @@ -159,7 +159,7 @@ and processing continues in the parent. .\" \fIflag\fP set to \fBFTW_DP\fP). .TP .B FTW_SKIP_SUBTREE -If \fIfn\fP() is called with an entry that is a directory +If \fIfn\fP() is called with an entry that is a directory (\fItypeflag\fP is \fBFTW_D\fP), this return value will prevent objects within that directory from being passed as arguments to \fIfn\fP(). @@ -170,7 +170,7 @@ continues processing with the next sibling of the directory. Causes \fBnftw\fP() to return immediately with the return value \fBFTW_STOP\fP. .PP -Other return values could be associated with new actions in the future; +Other return values could be associated with new actions in the future; \fIfn\fP() should not return values other than those listed above. The feature test macro _GNU_SOURCE must be defined in order to @@ -191,7 +191,7 @@ and its subdirectories. (By default, each directory is handled \fIbefore\fP its contents.) .TP .B FTW_MOUNT -If set, stay within the same file system +If set, stay within the same file system (i.e., do not cross mount points). .TP .B FTW_PHYS @@ -199,20 +199,20 @@ If set, do not follow symbolic links. (This is what you want.) If not set, symbolic links are followed, but no file is reported twice. .sp -If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, +If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, then the function .IR fn () is never called for a directory that would be a descendant of itself. .LP For each entry in the directory tree, .BR nftw () -calls +calls .IR fn () with four arguments. .I fpath -and +and .I sb -are as for +are as for .BR ftw (). .I typeflag may receive any of the same values as with @@ -221,7 +221,7 @@ or any of the following values: .TP .B FTW_DP .I fpath -is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. +is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. All of the files and subdirectories within \fIfpath\fP have been processed. .TP @@ -236,7 +236,7 @@ is a symbolic link pointing to a nonexistent file. .LP The fourth argument that .BR nftw () -supplies when calling +supplies when calling \fIfn\fP() is a structure of type \fIFTW\fP: .in +0.25i @@ -250,11 +250,11 @@ struct FTW { .fi .in -0.25i .I base -is the offset of the filename (i.e., basename component) -in the pathname given in +is the offset of the filename (i.e., basename component) +in the pathname given in .IR fpath . .IR level -is the depth of +is the depth of .I fpath in the directory tree, relative to the root of the tree .RI ( dirpath , @@ -266,9 +266,9 @@ If \fIfn\fP() returns non-zero, then the tree walk is terminated and the value returned by \fIfn\fP() is returned as the result of \fBftw\fP() or \fBnftw\fP(). -If \fBnftw\fP() is called with the \fBFTW_ACTIONRETVAL\fP flag, -then the only non-zero value that should be used by \fIfn\fP() -to terminate the tree walk is \fBFTW_STOP\fP, +If \fBnftw\fP() is called with the \fBFTW_ACTIONRETVAL\fP flag, +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 \fBnftw\fP(). .SH NOTES The function @@ -283,7 +283,8 @@ will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only for symbolic links that do not point to an existing file, and again on other systems .BR ftw () -will use \fBFTW_SL\fP for each symbolic link. For predictable control, use +will use \fBFTW_SL\fP for each symbolic link. +For predictable control, use .BR nftw (). .LP Under Linux, libc4 and libc5 and glibc 2.0.6 will @@ -302,8 +303,8 @@ The following program traverses the directory tree under the path named in its first command-line argument, or under the current directory if no argument is supplied. It displays various information about each file. -The second-command line argument can be used to specify characters that -control the value assigned to the \fIflags\fP +The second-command line argument can be used to specify characters that +control the value assigned to the \fIflags\fP argument when calling \fBnftw\fP(). .nf @@ -314,7 +315,7 @@ argument when calling \fBnftw\fP(). #include static int -display_info(const char *fpath, const struct stat *sb, +display_info(const char *fpath, const struct stat *sb, int tflag, struct FTW *ftwbuf) { printf("%-3s %2d %7lld %-40s %d %s\\n", diff --git a/man3/futimes.3 b/man3/futimes.3 index 63b102665..ac7f004b4 100644 --- a/man3/futimes.3 +++ b/man3/futimes.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,15 +36,16 @@ futimes \- change access and/or modification times of an open file changes the access and modification times of a file in the same way as .BR utimes (2), with the difference that the file whose timestamps are to be changed -is specified via a file descriptor, +is specified via a file descriptor, .IR fd , rather than via a pathname. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS -Errors are as for +Errors are as for .BR utimes (2), with the following additions: .TP @@ -60,7 +61,8 @@ file system could not be accessed. .BR futimes () is available since glibc 2.3. .SH "CONFORMING TO" -4.2BSD. Other than Linux, this function is only available on the BSDs. +4.2BSD. +Other than Linux, this function is only available on the BSDs. .SH "SEE ALSO" .BR futimesat (2), .BR utime (2) diff --git a/man3/fwide.3 b/man3/fwide.3 index dfd931feb..36d67dd0f 100644 --- a/man3/fwide.3 +++ b/man3/fwide.3 @@ -22,10 +22,13 @@ fwide \- set and determine the orientation of a FILE stream .fi .SH DESCRIPTION When \fImode\fP is zero, the \fBfwide\fP() function determines the current -orientation of \fIstream\fP. It returns a value > 0 if \fIstream\fP is +orientation of \fIstream\fP. +It returns a value > 0 if \fIstream\fP is wide-character oriented, i.e. if wide character I/O is permitted but char -I/O is disallowed. It returns a value < 0 if \fIstream\fP is byte oriented, -i.e. if char I/O is permitted but wide character I/O is disallowed. It +I/O is disallowed. +It returns a value < 0 if \fIstream\fP is byte oriented, +i.e. if char I/O is permitted but wide character I/O is disallowed. +It returns zero if \fIstream\fP has no orientation yet; in this case the next I/O operation might change the orientation (to byte oriented if it is a char I/O operation, or to wide-character oriented if it is a wide character I/O @@ -36,12 +39,16 @@ the stream is closed. .PP When \fImode\fP is non-zero, the \fBfwide\fP() function first attempts to set \fIstream\fP's orientation (to wide-character oriented if \fImode\fP > 0, or -to byte oriented if \fImode\fP < 0). It then returns a value denoting the +to byte oriented if \fImode\fP < 0). +It then returns a value denoting the current orientation, as above. .SH "RETURN VALUE" The \fBfwide\fP() function returns the stream's orientation, after possibly -changing it. A return value > 0 means wide-character oriented. A return value -< 0 means byte oriented. A return value of zero means undecided. +changing it. +A return value > 0 means wide-character oriented. +A return value +< 0 means byte oriented. +A return value of zero means undecided. .SH "CONFORMING TO" C99, POSIX.1-2001. .SH "SEE ALSO" diff --git a/man3/gamma.3 b/man3/gamma.3 index 915d46adb..d322d938f 100644 --- a/man3/gamma.3 +++ b/man3/gamma.3 @@ -29,7 +29,8 @@ Glibc has a function that is equivalent to .BR lgamma () and computes the natural logarithm of the Gamma function. -(This is for compatibility reasons only. Don't use this function.) +(This is for compatibility reasons only. +Don't use this function.) .SH HISTORY 4.2BSD had a .BR gamma () @@ -59,7 +60,8 @@ the "true gamma" function. .\" 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. +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 6c6dd4c2e..73430b42a 100644 --- a/man3/gcvt.3 +++ b/man3/gcvt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,7 +41,8 @@ terminated ASCII string and stores the result in \fIbuf\fP. It produces .BR printf (3) F format or E format. .SH NOTES -This function is obsolete. Instead, +This function is obsolete. +Instead, .BR sprintf () is recommended. .SH "RETURN VALUE" diff --git a/man3/getaddrinfo.3 b/man3/getaddrinfo.3 index 3bb24b8e1..8baf50d9a 100644 --- a/man3/getaddrinfo.3 +++ b/man3/getaddrinfo.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,13 +16,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" References: RFC 2553 .\" -.\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, +.\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, .\" and AI_NUMERICSERV. .\" .TH getaddrinfo 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual" @@ -102,7 +102,7 @@ structure, including: if the network host is multi-homed; or if the same service is available from multiple socket protocols (one .B SOCK_STREAM -address and another +address and another .B SOCK_DGRAM address, for example). .PP @@ -188,16 +188,16 @@ imposed by the parameter. The .I ai_canonname -field of the first of these -.I addrinfo +field of the first of these +.I addrinfo structures is set to point to the official name of the host, if .I hints.ai_flags includes the .B AI_CANONNAME flag. -.\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo +.\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo .\" structure was set pointing to the canonical name; that was -.\" more than POSIX.1-2001 specified, or other implementations provided. +.\" more than POSIX.1-2001 specified, or other implementations provided. .\" MTK, Aug 05 .IR ai_family , .IR ai_socktype , @@ -238,8 +238,8 @@ includes the .B AI_ADDRCONFIG flag, then IPv4 addresses are returned in the list pointed to by .I result -only if the local system has at least one -IPv4 address configured, and IPv6 addresses are only returned +only if the local system has at least one +IPv4 address configured, and IPv6 addresses are only returned if the local system has at least one IPv6 address configured. .PP If @@ -259,7 +259,7 @@ and .B AI_ALL are specified in .IR hints.ai_family , -then return both IPv6 and IPv4-mapped IPv6 addresses +then return both IPv6 and IPv4-mapped IPv6 addresses in the list pointed to by .IR result . .B AI_ALL @@ -275,10 +275,10 @@ is NULL the port number will be left uninitialized. If .B AI_NUMERICSERV is specified in -.IR hints.ai_flags +.IR hints.ai_flags and .I service -is not NULL, then +is not NULL, then .I service must point to a string containing a numeric port number. This flag is used to inhibit the invocation of a name resolution service @@ -292,9 +292,9 @@ for the dynamically allocated linked list .SS "Extensions to getaddrinfo() for Internationalized Domain Names" .PP Starting with glibc 2.3.4, -.BR getaddrinfo () -has been extended to selectively allow the incoming and outgoing -host names to be transparently converted to and from the +.BR getaddrinfo () +has been extended to selectively allow the incoming and outgoing +host names to be transparently converted to and from the Internationalized Domain Name (IDN) format (see RFC 3490, .IR "Internationalizing Domain Names in Applications (IDNA)" ). Four new flags are defined: @@ -305,10 +305,10 @@ If this flag is specified, then the node name given in is converted to IDN format if necessary. The source encoding is that of the current locale. -If the input name contains non-ASCII characters, then the IDN encoding -is used. +If the input name contains non-ASCII characters, then the IDN encoding +is used. Those parts of the node name (delimited by dots) that contain -non-ASCII characters are encoded using ASCII Compatible Encoding (ACE) +non-ASCII characters are encoded using ASCII Compatible Encoding (ACE) before being passed to the name resolution functions. .\" Implementation Detail: .\" To minimize effects on system performance the implementation might @@ -318,24 +318,24 @@ before being passed to the name resolution functions. .\" might be a problem. .TP .B AI_CANONIDN -After a successful name lookup, and if the -.B AI_CANONNAME +After a successful name lookup, and if the +.B AI_CANONNAME flag was specified, .BR getaddrinfo () will return the canonical name of the -node corresponding to the -.I addrinfo +node corresponding to the +.I addrinfo structure value passed back. The return value is an exact copy of the value returned by the name resolution function. -If the name is encoded using ACE, then it will contain the -.I xn-- -prefix for one or more components of the name. -To convert these components into a readable form the -.B AI_CANONIDN -flag can be passed in addition to -.BR AI_CANONNAME . +If the name is encoded using ACE, then it will contain the +.I xn-- +prefix for one or more components of the name. +To convert these components into a readable form the +.B AI_CANONIDN +flag can be passed in addition to +.BR AI_CANONNAME . The resulting string is encoded using the current locale's encoding. .\" .\"Implementation Detail: @@ -343,14 +343,14 @@ The resulting string is encoded using the current locale's encoding. .\"step can be skipped, therefore avoiding unnecessary slowdowns. .TP .BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES -Setting these flags will enable the +Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and -IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 -conforming host name) +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming host name) flags respectively to be used in the IDNA handling. .SH "RETURN VALUE" .\" FIXME glibc defines the following additional errors, some which -.\" can probably be returned by getaddrinfo(); they need to +.\" can probably be returned by getaddrinfo(); they need to .\" be documented. .\" # ifdef __USE_GNU .\" # define EAI_INPROGRESS -100 /* Processing request in progress. */ @@ -401,7 +401,7 @@ are NULL; or .B AI_NUMERICSERV was specified in .I hints.ai_flags -and +and .I service was not a numeric port-number string. .TP diff --git a/man3/getcwd.3 b/man3/getcwd.3 index daad955a2..19f826f06 100644 --- a/man3/getcwd.3 +++ b/man3/getcwd.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -76,14 +76,15 @@ allocates the buffer dynamically using .BR malloc () if .I buf -is NULL on call. +is NULL on call. In this case, the allocated buffer has the length .I size unless .I size is zero, when .I buf -is allocated as big as necessary. It is possible (and, indeed, +is allocated as big as necessary. +It is possible (and, indeed, advisable) to .BR free () the buffers if they have been obtained this way. @@ -91,7 +92,8 @@ the buffers if they have been obtained this way. .BR get_current_dir_name (), will .BR malloc (3) -an array big enough to hold the current directory name. If the environment +an array big enough to hold the current directory name. +If the environment variable .B PWD is set, and its value is correct, then that value will be returned. @@ -99,7 +101,7 @@ is set, and its value is correct, then that value will be returned. .BR getwd (), does not .BR malloc (3) -any memory. +any memory. The .I buf argument should be a pointer to an array at least @@ -112,7 +114,7 @@ bytes of the actual pathname. Note that .B PATH_MAX need not be a compile-time constant; it may depend on the filesystem -and may even be unlimited. +and may even be unlimited. For portability and security reasons, use of .BR getwd () is deprecated. @@ -122,20 +124,21 @@ on failure with .I errno set accordingly, and .I buf -on success. The contents of the array pointed to by +on success. +The contents of the array pointed to by .IR buf is undefined on error. .SH ERRORS .TP .B EACCES -Permission to read or search a component of the filename was denied. +Permission to read or search a component of the filename was denied. .TP .B EFAULT .IR buf points to a bad address. .TP .B EINVAL -The +The .IR size argument is zero and .IR buf @@ -156,19 +159,21 @@ is a system call (since 2.1.92). On older systems it would query .IR /proc/self/cwd . If both system call and proc file system are missing, a -generic implementation is called. Only in that case can +generic implementation is called. +Only in that case can these calls fail under Linux with .BR EACCES . .LP These functions are often used to save the location of the current working -directory for the purpose of returning to it later. Opening the current +directory for the purpose of returning to it later. +Opening the current 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. +conforms to POSIX.1-2001. .BR getwd() is present in POSIX.1-2001, but marked LEGACY. .BR get_current_dir_name () diff --git a/man3/getdate.3 b/man3/getdate.3 index 03667c853..7db8675fe 100644 --- a/man3/getdate.3 +++ b/man3/getdate.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,14 +16,14 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Modified, 2001-12-26, aeb .TH GETDATE 3 2001-12-26 "" "Linux Programmer's Manual" .SH NAME -getdate \- convert a string to struct tm +getdate \- convert a string to struct tm .SH SYNOPSIS .B "#define _XOPEN_SOURCE" .br @@ -49,7 +49,7 @@ into the tm structure that it returns. This tm structure may be found in static storage, so that it will be overwritten by the next call. -In contrast to +In contrast to .BR strptime (3), (which has a .I format @@ -98,7 +98,8 @@ Otherwise, it returns NULL and sets the global variable .IR getdate_err . Changes to .I errno -are unspecified. The following values for +are unspecified. +The following values for .I getdate_err are defined: .TP 4n @@ -126,16 +127,17 @@ There is no line in the file that matches the input. .B 8 Invalid input specification. .SH NOTES -Since +Since .BR getdate () -is not reentrant because of the use of +is not reentrant because of the use of .I getdate_err and the static buffer to return the result in, glibc provides a -thread-safe variant. The functionality is the same. The result -is returned in the buffer pointed to by +thread-safe variant. +The functionality is the same. +The result is returned in the buffer pointed to by .I res and in case of an error the return value is non-zero with the same -values as given above for +values as given above for .IR getdate_err . .LP The POSIX.1-2001 specification for @@ -157,10 +159,10 @@ The glibc implementation does not support the conversion specification. .SH ENVIRONMENT .TP -.B DATEMSK +.B DATEMSK File containing format patterns. .TP -.BR TZ ", " LC_TIME +.BR TZ ", " LC_TIME Variables used by \fBstrptime\fP(). .SH "CONFORMING TO" POSIX.1-2001 diff --git a/man3/getdirentries.3 b/man3/getdirentries.3 index df524c749..59ba1943f 100644 --- a/man3/getdirentries.3 +++ b/man3/getdirentries.3 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,7 +43,8 @@ into .IR buf . At most .I nbytes -are read. Reading starts at offset +are read. +Reading starts at offset .RI * basep , and .RI * basep @@ -57,10 +58,11 @@ is set appropriately. .SH ERRORS See the Linux library source code for details. .SH "CONFORMING TO" -Not in POSIX.1-2001. Present on the BSDs, and a few other systems. +Not in POSIX.1-2001. +Present on the BSDs, and a few other systems. Use .BR opendir (3) -and +and .BR readdir (3) instead. .SH "SEE ALSO" diff --git a/man3/getenv.3 b/man3/getenv.3 index de2a8b682..a1c6454b8 100644 --- a/man3/getenv.3 +++ b/man3/getenv.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/getfsent.3 b/man3/getfsent.3 index 5e61876d4..d3ad4ce49 100644 --- a/man3/getfsent.3 +++ b/man3/getfsent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -104,7 +104,7 @@ The .BR getfsent () function appeared in 4.0BSD; the other four functions appeared in 4.3BSD. .SH "CONFORMING TO" -These functions are not in POSIX.1-2001. +These functions are not in POSIX.1-2001. Several operating systems have them, e.g., *BSD, SunOS, Digital Unix, AIX (which also has a .BR getfstype ()). diff --git a/man3/getgrent.3 b/man3/getgrent.3 index ccf3d870b..c9b586df8 100644 --- a/man3/getgrent.3 +++ b/man3/getgrent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,13 +43,13 @@ getgrent, setgrent, endgrent \- get group file entry The \fBgetgrent\fP() function returns a pointer to a structure containing the broken-out fields of a record in the group database -(e.g., the local group file +(e.g., the local group file .IR /etc/group , NIS, and LDAP). The first time it is called it returns the first entry; thereafter, it returns successive entries. .PP -The \fBsetgrent\fP() function rewinds to the beginning +The \fBsetgrent\fP() function rewinds to the beginning of the group database, to allow repeated scans. .PP The \fBendgrent\fP() function is used to close the group database @@ -69,8 +69,8 @@ struct group { .RE .SH "RETURN VALUE" The \fBgetgrent\fP() function returns a pointer to a -.I group -structure, +.I group +structure, or NULL if there are no more entries or an error occurs. .LP Upon error, diff --git a/man3/getgrent_r.3 b/man3/getgrent_r.3 index 01d1a226e..043f8974b 100644 --- a/man3/getgrent_r.3 +++ b/man3/getgrent_r.3 @@ -71,9 +71,11 @@ The non-reentrant functions return a pointer to static storage, where this static storage contains further pointers to group name, password and members. The reentrant functions described here return all of that in -caller-provided buffers. First of all there is the buffer +caller-provided buffers. +First of all there is the buffer .I gbuf -that can hold a struct group. And next the buffer +that can hold a struct group. +And next the buffer .I buf of size .I buflen @@ -96,7 +98,8 @@ is NULL. No more entries. .TP .B ERANGE -Insufficient buffer space supplied. Try again with larger buffer. +Insufficient buffer space supplied. +Try again with larger buffer. .SH EXAMPLE .nf #define _GNU_SOURCE @@ -104,8 +107,8 @@ Insufficient buffer space supplied. Try again with larger buffer. #include #define BUFLEN 4096 -int -main(void) +int +main(void) { struct group grp, *grpp; char buf[BUFLEN]; diff --git a/man3/getgrnam.3 b/man3/getgrnam.3 index 3cc9e088b..6dadb1555 100644 --- a/man3/getgrnam.3 +++ b/man3/getgrnam.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -53,7 +53,7 @@ The .BR getgrnam () function returns a pointer to a structure containing the broken-out fields of the record in the group database -(e.g., the local group file +(e.g., the local group file .IR /etc/group , NIS, and LDAP) that matches the group name @@ -105,7 +105,7 @@ can be found using .BR sysconf (3) with the _SC_GETGR_R_SIZE_MAX parameter. .SH "RETURN VALUE" -The \fBgetgrnam\fP() and \fBgetgrgid\fP() functions return a pointer to a +The \fBgetgrnam\fP() and \fBgetgrgid\fP() functions return a pointer to a .I group structure, or NULL if the matching entry is not found or an error occurs. @@ -124,7 +124,8 @@ or .BR getgrnam (). .LP The \fBgetgrnam_r\fP() and \fBgetgrgid_r\fP() functions return -zero on success. In case of error, an error number is returned. +zero on success. +In case of error, an error number is returned. .SH ERRORS .TP .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " @@ -163,10 +164,13 @@ SVr4, 4.3BSD, POSIX.1-2001 The formulation given above under "RETURN VALUE" is from POSIX.1-2001. It does not call "not found" an error, hence does not specify what value .I errno -might have in this situation. But that makes it impossible to recognize -errors. One might argue that according to POSIX +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX .I errno -should be left unchanged if an entry is not found. Experiments on various +should be left unchanged if an entry is not found. +Experiments on various Unix-like systems shows that lots of different values occur in this situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. .\" more precisely: diff --git a/man3/getgrouplist.3 b/man3/getgrouplist.3 index c5d838293..3b4a4a23a 100644 --- a/man3/getgrouplist.3 +++ b/man3/getgrouplist.3 @@ -7,29 +7,31 @@ .SH NAME getgrouplist \- list of groups a user belongs to .SH SYNOPSIS -.sp +.sp .B #include .sp .BI "int getgrouplist(const char *" user ", gid_t " group , .in 24 .BI "gid_t *" groups ", int *" ngroups ); .SH DESCRIPTION -The +The .BR getgrouplist () function scans the group database for all the groups .I user -belongs to. Up to +belongs to. +Up to .RI * ngroups group IDs corresponding to these groups are stored in the array .IR groups ; the return value from the function is the number of group IDs -actually stored. The group +actually stored. +The group .I group -is automatically included in the list of groups returned by +is automatically included in the list of groups returned by .BR getgrouplist (). .SH "RETURN VALUE" If -.RI * ngroups +.RI * ngroups is smaller than the total number of groups found, then .BR getgrouplist () returns a value of `\-1'. @@ -51,8 +53,8 @@ This function is present since glibc 2.2.4. #include #include -int -main(void) +int +main(void) { int i, ng = 0; char *user = "who"; /* username here */ diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3 index 2f8a8b4c6..2b3d4926e 100644 --- a/man3/gethostbyname.3 +++ b/man3/gethostbyname.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -119,7 +119,8 @@ ends in a dot. .PP The \fBgethostbyaddr\fP() function returns a structure of type \fIhostent\fP for the given host address \fIaddr\fP of length \fIlen\fP and address type -\fItype\fP. Valid address types are +\fItype\fP. +Valid address types are .B AF_INET and .BR AF_INET6 . @@ -127,10 +128,10 @@ The host address argument is a pointer to a struct of a type depending on the address type, for example a \fBstruct in_addr *\fP (probably obtained via a call to \fIinet_addr\fP()) for address type AF_INET. .PP -The \fBsethostent\fP() function specifies, if \fIstayopen\fP is true (1), -that a connected TCP socket should be used for the name server queries and -that the connection should remain open during successive queries. Otherwise, -name server queries will use UDP datagrams. +The \fBsethostent\fP() function specifies, if \fIstayopen\fP is true (1), +that a connected TCP socket should be used for the name server queries and +that the connection should remain open during successive queries. +Otherwise, name server queries will use UDP datagrams. .PP The \fBendhostent\fP() function ends the use of a TCP connection for name server queries. @@ -202,7 +203,8 @@ and .BR gethostbyaddr () functions return the .I hostent -structure or a NULL pointer if an error occurs. On error, the +structure or a NULL pointer if an error occurs. +On error, the .I h_errno variable holds an error number. When non-NULL, the return value may point at static data, see the notes below. @@ -219,8 +221,8 @@ The requested name is valid but does not have an IP address. A non-recoverable name server error occurred. .TP .B TRY_AGAIN -A temporary error occurred on an authoritative name server. Try again -later. +A temporary error occurred on an authoritative name server. +Try again later. .SH FILES .TP .I /etc/host.conf @@ -239,13 +241,15 @@ POSIX requires the call, that should return the next entry in the host data base. When using DNS/BIND this does not make much sense, but it may be reasonable if the host data base is a file that can be read -line by line. On many systems a routine of this name reads +line by line. +On many systems a routine of this name reads from the file .IR /etc/hosts . .\" e.g. Linux, FreeBSD, Unixware, HP-UX It may be available only when the library was built without DNS support. .\" e.g. FreeBSD, AIX -The glibc version will ignore ipv6 entries. This function is not reentrant, +The glibc version will ignore ipv6 entries. +This function is not reentrant, and glibc adds a reentrant version .BR gethostent_r (). .SH "GNU EXTENSIONS" @@ -259,7 +263,8 @@ Glibc2 also has reentrant versions .BR gethostbyname_r () and .BR gethostbyname2_r (). -These return 0 on success and non-zero on error. The result of the call +These return 0 on success and non-zero on error. +The result of the call is now stored in the struct with address .IR ret . After the call, @@ -282,7 +287,8 @@ The functions and .BR gethostbyaddr () may return pointers to static data, which may be overwritten by -later calls. Copying the +later calls. +Copying the .I struct hostent does not suffice, since it contains pointers; a deep copy is required. .LP @@ -296,7 +302,7 @@ to be of type .IR int , and .I size_t -is not. +is not. POSIX.1-2001 makes it .IR socklen_t , which is OK.) @@ -311,7 +317,8 @@ POSIX.1-2001 marks .BR gethostbyaddr () and .BR gethostbyname () -obsolescent. See +obsolescent. +See .BR getaddrinfo (3), .BR getnameinfo (3), .BR gai_strerror (3). diff --git a/man3/getipnodebyname.3 b/man3/getipnodebyname.3 index b6d0512bb..3bcda8ba3 100644 --- a/man3/getipnodebyname.3 +++ b/man3/getipnodebyname.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,14 +16,14 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" References: RFC 2553 .TH getipnodebyname 3 2002-04-03 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -getipnodebyname, getipnodebyaddr, freehostent \- get network +getipnodebyname, getipnodebyaddr, freehostent \- get network host names and addresses .SH SYNOPSIS .nf @@ -42,7 +42,8 @@ host names and addresses .BI "void freehostent(struct hostent *" "ip" ); .fi .SH DESCRIPTION -These functions are deprecated. Use +These functions are deprecated. +Use .BR getaddrinfo (3) and .BR getnameinfo (3) @@ -147,7 +148,7 @@ This flag may be used by itself or with the flag. .TP .B AI_DEFAULT -This flag is equivalent to +This flag is equivalent to .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . .SS getipnodebyaddr parameters The @@ -252,7 +253,8 @@ network host. The array is terminated by a null pointer. .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 +removed again. +Several Unix-like systems support them, but all call them deprecated. .SH "CONFORMING TO" RFC\ 2553. diff --git a/man3/getline.3 b/man3/getline.3 index 68635756e..2ad990bb7 100644 --- a/man3/getline.3 +++ b/man3/getline.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -34,7 +34,7 @@ getline, getdelim \- delimited string input .BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim ", FILE *" stream ); .SH DESCRIPTION .BR getline () -reads an entire line from \fIstream\fP, +reads an entire line from \fIstream\fP, storing the address of the buffer containing the text into .IR "*lineptr" . The buffer is null-terminated and includes the newline character, if @@ -55,7 +55,8 @@ can contain a pointer to a .BR malloc ()\-allocated buffer .IR "*n" -bytes in size. If the buffer is not large enough to hold the line, +bytes in size. +If the buffer is not large enough to hold the line, .BR getline () resizes it with .BR realloc (), @@ -63,7 +64,8 @@ updating .IR "*lineptr" and .IR "*n" -as necessary. In either case, on a successful call, +as necessary. +In either case, on a successful call, .IR "*lineptr" and .IR "*n" @@ -74,7 +76,8 @@ works like .BR getline (), except a line delimiter other than newline can be specified as the .IR delimiter -argument. As with +argument. +As with .BR getline (), a delimiter character is not added if one was not present in the input before end of file was reached. @@ -84,7 +87,8 @@ On success, and .BR getdelim () return the number of characters read, including the delimiter character, -but not including the terminating null byte. This value can be used +but not including the terminating null byte. +This value can be used to handle embedded null bytes in the line read. Both functions return \-1 on failure to read a line (including end of file @@ -105,7 +109,7 @@ is not valid). #include #include -int +int main(void) { FILE * fp; @@ -125,10 +129,10 @@ main(void) } .fi .SH "CONFORMING TO" -Both -.BR getline () -and -.BR getdelim () +Both +.BR getline () +and +.BR getdelim () are GNU extensions. They are available since libc 4.6.27. .SH "SEE ALSO" diff --git a/man3/getloadavg.3 b/man3/getloadavg.3 index a3e41b338..b2e652ad6 100644 --- a/man3/getloadavg.3 +++ b/man3/getloadavg.3 @@ -63,6 +63,6 @@ function appeared in .Bx 4.3 Reno . This function is available in glibc since version 2.2. .Sh "CONFORMING TO" -Not in POSIX.1-2001. +Not in POSIX.1-2001. Present on the BSDs and Solaris. .\" mdoc seems to have a bug - there must be no newline here diff --git a/man3/getlogin.3 b/man3/getlogin.3 index 0c7d9ef80..1c152cc11 100644 --- a/man3/getlogin.3 +++ b/man3/getlogin.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,7 +41,8 @@ getlogin, getlogin_r, cuserid \- get user name .SH DESCRIPTION \fBgetlogin\fP() returns a pointer to a string containing the name of the user logged in on the controlling terminal of the process, or a -null pointer if this information cannot be determined. The string is +null pointer if this information cannot be determined. +The string is statically allocated and might be overwritten on subsequent calls to this function or to \fBcuserid\fP(). .PP @@ -51,10 +52,12 @@ of size .IR bufsize . .PP \fBcuserid\fP() returns a pointer to a string containing a user name -associated with the effective user ID of the process. If \fIstring\fP +associated with the effective user ID of the process. +If \fIstring\fP is not a null pointer, it should be an array that can hold at least \fBL_cuserid\fP characters; the string is returned in this array. -Otherwise, a pointer to a string in a static area is returned. This +Otherwise, a pointer to a string in a static area is returned. +This string is statically allocated and might be overwritten on subsequent calls to this function or to \fBgetlogin\fP(). .PP @@ -68,7 +71,8 @@ running (\fBcuserid\fP()) or the user who logged in this session involved.) .PP For most purposes, it is more useful to use the environment variable -\fBLOGNAME\fP to find out who the user is. This is more flexible +\fBLOGNAME\fP to find out who the user is. +This is more flexible precisely because the user can set \fBLOGNAME\fP arbitrarily. .SH "RETURN VALUE" \fBgetlogin\fP() returns a pointer to the user name when successful, @@ -88,7 +92,7 @@ The calling process has no controlling tty. .TP .B ERANGE (getlogin_r) -The length of the user name, including the terminating null byte, +The length of the user name, including the terminating null byte, is larger than .IR bufsize . .LP @@ -113,42 +117,45 @@ and specified in POSIX.1-2001. System V has a \fBcuserid\fP() function which uses the real -user ID rather than the effective user ID. +user ID rather than the effective user ID. The \fBcuserid\fP() function -was included in the 1988 version of POSIX, +was included in the 1988 version of POSIX, but removed from the 1990 version. It was present in SUSv2, but removed in POSIX.1-2001. .LP OpenBSD has \fBgetlogin\fP() and \fBsetlogin\fP(), and a username associated with a session, even if it has no controlling tty. .SH BUGS -Unfortunately, it is often rather easy to fool +Unfortunately, it is often rather easy to fool .BR getlogin (). Sometimes it does not work at all, because some program messed up -the utmp file. Often, it gives only the first 8 characters of -the login name. The user currently logged in on the controlling tty +the utmp file. +Often, it gives only the first 8 characters of +the login name. +The user currently logged in on the controlling tty of our program need not be the user who started it. -Avoid +Avoid .BR getlogin () for security-related purposes. .LP -Note that glibc does not follow the POSIX spec and uses +Note that glibc does not follow the POSIX spec and uses .I stdin instead of .IR /dev/tty . -A bug. (Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8 -all return the login name also when -.I stdin +A bug. +(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8 +all return the login name also when +.I stdin is redirected.) .LP -Nobody knows precisely what -.BR cuserid () +Nobody knows precisely what +.BR cuserid () does; avoid it in portable programs. -Or avoid it altogether: use +Or avoid it altogether: use .I getpwuid(geteuid()) instead, if that is what you meant. -DO NOT USE +DO NOT USE .BR cuserid (). .SH "SEE ALSO" .BR geteuid (2), diff --git a/man3/getmntent.3 b/man3/getmntent.3 index 7f43c9ad9..1ad69f9af 100644 --- a/man3/getmntent.3 +++ b/man3/getmntent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -54,19 +54,21 @@ getmntent_r \- get file system descriptor file entry .BI " char *" buf ", int " buflen ); .fi .SH DESCRIPTION -These routines are used to access the file system description file +These routines are used to access the file system description file \fI/etc/fstab\fP and the mounted file system description file \fI/etc/mtab\fP. .PP The \fBsetmntent\fP() function opens the file system description file \fIfp\fP and returns a file pointer which can be used by -\fBgetmntent\fP(). The argument \fItype\fP is the type of access -required and can take the same values as the \fImode\fP argument of +\fBgetmntent\fP(). +The argument \fItype\fP is the type of access +required and can take the same values as the \fImode\fP argument of .BR fopen (3). .PP The \fBgetmntent\fP() function reads the next line from the file system description file \fIfp\fP and returns a pointer to a structure -containing the broken out fields from a line in the file. The pointer +containing the broken out fields from a line in the file. +The pointer points to a static area of memory which is overwritten by subsequent calls to \fBgetmntent\fP(). .PP @@ -131,7 +133,7 @@ a match is found and NULL otherwise. The non-reentrant functions are from SunOS 4.1.3. A routine .BR getmntent_r () -was introduced in HP-UX 10, but it returns an int. +was introduced in HP-UX 10, but it returns an int. The prototype shown above is glibc-only. LSB deprecates the functions .BR endhostent (), @@ -140,7 +142,8 @@ and .BR setmntent (). .SH NOTES System V also has a \fBgetmntent\fP() function but the calling sequence -differs, and the returned structure is different. Under System V +differs, and the returned structure is different. +Under System V .I /etc/mnttab is used. 4.4BSD and Digital Unix have a routine \fBgetmntinfo\fP(), diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3 index 14b486938..4b85c6b63 100644 --- a/man3/getnameinfo.3 +++ b/man3/getnameinfo.3 @@ -55,7 +55,8 @@ argument or a zero .I hostlen (or .IR servlen ) -parameter. However, at least one of hostname or service name +parameter. +However, at least one of hostname or service name must be requested. The @@ -85,33 +86,34 @@ for example by its port number. .TP .B NI_DGRAM If set, then the service is datagram (UDP) based rather than -stream (TCP) based. This is required for the few ports (512-514) +stream (TCP) based. +This is required for the few ports (512-514) that have different services for UDP and TCP. .SS "Extensions to getaddrinfo() for Internationalized Domain Names" .PP Starting with glibc 2.3.4, -.BR getnameinfo () +.BR getnameinfo () has been extended to selectively allow -host names to be transparently converted to and from the +host names to be transparently converted to and from the Internationalized Domain Name (IDN) format (see RFC 3490, .IR "Internationalizing Domain Names in Applications (IDNA)" ). Three new flags are defined: .TP .B NI_IDN If this flag is used, then the name found in the lookup process is -converted from IDN format to the locale's encoding if necessary. +converted from IDN format to the locale's encoding if necessary. ASCII-only names are not affected by the conversion, which makes this flag usable in existing programs and environments. .TP .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES -Setting these flags will enable the +Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and -IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 -conforming host name) +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming host name) flags respectively to be used in the IDNA handling. .SH "RETURN VALUE" .\" FIXME glibc defines the following additional errors, some which -.\" can probably be returned by getnameinfo(); they need to +.\" can probably be returned by getnameinfo(); they need to .\" be documented. .\" # ifdef __USE_GNU .\" # define EAI_INPROGRESS -100 /* Processing request in progress. */ @@ -127,7 +129,8 @@ the specified buffer lengths. On error one of the following non-zero error codes is returned: .TP .B EAI_AGAIN -The name could not be resolved at this time. Try again later. +The name could not be resolved at this time. +Try again later. .TP .B EAI_BADFLAGS The @@ -157,7 +160,8 @@ or was too small. .TP .B EAI_SYSTEM -A system error occurred. The error code can be found in +A system error occurred. +The error code can be found in .IR errno . .PP The @@ -184,11 +188,13 @@ defines the constants .RE The former is the constant MAXDNAME in recent versions of BIND's .I -header file. The latter is a guess based on the services listed +header file. +The latter is a guess based on the services listed in the current Assigned Numbers RFC. .SH EXAMPLE The following code tries to get the numeric hostname and service name, for -a given socket address. Note that there is no hardcoded reference to +a given socket address. +Note that there is no hardcoded reference to a particular address family. .RS diff --git a/man3/getnetent.3 b/man3/getnetent.3 index 15756fe02..c028240e2 100644 --- a/man3/getnetent.3 +++ b/man3/getnetent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -28,7 +28,7 @@ .TH GETNETENT 3 1993-05-15 "BSD" "Linux Programmer's Manual" .SH NAME getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \- -get network entry +get network entry .SH SYNOPSIS .nf .B #include @@ -46,7 +46,8 @@ get network entry .SH DESCRIPTION The \fBgetnetent\fP() function reads the next line from the file \fI/etc/networks\fP and returns a structure \fInetent\fP containing -the broken out fields from the line. The \fI/etc/networks\fP file +the broken out fields from the line. +The \fI/etc/networks\fP file is opened if necessary. .PP The \fBgetnetbyname\fP() function returns a \fInetent\fP structure @@ -58,7 +59,8 @@ for the line that matches the network number \fInet\fP of type \fItype\fP. .PP The \fBsetnetent\fP() function opens and rewinds the -\fI/etc/networks\fP file. If \fIstayopen\fP is true (1), then the +\fI/etc/networks\fP file. +If \fIstayopen\fP is true (1), then the file will not be closed between calls to \fBgetnetbyname\fP() and \fBgetnetbyaddr\fP(). .PP diff --git a/man3/getopt.3 b/man3/getopt.3 index d9dd5d706..6d5e6a818 100644 --- a/man3/getopt.3 +++ b/man3/getopt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -64,7 +64,8 @@ getopt \- Parse command-line options .SH DESCRIPTION The .BR getopt () -function parses the command-line arguments. Its arguments +function parses the command-line arguments. +Its arguments .I argc and .I argv @@ -73,8 +74,10 @@ are the argument count and array as passed to the function on program invocation. An element of \fIargv\fP that starts with '\-' (and is not exactly "\-" or "\-\-") -is an option element. The characters of this element -(aside from the initial '\-') are option characters. If \fBgetopt\fP() +is an option element. +The characters of this element +(aside from the initial '\-') are option characters. +If \fBgetopt\fP() is called repeatedly, it returns successively each of the option characters from each of the option elements. .PP @@ -89,16 +92,18 @@ Then \fIoptind\fP is the index in \fIargv\fP of the first \fIargv\fP-element that is not an option. .PP .I optstring -is a string containing the legitimate option characters. If such a +is a string containing the legitimate option characters. +If such a character is followed by a colon, the option requires an argument, so \fBgetopt\fP() places a pointer to the following text in the same \fIargv\fP-element, or the text of the following \fIargv\fP-element, in .IR optarg . Two colons mean an option takes an optional arg; if there is text in the current \fIargv\fP-element -(i.e., in the same word as the option name itself, for example, "-oarg"), +(i.e., in the same word as the option name itself, for example, "-oarg"), then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. -This is a GNU extension. If +This is a GNU extension. +If .I optstring contains .B W @@ -113,11 +118,13 @@ This behaviour is a GNU extension, not available with libraries before GNU libc 2. .PP By default, \fBgetopt\fP() permutes the contents of \fIargv\fP as it -scans, so that eventually all the non-options are at the end. Two -other modes are also implemented. If the first character of +scans, so that eventually all the non-options are at the end. +Two other modes are also implemented. +If the first character of \fIoptstring\fP is '+' or the environment variable POSIXLY_CORRECT is set, then option processing stops as soon as a non-option argument is -encountered. If the first character of \fIoptstring\fP is '\-', then +encountered. +If the first character of \fIoptstring\fP is '\-', then each non-option \fIargv\fP-element is handled as if it were the argument of an option with character code 1. (This is used by programs that were written to expect options and other \fIargv\fP-elements in any order @@ -127,17 +134,20 @@ of the scanning mode. .PP If \fBgetopt\fP() does not recognize an option character, it prints an error message to stderr, stores the character in \fIoptopt\fP, and -returns '?'. The calling program may prevent the error message by +returns '?'. +The calling program may prevent the error message by setting \fIopterr\fP to 0. .PP If \fBgetopt\fP() finds an option character in \fIargv\fP that was not included in \fIoptstring\fP, or if it detects a missing option argument, it returns '?' and sets the external variable \fIoptopt\fP to the -actual option character. If the first character +actual option character. +If the first character (following any optional '+' or '\-' described above) of \fIoptstring\fP is a colon (':'), then \fBgetopt\fP() returns ':' instead of '?' to -indicate a missing option argument. If an error was detected, and +indicate a missing option argument. +If an error was detected, and the first character of \fIoptstring\fP is not a colon, and the external variable \fIopterr\fP is non-zero (which is the default), \fBgetopt\fP() prints an error message. @@ -151,7 +161,8 @@ except that it also accepts long options, started out by two dashes. .I optstring should be specified as an empty string (""), not NULL.) Long option names may be abbreviated if the abbreviation is -unique or is an exact match for some defined option. A long option +unique or is an exact match for some defined option. +A long option may take a parameter, of the form .B \-\-arg=param or @@ -188,14 +199,16 @@ is: \fBoptional_argument\fP (or 2) if the option takes an optional argument. .TP .I flag -specifies how results are returned for a long option. If \fIflag\fP +specifies how results are returned for a long option. +If \fIflag\fP is NULL, then \fBgetopt_long\fP() returns \fIval\fP. (For example, the calling program may set \fIval\fP to the equivalent short -option character.) Otherwise, \fBgetopt_long\fP() returns 0, and +option character.) +Otherwise, \fBgetopt_long\fP() returns 0, and \fIflag\fP points to a variable which is set to \fIval\fP if the option is found, but left unchanged if the option is not found. .TP -\fIval\fP +\fIval\fP is the value to return, or to load into the variable pointed to by \fIflag\fP. .PP @@ -205,10 +218,11 @@ If \fIlongindex\fP is not NULL, it points to a variable which is set to the index of the long option relative to .IR longopts . .PP -\fBgetopt_long_only\fP() is like \fBgetopt_long\fP(), but '\-' as well -as '\-\-' can indicate a long option. If an option that starts with '\-' +\fBgetopt_long_only\fP() is like \fBgetopt_long\fP(), but '\-' as well +as '\-\-' can indicate a long option. +If an option that starts with '\-' (not '\-\-') doesn't match a long option, but does match a short option, -it is parsed as a short option instead. +it is parsed as a short option instead. .SH "RETURN VALUE" If an option was successfully found, then .BR getopt () @@ -229,15 +243,16 @@ then the return value depends on the first character in if it is ':', then ':' is returned; otherwise '?' is returned. .PP \fBgetopt_long\fP() and \fBgetopt_long_only\fP() also return the option -character when a short option is recognized. For a long option, they -return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. Error -and \-1 returns are the same as for \fBgetopt\fP(), plus '?' for an +character when a short option is recognized. +For a long option, they +return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. +Error and \-1 returns are the same as for \fBgetopt\fP(), plus '?' for an ambiguous match or an extraneous parameter. .SH "ENVIRONMENT VARIABLES" .TP .SM .B POSIXLY_CORRECT -If this is set, then option processing stops as soon as a non-option +If this is set, then option processing stops as soon as a non-option argument is encountered. .TP .SM @@ -245,14 +260,14 @@ argument is encountered. This variable was used by .B bash 2.0 to communicate to GNU libc which arguments are the results of -wildcard expansion and so should not be considered as options. This -behaviour was removed in +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 EXAMPLE The following trivial example program uses .BR getopt () -to handle two program options: +to handle two program options: .IR -n , with no associated value; and .IR "-t val" , @@ -313,7 +328,7 @@ with most of its features. #include int -main(int argc, char **argv) +main(int argc, char **argv) { int c; int digit_optind = 0; @@ -390,29 +405,31 @@ main(int argc, char **argv) .SH BUGS The POSIX.2 specification of .BR getopt () -has a technical error described in POSIX.2 Interpretation 150. The GNU +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 \fBgetopt\fP(): -POSIX.2 and POSIX.1-2001, +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 +permute them. +We pretend they're const in the prototype to be compatible with other systems. .sp -On some older implementations, +On some older implementations, .BR getopt () was declared in .IR . -SUSv1 permitted the declaration to appear in either +SUSv1 permitted the declaration to appear in either .I or .IR . -POSIX.1-2001 marked the use of +POSIX.1-2001 marked the use of .I -for this purpose as LEGACY. +for this purpose as LEGACY. POSIX.1-2001 does not allow the declaration to appear in .IR . .SH "SEE ALSO" diff --git a/man3/getpass.3 b/man3/getpass.3 index 047689f40..6fe17eae6 100644 --- a/man3/getpass.3 +++ b/man3/getpass.3 @@ -28,7 +28,8 @@ getpass \- get a password .sp .B "char *getpass( const char *" prompt ); .SH DESCRIPTION -This function is obsolete. Do not use it. +This function is obsolete. +Do not use it. .PP The .BR getpass () @@ -54,7 +55,7 @@ is set appropriately, and NULL is returned. The function may fail if .TP .B ENXIO -The process does not have a controlling terminal. +The process does not have a controlling terminal. .SH NOTES For libc4 and libc5, the prompt is not written to .I /dev/tty @@ -100,7 +101,7 @@ A .BR getpass () function appeared in Version 7 AT&T UNIX. .SH "CONFORMING TO" -Present in SUSv2, but marked LEGACY. +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 diff --git a/man3/getprotoent.3 b/man3/getprotoent.3 index a6357764d..5a67f23ee 100644 --- a/man3/getprotoent.3 +++ b/man3/getprotoent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,8 +46,8 @@ endprotoent \- get protocol entry .SH DESCRIPTION The \fBgetprotoent\fP() function reads the next line from the file \fI/etc/protocols\fP and returns a structure \fIprotoent\fP -containing the broken out fields from the line. The -\fI/etc/protocols\fP file is opened if necessary. +containing the broken out fields from the line. +The \fI/etc/protocols\fP file is opened if necessary. .PP The \fBgetprotobyname\fP() function returns a \fIprotoent\fP structure for the line from \fI/etc/protocols\fP that matches @@ -57,7 +57,8 @@ The \fBgetprotobynumber\fP() function returns a \fIprotoent\fP structure for the line that matches the protocol number \fInumber\fP. .PP The \fBsetprotoent\fP() function opens and rewinds the -\fI/etc/protocols\fP file. If \fIstayopen\fP is true (1), then +\fI/etc/protocols\fP file. +If \fIstayopen\fP is true (1), then the file will not be closed between calls to \fBgetprotobyname\fP() or \fBgetprotobynumber\fP(). .PP diff --git a/man3/getpt.3 b/man3/getpt.3 index fbc6c6854..442b39b34 100644 --- a/man3/getpt.3 +++ b/man3/getpt.3 @@ -15,12 +15,13 @@ getpt \- open the pseudo-terminal master (PTM) .BR getpt () opens a pseudo-terminal master and returns its file descriptor. It is equivalent to -.BI "open(" \fI"/dev/ptmx" , O_RDWR|O_NOCTTY ) +.BI "open(" \fI"/dev/ptmx" , O_RDWR|O_NOCTTY ) on Linux systems, though the pseudo-terminal master is located elsewhere on some systems that use GNU Libc. .SH "RETURN VALUE" .BR getpt () -returns an open file descriptor upon successful completion. Otherwise, it +returns an open file descriptor upon successful completion. +Otherwise, it returns \-1 and sets .I errno to indicate the error. diff --git a/man3/getpw.3 b/man3/getpw.3 index 986ddc6f9..77fc2f699 100644 --- a/man3/getpw.3 +++ b/man3/getpw.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -79,7 +79,7 @@ The .BR getpw () function is dangerous as it may overflow the provided buffer .IR buf . -It is obsoleted by +It is obsoleted by .BR getpwuid (). .SH "SEE ALSO" .BR endpwent (3), diff --git a/man3/getpwent.3 b/man3/getpwent.3 index 2d7bfc65a..fe851e465 100644 --- a/man3/getpwent.3 +++ b/man3/getpwent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,14 +45,14 @@ getpwent, setpwent, endpwent \- get password file entry .SH DESCRIPTION The \fBgetpwent\fP() function returns a pointer to a structure containing the broken-out fields of a record from the password database -(e.g., the local password file +(e.g., the local password file .IR /etc/passwd , NIS, and LDAP). -The first time it -is called it returns the first entry; thereafter, it returns successive +The first time it +is called it returns the first entry; thereafter, it returns successive entries. .PP -The \fBsetpwent\fP() function rewinds to the beginning +The \fBsetpwent\fP() function rewinds to the beginning of the password database. .PP The \fBendpwent\fP() function is used to close the password database @@ -74,9 +74,9 @@ struct passwd { .fi .RE .SH "RETURN VALUE" -The \fBgetpwent\fP() function returns a pointer to a +The \fBgetpwent\fP() function returns a pointer to a .I passwd -structure, or NULL if +structure, or NULL if there are no more entries or an error occurs. If an error occurs, .I errno diff --git a/man3/getpwent_r.3 b/man3/getpwent_r.3 index 70b764e8a..df8a528a4 100644 --- a/man3/getpwent_r.3 +++ b/man3/getpwent_r.3 @@ -73,9 +73,11 @@ The non-reentrant functions return a pointer to static storage, where this static storage contains further pointers to user name, password, gecos field, home directory and shell. The reentrant functions described here return all of that in -caller-provided buffers. First of all there is the buffer +caller-provided buffers. +First of all there is the buffer .I pwbuf -that can hold a struct passwd. And next the buffer +that can hold a struct passwd. +And next the buffer .I buf of size .I buflen @@ -98,7 +100,8 @@ is NULL. No more entries. .TP .B ERANGE -Insufficient buffer space supplied. Try again with larger buffer. +Insufficient buffer space supplied. +Try again with larger buffer. .SH EXAMPLE .nf #define _GNU_SOURCE @@ -106,8 +109,8 @@ Insufficient buffer space supplied. Try again with larger buffer. #include #define BUFLEN 4096 -int -main(void) +int +main(void) { struct passwd pw, *pwp; char buf[BUFLEN]; @@ -118,7 +121,7 @@ main(void) i = getpwent_r(&pw, buf, BUFLEN, &pwp); if (i) break; - printf("%s (%d)\etHOME %s\etSHELL %s\en", pwp->pw_name, + printf("%s (%d)\etHOME %s\etSHELL %s\en", pwp->pw_name, pwp->pw_uid, pwp->pw_dir, pwp->pw_shell); } endpwent(); diff --git a/man3/getpwnam.3 b/man3/getpwnam.3 index 524cab34f..bed5bae4d 100644 --- a/man3/getpwnam.3 +++ b/man3/getpwnam.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -54,7 +54,7 @@ The .BR getpwnam () function returns a pointer to a structure containing the broken-out fields of the record in the password database -(e.g., the local password file +(e.g., the local password file .IR /etc/passwd , NIS, and LDAP) that matches the user name @@ -127,7 +127,8 @@ or .BR getpwuid (). .LP The \fBgetpwnam_r\fP() and \fBgetpwuid_r\fP() functions return -zero on success. In case of error, an error number is returned. +zero on success. +In case of error, an error number is returned. .SH ERRORS .TP .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " @@ -167,10 +168,13 @@ SVr4, 4.3BSD, POSIX.1-2001 The formulation given above under "RETURN VALUE" is from POSIX.1-2001. It does not call "not found" an error, and hence does not specify what value .I errno -might have in this situation. But that makes it impossible to recognize -errors. One might argue that according to POSIX +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX .I errno -should be left unchanged if an entry is not found. Experiments on various +should be left unchanged if an entry is not found. +Experiments on various Unix-like systems show that lots of different values occur in this situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. .\" more precisely: @@ -181,9 +185,9 @@ situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others. .\" SunOS 5.8 - gives EBADF .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 -The -.I pw_dir -field contains the name of the initial working directory of the user. +The +.I pw_dir +field contains the name of the initial working directory of the user. Login programs use the value of this field to initialize the HOME environment variable for the login shell. An application that wants to determine its user's home directory @@ -192,8 +196,8 @@ should inspect the value of HOME (rather than the value since this allows the user to modify their notion of "the home directory" during a login session. To determine the (initial) home directory of another user, -it is necessary to use -.I getpwnam("username")->pw_dir +it is necessary to use +.I getpwnam("username")->pw_dir or similar. .SH "SEE ALSO" .BR endpwent (3), diff --git a/man3/getrpcent.3 b/man3/getrpcent.3 index aec459c33..b4022c969 100644 --- a/man3/getrpcent.3 +++ b/man3/getrpcent.3 @@ -1,7 +1,7 @@ .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) .\" .\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI -.TH GETRPCENT 3 1987-12-14 +.TH GETRPCENT 3 1987-12-14 .SH NAME getrpcent, getrpcbyname, getrpcbynumber \- get RPC entry .SH SYNOPSIS @@ -70,7 +70,8 @@ The rpc program number for this service. reads the next line of the file, opening the file if necessary. .LP .BR setrpcent () -opens and rewinds the file. If the +opens and rewinds the file. +If the .I stayopen flag is non-zero, the net data base will not be closed after each call to @@ -93,7 +94,7 @@ program number is found, or until end-of-file is encountered. .I /etc/rpc .PD .SH "CONFORMING TO" -Not in POSIX.1-2001. +Not in POSIX.1-2001. Present on the BSDs, Solaris, and many other systems. .SH "SEE ALSO" .BR rpc (5), @@ -103,7 +104,7 @@ Present on the BSDs, Solaris, and many other systems. .LP A .SM NULL -pointer is returned on +pointer is returned on .SM EOF or error. .SH BUGS diff --git a/man3/getrpcport.3 b/man3/getrpcport.3 index 5c37e201b..a9ee625c0 100644 --- a/man3/getrpcport.3 +++ b/man3/getrpcport.3 @@ -1,7 +1,7 @@ .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) .\" .\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI -.TH GETRPCPORT 3 1987-10-06 +.TH GETRPCPORT 3 1987-10-06 .SH NAME getrpcport \- get RPC port number .SH SYNOPSIS @@ -23,7 +23,8 @@ and using protocol .IR proto . It returns 0 if it cannot contact the portmapper, or if .I prognum -is not registered. If +is not registered. +If .I prognum is registered but not with version .IR versnum , @@ -31,5 +32,5 @@ it will still return a port number (for some version of the program) indicating that the program is indeed registered. The version mismatch will be detected upon the first call to the service. .SH "CONFORMING TO" -Not in POSIX.1-2001. +Not in POSIX.1-2001. Present on the BSDs, Solaris, and many other systems. diff --git a/man3/gets.3 b/man3/gets.3 index d14cbd72e..e9652df92 100644 --- a/man3/gets.3 +++ b/man3/gets.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -43,7 +43,7 @@ fgetc, fgets, getc, getchar, gets, ungetc \- input of characters and strings .SH DESCRIPTION .BR fgetc () reads the next character from -.I stream +.I stream and returns it as an .I unsigned char cast to an @@ -63,7 +63,7 @@ more than once. is equivalent to .BI "getc(" stdin ) \fR. .PP -.BR gets () +.BR gets () reads a line from .I stdin into the buffer pointed to by @@ -85,7 +85,9 @@ and stores them into the buffer pointed to by .IR s . Reading stops after an .B EOF -or a newline. If a newline is read, it is stored into the buffer. A +or a newline. +If a newline is read, it is stored into the buffer. +A .B '\e0' is stored after the last character in the buffer. .PP @@ -96,7 +98,8 @@ back to .IR stream , cast to .IR "unsigned char" , -where it is available for subsequent read operations. Pushed-back characters +where it is available for subsequent read operations. +Pushed-back characters will be returned in reverse order; only one pushback is guaranteed. .PP Calls to the functions described here can be mixed with each other and with @@ -107,9 +110,9 @@ library for the same input stream. For non-locking counterparts, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -.BR fgetc (), -.BR getc () -and +.BR fgetc (), +.BR getc () +and .BR getchar () return the character read as an .I unsigned char @@ -119,8 +122,8 @@ or .B EOF on end of file or error. .PP -.BR gets () -and +.BR gets () +and .BR fgets () return .I s @@ -128,7 +131,7 @@ on success, and NULL on error or when end of file occurs while no characters have been read. .PP .BR ungetc () -returns +returns .I c on success, or .B EOF @@ -145,8 +148,10 @@ characters .BR gets () will read, and because .BR gets () -will continue to store characters past the end of the buffer, it is extremely -dangerous to use. It has been used to break computer security. Use +will continue to store characters past the end of the buffer, +it is extremely dangerous to use. +It has been used to break computer security. +Use .BR fgets () instead. .PP diff --git a/man3/getservent.3 b/man3/getservent.3 index a2162a8ad..c7a79dd50 100644 --- a/man3/getservent.3 +++ b/man3/getservent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,7 +32,7 @@ .TH GETSERVENT 3 2001-07-25 "BSD" "Linux Programmer's Manual" .SH NAME getservent, getservbyname, getservbyport, setservent, endservent \- -get service entry +get service entry .SH SYNOPSIS .nf .B #include @@ -50,7 +50,8 @@ get service entry .SH DESCRIPTION The \fBgetservent\fP() function reads the next line from the file \fI/etc/services\fP and returns a structure \fIservent\fP containing -the broken out fields from the line. The \fI/etc/services\fP file +the broken out fields from the line. +The \fI/etc/services\fP file is opened if necessary. .PP The \fBgetservbyname\fP() function returns a \fIservent\fP structure @@ -64,7 +65,8 @@ using protocol \fIproto\fP. If \fIproto\fP is NULL, any protocol will be matched. .PP The \fBsetservent\fP() function opens and rewinds the -\fI/etc/services\fP file. If \fIstayopen\fP is true (1), then the +\fI/etc/services\fP file. +If \fIstayopen\fP is true (1), then the file will not be closed between calls to \fBgetservbyname\fP() and \fBgetservbyport\fP(). .PP diff --git a/man3/getspnam.3 b/man3/getspnam.3 index 69b0f70b3..e899fb81f 100644 --- a/man3/getspnam.3 +++ b/man3/getspnam.3 @@ -56,12 +56,13 @@ lckpwdf, ulckpwdf \- get shadow password file entry .fi .SH DESCRIPTION Long ago it was considered safe to have encrypted passwords openly -visible in the password file. When computers got faster and people +visible in the password file. +When computers got faster and people got more security-conscious, this was no longer acceptable. Julianne Frances Haugh implemented the shadow password suite that keeps the encrypted passwords in the shadow password database -(e.g., the local shadow password file +(e.g., the local shadow password file .IR /etc/shadow , NIS, and LDAP), readable only by root. @@ -73,12 +74,12 @@ the traditional password database and .BR getpwent (3)). .\" FIXME I've commented out the following for the -.\" moment. The relationship between PAM and nsswitch.conf needs -.\" to be clearly documented in one place, which is pointed to by -.\" the pages for the user, group, and shadow password functions. +.\" moment. The relationship between PAM and nsswitch.conf needs +.\" to be clearly documented in one place, which is pointed to by +.\" the pages for the user, group, and shadow password functions. .\" (Jul 2005, mtk) -.\" -.\" This shadow password setup has been superseded by PAM +.\" +.\" This shadow password setup has been superseded by PAM .\" (pluggable authentication modules), and the file .\" .I /etc/nsswitch.conf .\" now describes the sources to be used. @@ -128,7 +129,7 @@ are written as an empty string. .LP The .BR lckpwdf () -function is intended to protect against multiple simultaneous accesses +function is intended to protect against multiple simultaneous accesses of the shadow password database. It tries to acquire a lock, and returns 0 on success, or \-1 on failure (lock not obtained within 15 seconds). @@ -136,7 +137,8 @@ The .BR ulckpwdf () function releases the lock again. Note that there is no protection against direct access of the shadow -password file. Only programs that use +password file. +Only programs that use .BR lckpwdf () will notice the lock. .LP @@ -221,7 +223,7 @@ The include file defines the constant _PATH_SHADOW to the pathname of the shadow password file. .SH "CONFORMING TO" -The shadow password database and its associated API are +The shadow password database and its associated API are not specified in POSIX.1-2001. However, many other systems provide a similar API. .SH "SEE ALSO" diff --git a/man3/getttyent.3 b/man3/getttyent.3 index 3e93fd1d6..b809fdfea 100644 --- a/man3/getttyent.3 +++ b/man3/getttyent.3 @@ -1,6 +1,6 @@ .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) .\" Distributed under GPL -.\" +.\" .TH GETTTYENT 3 2002-07-18 "glibc" .SH NAME getttyent, getttynam, setttyent, endttyent \- get ttys file entry @@ -21,7 +21,7 @@ These functions provide an interface to the file (e.g., .IR /etc/ttys ). -The function +The function .BR setttyent () opens the file or rewinds it if already open. @@ -29,9 +29,10 @@ The function .BR endttyent () closes the file. -The function +The function .BR getttynam () -searches for a given ttyname in the file. It returns a pointer to a +searches for a given ttyname in the file. +It returns a pointer to a struct ttyent (description below). The function @@ -62,7 +63,7 @@ Under Linux the file .IR /etc/ttys , and the functions described above, are not used. .SH "CONFORMING TO" -Not in POSIX.1-2001. +Not in POSIX.1-2001. Present on the BSDs, and perhaps other systems. .SH "SEE ALSO" .BR ttyname (3), diff --git a/man3/getumask.3 b/man3/getumask.3 index 86b63e695..e6367162c 100644 --- a/man3/getumask.3 +++ b/man3/getumask.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,7 @@ It is equivalent to .in +0.5i .nf -mode_t getumask(void) +mode_t getumask(void) { mode_t mask = umask(0); umask(mask); diff --git a/man3/getusershell.3 b/man3/getusershell.3 index d6a113bac..f58076cdb 100644 --- a/man3/getusershell.3 +++ b/man3/getusershell.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,9 +40,11 @@ getusershell, setusershell, endusershell \- get legal user shells .fi .SH DESCRIPTION The \fBgetusershell\fP() function returns the next line from the file -\fI/etc/shells\fP, opening the file if necessary. The line should contain -the pathname of a valid user shell. If \fI/etc/shells\fP does not exist or -is unreadable, \fBgetusershell\fP() behaves as if \fI/bin/sh\fP and +\fI/etc/shells\fP, opening the file if necessary. +The line should contain +the pathname of a valid user shell. +If \fI/etc/shells\fP does not exist or +is unreadable, \fBgetusershell\fP() behaves as if \fI/bin/sh\fP and \fI/bin/csh\fP were listed in the file. .PP The \fBsetusershell\fP() function rewinds \fI/etc/shells\fP. diff --git a/man3/getutent.3 b/man3/getutent.3 index bd1195d2e..ff41e91c0 100644 --- a/man3/getutent.3 +++ b/man3/getutent.3 @@ -47,7 +47,8 @@ getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- access .BI "void utmpname(const char *" file ); .SH DESCRIPTION \fButmpname\fP() sets the name of the utmp-format file for the other utmp -functions to access. If \fButmpname\fP() is not used to set the filename +functions to access. +If \fButmpname\fP() is not used to set the filename before the other functions are used, they assume \fB_PATH_UTMP\fP, as defined in \fI\fP. .PP @@ -55,15 +56,18 @@ defined in \fI\fP. It is generally a Good Idea to call it before any of the other functions. .PP -\fBendutent\fP() closes the utmp file. It should be called when the user +\fBendutent\fP() closes the utmp file. +It should be called when the user code is done accessing the file with the other functions. .PP \fBgetutent\fP() reads a line from the current file position in the utmp -file. It returns a pointer to a structure containing the fields of +file. +It returns a pointer to a structure containing the fields of the line. .PP \fBgetutid\fP() searches forward from the current file position in the utmp -file based upon \fIut\fP. If \fIut\fP->ut_type is one of \fBRUN_LVL\fP, +file based upon \fIut\fP. +If \fIut\fP->ut_type is one of \fBRUN_LVL\fP, \fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, \fBgetutid\fP() will find the first entry whose \fIut_type\fP field matches \fIut\fP->ut_type. If \fIut\fP->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, @@ -71,13 +75,15 @@ If \fIut\fP->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, first entry whose ut_id field matches \fIut\fP->ut_id. .PP \fBgetutline\fP() searches forward from the current file position in the -utmp file. It scans entries whose ut_type is \fBUSER_PROCESS\fP +utmp file. +It scans entries whose ut_type is \fBUSER_PROCESS\fP or \fBLOGIN_PROCESS\fP and returns the first one whose ut_line field matches \fIut\fP->ut_line. .PP -\fBpututline\fP() writes the utmp structure \fIut\fP into the utmp file. It -uses \fBgetutid\fP() to search for the proper place in the file to insert -the new entry. If it cannot find an appropriate slot for \fIut\fP, +\fBpututline\fP() writes the utmp structure \fIut\fP into the utmp file. +It uses \fBgetutid\fP() to search for the proper place in the file to insert +the new entry. +If it cannot find an appropriate slot for \fIut\fP, \fBpututline\fP() will append the new entry to the end of the file. .SH "RETURN VALUE" \fBgetutent\fP(), \fBgetutid\fP(), \fBgetutline\fP() and \fBpututline\fP() @@ -85,7 +91,8 @@ 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 "REENTRANT VERSIONS" -These above functions are not thread-safe. Glibc adds reentrant versions +These above functions are not thread-safe. +Glibc adds reentrant versions .sp .nf .BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */" @@ -101,7 +108,8 @@ These above functions are not thread-safe. Glibc adds reentrant versions .fi .sp These functions are GNU extensions, analogs of the functions of the -same name without the _r suffix. The +same name without the _r suffix. +The .I ubuf parameter gives these functions a place to store their result. On success they return 0, and a pointer to the result is written in @@ -109,10 +117,11 @@ On success they return 0, and a pointer to the result is written in On error these functions return \-1. .SH EXAMPLE The following example adds and removes a utmp record, assuming it is run -from within a pseudo terminal. For usage in a real application, you -should check the return values of -.BR getpwuid () -and +from within a pseudo terminal. +For usage in a real application, you +should check the return values of +.BR getpwuid () +and .BR ttyname (). .PP .nf @@ -122,7 +131,7 @@ and #include #include -int +int main(int argc, char *argv[]) { struct utmp entry; @@ -195,7 +204,8 @@ 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 +\fIutmp\fP structure is already large enough. +The functions \fIgetutxent\fP etc. are aliases for \fIgetutent\fP etc. .SH "SEE ALSO" .BR utmp (5), diff --git a/man3/getw.3 b/man3/getw.3 index b24cfd38d..d3d9da74f 100644 --- a/man3/getw.3 +++ b/man3/getw.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. diff --git a/man3/getwchar.3 b/man3/getwchar.3 index f9d80608a..595008317 100644 --- a/man3/getwchar.3 +++ b/man3/getwchar.3 @@ -23,9 +23,12 @@ getwchar \- read a wide character from standard input .fi .SH DESCRIPTION The \fBgetwchar\fP() function is the wide-character equivalent of the -\fBgetchar\fP() function. It reads a wide character from \fBstdin\fP and returns -it. If the end of stream is reached, or if \fIferror(stdin)\fP becomes -true, it returns WEOF. If a wide character conversion error occurs, it sets +\fBgetchar\fP() function. +It reads a wide character from \fBstdin\fP and returns +it. +If the end of stream is reached, or if \fIferror(stdin)\fP becomes +true, it returns WEOF. +If a wide character conversion error occurs, it sets \fIerrno\fP to \fBEILSEQ\fP and returns WEOF. .PP For a non-locking counterpart, see diff --git a/man3/glob.3 b/man3/glob.3 index 363e49c52..24c03fcaa 100644 --- a/man3/glob.3 +++ b/man3/glob.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -106,8 +106,8 @@ slots will be reserved at the beginning of the list of strings in which means that, if no pattern matches, to return the original pattern, .TP .B GLOB_APPEND -which means to append to the results of a previous call. Do not set -this flag on the first invocation of +which means to append to the results of a previous call. +Do not set this flag on the first invocation of .BR glob (). .TP .B GLOB_NOESCAPE @@ -153,29 +153,30 @@ a pointer to the path which failed, and the value of .I errno as returned from one of the calls to -.BR opendir (), -.BR readdir (), -or +.BR opendir (), +.BR readdir (), +or .BR stat (). -If +If .I errfunc returns non-zero, or if .B GLOB_ERR -is set, +is set, .BR glob () will terminate after the call to .IR errfunc . .PP -Upon successful return, +Upon successful return, .I pglob->gl_pathc contains the number of matched pathnames and .I pglob->gl_pathv -a pointer to the list of matched pathnames. The first pointer after -the last pathname is NULL. +a pointer to the list of matched pathnames. +The first pointer after the last pathname is NULL. .PP It is possible to call .BR glob () -several times. In that case, the +several times. +In that case, the .B GLOB_APPEND flag has to be set in .I flags @@ -187,7 +188,7 @@ is set to the flags specified, \fBor\fRed with .B GLOB_MAGCHAR if any metacharacters were found. .SH "RETURN VALUE" -On successful completion, +On successful completion, .BR glob () returns zero. Other possible returns are: @@ -224,7 +225,7 @@ POSIX.2, POSIX.1-2001. The .BR glob () function may fail due to failure of underlying function calls, such as -.BR malloc () +.BR malloc () or .BR opendir (). These will store their error code in diff --git a/man3/grantpt.3 b/man3/grantpt.3 index 597f901a6..7a2641617 100644 --- a/man3/grantpt.3 +++ b/man3/grantpt.3 @@ -26,7 +26,7 @@ The behavior of .BR grantpt () is unspecified if a signal handler is installed to catch SIGCHLD signals. .SH "RETURN VALUE" -When successful, +When successful, .BR grantpt () returns 0. Otherwise, it returns \-1 and sets .I errno diff --git a/man3/gsignal.3 b/man3/gsignal.3 index 88d58f44a..32e1160a3 100644 --- a/man3/gsignal.3 +++ b/man3/gsignal.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,7 +45,8 @@ respectively. .LP Elsewhere, on System V-like systems, these functions implement software signalling, entirely independent of the classical -signal and kill functions. The function +signal and kill functions. +The function .BR ssignal () defines the action to take when the software signal with number diff --git a/man3/hash.3 b/man3/hash.3 index 5c68ceada..71e54b9a0 100644 --- a/man3/hash.3 +++ b/man3/hash.3 @@ -31,7 +31,7 @@ .\" .\" @(#)hash.3 8.6 (Berkeley) 8/18/94 .\" -.TH HASH 3 1994-08-18 +.TH HASH 3 1994-08-18 .UC 7 .SH NAME hash \- hash database access method @@ -114,7 +114,7 @@ value. .TP lorder The byte order for integers in the stored database metadata. -The number should represent the order as an integer; for example, +The number should represent the order as an integer; for example, big endian order would be the number 4,321. If .I lorder diff --git a/man3/hsearch.3 b/man3/hsearch.3 index b89d09041..98d866b52 100644 --- a/man3/hsearch.3 +++ b/man3/hsearch.3 @@ -46,7 +46,7 @@ hcreate, hdestroy, hsearch \- hash table management .sp .BI "int hcreate_r(size_t " nel ", struct hsearch_data *" tab ); .sp -.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" ret , +.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" ret , .BI " struct hsearch_data *" tab ); .sp .BI "void hdestroy_r(struct hsearch_data *" tab ); @@ -74,9 +74,9 @@ The argument \fIitem\fP is of type \fBENTRY\fP, which is a typedef defined in .RS .sp .nf -typedef struct entry { +typedef struct entry { char *\fIkey\fP; - void *\fIdata\fP; + void *\fIdata\fP; } ENTRY; .RE .fi @@ -89,7 +89,8 @@ item with the same key as \fIitem\fP (where "the same" is determined using .BR strcmp (3)), and if successful returns a pointer to it. The argument \fIaction\fP determines what \fBhsearch\fP() does -after an unsuccessful search. A value of \fBENTER\fP instructs it to +after an unsuccessful search. +A value of \fBENTER\fP instructs it to insert a copy of \fIitem\fP, while a value of \fBFIND\fP means to return NULL. .PP @@ -98,7 +99,8 @@ The three functions .BR hsearch_r (), .BR hdestroy_r () are reentrant versions that allow the use of more than one table. -The last argument used identifies the table. The struct it points to +The last argument used identifies the table. +The struct it points to must be zeroed before the first call to .BR hcreate_r (). .SH "RETURN VALUE" @@ -140,7 +142,8 @@ are GNU extensions. .SH BUGS SVr4 and POSIX.1-2001 specify that \fIaction\fP is significant only for unsuccessful searches, so that an ENTER -should not do anything for a successful search. The libc and glibc +should not do anything for a successful search. +The libc and glibc implementations update the \fIdata\fP for the given \fIkey\fP in this case. .\" Tue Jan 29 09:27:40 2002: fixed in latest glibc snapshot @@ -155,25 +158,25 @@ some of them. #include #include #include - + char *data[] = { "alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel", "india", "juliet", "kilo", "lima", "mike", "november", "oscar", "papa", "quebec", "romeo", "sierra", "tango", "uniform", - "victor", "whisky", "x-ray", "yankee", "zulu" + "victor", "whisky", "x-ray", "yankee", "zulu" }; -int -main(void) +int +main(void) { ENTRY e, *ep; int i; - + /* starting with small table, and letting it grow does not work */ hcreate(30); for (i = 0; i < 24; i++) { - e.key = data[i]; - /* data is just an integer, instead of a + e.key = data[i]; + /* data is just an integer, instead of a pointer to something */ e.data = (void *)i; ep = hsearch(e, ENTER); diff --git a/man3/hypot.3 b/man3/hypot.3 index 774a391d2..44162a468 100644 --- a/man3/hypot.3 +++ b/man3/hypot.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -58,7 +58,7 @@ or the distance of the point from the origin. .SH "CONFORMING TO" SVr4, 4.3BSD, C99. -The +The .I float and .I "long double" diff --git a/man3/iconv.3 b/man3/iconv.3 index d79ac964b..23fe54215 100644 --- a/man3/iconv.3 +++ b/man3/iconv.3 @@ -7,7 +7,7 @@ .\" .\" References consulted: .\" GNU glibc-2 source code and manual -.\" OpenGroup's Single Unix specification +.\" OpenGroup's Single Unix specification .\" http://www.UNIX-systems.org/online.html .\" .\" 2000-06-30 correction by Yuichi SATO @@ -41,34 +41,40 @@ each character conversion it increments \fI*inbuf\fP and decrements output bytes, and it updates the conversion state contained in \fIcd\fP. The conversion can stop for four reasons: .PP -1. An invalid multibyte sequence is encountered in the input. In this case +1. An invalid multibyte sequence is encountered in the input. +In this case it sets \fIerrno\fP to \fBEILSEQ\fP and returns (size_t)(\-1). \fI*inbuf\fP is left pointing to the beginning of the invalid multibyte sequence. .PP 2. The input byte sequence has been entirely converted, i.e. \fI*inbytesleft\fP -has gone down to 0. In this case \fBiconv\fP() returns the number of +has gone down to 0. +In this case \fBiconv\fP() returns the number of non-reversible conversions performed during this call. .PP 3. An incomplete multibyte sequence is encountered in the input, and the -input byte sequence terminates after it. In this case it sets \fIerrno\fP to +input byte sequence terminates after it. +In this case it sets \fIerrno\fP to \fBEINVAL\fP and returns (size_t)(\-1). \fI*inbuf\fP is left pointing to the beginning of the incomplete multibyte sequence. .PP -4. The output buffer has no more room for the next converted character. In -this case it sets \fIerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). +4. The output buffer has no more room for the next converted character. +In this case it sets \fIerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). .PP A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but -\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the +\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. +In this case, the \fBiconv\fP() function attempts to set \fIcd\fP's conversion state to the initial state and store a corresponding shift sequence at \fI*outbuf\fP. At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. If the output buffer has no more room for this reset sequence, it sets -\fIerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). Otherwise it increments +\fIerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). +Otherwise it increments \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes written. .PP A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and -\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the \fBiconv\fP() +\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. +In this case, the \fBiconv\fP() function sets \fIcd\fP's conversion state to the initial state. .SH "RETURN VALUE" The \fBiconv\fP() function returns the number of characters converted in a diff --git a/man3/iconv_open.3 b/man3/iconv_open.3 index 17a76f5db..7a0faab3a 100644 --- a/man3/iconv_open.3 +++ b/man3/iconv_open.3 @@ -24,22 +24,28 @@ for converting byte sequences from character encoding \fIfromcode\fP to character encoding \fItocode\fP. .PP The values permitted for \fIfromcode\fP and \fItocode\fP and the supported -combinations are system dependent. For the GNU C library, the permitted +combinations are system dependent. +For the GNU C library, the permitted values are listed by the \fBiconv \-\-list\fP command, and all combinations of the listed values are supported. .PP The resulting conversion descriptor can be used with \fBiconv\fP() any number -of times. It remains valid until deallocated using \fBiconv_close\fP(). +of times. +It remains valid until deallocated using \fBiconv_close\fP(). .PP -A conversion descriptor contains a conversion state. After creation using -\fBiconv_open\fP(), the state is in the initial state. Using \fBiconv\fP() -modifies the descriptor's conversion state. (This implies that a conversion -descriptor can not be used in multiple threads simultaneously.) To bring the -state back to the initial state, use \fBiconv\fP() with NULL as \fIinbuf\fP -argument. +A conversion descriptor contains a conversion state. +After creation using +\fBiconv_open\fP(), the state is in the initial state. +Using \fBiconv\fP() +modifies the descriptor's conversion state. +(This implies that a conversion +descriptor can not be used in multiple threads simultaneously.) +To bring the state back to the initial state, use \fBiconv\fP() +with NULL as \fIinbuf\fP argument. .SH "RETURN VALUE" The \fBiconv_open\fP() function returns a freshly allocated conversion -descriptor. In case of error, it sets \fIerrno\fP and returns (iconv_t)(\-1). +descriptor. +In case of error, it sets \fIerrno\fP and returns (iconv_t)(\-1). .SH ERRORS The following error can occur, among others: .TP diff --git a/man3/ilogb.3 b/man3/ilogb.3 index de346cada..1ed02ff3d 100644 --- a/man3/ilogb.3 +++ b/man3/ilogb.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,7 +37,8 @@ ilogb, ilogbf, ilogbl \- get integer exponent of a floating point value Link with \-lm. .SH DESCRIPTION These functions return the exponent part of their argument -as a signed integer. When no error occurs, these functions +as a signed integer. +When no error occurs, these functions are equivalent to the corresponding .BR logb () functions, cast to (int). @@ -51,7 +52,8 @@ In order to check for errors, set .I errno to zero and call .I feclearexcept(FE_ALL_EXCEPT) -before calling these functions. On return, if +before calling these functions. +On return, if .I errno is non-zero or .I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) diff --git a/man3/index.3 b/man3/index.3 index 8d000008f..aaa9a3192 100644 --- a/man3/index.3 +++ b/man3/index.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/inet.3 b/man3/inet.3 index 6cdde291c..06a42c48d 100644 --- a/man3/inet.3 +++ b/man3/inet.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,7 +34,7 @@ .\" .TH INET 3 2001-07-25 "BSD" "Linux Programmer's Manual" .SH NAME -inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, +inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, inet_netof \- Internet address manipulation routines .SH SYNOPSIS .nf @@ -64,7 +64,8 @@ non-zero if the address is valid, zero if not. .PP The \fBinet_addr\fP() function converts the Internet host address \fIcp\fP from numbers-and-dots notation into binary data in network -byte order. If the input is invalid, INADDR_NONE (usually \-1) is returned. +byte order. +If the input is invalid, INADDR_NONE (usually \-1) is returned. This is an \fIobsolete\fP interface to \fBinet_aton\fP(), described immediately above; it is obsolete because \-1 is a valid address (255.255.255.255), and \fBinet_aton\fP() provides a cleaner way @@ -72,12 +73,13 @@ to indicate error return. .PP The \fBinet_network\fP() function extracts a number in host byte order suitable for use as an Internet address -from \fIcp\fP, which is a string in numbers-and-dots notation. +from \fIcp\fP, which is a string in numbers-and-dots notation. If the input is invalid, \-1 is returned. .PP The \fBinet_ntoa\fP() function converts the Internet host address \fIin\fP given in network byte order to a string in standard -numbers-and-dots notation. The string is returned in a statically +numbers-and-dots notation. +The string is returned in a statically allocated buffer, which subsequent calls will overwrite. .PP The \fBinet_makeaddr\fP() function makes an Internet host address @@ -86,11 +88,13 @@ with the local address \fIhost\fP in network \fInet\fP, both in local host byte order. .PP The \fBinet_lnaof\fP() function returns the local host address part -of the Internet address \fIin\fP. The local host address is returned +of the Internet address \fIin\fP. +The local host address is returned in local host byte order. .PP The \fBinet_netof\fP() function returns the network number part of -the Internet Address \fIin\fP. The network number is returned in +the Internet Address \fIin\fP. +The network number is returned in local host byte order. .PP The structure \fIin_addr\fP as used in \fBinet_ntoa\fP(), @@ -111,13 +115,13 @@ Internet, is Most Significant Byte first (big endian). .SH NOTE When you using numbers-and-dots notation for addresses, be aware that each number will be interpreted as octal -if preceded by a 0 and as hexadecimal if preceded by 0x. +if preceded by a 0 and as hexadecimal if preceded by 0x. For example, \fBinet_aton("226.000.000.037", &t)\fP will interpret the address as \fI226.0.0.31\fP and not \fI226.0.0.37\fP. .SH "GLIBC NOTES" -In order to expose the declaration of +In order to expose the declaration of .BR inet_aton (), -one of the feature test macros _BSD_SOURCE, _SVID_SOURCE, or +one of the feature test macros _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE must be defined. .SH "CONFORMING TO" 4.3BSD. diff --git a/man3/inet_ntop.3 b/man3/inet_ntop.3 index 7e56f8d37..89ed1ed49 100644 --- a/man3/inet_ntop.3 +++ b/man3/inet_ntop.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/inet_pton.3 b/man3/inet_pton.3 index ec055e183..cb4277e18 100644 --- a/man3/inet_pton.3 +++ b/man3/inet_pton.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/infnan.3 b/man3/infnan.3 index 7c147b96a..41bb8961c 100644 --- a/man3/infnan.3 +++ b/man3/infnan.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,7 +41,8 @@ infnan \- deal with infinite or not-a-number (NaN) result Link with \-lm. .SH DESCRIPTION The \fBinfnan\fP() function returns a suitable value for infinity and -"not-a-number" (NaN) results. The value of \fIerror\fP can be ERANGE +"not-a-number" (NaN) results. +The value of \fIerror\fP can be ERANGE to represent infinity or anything else to represent NaN. \fIerrno\fP is also set. .SH NOTES diff --git a/man3/initgroups.3 b/man3/initgroups.3 index e9de58467..c71a9bcae 100644 --- a/man3/initgroups.3 +++ b/man3/initgroups.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,7 +40,8 @@ initgroups \- initialize the supplementary group access list .SH DESCRIPTION The \fBinitgroups\fP() function initializes the group access list by reading the group database \fI/etc/group\fP and using all groups of -which \fIuser\fP is a member. The additional group \fIgroup\fP is +which \fIuser\fP is a member. +The additional group \fIgroup\fP is also added to the list. The @@ -57,7 +58,8 @@ is set appropriately. Insufficient memory to allocate group information structure. .TP .B EPERM -The calling process has insufficient privilege. See the underlying system call +The calling process has insufficient privilege. +See the underlying system call .BR setgroups (2). .SH FILES .nf diff --git a/man3/insque.3 b/man3/insque.3 index fbc332979..9091b6866 100644 --- a/man3/insque.3 +++ b/man3/insque.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,13 +39,14 @@ insque, remque \- insert/remove an item from a queue .BI "void remque(void *" elem ); .SH DESCRIPTION \fBinsque\fP() and \fBremque\fP() are functions for manipulating -doubly-linked lists. Each element in the list is a structure of +doubly-linked lists. +Each element in the list is a structure of which the first two structure elements are a forward and a backward pointer. \fBinsque\fP() inserts the element pointed to by \fIelem\fP immediately after the element pointed to by \fIprev\fP, which must -not be NULL. +not be NULL. \fBremque\fP() removes the element pointed to by \fIelem\fP from the doubly-linked list. @@ -54,7 +55,7 @@ POSIX.1-2001 .SH "HISTORICAL NOTES" Traditionally (e.g. SunOS, Linux libc 4,5) the parameters of these functions were of type \fIstruct qelem *\fP, where the struct -is defined as +is defined as .RS .nf @@ -70,6 +71,8 @@ This is still what you will get if _GNU_SOURCE is defined before including . The location of the prototypes for these functions differs among several -versions of UNIX. The above is the POSIX version. -Some systems place them in . Linux libc4,5 placed them +versions of UNIX. +The above is the POSIX version. +Some systems place them in . +Linux libc4,5 placed them in . diff --git a/man3/intro.3 b/man3/intro.3 index 62d6e2fcd..ea76f55c4 100644 --- a/man3/intro.3 +++ b/man3/intro.3 @@ -27,7 +27,7 @@ intro \- Introduction to library functions .SH DESCRIPTION This chapter describes all library functions excluding the library -functions described in chapter 2, which implement system calls. +functions described in chapter 2, which implement system calls. .\" There .\" are various function groups which can be identified by a letter which .\" is appended to the chapter number: @@ -55,7 +55,8 @@ functions described in chapter 2, which implement system calls. .\" specify the library names. .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! .SH "SEE ALSO" .BR intro (2), .BR errno (3), diff --git a/man3/isalpha.3 b/man3/isalpha.3 index 68546a22e..335882927 100644 --- a/man3/isalpha.3 +++ b/man3/isalpha.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -28,8 +28,8 @@ .\" .TH ISALPHA 3 1995-09-02 "GNU" "Linux Programmer's Manual" .SH NAME -isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, -isprint, ispunct, isspace, isupper, isxdigit \- character +isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, +isprint, ispunct, isspace, isupper, isxdigit \- character classification routines .SH SYNOPSIS .nf @@ -69,19 +69,19 @@ which must have the value of an or .BR EOF , falls into a certain character class according to the current locale. -.TP +.TP .BR isalnum () checks for an alphanumeric character; it is equivalent to .BI "(isalpha(" c ") || isdigit(" c "))" \fR. .TP .BR isalpha () -checks for an alphabetic character; in the standard \fB"C"\fP +checks for an alphabetic character; in the standard \fB"C"\fP locale, it is equivalent to .BI "(isupper(" c ") || islower(" c "))" \fR. In some locales, there may be additional characters for which .BR isalpha () is true\(emletters which are neither upper case nor lower -case. +case. .TP .BR isascii () checks whether \fIc\fP is a 7-bit @@ -112,7 +112,8 @@ checks for any printable character which is not a space or an alphanumeric character. .TP .BR isspace () -checks for white-space characters. In the +checks for white-space characters. +In the .B """C""" and .B """POSIX""" @@ -137,18 +138,19 @@ checks for a hexadecimal digits, i.e. one of .SH "RETURN VALUE" The values returned are non-zero if the character .I c -falls into the tested class, and a zero value +falls into the tested class, and a zero value if not. .SH "CONFORMING TO" C99, 4.3BSD. -C89 specifies all of these functions except \fBisascii\fP() and +C89 specifies all of these functions except \fBisascii\fP() and \fBisblank\fP(). \fBisascii\fP() is a BSD extension and is also an SVr4 extension. \fBisblank\fP() conforms to POSIX.1-2001 and C99 7.4.1.3. .SH NOTE The details of what characters belong into which class depend on the current -locale. For example, +locale. +For example, .BR isupper () will not recognize an A-umlaut (\(:A) as an uppercase letter in the default .B "C" diff --git a/man3/isatty.3 b/man3/isatty.3 index 759272500..8ef1c9b46 100644 --- a/man3/isatty.3 +++ b/man3/isatty.3 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:38:23 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt .TH ISATTY 3 1995-04-20 "Linux" "Linux Programmer's Manual" diff --git a/man3/isgreater.3 b/man3/isgreater.3 index 54e81f5e3..f7df3afb6 100644 --- a/man3/isgreater.3 +++ b/man3/isgreater.3 @@ -27,8 +27,11 @@ to test a relation Compile with \-std=c99; link with \-lm. .SH DESCRIPTION The normal relation operations (like less) will fail if one of the -operands is NaN. This will cause an exception. To avoid this, C99 defines -these macros. The macros are guaranteed to evaluate their operands only once. +operands is NaN. +This will cause an exception. +To avoid this, C99 defines +these macros. +The macros are guaranteed to evaluate their operands only once. The operand can be of any real floating-point type. .TP isgreater() @@ -36,7 +39,7 @@ determines (x) > (y) without an exception if x or y is NaN. .TP isgreaterequal() determines (x) >= (y) without an exception if x or y is NaN. -.TP +.TP isless() determines (x) < (y) without an exception if x or y is NaN. .TP @@ -52,7 +55,8 @@ isunordered() is true if x or y is NaN and false otherwise. .SH NOTE Not all hardware supports these functions, and where it doesn't, they -will be emulated by macros. This will give you a performance penalty. +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 diff --git a/man3/iswalnum.3 b/man3/iswalnum.3 index d93a0116d..907e8a5f0 100644 --- a/man3/iswalnum.3 +++ b/man3/iswalnum.3 @@ -22,7 +22,8 @@ iswalnum \- test for alphanumeric wide character .fi .SH DESCRIPTION The \fBiswalnum\fP() function is the wide-character equivalent of the -\fBisalnum\fP() function. It tests whether \fIwc\fP is a wide character +\fBisalnum\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "alnum". .PP The wide character class "alnum" is a subclass of the wide character class @@ -39,14 +40,16 @@ The wide character class "alnum" is disjoint from the wide character class "punct". .PP The wide character class "alnum" is the union of the wide character classes -"alpha" and "digit". As such, it also contains the wide character class +"alpha" and "digit". +As such, it also contains the wide character class "xdigit". .PP The wide character class "alnum" always contains at least the letters 'A' to 'Z', 'a' to 'z' and the digits '0' to '9'. .SH "RETURN VALUE" The \fBiswalnum\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "alnum". Otherwise it returns zero. +belonging to the wide character class "alnum". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswalpha.3 b/man3/iswalpha.3 index 4da154a1f..969d942e9 100644 --- a/man3/iswalpha.3 +++ b/man3/iswalpha.3 @@ -22,7 +22,8 @@ iswalpha \- test for alphabetic wide character .fi .SH DESCRIPTION The \fBiswalpha\fP() function is the wide-character equivalent of the -\fBisalpha\fP() function. It tests whether \fIwc\fP is a wide character +\fBisalpha\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "alpha". .PP The wide character class "alpha" is a subclass of the wide character class @@ -49,7 +50,8 @@ The wide character class "alpha" always contains at least the letters 'A' to 'Z' and 'a' to 'z'. .SH "RETURN VALUE" The \fBiswalpha\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "alpha". Otherwise it returns zero. +belonging to the wide character class "alpha". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswblank.3 b/man3/iswblank.3 index cf1016ab4..ae150c6d3 100644 --- a/man3/iswblank.3 +++ b/man3/iswblank.3 @@ -22,7 +22,8 @@ iswblank \- test for whitespace wide character .fi .SH DESCRIPTION The \fBiswblank\fP() function is the wide-character equivalent of the -\fBisblank\fP() function. It tests whether \fIwc\fP is a wide character +\fBisblank\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "blank". .PP The wide character class "blank" is a subclass of the wide character class @@ -37,7 +38,8 @@ The wide character class "blank" always contains at least the space character and the control character '\\t'. .SH "RETURN VALUE" The \fBiswblank\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "blank". Otherwise it returns zero. +belonging to the wide character class "blank". +Otherwise it returns zero. .SH "CONFORMING TO" This function is a GNU extension. .SH "SEE ALSO" diff --git a/man3/iswcntrl.3 b/man3/iswcntrl.3 index 0ec0d9a13..126c53bd5 100644 --- a/man3/iswcntrl.3 +++ b/man3/iswcntrl.3 @@ -22,7 +22,8 @@ iswcntrl \- test for control wide character .fi .SH DESCRIPTION The \fBiswcntrl\fP() function is the wide-character equivalent of the -\fBiscntrl\fP() function. It tests whether \fIwc\fP is a wide character +\fBiscntrl\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "cntrl". .PP The wide character class "cntrl" is disjoint from the wide character class @@ -33,7 +34,8 @@ For an unsigned char \fIc\fP, \fIiscntrl(c)\fP implies \fIiswcntrl(btowc(c))\fP, but not vice versa. .SH "RETURN VALUE" The \fBiswcntrl\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "cntrl". Otherwise it returns zero. +belonging to the wide character class "cntrl". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswctype.3 b/man3/iswctype.3 index 8356af6f1..9c0cc4b1d 100644 --- a/man3/iswctype.3 +++ b/man3/iswctype.3 @@ -23,14 +23,17 @@ iswctype \- wide character classification .SH DESCRIPTION If \fIwc\fP is a wide character having the character property designated by \fIdesc\fP (or in other words: belongs to the character class designated by -\fIdesc\fP), the \fBiswctype\fP() function returns non-zero. Otherwise it -returns zero. If \fIwc\fP is WEOF, zero is returned. +\fIdesc\fP), the \fBiswctype\fP() function returns non-zero. +Otherwise it +returns zero. +If \fIwc\fP is WEOF, zero is returned. .PP \fIdesc\fP must be a character property descriptor returned by the \fBwctype\fP function. .SH "RETURN VALUE" The \fBiswctype\fP() function returns non-zero if the \fIwc\fP has the designated -property. Otherwise it returns 0. +property. +Otherwise it returns 0. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswdigit.3 b/man3/iswdigit.3 index 2a00ae800..aa7d0d6cd 100644 --- a/man3/iswdigit.3 +++ b/man3/iswdigit.3 @@ -22,7 +22,8 @@ iswdigit \- test for decimal digit wide character .fi .SH DESCRIPTION The \fBiswdigit\fP() function is the wide-character equivalent of the -\fBisdigit\fP() function. It tests whether \fIwc\fP is a wide character +\fBisdigit\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "digit". .PP The wide character class "digit" is a subclass of the wide character class @@ -45,7 +46,8 @@ The wide character class "digit" is disjoint from the wide character class The wide character class "digit" always contains exactly the digits '0' to '9'. .SH "RETURN VALUE" The \fBiswdigit\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "digit". Otherwise it returns zero. +belonging to the wide character class "digit". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswgraph.3 b/man3/iswgraph.3 index a7512f323..b64f3fffd 100644 --- a/man3/iswgraph.3 +++ b/man3/iswgraph.3 @@ -22,7 +22,8 @@ iswgraph \- test for graphic wide character .fi .SH DESCRIPTION The \fBiswgraph\fP() function is the wide-character equivalent of the -\fBisgraph\fP() function. It tests whether \fIwc\fP is a wide character +\fBisgraph\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "graph". .PP The wide character class "graph" is a subclass of the wide character class @@ -42,7 +43,8 @@ wide character class "print" except the space character. It therefore contains the wide character classes "alnum" and "punct". .SH "RETURN VALUE" The \fBiswgraph\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "graph". Otherwise it returns zero. +belonging to the wide character class "graph". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswlower.3 b/man3/iswlower.3 index 8fc71f3f5..ac871ec5e 100644 --- a/man3/iswlower.3 +++ b/man3/iswlower.3 @@ -22,7 +22,8 @@ iswlower \- test for lowercase wide character .fi .SH DESCRIPTION The \fBiswlower\fP() function is the wide-character equivalent of the -\fBislower\fP() function. It tests whether \fIwc\fP is a wide character +\fBislower\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "lower". .PP The wide character class "lower" is a subclass of the wide character class @@ -49,7 +50,8 @@ The wide character class "lower" always contains at least the letters 'a' to 'z'. .SH "RETURN VALUE" The \fBiswlower\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "lower". Otherwise it returns zero. +belonging to the wide character class "lower". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswprint.3 b/man3/iswprint.3 index b10659b53..87f5ffc43 100644 --- a/man3/iswprint.3 +++ b/man3/iswprint.3 @@ -22,7 +22,8 @@ iswprint \- test for printing wide character .fi .SH DESCRIPTION The \fBiswprint\fP() function is the wide-character equivalent of the -\fBisprint\fP() function. It tests whether \fIwc\fP is a wide character +\fBisprint\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "print". .PP The wide character class "print" is disjoint from the wide character class @@ -31,7 +32,8 @@ The wide character class "print" is disjoint from the wide character class The wide character class "print" contains the wide character class "graph". .SH "RETURN VALUE" The \fBiswprint\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "print". Otherwise it returns zero. +belonging to the wide character class "print". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswpunct.3 b/man3/iswpunct.3 index 64272212d..cf720e891 100644 --- a/man3/iswpunct.3 +++ b/man3/iswpunct.3 @@ -22,7 +22,8 @@ iswpunct \- test for punctuation or symbolic wide character .fi .SH DESCRIPTION The \fBiswpunct\fP() function is the wide-character equivalent of the -\fBispunct\fP() function. It tests whether \fIwc\fP is a wide character +\fBispunct\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "punct". .PP The wide character class "punct" is a subclass of the wide character class @@ -40,7 +41,8 @@ Being a subclass of the wide character class "graph", the wide character class "blank". .SH "RETURN VALUE" The \fBiswpunct\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "punct". Otherwise it returns zero. +belonging to the wide character class "punct". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswspace.3 b/man3/iswspace.3 index 668160106..a2b94142d 100644 --- a/man3/iswspace.3 +++ b/man3/iswspace.3 @@ -22,7 +22,8 @@ iswspace \- test for whitespace wide character .fi .SH DESCRIPTION The \fBiswspace\fP() function is the wide-character equivalent of the -\fBisspace\fP() function. It tests whether \fIwc\fP is a wide character +\fBisspace\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "space". .PP The wide character class "space" is disjoint from the wide character class @@ -38,7 +39,8 @@ The wide character class "space" always contains at least the space character and the control characters '\\f', '\\n', '\\r', '\\t', '\\v'. .SH "RETURN VALUE" The \fBiswspace\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "space". Otherwise it returns zero. +belonging to the wide character class "space". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswupper.3 b/man3/iswupper.3 index 60b3bd79f..ce9cd38e2 100644 --- a/man3/iswupper.3 +++ b/man3/iswupper.3 @@ -22,7 +22,8 @@ iswupper \- test for uppercase wide character .fi .SH DESCRIPTION The \fBiswupper\fP() function is the wide-character equivalent of the -\fBisupper\fP() function. It tests whether \fIwc\fP is a wide character +\fBisupper\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "upper". .PP The wide character class "upper" is a subclass of the wide character class @@ -49,7 +50,8 @@ The wide character class "upper" always contains at least the letters 'A' to 'Z'. .SH "RETURN VALUE" The \fBiswupper\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "upper". Otherwise it returns zero. +belonging to the wide character class "upper". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/iswxdigit.3 b/man3/iswxdigit.3 index eb3200288..b4a37a05c 100644 --- a/man3/iswxdigit.3 +++ b/man3/iswxdigit.3 @@ -22,7 +22,8 @@ iswxdigit \- test for hexadecimal digit wide character .fi .SH DESCRIPTION The \fBiswxdigit\fP() function is the wide-character equivalent of the -\fBisxdigit\fP() function. It tests whether \fIwc\fP is a wide character +\fBisxdigit\fP() function. +It tests whether \fIwc\fP is a wide character belonging to the wide character class "xdigit". .PP The wide character class "xdigit" is a subclass of the wide character class @@ -43,7 +44,8 @@ The wide character class "xdigit" always contains at least the letters 'A' to 'F', 'a' to 'f' and the digits '0' to '9'. .SH "RETURN VALUE" The \fBiswxdigit\fP() function returns non-zero if \fIwc\fP is a wide character -belonging to the wide character class "xdigit". Otherwise it returns zero. +belonging to the wide character class "xdigit". +Otherwise it returns zero. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/j0.3 b/man3/j0.3 index 564946771..0fa1b2694 100644 --- a/man3/j0.3 +++ b/man3/j0.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -77,26 +77,29 @@ y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- Bessel functions Link with \-lm. .SH DESCRIPTION The \fBj0\fP() and \fBj1\fP() functions return Bessel functions of \fIx\fP -of the first kind of orders 0 and 1, respectively. The \fBjn\fP() function +of the first kind of orders 0 and 1, respectively. +The \fBjn\fP() function returns the Bessel function of \fIx\fP of the first kind of order \fIn\fP. .PP The \fBy0\fP() and \fBy1\fP() functions return Bessel functions of \fIx\fP -of the second kind of orders 0 and 1, respectively. The \fByn\fP() function +of the second kind of orders 0 and 1, respectively. +The \fByn\fP() function returns the Bessel function of \fIx\fP of the second kind of order \fIn\fP. .PP For the functions \fBy0\fP(), \fBy1\fP() and \fByn\fP(), the value of \fIx\fP -must be positive. For negative values of \fIx\fP, these functions return +must be positive. +For negative values of \fIx\fP, these functions return \-HUGE_VAL. .PP The \fBj0f\fP() etc. and \fBj0l\fP() etc. functions are versions that take -and return -.I float -and +and return +.I float +and .I "long double" values, respectively. .SH "CONFORMING TO" -The functions returning -.I double +The functions returning +.I double conform to SVr4, 4.3BSD, POSIX.1-2001. .SH BUGS diff --git a/man3/key_setsecret.3 b/man3/key_setsecret.3 index 14dc99887..66cc8f638 100644 --- a/man3/key_setsecret.3 +++ b/man3/key_setsecret.3 @@ -23,13 +23,15 @@ key_secretkey_is_set \- interfaces to rpc keyserver daemon .B "int key_secretkey_is_set(void);" .SH DESCRIPTION The functions here are used within the RPC's secure authentication -mechanism (AUTH_DES). There should be no need for user programs to +mechanism (AUTH_DES). +There should be no need for user programs to use this functions. The function -.BR key_decryptsession () -uses the (remote) server netname and takes the DES key -for decrypting. It uses the public key of the server and the +.BR key_decryptsession () +uses the (remote) server netname and takes the DES key +for decrypting. +It uses the public key of the server and the secret key associated with the effective UID of the calling process. The function @@ -40,20 +42,22 @@ It encrypts the DES keys with the public key of the server and the secret key associated with the effective UID of the calling process. The function -.BR key_gendes () +.BR key_gendes () is used to ask the keyserver for a secure conversation key. The function -.BR key_setsecret () -is used to set the key for the effective UID of the calling process. +.BR key_setsecret () +is used to set the key for the effective UID of the calling process. 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. +set for the effective UID of the calling process. .SH NOTE -Note that we talk about two types of encryption here. One is -asymmetric using a public and secret key. The other is symmetric, the +Note that we talk about two types of encryption here. +One is +asymmetric using a public and secret key. +The other is symmetric, the 64-bit DES. .br The routines were part of the linux/doors-project, abandoned by now. diff --git a/man3/killpg.3 b/man3/killpg.3 index 861945a73..7d4a6735b 100644 --- a/man3/killpg.3 +++ b/man3/killpg.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. diff --git a/man3/ldexp.3 b/man3/ldexp.3 index 747650464..9376d150f 100644 --- a/man3/ldexp.3 +++ b/man3/ldexp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,7 +51,7 @@ by 2 raised to the power .IR exp . .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/lgamma.3 b/man3/lgamma.3 index 77a452a57..1692b748f 100644 --- a/man3/lgamma.3 +++ b/man3/lgamma.3 @@ -50,7 +50,8 @@ In order to check for errors, set .I errno to zero and call .I feclearexcept(FE_ALL_EXCEPT) -before calling these functions. On return, if +before calling these functions. +On return, if .I errno is non-zero or .I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) diff --git a/man3/localeconv.3 b/man3/localeconv.3 index 2f93eae62..8b136a2ad 100644 --- a/man3/localeconv.3 +++ b/man3/localeconv.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -35,7 +35,8 @@ The .BR localeconv () function returns a pointer to a .I struct lconv -for the current locale. This structure is shown in +for the current locale. +This structure is shown in .BR locale (7), and contains all values associated with the locale categories .B LC_NUMERIC diff --git a/man3/lockf.3 b/man3/lockf.3 index 8b9a45e7c..049030f7a 100644 --- a/man3/lockf.3 +++ b/man3/lockf.3 @@ -65,8 +65,8 @@ blocks until the previous lock is released. If this section overlaps an earlier locked section, both are merged. File locks are released as soon as the process holding the locks -closes some file descriptor for the file. A child process does not -inherit these locks. +closes some file descriptor for the file. +A child process does not inherit these locks. .TP .B F_TLOCK Same as @@ -83,12 +83,13 @@ Test the lock: return 0 if the specified section is unlocked or locked by this process; return \-1, set .I errno to -.BR EAGAIN +.BR EAGAIN .RB ( EACCES on some other systems), if another process holds a lock. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man3/log.3 b/man3/log.3 index 98b4a2d8f..74c90893b 100644 --- a/man3/log.3 +++ b/man3/log.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -53,11 +53,12 @@ The \fBlog\fP() function can return the following errors: The argument \fIx\fP is negative. .TP .B ERANGE -The argument \fIx\fP is zero. The log of zero is not defined +The argument \fIx\fP is zero. +The log of zero is not defined (minus infinity). .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/log10.3 b/man3/log10.3 index 14abcd685..a277c0dec 100644 --- a/man3/log10.3 +++ b/man3/log10.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -53,10 +53,11 @@ The \fBlog10\fP() function can return the following errors: The argument \fIx\fP is negative. .TP .B ERANGE -The argument \fIx\fP is zero. The log of zero is not defined. +The argument \fIx\fP is zero. +The log of zero is not defined. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/log1p.3 b/man3/log1p.3 index 76a95ca77..617e58b9d 100644 --- a/man3/log1p.3 +++ b/man3/log1p.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,7 +34,7 @@ log1p \- logarithm of 1 plus argument .BI "float log1pf(float " x ); .br .BI "long double log1pl(long double " x ); -.sp +.sp .fi Compile with \-std=c99; link with \-lm. .SH DESCRIPTION @@ -43,7 +43,7 @@ returns a value equivalent to `log (1 + \fIx\fP)'. It is computed in a way that is accurate even if the value of \fIx\fP is near zero. .SH "CONFORMING TO" BSD, C99. -The +The .I float and .I "long double" diff --git a/man3/log2.3 b/man3/log2.3 index 404ddf977..8c0ea0125 100644 --- a/man3/log2.3 +++ b/man3/log2.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -53,11 +53,12 @@ The \fBlog2\fP() function can return the following error: The argument \fIx\fP is negative. .TP .B ERANGE -The argument \fIx\fP is zero. The log of zero is not defined +The argument \fIx\fP is zero. +The log of zero is not defined (minus infinity). .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/logb.3 b/man3/logb.3 index 939afe4a4..91926da94 100644 --- a/man3/logb.3 +++ b/man3/logb.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,17 +38,18 @@ Link with \-lm. .SH DESCRIPTION These functions extract the exponent of .I x -and return it as a floating-point value. If +and return it as a floating-point value. +If .B FLT_RADIX -is two, -.BI logb( x ) +is two, +.BI logb( x ) is equal to .BI floor(log2( x ))\fR, except it's probably faster. .LP If .I x -is de-normalized, +is de-normalized, .BR logb () returns the exponent .I x @@ -71,7 +72,8 @@ In order to check for errors, set .I errno to zero and call .I feclearexcept(FE_ALL_EXCEPT) -before calling these functions. On return, if +before calling these functions. +On return, if .I errno is non-zero or .I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) diff --git a/man3/login.3 b/man3/login.3 index 424612208..eac7a64e4 100644 --- a/man3/login.3 +++ b/man3/login.3 @@ -32,7 +32,8 @@ login, logout \- write utmp and wtmp entries .BI "int logout(const char *" ut_line ); .SH DESCRIPTION The utmp file records who is currently using the system. -The wtmp file records all logins and logouts. See +The wtmp file records all logins and logouts. +See .BR utmp (5). .LP The function @@ -69,7 +70,8 @@ The .BR logout () function searches the utmp file for an entry matching the .I ut_line -argument. If a record is found, it is updated by zeroing out the +argument. +If a record is found, it is updated by zeroing out the .I ut_name and .I ut_host @@ -92,8 +94,8 @@ to your compiler command line. Note that the member .I ut_user -of -.I struct utmp +of +.I struct utmp is called .I ut_name in BSD. Therefore, @@ -112,7 +114,7 @@ user accounting database, configured through _PATH_UTMP in user accounting log file, configured through _PATH_WTMP in .I .SH "CONFORMING TO" -Not in POSIX.1-2001. +Not in POSIX.1-2001. Present on the BSDs. .SH "SEE ALSO" .BR getutent (3), diff --git a/man3/longjmp.3 b/man3/longjmp.3 index 70699adc2..f8aadb83a 100644 --- a/man3/longjmp.3 +++ b/man3/longjmp.3 @@ -39,14 +39,17 @@ longjmp, siglongjmp \- non-local jump to a saved stack context \fBlongjmp\fP() and \fBsetjmp\fP() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. \fBlongjmp\fP() restores the environment saved by the last call of -\fBsetjmp\fP() with the corresponding \fIenv\fP argument. After +\fBsetjmp\fP() with the corresponding \fIenv\fP argument. +After \fBlongjmp\fP() is completed, program execution continues as if the corresponding call of \fBsetjmp\fP() had just returned the value -\fIval\fP. \fBlongjmp\fP() cannot cause 0 to be returned. If longjmp +\fIval\fP. \fBlongjmp\fP() cannot cause 0 to be returned. +If \fBlongjmp\fP() is invoked with a second argument of 0, 1 will be returned instead. .P \fBsiglongjmp\fP() is similar to \fBlongjmp\fP() except for the type of -its \fIenv\fP argument. If the \fBsigsetjmp\fP() call that set this +its \fIenv\fP argument. +If the \fBsigsetjmp\fP() call that set this \fIenv\fP used a non-zero \fIsavesigs\fP flag, \fBsiglongjmp\fP() also restores the set of blocked signals. .SH "RETURN VALUE" @@ -56,11 +59,13 @@ C89, C99, and POSIX.1-2001 specify \fBlongjmp\fP(). POSIX.1-2001 specifies \fBsiglongjmp\fP(). .SH NOTES POSIX does not specify whether \fBlongjmp\fP() will restore the signal -context. If you want to save and restore signal masks, use +context. +If you want to save and restore signal masks, use \fBsiglongjmp\fP(). .P \fBlongjmp\fP() and \fBsiglongjmp\fP() make programs hard to -understand and maintain. If possible an alternative should be used. +understand and maintain. +If possible an alternative should be used. .SH "SEE ALSO" .BR setjmp (3), .BR sigsetjmp (3) diff --git a/man3/lrint.3 b/man3/lrint.3 index 0b7c0cbbd..543902a28 100644 --- a/man3/lrint.3 +++ b/man3/lrint.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/lround.3 b/man3/lround.3 index 60b0f74f4..c9084873d 100644 --- a/man3/lround.3 +++ b/man3/lround.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,13 +16,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .TH LROUND 3 2001-05-31 "" "Linux Programmer's Manual" .SH NAME -lround, lroundf, lroundl, llround, llroundf, llroundl \- round to +lround, lroundf, lroundl, llround, llroundf, llroundl \- round to nearest integer, away from zero .SH SYNOPSIS .nf diff --git a/man3/lsearch.3 b/man3/lsearch.3 index 848cc5a1a..f4fe16cec 100644 --- a/man3/lsearch.3 +++ b/man3/lsearch.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,7 +42,8 @@ lfind, lsearch \- linear search of an array .SH DESCRIPTION \fBlfind\fP() and \fBlsearch\fP() perform a linear search for \fIkey\fP in the array \fIbase\fP which has *\fInmemb\fP elements of -\fIsize\fP bytes each. The comparison function referenced by +\fIsize\fP bytes each. +The comparison function referenced by \fIcompar\fP is expected to have two arguments which point to the \fIkey\fP object and to an array member, in that order, and which returns zero if the \fIkey\fP object matches the array member, and diff --git a/man3/lseek64.3 b/man3/lseek64.3 index c0e507885..646d653b4 100644 --- a/man3/lseek64.3 +++ b/man3/lseek64.3 @@ -94,7 +94,8 @@ The library routine .BR lseek64 () uses a 64-bit type even when .I off_t -is a 32-bit type. Its prototype (and the type +is a 32-bit type. +Its prototype (and the type .IR off64_t ) is available only when one compiles with .nf @@ -128,7 +129,8 @@ is available in libc5 and glibc and works without special defines. Its prototype was given in .I with libc5, but glibc does not provide a prototype. -This is bad, since a prototype is needed. Users should add +This is bad, since a prototype is needed. +Users should add the above prototype, or something equivalent, to their own source. When users complained about data loss caused by a miscompilation of .BR e2fsck (8), diff --git a/man3/makecontext.3 b/man3/makecontext.3 index 965d4489b..9d22d4be1 100644 --- a/man3/makecontext.3 +++ b/man3/makecontext.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,19 +44,19 @@ For the type and the first two functions, see The \fBmakecontext\fP() function modifies the context pointed to by \fIucp\fP (which was obtained from a call to \fBgetcontext\fP()). Before invoking \fBmakecontext\fP(), the caller must allocate a new stack -for this context and assign its address to \fIucp->uc_stack\fP, +for this context and assign its address to \fIucp->uc_stack\fP, and define a successor context and assign its address to \fIucp->uc_link\fP. When this context is later activated (using \fBsetcontext\fP() or \fBswapcontext\fP()) the function \fIfunc\fP is called, -and passed the series of integer +and passed the series of integer .RI ( int ) arguments that follow .IR argc ; the caller must specify the number of these arguments in .IR argc . -When this function returns, the successor context is activated. +When this function returns, the successor context is activated. If the successor context pointer is NULL, the thread exits. .LP The \fBswapcontext\fP() function saves the current context in @@ -64,7 +64,8 @@ the structure pointed to by \fIoucp\fP, and then activates the context pointed to by \fIucp\fP. .SH "RETURN VALUE" When successful, \fBswapcontext\fP() -does not return. (But we may return later, in case \fIoucp\fP is +does not return. +(But we may return later, in case \fIoucp\fP is activated, in which case it looks like \fBswapcontext\fP() returns 0.) On error, \fBswapcontext\fP() returns \-1 and sets \fIerrno\fP appropriately. @@ -77,7 +78,7 @@ The interpretation of \fIucp->uc_stack\fP is just as in .BR sigaltstack (2), namely, this struct contains the start and length of a memory area to be used as the stack, regardless of the direction of growth of -the stack. +the stack. Thus, it is not necessary for the user program to worry about this direction. .SH "CONFORMING TO" diff --git a/man3/malloc.3 b/man3/malloc.3 index 9fd71caed..eb695edc0 100644 --- a/man3/malloc.3 +++ b/man3/malloc.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -41,17 +41,17 @@ calloc, malloc, free, realloc \- Allocate and free dynamic memory .fi .SH DESCRIPTION .BR calloc () -allocates memory for an array of +allocates memory for an array of .I nmemb -elements of +elements of .I size -bytes each and returns a pointer to the allocated memory. +bytes each and returns a pointer to the allocated memory. The memory is set to zero. .PP .BR malloc () allocates .I size -bytes and returns a pointer to the allocated memory. +bytes and returns a pointer to the allocated memory. The memory is not cleared. .PP .BR free () @@ -81,8 +81,8 @@ If .I ptr is NULL, the call is equivalent to .BR malloc(size) ; -if -.I size +if +.I size is equal to zero, the call is equivalent to .BI "free(" "ptr" ) . @@ -98,8 +98,8 @@ If the area pointed to was moved, a is done. .SH "RETURN VALUE" For -.BR calloc () -and +.BR calloc () +and .BR malloc (), the value returned is a pointer to the allocated memory, which is suitably aligned for any kind of variable, or NULL if the request fails. @@ -111,12 +111,13 @@ returns no value. returns a pointer to the newly allocated memory, which is suitably aligned for any kind of variable and may be different from .IR ptr , -or NULL if the request fails. +or NULL if the request fails. If .I size was equal to 0, either NULL or a pointer suitable to be passed to .BR free () -is returned. If +is returned. +If .BR realloc () fails the original block is left untouched; it is not freed or moved. .SH "CONFORMING TO" @@ -132,7 +133,8 @@ and .BR realloc () to set .I errno -to ENOMEM upon failure. Glibc assumes that this is done +to ENOMEM upon failure. +Glibc assumes that this is done (and the glibc versions of these routines do this); if you use a private malloc implementation that does not set .IR errno , @@ -151,14 +153,16 @@ an allocated chunk or freeing the same pointer twice. .PP Recent versions of Linux libc (later than 5.4.23) and GNU libc (2.x) include a malloc implementation which is tunable via environment -variables. When +variables. +When .BR MALLOC_CHECK_ is set, a special (less efficient) implementation is used which is designed to be tolerant against simple errors, such as double calls of .BR free () with the same argument, or overruns of a single byte (off-by-one -bugs). Not all such errors can be protected against, however, and +bugs). +Not all such errors can be protected against, however, and memory leaks can result. If .BR MALLOC_CHECK_ @@ -166,7 +170,8 @@ is set to 0, any detected heap corruption is silently ignored; if set to 1, a diagnostic is printed on stderr; if set to 2, .BR abort () -is called immediately. This can be useful because otherwise +is called immediately. +This can be useful because otherwise a crash may happen much later, and the true cause for the problem is then very hard to track down. .SH BUGS @@ -174,7 +179,8 @@ By default, Linux follows an optimistic memory allocation strategy. This means that when .BR malloc () returns non-NULL there is no guarantee that the memory really -is available. This is a really bad bug. +is available. +This is a really bad bug. In case it turns out that the system is out of memory, one or more processes will be killed by the infamous OOM killer. In case Linux is employed under circumstances where it would be diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3 index 4e20eb8d7..f53b5d986 100644 --- a/man3/malloc_hook.3 +++ b/man3/malloc_hook.3 @@ -5,24 +5,24 @@ .TH MALLOC_HOOK 3 2002-07-20 "GNU" "Linux Programmer's Manual" .SH NAME __malloc_hook, __malloc_initialize_hook, -__memalign_hook, __free_hook, __realloc_hook, +__memalign_hook, __free_hook, __realloc_hook, __after_morecore_hook \- malloc debugging variables .SH SYNOPSIS .sp .BR "#include " .sp -.BI "void *(*__malloc_hook)(size_t " size , +.BI "void *(*__malloc_hook)(size_t " size , .BI "const void *" caller ); .sp -.BI "void *(*__realloc_hook)(void *" ptr , -.BI "size_t " size , +.BI "void *(*__realloc_hook)(void *" ptr , +.BI "size_t " size , .BI "const void *" caller ); .sp .BI "void *(*__memalign_hook)(size_t " alignment , .BI "size_t " size , .BI "const void *" caller ); .sp -.BI "void (*__free_hook)(void *" ptr , +.BI "void (*__free_hook)(void *" ptr , .BI "const void *" caller ); .sp .BI "void (*__malloc_initialize_hook)(void);" @@ -34,14 +34,16 @@ The GNU C library lets you modify the behavior of .BR realloc (), and .BR free () -by specifying appropriate hook functions. You can use these hooks +by specifying appropriate hook functions. +You can use these hooks to help you debug programs that use dynamic memory allocation, for example. .LP The variable .B __malloc_initialize_hook points at a function that is called once when the malloc implementation -is initialized. This is a weak variable, so it can be overridden in +is initialized. +This is a weak variable, so it can be overridden in the application with a definition like the following: .br .nf @@ -79,26 +81,26 @@ Here is a short example of how to use these variables. .nf #include #include - + /* Prototypes for our hooks. */ static void my_init_hook(void); static void *my_malloc_hook(size_t, const void *); /* Variables to save original hooks. */ static void *(*old_malloc_hook)(size_t, const void *); - + /* Override initialising hook from the C library. */ void (*__malloc_initialize_hook) (void) = my_init_hook; static void -my_init_hook(void) +my_init_hook(void) { old_malloc_hook = __malloc_hook; __malloc_hook = my_malloc_hook; } static void * -my_malloc_hook(size_t size, const void *caller) +my_malloc_hook(size_t size, const void *caller) { void *result; diff --git a/man3/mblen.3 b/man3/mblen.3 index 1c3a8a440..66d5a4f4c 100644 --- a/man3/mblen.3 +++ b/man3/mblen.3 @@ -23,18 +23,22 @@ mblen \- determine number of bytes in next multibyte character .SH DESCRIPTION If \fIs\fP is not a NULL pointer, the \fBmblen\fP() function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP and extracts the -next complete multibyte character. It uses a static anonymous shift state only -known to the mblen function. If the multibyte character is not the null wide -character, it returns the number of bytes that were consumed from \fIs\fP. If -the multibyte character is the null wide character, it returns 0. +next complete multibyte character. +It uses a static anonymous shift state only +known to the mblen function. +If the multibyte character is not the null wide +character, it returns the number of bytes that were consumed from \fIs\fP. +If the multibyte character is the null wide character, it returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, \fBmblen\fP() returns \fI-1\fP. This can happen even if +character, \fBmblen\fP() returns \fI-1\fP. +This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP If the multibyte string starting at \fIs\fP contains an invalid multibyte -sequence before the next complete character, \fBmblen\fP() also returns \fI-1\fP. +sequence before the next complete character, \fBmblen\fP() +also returns \fI-1\fP. .PP If \fIs\fP is a NULL pointer, the \fBmblen\fP() function .\" The Dinkumware doc and the Single Unix specification say this, but @@ -43,9 +47,11 @@ resets the shift state, only known to this function, to the initial state, and returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "RETURN VALUE" -The \fBmblen\fP() function returns the number of bytes parsed from the multibyte +The \fBmblen\fP() function returns the number of +bytes parsed from the multibyte sequence starting at \fIs\fP, if a non-null wide character was recognized. -It returns 0, if a null wide character was recognized. It returns \-1, if an +It returns 0, if a null wide character was recognized. +It returns \-1, if an invalid multibyte sequence was encountered or if it couldn't parse a complete multibyte character. .SH "CONFORMING TO" diff --git a/man3/mbrlen.3 b/man3/mbrlen.3 index f485e7362..4bc21b8fd 100644 --- a/man3/mbrlen.3 +++ b/man3/mbrlen.3 @@ -23,29 +23,36 @@ mbrlen \- determine number of bytes in next multibyte character .SH DESCRIPTION The \fBmbrlen\fP() function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP and extracts the next complete multibyte character. -It updates the shift state \fI*ps\fP. If the multibyte character is not the +It updates the shift state \fI*ps\fP. +If the multibyte character is not the null wide character, it returns the number of bytes that were consumed from -\fIs\fP. If the multibyte character is the null wide character, it resets the +\fIs\fP. +If the multibyte character is the null wide character, it resets the shift state \fI*ps\fP to the initial state and returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, \fBmbrlen\fP() returns \fI(size_t)(\-2)\fP. This can happen even if +character, \fBmbrlen\fP() returns \fI(size_t)(\-2)\fP. +This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP If the multibyte string starting at \fIs\fP contains an invalid multibyte sequence before the next complete character, \fBmbrlen\fP() returns -\fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP. In this case, +\fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP. +In this case, the effects on \fI*ps\fP are undefined. .PP If \fIps\fP is a NULL pointer, a static anonymous state only known to the mbrlen function is used instead. .SH "RETURN VALUE" -The \fBmbrlen\fP() function returns the number of bytes parsed from the multibyte +The \fBmbrlen\fP() function returns the number of bytes +parsed from the multibyte sequence starting at \fIs\fP, if a non-null wide character was recognized. -It returns 0, if a null wide character was recognized. It returns (size_t)(\-1) +It returns 0, if a null wide character was recognized. +It returns (size_t)(\-1) and sets \fIerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was -encountered. It returns (size_t)(\-2) if it couldn't parse a complete multibyte +encountered. +It returns (size_t)(\-2) if it couldn't parse a complete multibyte character, meaning that \fIn\fP should be increased. .SH "CONFORMING TO" C99 diff --git a/man3/mbrtowc.3 b/man3/mbrtowc.3 index 9aa03d35e..fdbed133a 100644 --- a/man3/mbrtowc.3 +++ b/man3/mbrtowc.3 @@ -23,33 +23,43 @@ mbrtowc \- convert a multibyte sequence to a wide character .fi .SH DESCRIPTION The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is -not NULL. In this case, the \fBmbrtowc\fP() function inspects at most \fIn\fP +not NULL. +In this case, the \fBmbrtowc\fP() function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP, extracts the next complete multibyte character, converts it to a wide character and stores it at -\fI*pwc\fP. It updates the shift state \fI*ps\fP. If the converted wide +\fI*pwc\fP. +It updates the shift state \fI*ps\fP. +If the converted wide character is not L'\\0', it returns the number of bytes that were consumed -from \fIs\fP. If the converted wide character is L'\\0', it resets the shift +from \fIs\fP. +If the converted wide character is L'\\0', it resets the shift state \fI*ps\fP to the initial state and returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, \fBmbrtowc\fP() returns \fI(size_t)(\-2)\fP. This can happen even if +character, \fBmbrtowc\fP() returns \fI(size_t)(\-2)\fP. +This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP If the multibyte string starting at \fIs\fP contains an invalid multibyte sequence before the next complete character, \fBmbrtowc\fP() returns -\fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP. In this case, +\fI(size_t)(\-1)\fP and sets \fIerrno\fP to \fBEILSEQ\fP. +In this case, the effects on \fI*ps\fP are undefined. .PP -A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this +A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. +In this case the \fBmbrtowc\fP() function behaves as above, excepts that it does not store the converted wide character in memory. .PP -A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are -ignored. If the conversion state represented by \fI*ps\fP denotes an +A third case is when \fIs\fP is NULL. +In this case, \fIpwc\fP and \fIn\fP are +ignored. +If the conversion state represented by \fI*ps\fP denotes an incomplete multibyte character conversion, the \fBmbrtowc\fP() function returns \fI(size_t)(\-1)\fP, sets \fIerrno\fP to \fBEILSEQ\fP, and -leaves \fI*ps\fP in an undefined state. Otherwise, the \fBmbrtowc\fP() function +leaves \fI*ps\fP in an undefined state. +Otherwise, the \fBmbrtowc\fP() function puts \fI*ps\fP in the initial state and returns 0. .PP In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous @@ -65,10 +75,11 @@ memset(&a, 0, sizeof(a)); The \fBmbrtowc\fP() function returns the number of bytes parsed from the multibyte sequence starting at \fIs\fP, if a non-L'\\0' wide character was recognized. -It returns 0, if a L'\\0' wide character was recognized. +It returns 0, if a L'\\0' wide character was recognized. It returns (size_t)(\-1) and sets \fIerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was -encountered. It returns (size_t)(\-2) if it couldn't parse a complete multibyte +encountered. +It returns (size_t)(\-2) if it couldn't parse a complete multibyte character, meaning that \fIn\fP should be increased. .SH "CONFORMING TO" C99 diff --git a/man3/mbsinit.3 b/man3/mbsinit.3 index 0262a164e..bd349b091 100644 --- a/man3/mbsinit.3 +++ b/man3/mbsinit.3 @@ -25,7 +25,8 @@ Character conversion between the multibyte representation and the wide character representation uses conversion state, of type \fBmbstate_t\fP. Conversion of a string uses a finite-state machine; when it is interrupted after the complete conversion of a number of characters, it may need to -save a state for processing the remaining characters. Such a conversion +save a state for processing the remaining characters. +Such a conversion state is needed for the sake of encodings such as ISO-2022 and UTF-7. .PP The initial state is the state at the beginning of conversion of a string. @@ -55,7 +56,8 @@ The function \fBmbsinit\fP() tests whether \fI*ps\fP corresponds to an initial state. .SH "RETURN VALUE" \fBmbsinit\fP() returns non-zero if \fI*ps\fP is an initial state, or if -\fIps\fP is a null pointer. Otherwise it returns 0. +\fIps\fP is a null pointer. +Otherwise it returns 0. .SH "CONFORMING TO" C99 .SH "SEE ALSO" diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 index c3dd0a99e..5ad4c7403 100644 --- a/man3/mbsnrtowcs.3 +++ b/man3/mbsnrtowcs.3 @@ -28,25 +28,31 @@ the number of bytes to be converted, starting at \fI*src\fP, is limited to If \fIdest\fP is not a NULL pointer, the \fBmbsnrtowcs\fP() function converts at most \fInms\fP bytes from the multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP. -At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state -\fI*ps\fP is updated. The conversion is effectively performed by repeatedly +At most \fIlen\fP wide characters are written to \fIdest\fP. +The shift state +\fI*ps\fP is updated. +The conversion is effectively performed by repeatedly calling mbrtowc(\fIdest\fP,\fI*src\fP,\fIn\fP,\fIps\fP) where \fIn\fP is some positive number, as long as this call succeeds, and then incrementing -\fIdest\fP by one and \fI*src\fP by the number of bytes consumed. The +\fIdest\fP by one and \fI*src\fP by the number of bytes consumed. +The conversion can stop for three reasons: .PP -1. An invalid multibyte sequence has been encountered. In this case \fI*src\fP +1. An invalid multibyte sequence has been encountered. +In this case \fI*src\fP is left pointing to the invalid multibyte sequence, (size_t)(\-1) is returned, and \fIerrno\fP is set to \fBEILSEQ\fP. .PP 2. The \fInms\fP limit forces a stop, or \fIlen\fP non-L'\\0' wide characters -have been stored at \fIdest\fP. In this case \fI*src\fP is left pointing to the +have been stored at \fIdest\fP. +In this case \fI*src\fP is left pointing to the next multibyte sequence to be converted, and the number of wide characters written to \fIdest\fP is returned. .PP 3. The multibyte string has been completely converted, including the terminating '\\0' (which has the side effect of bringing back \fI*ps\fP to the -initial state). In this case \fI*src\fP is set to NULL, and the number of wide +initial state). +In this case \fI*src\fP is set to NULL, and the number of wide characters written to \fIdest\fP, excluding the terminating L'\\0' character, is returned. .PP @@ -62,7 +68,8 @@ characters at \fIdest\fP. .SH "RETURN VALUE" The \fBmbsnrtowcs\fP() function returns the number of wide characters that make up the converted part of the wide character string, not including the -terminating null wide character. If an invalid multibyte sequence was +terminating null wide character. +If an invalid multibyte sequence was encountered, (size_t)(\-1) is returned, and \fIerrno\fP set to \fBEILSEQ\fP. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3 index 302a61a9b..087a9ddcc 100644 --- a/man3/mbsrtowcs.3 +++ b/man3/mbsrtowcs.3 @@ -24,24 +24,29 @@ mbsrtowcs \- convert a multibyte string to a wide character string .SH DESCRIPTION If \fIdest\fP is not a NULL pointer, the \fBmbsrtowcs\fP() function converts the multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP. -At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state -\fI*ps\fP is updated. The conversion is effectively performed by repeatedly +At most \fIlen\fP wide characters are written to \fIdest\fP. +The shift state +\fI*ps\fP is updated. +The conversion is effectively performed by repeatedly calling mbrtowc(\fIdest\fP,\fI*src\fP,\fIn\fP,\fIps\fP) where \fIn\fP is some positive number, as long as this call succeeds, and then incrementing -\fIdest\fP by one and \fI*src\fP by the number of bytes consumed. The -conversion can stop for three reasons: +\fIdest\fP by one and \fI*src\fP by the number of bytes consumed. +The conversion can stop for three reasons: .PP -1. An invalid multibyte sequence has been encountered. In this case \fI*src\fP +1. An invalid multibyte sequence has been encountered. +In this case \fI*src\fP is left pointing to the invalid multibyte sequence, (size_t)(\-1) is returned, and \fIerrno\fP is set to \fBEILSEQ\fP. .PP -2. \fIlen\fP non-L'\\0' wide characters have been stored at \fIdest\fP. In this +2. \fIlen\fP non-L'\\0' wide characters have been stored at \fIdest\fP. +In this case \fI*src\fP is left pointing to the next multibyte sequence to be converted, and the number of wide characters written to \fIdest\fP is returned. .PP 3. The multibyte string has been completely converted, including the terminating '\\0' (which has the side effect of bringing back \fI*ps\fP to the -initial state). In this case \fI*src\fP is set to NULL, and the number of wide +initial state). +In this case \fI*src\fP is set to NULL, and the number of wide characters written to \fIdest\fP, excluding the terminating L'\\0' character, is returned. .PP @@ -57,7 +62,8 @@ characters at \fIdest\fP. .SH "RETURN VALUE" The \fBmbsrtowcs\fP() function returns the number of wide characters that make up the converted part of the wide character string, not including the -terminating null wide character. If an invalid multibyte sequence was +terminating null wide character. +If an invalid multibyte sequence was encountered, (size_t)(\-1) is returned, and \fIerrno\fP set to \fBEILSEQ\fP. .SH "CONFORMING TO" C99 diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 index fb7901c86..e5b15d906 100644 --- a/man3/mbstowcs.3 +++ b/man3/mbstowcs.3 @@ -21,20 +21,26 @@ mbstowcs \- convert a multibyte string to a wide character string .BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n ); .fi .SH DESCRIPTION -If \fIdest\fP is not a NULL pointer, the \fBmbstowcs\fP() function converts the +If \fIdest\fP is not a NULL pointer, +the \fBmbstowcs\fP() function converts the multibyte string \fIsrc\fP to a wide-character string starting at \fIdest\fP. -At most \fIn\fP wide characters are written to \fIdest\fP. The conversion starts -in the initial state. The conversion can stop for three reasons: +At most \fIn\fP wide characters are written to \fIdest\fP. +The conversion starts +in the initial state. +The conversion can stop for three reasons: .PP -1. An invalid multibyte sequence has been encountered. In this case +1. An invalid multibyte sequence has been encountered. +In this case (size_t)(\-1) is returned. .PP -2. \fIn\fP non-L'\\0' wide characters have been stored at \fIdest\fP. In this +2. \fIn\fP non-L'\\0' wide characters have been stored at \fIdest\fP. +In this case the number of wide characters written to \fIdest\fP is returned, but the shift state at this point is lost. .PP 3. The multibyte string has been completely converted, including the -terminating '\\0'. In this case the number of wide characters written to +terminating '\\0'. +In this case the number of wide characters written to \fIdest\fP, excluding the terminating L'\\0' character, is returned. .PP The programmer must ensure that there is room for at least \fIn\fP wide @@ -49,7 +55,8 @@ greater or equal to \fImbstowcs(NULL,src,0)+1\fP. .SH "RETURN VALUE" The \fBmbstowcs\fP() function returns the number of wide characters that make up the converted part of the wide character string, not including the -terminating null wide character. If an invalid multibyte sequence was +terminating null wide character. +If an invalid multibyte sequence was encountered, (size_t)(\-1) is returned. .SH "CONFORMING TO" C99 diff --git a/man3/mbtowc.3 b/man3/mbtowc.3 index 5fc1d4826..4480253e1 100644 --- a/man3/mbtowc.3 +++ b/man3/mbtowc.3 @@ -22,27 +22,36 @@ mbtowc \- convert a multibyte sequence to a wide character .fi .SH DESCRIPTION The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is -not NULL. In this case, the \fBmbtowc\fP() function inspects at most \fIn\fP -bytes of the multibyte string starting at \fIs\fP, extracts the next complete +not NULL. +In this case, the \fBmbtowc\fP() function inspects at most \fIn\fP +bytes of the multibyte string starting at \fIs\fP, +extracts the next complete multibyte character, converts it to a wide character and stores it at -\fI*pwc\fP. It updates an internal shift state only known to the mbtowc -function. If \fIs\fP does not point to a '\\0' byte, it returns the number +\fI*pwc\fP. +It updates an internal shift state only known to the mbtowc +function. +If \fIs\fP does not point to a '\\0' byte, it returns the number of bytes that were consumed from \fIs\fP, otherwise it returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte character, or if they contain an invalid multibyte sequence, \fBmbtowc\fP() -returns \fI-1\fP. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, +returns \fI-1\fP. +This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP -A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this +A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. +In this case the \fBmbtowc\fP() function behaves as above, excepts that it does not store the converted wide character in memory. .PP -A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are -ignored. The \fBmbtowc\fP() function +A third case is when \fIs\fP is NULL. +In this case, \fIpwc\fP and \fIn\fP are +ignored. +The \fBmbtowc\fP() function .\" The Dinkumware doc and the Single Unix specification say this, but .\" glibc doesn't implement this. -resets the shift state, only known to this function, to the initial state, and +resets the shift state, only known to this function, +to the initial state, and returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "RETURN VALUE" @@ -50,7 +59,8 @@ If \fIs\fP is not NULL, the \fBmbtowc\fP() function returns the number of consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte, or \-1 upon failure. .PP -If \fIs\fP is NULL, the \fBmbtowc\fP() function returns non-zero if the encoding +If \fIs\fP is NULL, the \fBmbtowc\fP() function +returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "CONFORMING TO" C99 @@ -62,5 +72,6 @@ C99 The behaviour of \fBmbtowc\fP() depends on the LC_CTYPE category of the current locale. .PP -This function is not multi-thread safe. The function \fBmbrtowc\fP() provides +This function is not multi-thread safe. +The function \fBmbrtowc\fP() provides a better interface to the same functionality. diff --git a/man3/memccpy.3 b/man3/memccpy.3 index 0219ef9c5..ac9fb4908 100644 --- a/man3/memccpy.3 +++ b/man3/memccpy.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,12 +35,12 @@ memccpy \- copy memory area .BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n ); .fi .SH DESCRIPTION -The \fBmemccpy\fP() function copies no more than \fIn\fP bytes from +The \fBmemccpy\fP() function copies no more than \fIn\fP bytes from memory area \fIsrc\fP to memory area \fIdest\fP, stopping when the character \fIc\fP is found. .SH "RETURN VALUE" The \fBmemccpy\fP() function returns a pointer to the next character -in \fIdest\fP after \fIc\fP, or NULL if \fIc\fP was not found in the +in \fIdest\fP after \fIc\fP, or NULL if \fIc\fP was not found in the first \fIn\fP characters of \fIsrc\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C99 diff --git a/man3/memchr.3 b/man3/memchr.3 index 556539ae3..8c4017eb4 100644 --- a/man3/memchr.3 +++ b/man3/memchr.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,15 +36,15 @@ memchr, memrchr \- scan memory for a character .BI "void *memrchr(const void *" s ", int " c ", size_t " n ); .fi .SH DESCRIPTION -The +The .BR memchr () function scans the first \fIn\fP bytes of the memory area pointed to by \fIs\fP for the character \fIc\fP. The first byte to match \fIc\fP (interpreted as an unsigned character) stops the operation. .PP -The +The .BR memrchr () -function is like the +function is like the .BR memchr () function, except that it searches backwards from the end of the \fIn\fP bytes @@ -54,10 +54,10 @@ The \fBmemchr\fP() and \fBmemrchr\fP() functions return a pointer to the matching byte or NULL if the character does not occur in the given memory area. .SH "CONFORMING TO" -The +The .BR memchr () function conforms to SVr4, 4.3BSD, C89, C99, POSIX.1-2001. -The +The .BR memrchr () function is a GNU extension, available since glibc 2.1.91. .SH "SEE ALSO" diff --git a/man3/memcmp.3 b/man3/memcmp.3 index 83a6c34cb..aad84b7ba 100644 --- a/man3/memcmp.3 +++ b/man3/memcmp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,8 +40,8 @@ memory areas \fIs1\fP and \fIs2\fP. It returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .SH "RETURN VALUE" -The \fBmemcmp\fP() function returns an integer less than, equal to, or -greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, +The \fBmemcmp\fP() function returns an integer less than, equal to, or +greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, respectively, to be less than, to match, or be greater than the first \fIn\fP bytes of \fIs2\fP. .SH "CONFORMING TO" diff --git a/man3/memcpy.3 b/man3/memcpy.3 index d2aa97617..0b64de37a 100644 --- a/man3/memcpy.3 +++ b/man3/memcpy.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,8 +36,9 @@ memcpy \- copy memory area .fi .SH DESCRIPTION The \fBmemcpy\fP() function copies \fIn\fP bytes from memory area -\fIsrc\fP to memory area \fIdest\fP. The memory areas should not -overlap. Use \fBmemmove\fP(3) if the memory areas do overlap. +\fIsrc\fP to memory area \fIdest\fP. +The memory areas should not overlap. +Use \fBmemmove\fP(3) if the memory areas do overlap. .SH "RETURN VALUE" The \fBmemcpy\fP() function returns a pointer to \fIdest\fP. .SH "CONFORMING TO" diff --git a/man3/memfrob.3 b/man3/memfrob.3 index fb4e7ec42..7c4437907 100644 --- a/man3/memfrob.3 +++ b/man3/memfrob.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,7 +37,7 @@ memfrob \- frobnicate (encrypt) a memory area .SH DESCRIPTION The \fBmemfrob\fP() function encrypts the first \fIn\fP bytes of the memory area \fIs\fP by exclusive-ORing each character with the number -42. The effect can be reversed by using \fBmemfrob\fP() on the +42. The effect can be reversed by using \fBmemfrob\fP() on the encrypted memory area. .PP Note that this function is not a proper encryption routine as the XOR @@ -46,7 +46,7 @@ constant is fixed, and is only suitable for hiding strings. The \fBmemfrob\fP() function returns a pointer to the encrypted memory area. .SH "CONFORMING TO" -The \fBmemfrob\fP() function is unique to the +The \fBmemfrob\fP() function is unique to the GNU C Library. .SH "SEE ALSO" .BR strfry (3) diff --git a/man3/memmem.3 b/man3/memmem.3 index c0aac5955..9d0df6e77 100644 --- a/man3/memmem.3 +++ b/man3/memmem.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -52,7 +52,8 @@ This function is a GNU extension. This function was broken in Linux libraries up to and including libc 5.0.9; there the `needle' and `haystack' arguments were interchanged, and a pointer to the end of the first occurrence of \fIneedle\fP -was returned. Since libc 5.0.9 is still widely used, this is a +was returned. +Since libc 5.0.9 is still widely used, this is a dangerous function to use. .br Both old and new libc's have the bug that if \fIneedle\fP is empty diff --git a/man3/memmove.3 b/man3/memmove.3 index ed795c696..4c6f2a34b 100644 --- a/man3/memmove.3 +++ b/man3/memmove.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/mempcpy.3 b/man3/mempcpy.3 index 465fe11f6..dc382c9c9 100644 --- a/man3/mempcpy.3 +++ b/man3/mempcpy.3 @@ -21,17 +21,18 @@ mempcpy, wmempcpy \- copy memory area .BI "wchar_t *wmempcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The +The .BR mempcpy () function is nearly identical to the .BR memcpy () -function. It copies -.I n +function. +It copies +.I n bytes from the object beginning at -.I src -into the object pointed to by -.IR dest . -But instead of returning the value of +.I src +into the object pointed to by +.IR dest . +But instead of returning the value of .I dest it returns a pointer to the byte following the last written byte. .PP @@ -50,7 +51,7 @@ wide characters. .SH "EXAMPLE" .nf void * -combine(void *o1, size_t s1, void *o2, size_t s2) +combine(void *o1, size_t s1, void *o2, size_t s2) { void *result = malloc(s1 + s2); if (result != NULL) diff --git a/man3/memset.3 b/man3/memset.3 index 663b58287..a6f64b449 100644 --- a/man3/memset.3 +++ b/man3/memset.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/mkdtemp.3 b/man3/mkdtemp.3 index cb71fff7c..ff677f7f9 100644 --- a/man3/mkdtemp.3 +++ b/man3/mkdtemp.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .TH MKDTEMP 3 2001-10-07 "GNU" "Linux Programmer's Manual" @@ -32,9 +32,11 @@ mkdtemp \- create a unique temporary directory .fi .SH DESCRIPTION The \fBmkdtemp\fP() function generates a uniquely-named temporary -directory from \fItemplate\fP. The last six characters of \fItemplate\fP +directory from \fItemplate\fP. +The last six characters of \fItemplate\fP must be XXXXXX and these are replaced with a string that makes the -directory name unique. The directory is then created with +directory name unique. +The directory is then created with permissions 0700. Since it will be modified, .I template diff --git a/man3/mkfifo.3 b/man3/mkfifo.3 index 033d6a34e..bba675533 100644 --- a/man3/mkfifo.3 +++ b/man3/mkfifo.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,26 +36,29 @@ mkfifo \- make a FIFO special file (a named pipe) .fi .SH DESCRIPTION \fBmkfifo\fP() makes a FIFO special file with name \fIpathname\fP. -\fImode\fP specifies the FIFO's permissions. It is modified by the +\fImode\fP specifies the FIFO's permissions. +It is modified by the process's \fBumask\fP in the usual way: the permissions of the created file are \fB(\fP\fImode\fP\fB & ~umask)\fP. .PP A FIFO special file is similar to a pipe, except that it is created -in a different way. Instead of being an anonymous communications +in a different way. +Instead of being an anonymous communications channel, a FIFO special file is entered into the file system by calling \fBmkfifo\fP(). .PP Once you have created a FIFO special file in this way, any process can open it for reading or writing, in the same way as an ordinary file. However, it has to be open at both ends simultaneously before you can -proceed to do any input or output operations on it. Opening a FIFO -for reading normally blocks until some other process opens the same -FIFO for writing, and vice versa. See +proceed to do any input or output operations on it. +Opening a FIFO for reading normally blocks until some +other process opens the same FIFO for writing, and vice versa. +See .BR fifo (7) for non-blocking handling of FIFO special files. .SH "RETURN VALUE" -On success \fImkfifo\fP() returns 0. In -the case of an error, -1 is returned (in which case, \fIerrno\fP +On success \fImkfifo\fP() returns 0. +In the case of an error, -1 is returned (in which case, \fIerrno\fP is set appropriately). .SH ERRORS .TP @@ -69,7 +72,8 @@ One of the directories in \fIpathname\fP did not allow search .B ENAMETOOLONG Either the total length of \fIpathname\fP is greater than \fBPATH_MAX\fP, or an individual filename component has a length -greater than \fBNAME_MAX\fP. In the GNU system, there is no imposed +greater than \fBNAME_MAX\fP. +In the GNU system, there is no imposed limit on overall filename length, but some file systems may place limits on the length of a component. .TP diff --git a/man3/mkfifoat.3 b/man3/mkfifoat.3 index 5a8635b7d..603931964 100644 --- a/man3/mkfifoat.3 +++ b/man3/mkfifoat.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,37 +40,37 @@ system call operates in exactly the same way as .BR mkfifo (3), except for the differences described in this manual page. -If the pathname given in +If the pathname given in .I pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor -.IR dirfd -(rather than relative to the current working directory of +.IR dirfd +(rather than relative to the current working directory of the calling process, as is done by .BR mkfifo (3) for a relative pathname). If .I pathname -is relative and +is relative and .I dirfd is the special value .BR AT_FDCWD , -then -.I pathname -is interpreted relative to the current working +then +.I pathname +is interpreted relative to the current working directory of the calling process (like .BR mkfifo (3)). If .IR pathname -is absolute, then -.I dirfd +is absolute, then +.I dirfd is ignored. .SH "RETURN VALUE" On success, -.BR mkfifoat () -returns 0. +.BR mkfifoat () +returns 0. On error, \-1 is returned and .I errno is set to indicate the error. @@ -79,7 +79,7 @@ The same errors that occur for .BR mkfifo (3) can also occur for .BR mkfifoat (). -The following additional errors can occur for +The following additional errors can occur for .BR mkfifoat (): .TP .B EBADF diff --git a/man3/mkstemp.3 b/man3/mkstemp.3 index 47f421277..c69b1fbb3 100644 --- a/man3/mkstemp.3 +++ b/man3/mkstemp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,14 +41,15 @@ mkstemp \- create a unique temporary file The \fBmkstemp\fP() function generates a unique temporary filename from \fItemplate\fP. The last six characters of \fItemplate\fP must be XXXXXX and these are replaced with a string that makes the -filename unique. The file is then created with mode read/write and +filename unique. +The file is then created with mode read/write and permissions 0666 (glibc 2.0.6 and earlier), 0600 (glibc 2.0.7 and later). Since it will be modified, .I template must not be a string constant, but should be declared as a character array. -The file is opened with the +The file is opened with the .BR open (2) -.B O_EXCL +.B O_EXCL flag, guaranteeing that when .BR mkstemp () returns successfully we are the only user. diff --git a/man3/mktemp.3 b/man3/mktemp.3 index fa0603635..73063374d 100644 --- a/man3/mktemp.3 +++ b/man3/mktemp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,7 +42,8 @@ mktemp \- make a unique temporary filename The \fBmktemp\fP() function generates a unique temporary filename from \fItemplate\fP. The last six characters of \fItemplate\fP must be XXXXXX and these are replaced with a string that makes the -filename unique. Since it will be modified, +filename unique. +Since it will be modified, .I template must not be a string constant, but should be declared as a character array. .SH "RETURN VALUE" @@ -50,7 +51,8 @@ The \fBmktemp\fP() function returns NULL on error (\fItemplate\fP did not end in XXXXXX) and \fItemplate\fP otherwise. If the call was successful, the last six bytes of \fItemplate\fP will have been modified in such a way that the resulting name is unique -(does not exist already). If the call was unsuccessful, \fItemplate\fP +(does not exist already). +If the call was unsuccessful, \fItemplate\fP is made an empty string. .SH ERRORS .TP @@ -65,7 +67,8 @@ for libc4, libc5, glibc1; glibc2 follows the Single Unix Specification and has the prototype in .IR . .SH BUGS -Never use \fBmktemp\fP(). Some implementations follow 4.3BSD +Never use \fBmktemp\fP(). +Some implementations follow 4.3BSD and replace XXXXXX by the current process ID and a single letter, so that at most 26 different names can be returned. Since on the one hand the names are easy to guess, and on the other diff --git a/man3/modf.3 b/man3/modf.3 index 64fb10f2b..2a16c5a98 100644 --- a/man3/modf.3 +++ b/man3/modf.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -30,7 +30,7 @@ .\" .TH MODF 3 2002-07-27 "" "Linux Programmer's Manual" .SH NAME -modf, modff, modfl \- extract signed integral and fractional values from +modf, modff, modfl \- extract signed integral and fractional values from floating-point number .SH SYNOPSIS .nf @@ -52,7 +52,7 @@ The integral part is stored in \fIiptr\fP. The \fBmodf\fP() function returns the fractional part of \fIx\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/mpool.3 b/man3/mpool.3 index e6c9a0fe8..d90b6b358 100644 --- a/man3/mpool.3 +++ b/man3/mpool.3 @@ -31,7 +31,7 @@ .\" .\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 .\" -.TH MPOOL 3 1993-06-04 +.TH MPOOL 3 1993-06-04 .UC 7 .SH NAME mpool \- shared memory buffer pool @@ -213,7 +213,7 @@ function may fail and set for any of the errors specified for the library routine .BR free (3). .SH "CONFORMING TO" -Not in POSIX.1-2001. +Not in POSIX.1-2001. Present on the BSDs. .SH "SEE ALSO" .BR dbopen (3), diff --git a/man3/mq_close.3 b/man3/mq_close.3 index 75e5d0443..26d3c4810 100644 --- a/man3/mq_close.3 +++ b/man3/mq_close.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,10 +34,10 @@ mq_close \- close a message queue descriptor closes the message queue descriptor .IR mqdes . -If the calling process has attached a notification request +If the calling process has attached a notification request to this message queue via .IR mqdes , -then this request is removed, +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, @@ -47,12 +47,12 @@ or upon On success .BR mq_close () returns 0; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP .B EBADF -The descriptor specified in +The descriptor specified in .I mqdes is invalid. .SH CONFORMING TO diff --git a/man3/mq_getattr.3 b/man3/mq_getattr.3 index 920d1c126..c33ea9d44 100644 --- a/man3/mq_getattr.3 +++ b/man3/mq_getattr.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,14 +35,14 @@ mq_getattr, mq_setattr \- get/set message queue attributes .BR mq_getattr () and .BR mq_setattr () -respectively retrieve and modify attributes of the message queue +respectively retrieve and modify attributes of the message queue referred to by the descriptor .IR mqdes . .BR mq_getattr () returns an .I mq_attr -structure in the buffer pointed by +structure in the buffer pointed by .IR attr . This structure is defined as: .in +0.25i @@ -65,7 +65,7 @@ This field is initialised when the queue is created by The only flag that can appear in this field is .BR O_NONBLOCK . -The +The .I mq_maxmsg and .I mq_msgsize @@ -73,7 +73,7 @@ fields are set when the message queue is created by .BR mq_open (). The .I mq_maxmsg -field is an upper limit on the number of messages +field is an upper limit on the number of messages that may be placed on the queue using .BR mq_send (). The @@ -81,17 +81,17 @@ The field is an upper limit on the size of messages that may be placed on the queue. Both of these fields must have a value greater than zero. -Two -.I /proc -files that place ceilings on the values for these fields are described in +Two +.I /proc +files that place ceilings on the values for these fields are described in .BR mq_open (3). -The +The .I mq_curmsgs field returns the number of messages currently held in the queue. .BR mq_setattr () -sets message queue attributes using information supplied in the +sets message queue attributes using information supplied in the .I mq_attr structure pointed to by .IR newattr . @@ -115,12 +115,12 @@ On success and .BR mq_setattr () return 0; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP .B EBADF -The descriptor specified in +The descriptor specified in .I mqdes is invalid. .TP diff --git a/man3/mq_notify.3 b/man3/mq_notify.3 index 124aeb5b5..10c95f173 100644 --- a/man3/mq_notify.3 +++ b/man3/mq_notify.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,14 +31,14 @@ mq_notify \- register for notification when a message is available .fi .SH DESCRIPTION .BR mq_notify () -allows the calling process to register or unregister for delivery of -an asynchronous notification when a new message arrives on +allows the calling process to register or unregister for delivery of +an asynchronous notification when a new message arrives on the empty message queue referred to by the descriptor .IR mqdes . -The +The .I notification -argument is a pointer to a +argument is a pointer to a .I sigevent structure that is defined something like the following: .in +0.25i @@ -61,13 +61,13 @@ struct sigevent { .fi .in -0.25i .PP -If +If .I notification -is a non-NULL pointer, then +is a non-NULL pointer, then .BR mq_notify () registers the calling process to receive message notification. -The -.I sigev_notify +The +.I sigev_notify field of the .I sigevent to which @@ -76,14 +76,14 @@ points specifies how notification is to be performed. This field has one of the following values: .TP .B SIGEV_NONE -A "null" notification: the calling process is registered as the target +A "null" notification: the calling process is registered as the target for notification, but when a message arrives, no notification is sent. .\" When is SIGEV_NONE useful? .TP .B SIGEV_SIGNAL Notify the process by sending the signal specified in .IR sigev_signo . -If the signal is caught with a signal handler that +If the signal is caught with a signal handler that was registered using the .BR sigaction (2) .B SA_SIGINFO @@ -94,7 +94,7 @@ structure that is passed as the second argument of the handler: is set to .BR SI_MESGQ ; .I si_signo -is set to the signal number; +is set to the signal number; .I si_value is set to the value specified in .IR notification->sigev_value ; @@ -114,7 +114,7 @@ as the start function of a new thread. The function is invoked with .IR notification->sigev_value as its sole argument. -If +If .IR notification->sigev_notify_attributes is not NULL, then it should point to a .I pthread_attr_t @@ -125,48 +125,48 @@ structure that defines attributes for the thread. Only one process can be registered to receive notification from a message queue. -If +If .I notification is NULL, and the calling process is currently registered to receive notifications for this message queue, then the registration is removed; -another process can then register to receive a message notification +another process can then register to receive a message notification for this queue. -Message notification only occurs when a new message arrives and +Message notification only occurs when a new message arrives and the queue was previously empty. If the queue was not empty at the time .BR mq_notify () -was called, then a notification will only occur after +was called, then a notification will only occur after the queue is emptied and a new message arrives. If another process or thread is waiting to read a message from an empty queue using .BR mq_receive (), -then any message notification registration is ignored: +then any message notification registration is ignored: the message is delivered to the process or thread calling .BR mq_receive (), and the message notification registration remains in effect. -Notification occurs once: after a notification is delivered, -the notification registration is removed, +Notification occurs once: after a notification is delivered, +the notification registration is removed, and another process can register for message notification. If the notified process wishes to receive the next notification, -it can use +it can use .BR mq_notify () to request a further notification. This should be done before emptying all unread messages from the queue. -(Placing the queue in non-blocking mode is useful for emptying +(Placing the queue in non-blocking mode is useful for emptying the queue of messages without blocking once it is empty.) .SH RETURN VALUE On success .BR mq_notify () returns 0; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP .B EBADF -The descriptor specified in +The descriptor specified in .I mqdes is invalid. .TP @@ -178,9 +178,9 @@ for this message queue. .I notification->sigev_notify is not one of the permitted values; or .I notification->sigev_notify -is -.B SIGEV_SIGNAL -and +is +.B SIGEV_SIGNAL +and .I notification->sigev_signo is not a valid signal number. .TP @@ -192,7 +192,7 @@ POSIX.1-2001. The following program registers a notification request for the message queue named in its command-line argument. Notification is performed by creating a thread. -The thread executes a function which reads one message from the +The thread executes a function which reads one message from the queue and then terminates the process. .nf diff --git a/man3/mq_open.3 b/man3/mq_open.3 index c6c66303c..2bced0b1c 100644 --- a/man3/mq_open.3 +++ b/man3/mq_open.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -28,7 +28,7 @@ mq_open \- open a message queue .B #include .sp .BI "mqd_t mq_open(const char *" name ", int " oflag ); -.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , +.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , .BI " struct mq_attr *" attr ); .fi .SH DESCRIPTION @@ -36,15 +36,15 @@ mq_open \- open a message queue creates a new POSIX message queue or opens an existing queue. The queue is identified by .IR name . -For details of the construction of -.IR name , +For details of the construction of +.IR name , see .BR mq_overview (7). The .I oflag argument specifies flags that control the operation of the call. -Exactly one of the following must be specified in +Exactly one of the following must be specified in .IR oflag: .TP .B O_RDONLY @@ -73,8 +73,8 @@ would normally block, these functions instead fail with the error .B O_CREAT Create the message queue if it does not exist. The owner (user ID) of the message queue is set to the effective -user ID of the calling process. -The group ownership (group ID) is set to the effective group ID +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID of the calling process. .\" In reality the file system IDs are used on Linux. .TP @@ -88,34 +88,35 @@ and a queue with the given already exists, then fail with the error .BR EEXIST . .PP -If +If .B O_CREAT -is specified in +is specified in .IR oflag , then two additional arguments must be supplied. The .I mode -argument specifies the permissions to be placed on the new queue, +argument specifies the permissions to be placed on the new queue, as for .BR open (2). The permissions settings are masked against the process umask. -The +The .I attr -argument specifies attributes for the queue. See +argument specifies attributes for the queue. +See .BR mq_getattr (2) -for details. +for details. If .I attr -is NULL, then the queue is created with implementation-defined +is NULL, then the queue is created with implementation-defined default attributes. .SH RETURN VALUE On success, .BR mq_open () -returns a message queue descriptor for use by other +returns a message queue descriptor for use by other message queue functions. -On error, +On error, .BR mq_open () -returns +returns .IR "(mqd_t)\ \-1", with .I errno @@ -123,14 +124,14 @@ set to indicate the error. .SH ERRORS .TP .B EACCES -The queue exists, but the caller does not have permission to +The queue exists, but the caller does not have permission to open it in the specified mode. .TP .B EINVAL .B O_CREAT -was specified in -.IR oflag , -and +was specified in +.IR oflag , +and .I attr was not NULL, but .I attr->mq_maxmsg @@ -148,14 +149,14 @@ limit, and .I attr->mq_msgsize must be less than or equal to the .I msgsize_max -limit. +limit. In addition, even in a privileged process, .I attr->mq_maxmsg cannot exceed the .B HARD_MAX limit. (See -.BR mq_overview (7) +.BR mq_overview (7) for details of these limits.) .TP .B EEXIST @@ -163,14 +164,14 @@ Both .B O_CREAT and .B O_EXCL -were specified in +were specified in .IR oflag , -but a queue with this +but a queue with this .I name already exists. .TP .B EMFILE -The process already has the maximum number of files and +The process already has the maximum number of files and message queues open. .TP .B ENAMETOOLONG @@ -178,15 +179,15 @@ message queues open. was too long. .TP .B ENFILE -The system limit on the total number of open files and message queues +The system limit on the total number of open files and message queues has been reached. .TP .B ENOENT The .B O_CREAT -flag was not specified in +flag was not specified in .IR oflag , -and no queue with this +and no queue with this .I name exists. .TP @@ -202,8 +203,8 @@ limit was encountered; see .SH CONFORMING TO POSIX.1-2001. .SH BUGS -In kernels before 2.6.14, -the process umask was not applied to the permissions specified in +In kernels before 2.6.14, +the process umask was not applied to the permissions specified in .IR mode . .SH "SEE ALSO" .BR mq_close (3), diff --git a/man3/mq_receive.3 b/man3/mq_receive.3 index 020906fc9..223945ba4 100644 --- a/man3/mq_receive.3 +++ b/man3/mq_receive.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,8 +40,8 @@ mq_receive, mq_timedreceive \- receive a message from a message queue .fi .SH DESCRIPTION .BR mq_receive () -removes the oldest message with the highest priority from -the message queue referred to by the descriptor +removes the oldest message with the highest priority from +the message queue referred to by the descriptor .IR mqdes , and places it in the buffer pointed to by .IR msg_ptr . @@ -51,18 +51,18 @@ argument specifies the size of the buffer pointed to by .IR msg_ptr ; this must be greater than the .I mq_msgsize -attribute of the queue (see +attribute of the queue (see .BR mq_getattr (3)). If .I prio -is not NULL, then the buffer to which it points is used +is not NULL, then the buffer to which it points is used to return the priority associated with the received message. If the queue is empty, then, by default, .BR mq_receive () blocks until a message becomes available, or the call is interrupted by a signal handler. -If the +If the .B O_NONBLOCK flag is enabled for the message queue description, then the call instead fails immediately with the error @@ -75,7 +75,7 @@ except that if the queue is empty and the .B O_NONBLOCK flag is not enabled for the message queue description, then .I abs_timeout -points to a structure which specifies a ceiling on the time for which +points to a structure which specifies a ceiling on the time for which the call will block. This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch (midnight on the morning of 1 January 1970), @@ -101,7 +101,7 @@ and .BR mq_timedreceive () return the number of bytes in the received message; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP @@ -112,13 +112,13 @@ flag was set for the message queue description referred to by .IR mqdes . .TP .B EBADF -The descriptor specified in +The descriptor specified in .I mqdes was invalid. .TP .B EMSGSIZE -.IR msg_len -was less than the +.IR msg_len +was less than the .I mq_msgsize attribute of the message queue. .TP @@ -126,12 +126,12 @@ attribute of the message queue. The call was interrupted by a signal handler. .TP .B EINVAL -The call would have blocked, and +The call would have blocked, and .I abs_timeout was invalid, either because .I tv_sec was less than zero, or because -.I tv_nsec +.I tv_nsec was less than zero or greater than 1000 million. .TP .B ETIMEDOUT diff --git a/man3/mq_send.3 b/man3/mq_send.3 index a041eea6b..9c1405960 100644 --- a/man3/mq_send.3 +++ b/man3/mq_send.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,7 +44,7 @@ adds the message pointed to by .IR msg_ptr to the message queue referred to by the descriptor .IR mqdes . -The +The .I msg_len argument specifies the length of the message pointed to by .IR msg_ptr ; @@ -53,22 +53,22 @@ this length must be less than or equal to the queue's attribute. Zero-length messages are allowed. -The +The .I msg_prio -argument is a non-negative integer that specifies the priority +argument is a non-negative integer that specifies the priority of this message. -Messages are placed on the queue in decreasing order of priority, -with newer messages of the same priority being placed after +Messages are placed on the queue in decreasing order of priority, +with newer messages of the same priority being placed after older messages with the same priority. -If the message queue is already full +If the message queue is already full (i.e., the number of messages on the queue equals the queue's .I mq_maxmsg attribute), then, by default, .BR mq_send () -blocks until sufficient space becomes available to allow the message +blocks until sufficient space becomes available to allow the message to be queued, or until the call is interrupted by a signal handler. -If the +If the .B O_NONBLOCK flag is enabled for the message queue description, then the call instead fails immediately with the error @@ -81,7 +81,7 @@ except that if the queue is full and the .B O_NONBLOCK flag is not enabled for the message queue description, then .I abs_timeout -points to a structure which specifies a ceiling on the time for which +points to a structure which specifies a ceiling on the time for which the call will block. This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch (midnight on the morning of 1 January 1970), @@ -106,7 +106,7 @@ On success, and .BR mq_timedsend () return zero; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP @@ -117,13 +117,13 @@ flag was set for the message queue description referred to by .IR mqdes . .TP .B EBADF -The descriptor specified in +The descriptor specified in .I mqdes was invalid. .TP .B EMSGSIZE -.IR msg_len -was greater than the +.IR msg_len +was greater than the .I mq_msgsize attribute of the message queue. .TP @@ -131,12 +131,12 @@ attribute of the message queue. The call was interrupted by a signal handler. .TP .B EINVAL -The call would have blocked, and +The call would have blocked, and .I abs_timeout was invalid, either because .I tv_sec was less than zero, or because -.I tv_nsec +.I tv_nsec was less than zero or greater than 1000 million. .TP .B ETIMEDOUT diff --git a/man3/mq_unlink.3 b/man3/mq_unlink.3 index edae320e8..d6d28a7fe 100644 --- a/man3/mq_unlink.3 +++ b/man3/mq_unlink.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,13 +34,13 @@ mq_unlink \- remove a message queue removes the specified message queue .IR name . The message queue name is removed immediately. -The queue itself is destroyed once any other processes that have +The queue itself is destroyed once any other processes that have the queue open close their descriptors referring to the queue. .SH RETURN VALUE On success .BR mq_unlink () returns 0; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP diff --git a/man3/mtrace.3 b/man3/mtrace.3 index 654dac660..2db2166c3 100644 --- a/man3/mtrace.3 +++ b/man3/mtrace.3 @@ -23,11 +23,11 @@ The function .BR muntrace () disables these handlers. .br -The environment variable +The environment variable .B MALLOC_TRACE defines a file where .BR mtrace () -writes its output. +writes its output. This file must be writable to the user or .BR mtrace () will do nothing. @@ -35,8 +35,8 @@ If the file is not empty it will be truncated. .SH NOTE 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. +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" diff --git a/man3/nan.3 b/man3/nan.3 index 0de5255a8..774d2e18d 100644 --- a/man3/nan.3 +++ b/man3/nan.3 @@ -24,7 +24,7 @@ quiet NaNs, these functions return zero. .LP The call .I nan("char-sequence") -is equivalent to +is equivalent to .I strtod ("NAN(char-sequence)",NULL) and similarly calls to .BR nanf () @@ -37,10 +37,11 @@ and .PP The argument .I tagp -is used in an unspecified manner. On IEEE 754 systems, there are -many representations of NaN, and +is used in an unspecified manner. +On IEEE 754 systems, there are many representations of NaN, and .I tagp -selects one. On other systems it may do nothing. +selects one. +On other systems it may do nothing. .SH "CONFORMING TO" C99. See also IEC 559 and the appendix with recommended functions in IEEE 754/IEEE 854. diff --git a/man3/netlink.3 b/man3/netlink.3 index 76fc90f96..5f0b1294f 100644 --- a/man3/netlink.3 +++ b/man3/netlink.3 @@ -9,10 +9,10 @@ netlink \- Netlink macros .\" FIXME what will glibc 2.1 use here? .B #include .br -.B #include +.B #include .br .BI "int NLMSG_ALIGN(size_t " len ); -.br +.br .BI "int NLMSG_LENGTH(size_t " len ); .br .BI "int NLMSG_SPACE(size_t " len ); @@ -28,10 +28,11 @@ netlink \- Netlink macros .SH DESCRIPTION .I defines several standard macros to access or create a netlink datagram. -They are similar in spirit to the macros defined in +They are similar in spirit to the macros defined in .BR cmsg (3) -for auxiliary data. The buffer passed to and from a netlink socket should -be only accessed using these macros. +for auxiliary data. +The buffer passed to and from a netlink socket should +be only accessed using these macros. .TP NLMSG_ALIGN Round the length of a netlink message up to align it properly. @@ -40,36 +41,36 @@ NLMSG_LENGTH Gets the payload length as argument and returns the aligned length to store in the .B nlmsg_len -field of the +field of the .IR nlmsghdr . .TP NLMSG_SPACE -Return the number of bytes a netlink message with payload of the passed length +Return the number of bytes a netlink message with payload of the passed length would occupy. .TP NLMSG_DATA -Return a pointer to the payload associated with the passed +Return a pointer to the payload associated with the passed .IR nlmsghdr . .TP .\" FIXME this is bizarre, maybe the interface should be fixed. NLMSG_NEXT -Get the next +Get the next .I nlmsghdr -in a multipart message. -The caller must check if the current nlmsghdr didn't have the NLMSG_DONE -set \(em this function doesn't return NULL on end. -The length parameter is an lvalue containing the remaining length -of the message buffer. +in a multipart message. +The caller must check if the current nlmsghdr didn't have the NLMSG_DONE +set \(em this function doesn't return NULL on end. +The length parameter is an lvalue containing the remaining length +of the message buffer. This macro decrements it by the length of the message header. .TP NLMSG_OK -Return true if the netlink message is not truncated and ok to parse. +Return true if the netlink message is not truncated and ok to parse. .TP NLMSG_PAYLOAD -Return the length of the payload associated with the +Return the length of the payload associated with the .IR nlmsghdr . .SH NOTES -It is often better to use netlink via +It is often better to use netlink via .B libnetlink than via the low level kernel interface. .SH "SEE ALSO" diff --git a/man3/nextafter.3 b/man3/nextafter.3 index 7aef1d735..f284bfa1e 100644 --- a/man3/nextafter.3 +++ b/man3/nextafter.3 @@ -3,7 +3,7 @@ .\" Based on glibc infopages .TH NEXTAFTER 3 2002-08-10 "GNU" "libc math functions" .SH NAME -nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- +nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- floating point number manipulation .SH SYNOPSIS .B #include @@ -18,21 +18,23 @@ floating point number manipulation .br .BI "float nexttowardf(float " x ", long double " y ); .br -.BI "long double nexttowardl(long double " x ", long double " y ); +.BI "long double nexttowardl(long double " x ", long double " y ); .sp Link with \-lm. .SH DESCRIPTION -The +The .BR nextafter () functions return the next representable neighbor of -\fIx\fP in the direction towards \fIy\fP. The size of the step +\fIx\fP in the direction towards \fIy\fP. +The size of the step between \fIx\fP and the result depends on the type of the result. If \fIx\fP = \fIy\fP the function simply returns \fIy\fP. -If either value is +If either value is .IR NaN , then .I NaN -is returned. Otherwise a value corresponding to the value of the +is returned. +Otherwise a value corresponding to the value of the least significant bit in the mantissa is added or subtracted, depending on the direction. .PP diff --git a/man3/nl_langinfo.3 b/man3/nl_langinfo.3 index 75807c551..d6e19bc5a 100644 --- a/man3/nl_langinfo.3 +++ b/man3/nl_langinfo.3 @@ -24,7 +24,8 @@ nl_langinfo \- query language and locale information The \fBnl_langinfo\fP() function provides access to locale information in a more flexible way than .BR localeconv (3) -does. Individual and additional elements of the locale categories can +does. +Individual and additional elements of the locale categories can be queried. .PP Examples for the locale elements that can be specified in \fIitem\fP @@ -33,8 +34,10 @@ using the constants defined in are: .BR CODESET \ (LC_CTYPE) Return a string with the name of the character encoding used in the selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968" -(better known as US-ASCII). This is the same string that you get with -"locale charmap". For a list of character encoding names, +(better known as US-ASCII). +This is the same string that you get with +"locale charmap". +For a list of character encoding names, try "locale \-m", cf.\& .BR locale (1). .TP @@ -73,13 +76,13 @@ Return radix character (decimal dot, decimal comma, etc.). .BR THOUSEP \ (LC_NUMERIC) Return separator character for thousands (groups of three digits). .TP -.BR YESEXPR \ (LC_MESSAGES) -Return a regular expression that can be used with the +.BR YESEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the .BR regex (3) function to recognize a positive response to a yes/no question. .TP -.BR NOEXPR \ (LC_MESSAGES) -Return a regular expression that can be used with the +.BR NOEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the .BR regex (3) function to recognize a negative response to a yes/no question. .TP @@ -88,7 +91,7 @@ Return the currency symbol, preceded by "\-" if the symbol should appear before the value, "+" if the symbol should appear after the value, or "." if the symbol should replace the radix character. .PP -The above list covers just some examples of items that can be requested. +The above list covers just some examples of items that can be requested. For a more detailed list, consult .IR "The GNU C Library Reference Manual" . .SH "RETURN VALUE" diff --git a/man3/offsetof.3 b/man3/offsetof.3 index f7e8b6af7..b28241045 100644 --- a/man3/offsetof.3 +++ b/man3/offsetof.3 @@ -34,15 +34,15 @@ offsetof \- offset of a structure member The macro \fBoffsetof\fP() returns the offset of the field \fImember\fP from the start of the structure \fItype\fP. -This macro is useful because the sizes of the fields that compose -a structure can vary across implementations, -and compilers may insert different numbers of padding +This macro is useful because the sizes of the fields that compose +a structure can vary across implementations, +and compilers may insert different numbers of padding bytes between fields. Consequently, an element's offset is not necessarily given by the sum of the sizes of the previous elements. -A compiler error will result if -\fImember\fP is not aligned to a byte boundary +A compiler error will result if +\fImember\fP is not aligned to a byte boundary (i.e., it is a bit field). .SH "RETURN VALUE" \fBoffsetof\fP() returns the offset of the given element within the @@ -55,14 +55,14 @@ options, the program below produces the following output: $ ./a.out offsets: i=0; c=4; d=8 a=16 sizeof(struct s)=16 - + .nf .nf #include #include #include -int +int main(void) { struct s { @@ -73,19 +73,19 @@ main(void) }; /* Output is compiler dependent */ - + printf("offsets: i=%ld; c=%ld; d=%ld a=%ld\\n", - (long) offsetof(struct s, i), + (long) offsetof(struct s, i), (long) offsetof(struct s, c), - (long) offsetof(struct s, d), + (long) offsetof(struct s, d), (long) offsetof(struct s, a)); printf("sizeof(struct s)=%ld\\n", (long) sizeof(struct s)); - + 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 +.\" FIXME . When one day readdir_r(3) is documented, it should have .\" a SEE ALSO that refers to this page. diff --git a/man3/on_exit.3 b/man3/on_exit.3 index 5a1dbcc1d..a3e1a14e2 100644 --- a/man3/on_exit.3 +++ b/man3/on_exit.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,7 +48,7 @@ The \fBon_exit\fP() function returns the value 0 if successful; otherwise it returns a non-zero value. .SH "CONFORMING TO" This function comes from SunOS 4, but is also present in -libc4, libc5 and glibc. +libc4, libc5 and glibc. It no longer occurs in Solaris (SunOS 5). Avoid this function, and use the standard .BR atexit (3) diff --git a/man3/opendir.3 b/man3/opendir.3 index 21b9b453b..4c7edb902 100644 --- a/man3/opendir.3 +++ b/man3/opendir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,8 +39,8 @@ opendir \- open a directory .fi .SH DESCRIPTION The \fBopendir\fP() function opens a directory stream corresponding to the -directory \fIname\fP, and returns a pointer to the directory stream. The -stream is positioned at the first entry in the directory. +directory \fIname\fP, and returns a pointer to the directory stream. +The stream is positioned at the first entry in the directory. .SH "RETURN VALUE" The \fBopendir\fP() function returns a pointer to the directory stream. On error, NULL is returned, and diff --git a/man3/openpty.3 b/man3/openpty.3 index 9209fc358..6a14f8764 100644 --- a/man3/openpty.3 +++ b/man3/openpty.3 @@ -40,12 +40,12 @@ openpty, login_tty, forkpty \- tty utility functions .B #include /* for login_tty */ .sp -.BI "int openpty(int *" amaster ", int *" aslave ", char *" name , +.BI "int openpty(int *" amaster ", int *" aslave ", char *" name , .BI " struct termios *" termp ", struct winsize *" winp ); .sp .BI "int login_tty(int " fd ); .sp -.BI "pid_t forkpty(int *" amaster ", char *" name ", struct termios *" termp , +.BI "pid_t forkpty(int *" amaster ", char *" name ", struct termios *" termp , .BI " struct winsize *" winp ); .sp Link with \-lutil. @@ -94,12 +94,14 @@ function combines .BR fork (), and .BR login_tty () -to create a new process operating in a pseudo-terminal. The file +to create a new process operating in a pseudo-terminal. +The file descriptor of the master side of the pseudo-terminal is returned in .IR amaster , and the filename of the slave in .I name -if it is not NULL. The +if it is not NULL. +The .I termp and .I winp @@ -114,7 +116,8 @@ or .BR forkpty () is not successful, \-1 is returned and .I errno -is set to indicate the error. Otherwise, +is set to indicate the error. +Otherwise, .BR openpty (), .BR login_tty (), and the child process of @@ -149,8 +152,8 @@ to your compiler command line. In versions of glibc before 2.0.92, .BR openpty () -returns file descriptors for a BSD pseudo-terminal pair; -since glibc 2.0.92, +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" diff --git a/man3/perror.3 b/man3/perror.3 index 084f88d08..2fd75bf54 100644 --- a/man3/perror.3 +++ b/man3/perror.3 @@ -57,7 +57,8 @@ is printed, followed by a colon and a blank. Then the message and a new-line. To be of most use, the argument string should include the name -of the function that incurred the error. The error number is taken from +of the function that incurred the error. +The error number is taken from the external variable .IR errno , which is set when errors occur but not @@ -77,7 +78,8 @@ may not have been added to When a system call fails, it usually returns \-1 and sets the variable .I errno -to a value describing what went wrong. (These values can be found in +to a value describing what went wrong. +(These values can be found in .IR "" .) Many library functions do likewise. The function diff --git a/man3/popen.3 b/man3/popen.3 index 5c42920f5..ca7f4b501 100644 --- a/man3/popen.3 +++ b/man3/popen.3 @@ -48,7 +48,8 @@ popen, pclose \- process I/O The .BR popen () function opens a process by creating a pipe, forking, and invoking the -shell. Since a pipe is by definition unidirectional, the +shell. +Since a pipe is by definition unidirectional, the .I type argument may specify only reading or writing, not both; the resulting stream is correspondingly read-only or write-only. @@ -56,11 +57,13 @@ stream is correspondingly read-only or write-only. The .I command argument is a pointer to a null-terminated string containing a shell -command line. This command is passed to +command line. +This command is passed to .I /bin/sh using the .B \-c -flag; interpretation, if any, is performed by the shell. The +flag; interpretation, if any, is performed by the shell. +The .I type argument is a pointer to a null-terminated string which must be either `r' for reading or `w' for writing. @@ -75,7 +78,8 @@ rather than Writing to such a stream writes to the standard input of the command; the command's standard output is the same as that of the process that called .BR popen (), -unless this is altered by the command itself. Conversely, reading from a +unless this is altered by the command itself. +Conversely, reading from a ``popened'' stream reads the command's standard output, and the command's standard input is the same as that of the process that called .BR popen (). @@ -114,13 +118,15 @@ The .BR popen () function does not set .I errno -if memory allocation fails. If the underlying -.BR fork () -or +if memory allocation fails. +If the underlying +.BR fork () +or .BR pipe () fails, .I errno -is set appropriately. If the +is set appropriately. +If the .I type argument is invalid, and this condition is detected, .I errno @@ -140,16 +146,18 @@ Since the standard input of a command opened for reading shares its seek offset with the process that called .BR popen (), if the original process has done a buffered read, the command's input -position may not be as expected. Similarly, the output from a command +position may not be as expected. +Similarly, the output from a command opened for writing may become intermingled with that of the original -process. The latter can be avoided by calling +process. +The latter can be avoided by calling .BR fflush (3) before .BR popen (). .PP Failure to execute the shell is indistinguishable from the shell's failure -to execute command, or an immediate exit of the command. The only hint is -an exit status of 127. +to execute command, or an immediate exit of the command. +The only hint is an exit status of 127. .SH HISTORY A .BR popen () diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3 index 906252217..c615a1426 100644 --- a/man3/posix_fallocate.3 +++ b/man3/posix_fallocate.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,7 @@ descriptor .I fd for the bytes in the range starting at .IR offset -and continuing for +and continuing for .I len bytes. After a successful call to @@ -77,7 +77,7 @@ was less than 0. does not refer to a regular file. .TP .B ENOSPC -There is not enough space left on the device containing the file +There is not enough space left on the device containing the file referred to by .IR fd. .TP diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 index 4227c4c71..432b192df 100644 --- a/man3/posix_memalign.3 +++ b/man3/posix_memalign.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -77,7 +77,8 @@ return the pointer to the allocated memory, or NULL if the request fails. .BR posix_memalign () returns zero on success, or one of the error values listed in the -next section on failure. Note that +next section on failure. +Note that .IR errno is not set. .SH "ERRORS" @@ -92,9 +93,11 @@ parameter was not a power of two, or was not a multiple of There was insufficient memory to fulfill the allocation request. .SH NOTES On many systems there are alignment restrictions, e.g. on buffers -used for direct block device I/O. POSIX specifies the +used for direct block device I/O. +POSIX specifies the .I "pathconf(path,_PC_REC_XFER_ALIGN)" -call that tells what alignment is needed. Now one can use +call that tells what alignment is needed. +Now one can use .BR posix_memalign () to satisfy this requirement. @@ -150,9 +153,9 @@ is available since glibc 2.1.91. .SH "CONFORMING TO" The function .BR valloc () -appeared in 3.0BSD. +appeared in 3.0BSD. It is documented as being obsolete in 4.3BSD, -and as legacy in SUSv2. +and as legacy in SUSv2. It does not appear in POSIX.1-2001. The function .BR memalign () @@ -163,7 +166,8 @@ comes from POSIX.1d. .SH HEADERS Everybody agrees that .BR posix_memalign () -is declared in . In order to declare it, glibc needs +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 diff --git a/man3/posix_openpt.3 b/man3/posix_openpt.3 index b4fd0a2d0..3e2ff3e03 100644 --- a/man3/posix_openpt.3 +++ b/man3/posix_openpt.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/pow.3 b/man3/pow.3 index 716cafa4b..4f7cb1919 100644 --- a/man3/pow.3 +++ b/man3/pow.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,7 +45,7 @@ pow, powf, powl \- power functions Link with \-lm. .SH DESCRIPTION The \fBpow\fP() function returns the value of \fIx\fP raised to the -power of \fIy\fP. +power of \fIy\fP. .SH ERRORS The \fBpow\fP() function can return the following error: .TP @@ -54,7 +54,7 @@ The argument \fIx\fP is negative and \fIy\fP is not an integral value. This would result in a complex number. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/pow10.3 b/man3/pow10.3 index bf9b91cba..49ae63e57 100644 --- a/man3/pow10.3 +++ b/man3/pow10.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/printf.3 b/man3/printf.3 index bcf152fd8..f28565874 100644 --- a/man3/printf.3 +++ b/man3/printf.3 @@ -59,7 +59,8 @@ The functions in the .BR printf () family produce output according to a .I format -as described below. The functions +as described below. +The functions .BR printf () and .BR vprintf () @@ -72,7 +73,7 @@ and write output to the given output .IR stream ; .BR sprintf (), -.BR snprintf (), +.BR snprintf (), .BR vsprintf () and .BR vsnprintf () @@ -90,11 +91,14 @@ are equivalent to the functions .BR sprintf (), .BR snprintf (), respectively, except that they are called with a va_list instead -of a variable number of arguments. These functions do not call the +of a variable number of arguments. +These functions do not call the .I va_end -macro. Consequently, the value of +macro. +Consequently, the value of .I ap -is undefined after the call. The application should call +is undefined after the call. +The application should call .I va_end(ap) itself afterwards. .PP @@ -109,7 +113,7 @@ Upon successful return, these functions return the number of characters printed (not including the trailing '\e0' used to end output to strings). The functions .BR snprintf () -and +and .BR vsnprintf () do not write more than .I size @@ -117,10 +121,11 @@ bytes (including the trailing '\e0'). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing '\e0') which would have been written to the final string if enough space -had been available. Thus, a return value of +had been available. +Thus, a return value of .I size -or more means that the output was truncated. (See also below -under NOTES.) +or more means that the output was truncated. +(See also below under NOTES.) If an output error is encountered, a negative value is returned. .SS "Format of the format string" The format string is a character string, beginning and ending @@ -130,7 +135,8 @@ characters (not .BR % ), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or -more subsequent arguments. Each conversion specification is introduced by +more subsequent arguments. +Each conversion specification is introduced by the character .BR % , and ends with a @@ -145,14 +151,16 @@ and an optional .IR "length modifier" . The arguments must correspond properly (after type promotion) with the -conversion specifier. By default, the arguments are used in the order +conversion specifier. +By default, the arguments are used in the order given, where each `*' and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given). One can also specify explicitly which argument is taken, at each place where an argument is required, by writing `%m$' instead of `%' and `*m$' instead of `*', where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting -from 1. Thus, +from 1. +Thus, .RS .nf @@ -168,19 +176,25 @@ and .fi .RE -are equivalent. The second style allows repeated references to the -same argument. The C99 standard does not include the style using `$', -which comes from the Single Unix Specification. If the style using +are equivalent. +The second style allows repeated references to the +same argument. +The C99 standard does not include the style using `$', +which comes from the Single Unix Specification. +If the style using `$' is used, it must be used throughout for all conversions taking an argument and all width and precision arguments, but it may be mixed -with `%%' formats which do not consume an argument. There may be no +with `%%' formats which do not consume an argument. +There may be no gaps in the numbers of arguments specified using `$'; for example, if arguments 1 and 3 are specified, argument 2 must also be specified somewhere in the format string. For some numeric conversions a radix character (`decimal point') or -thousands' grouping character is used. The actual character used -depends on the LC_NUMERIC part of the locale. The POSIX locale +thousands' grouping character is used. +The actual character used +depends on the LC_NUMERIC part of the locale. +The POSIX locale uses `.' as radix character, and does not have a grouping character. Thus, .RS @@ -205,7 +219,8 @@ and .B X conversions, a non\-zero result has the string `0x' (or `0X' for .B X -conversions) prepended to it. For +conversions) prepended to it. +For .BR a , .BR A , .BR e , @@ -217,7 +232,8 @@ and .B G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those -conversions only if a digit follows). For +conversions only if a digit follows). +For .B g and .B G @@ -226,7 +242,8 @@ otherwise be. For other conversions, the result is undefined. .TP .B \&0 -The value should be zero padded. For +The value should be zero padded. +For .BR d , .BR i , .BR o , @@ -266,10 +283,12 @@ For other conversions, the behavior is undefined. .TP .B \- The converted value is to be left adjusted on the field boundary. -(The default is right justification.) Except for +(The default is right justification.) +Except for .B n conversions, the converted value is padded on the right with blanks, rather -than on the left with blanks or zeros. A +than on the left with blanks or zeros. +A .B \- overrides a .B \&0 @@ -281,13 +300,15 @@ if both are given. .TP .B + A sign (+ or \-) should always be placed before a number produced by a signed -conversion. By default a sign is used only for negative numbers. A +conversion. +By default a sign is used only for negative numbers. +A .B + overrides a space if both are used. .PP The five flag characters above are defined in the C standard. The SUSv2 specifies one further flag character. -.TP +.TP .B ' For decimal conversion .BR "" ( i , @@ -298,9 +319,11 @@ For decimal conversion .BR g , .BR G ) the output is to be grouped with thousands' grouping characters -if the locale information indicates any. Note that many versions of +if the locale information indicates any. +Note that many versions of .BR gcc (1) -cannot parse this option and will issue a warning. SUSv2 does not +cannot parse this option and will issue a warning. +SUSv2 does not include %'F. .PP glibc 2.2 adds one further flag character. @@ -316,7 +339,8 @@ in the Persian (`fa_IR') locale. .\" outdigits keyword in locale file .SS "The field width" An optional decimal digit string (with non-zero first digit) specifying -a minimum field width. If the converted value has fewer characters +a minimum field width. +If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write `*' or `*m$' @@ -446,7 +470,8 @@ argument. (C99 allows %LF, but SUSv2 does not.) .TP .B q -(`quad'. 4.4BSD and Linux libc5 only. Don't use.) +(`quad'. 4.4BSD and Linux libc5 only. +Don't use.) This is a synonym for .BR ll . .TP @@ -462,9 +487,11 @@ A following integer conversion corresponds to a .I size_t or .I ssize_t -argument. (Linux libc5 has +argument. +(Linux libc5 has .B Z -with this meaning. Don't use it.) +with this meaning. +Don't use it.) .TP .B t A following integer conversion corresponds to a @@ -509,7 +536,8 @@ The argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is -padded on the left with zeros. The default precision is 1. +padded on the left with zeros. +The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. .TP .BR o , u , x , X @@ -523,7 +551,8 @@ or unsigned hexadecimal .BR "" ( x and .BR X ) -notation. The letters +notation. +The letters .B abcdef are used for .B x @@ -531,9 +560,11 @@ conversions; the letters .B ABCDEF are used for .B X -conversions. The precision, if any, gives the minimum number of digits +conversions. +The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is -padded on the left with zeros. The default precision is 1. +padded on the left with zeros. +The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. .TP .BR e , E @@ -545,13 +576,15 @@ argument is rounded and converted in the style where there is one digit before the decimal\-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal\-point character -appears. An +appears. +An .B E conversion uses the letter .B E (rather than .BR e ) -to introduce the exponent. The exponent always contains at least two +to introduce the exponent. +The exponent always contains at least two digits; if the value is zero, the exponent is 00. .TP .BR f , F @@ -560,14 +593,16 @@ The argument is rounded and converted to decimal notation in the style .BR "" [\-]ddd \&. ddd, where the number of digits after the decimal\-point character is equal to -the precision specification. If the precision is missing, it is taken as +the precision specification. +If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal\-point character appears. If a decimal point appears, at least one digit appears before it. (The SUSv2 does not know about .B F and says that character string representations for infinity and NaN -may be made available. The C99 standard specifies `[\-]inf' or `[\-]infinity' +may be made available. +The C99 standard specifies `[\-]inf' or `[\-]infinity' for infinity, and a string starting with `nan' for NaN, in the case of .B f conversion, and `[\-]INF' or `[\-]INFINITY' or `NAN*' in the case of @@ -587,12 +622,15 @@ or .B E for .B G -conversions). The precision specifies the number of significant digits. +conversions). +The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, -it is treated as 1. Style +it is treated as 1. +Style .B e is used if the exponent from its conversion is less than \-4 or greater -than or equal to the precision. Trailing zeros are removed from the +than or equal to the precision. +Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit. .TP @@ -644,10 +682,12 @@ If no modifier is present: The .I "const char *" argument is expected to be a pointer to an array of character type (pointer -to a string). Characters from the array are written up to (but not +to a string). +Characters from the array are written up to (but not including) a terminating null byte ('\\0'); if a precision is specified, no more than the number specified -are written. If a precision is given, no null byte need be present; +are written. +If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte. @@ -661,10 +701,13 @@ Wide characters from the array are converted to multibyte characters .BR wcrtomb () function, with a conversion state starting in the initial state before the first wide character), up to and including a terminating null -wide character. The resulting multibyte characters are written up to -(but not including) the terminating null byte. If a precision is +wide character. +The resulting multibyte characters are written up to +(but not including) the terminating null byte. +If a precision is specified, no more bytes than the number specified are written, but -no partial multibyte characters are written. Note that the precision +no partial multibyte characters are written. +Note that the precision determines the number of .I bytes written, not the number of @@ -699,15 +742,19 @@ or The number of characters written so far is stored into the integer indicated by the .I "int *" -(or variant) pointer argument. No argument is converted. -.TP +(or variant) pointer argument. +No argument is converted. +.TP .B m -(Glibc extension.) Print output of +(Glibc extension.) +Print output of .IR strerror(errno) . No argument is required. .TP .B % -A `%' is written. No argument is converted. The complete conversion +A `%' is written. +No argument is converted. +The complete conversion specification is `%%'. .SH EXAMPLE .br @@ -751,7 +798,8 @@ fprintf(stdout, format, .RE where .I format -depends on locale, and may permute the arguments. With the value +depends on locale, and may permute the arguments. +With the value .RS .nf "%1$s, %3$d. %2$s, %4$d:%5$.2d\en" @@ -769,7 +817,7 @@ To allocate a sufficiently large string and print into it #include char * -make_message(const char *fmt, ...) +make_message(const char *fmt, ...) { /* Guess we need no more than 100 bytes. */ int n, size = 100; @@ -778,7 +826,7 @@ make_message(const char *fmt, ...) if ((p = malloc(size)) == NULL) return NULL; - + while (1) { /* Try to print in the allocated space. */ va_start(ap, fmt); @@ -808,7 +856,8 @@ The glibc implementation of the functions 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 +since glibc version 2.1. +Until glibc 2.0.6 they would return \-1 when the output was truncated. .SH "CONFORMING TO" The @@ -844,7 +893,8 @@ 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, +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, @@ -863,7 +913,7 @@ glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A. glibc 2.2 adds the conversion character F with C99 semantics, and the flag character I. .SH HISTORY -Unix V7 defines the three routines +Unix V7 defines the three routines .BR printf (), .BR fprintf (), .BR sprintf (), @@ -871,7 +921,7 @@ 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 +2.11BSD has .BR vprintf (), .BR vfprintf (), .BR vsprintf (), @@ -901,7 +951,8 @@ Because 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 +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 () @@ -929,7 +980,8 @@ Code such as .BI printf( foo ); often indicates a bug, since .I foo -may contain a % character. If +may contain a % character. +If .I foo comes from untrusted user input, it may contain %n, causing the .BR printf () diff --git a/man3/profil.3 b/man3/profil.3 index 42cfbb86f..e1b0cd591 100644 --- a/man3/profil.3 +++ b/man3/profil.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,11 +34,13 @@ profil \- execution time profile .BI "int profil(u_short *" buf ", size_t " bufsiz ", size_t " offset ", u_int " scale ); .SH DESCRIPTION This routine provides a means to find out in what areas your program -spends most of its time. The argument +spends most of its time. +The argument .I buf points to .I bufsiz -bytes of core. Every virtual 10 milliseconds, the user's program counter (PC) +bytes of core. +Every virtual 10 milliseconds, the user's program counter (PC) is examined: .I offset is subtracted and the result is multiplied by diff --git a/man3/program_invocation_name.3 b/man3/program_invocation_name.3 index 6aaf84d6f..b79584815 100644 --- a/man3/program_invocation_name.3 +++ b/man3/program_invocation_name.3 @@ -33,22 +33,22 @@ obtain name used to invoke calling program .SH DESCRIPTION .I program_invocation_name contains the name that was used to invoke the calling program. -This is the same as the value of +This is the same as the value of .I argv[0] -in +in .IR main (), -with the difference that the scope of +with the difference that the scope of .I program_invocation_name is global. .I program_invocation_short_name -contains the basename component of name that was used to invoke +contains the basename component of name that was used to invoke the calling program. That is, it is the same value as .IR program_invocation_name , with all text up to and including the final slash (/), if any, removed. -These variables are automatically initialised by the glibc run-time +These variables are automatically initialised by the glibc run-time startup code. .SH NOTES The Linux-specific diff --git a/man3/psignal.3 b/man3/psignal.3 index d739054c5..67ab42077 100644 --- a/man3/psignal.3 +++ b/man3/psignal.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/putenv.3 b/man3/putenv.3 index 041f1478c..8a8c22cde 100644 --- a/man3/putenv.3 +++ b/man3/putenv.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,10 +43,12 @@ putenv \- change or add an environment variable .fi .SH DESCRIPTION The \fBputenv\fP() function adds or changes the value of environment -variables. The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. -If \fIname\fP does not already exist in the environment, then -\fIstring\fP is added to the environment. If \fIname\fP does exist, -then the value of \fIname\fP in the environment is changed to +variables. +The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. +If \fIname\fP does not already exist in the environment, then +\fIstring\fP is added to the environment. +If \fIname\fP does exist, +then the value of \fIname\fP in the environment is changed to \fIvalue\fP. The string pointed to by \fIstring\fP becomes part of the environment, so altering the string changes the environment. @@ -67,7 +69,8 @@ and does not contain an `=' character, then the variable \fIname\fP is removed from the environment. If \fBputenv\fP() has to allocate a new array \fIenviron\fP, and the previous array was also allocated by \fBputenv\fP(), -then it will be freed. In no case will the old storage associated +then it will be freed. +In no case will the old storage associated to the environment variable itself be freed. .LP The libc4 and libc5 and glibc 2.1.2 versions conform to SUSv2: @@ -79,7 +82,8 @@ as the argument, then return from the calling function while \fIstring\fP is still part of the environment.) However, glibc 2.0-2.1.1 differs: a copy of the string is used. On the one hand this causes a memory leak, and on the other hand -it violates SUSv2. This has been fixed in glibc2.1.2. +it violates SUSv2. +This has been fixed in glibc2.1.2. .LP The 4.4BSD version, like glibc 2.0, uses a copy. .LP diff --git a/man3/putgrent.3 b/man3/putgrent.3 index 35e1f1217..739e5e18e 100644 --- a/man3/putgrent.3 +++ b/man3/putgrent.3 @@ -11,12 +11,12 @@ putgrent \- write a group database entry to a file .sp .BI "int putgrent(const struct group *" grp ", FILE *" fp ); .SH DESCRIPTION -The +The .BR putgrent () function is the counterpart for .BR fgetgrent (). The function writes the content of the provided struct group into the -file pointed to by +file pointed to by .IR fp . The list of group members must be NULL terminated or NULL initialized. .sp diff --git a/man3/putpwent.3 b/man3/putpwent.3 index b5da3b69e..e05e7833b 100644 --- a/man3/putpwent.3 +++ b/man3/putpwent.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/puts.3 b/man3/puts.3 index a473698cb..8182daeb3 100644 --- a/man3/puts.3 +++ b/man3/puts.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -80,8 +80,8 @@ library for the same output stream. For non-locking counterparts, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -.BR fputc (), -.BR putc () +.BR fputc (), +.BR putc () and .BR putchar () return the character written as an @@ -92,8 +92,8 @@ or .B EOF on error. .PP -.BR puts () -and +.BR puts () +and .BR fputs () return a non-negative number on success, or .B EOF diff --git a/man3/putwchar.3 b/man3/putwchar.3 index b6eb55673..7a5a94a3f 100644 --- a/man3/putwchar.3 +++ b/man3/putwchar.3 @@ -23,16 +23,18 @@ putwchar \- write a wide character to standard output .fi .SH DESCRIPTION The \fBputwchar\fP() function is the wide-character equivalent of the -\fBputchar\fP() function. It writes the wide character \fIwc\fP to \fBstdout\fP. -If \fIferror(stdout)\fP becomes true, it returns WEOF. If a wide character +\fBputchar\fP() function. +It writes the wide character \fIwc\fP to \fBstdout\fP. +If \fIferror(stdout)\fP becomes true, it returns WEOF. +If a wide character conversion error occurs, it sets \fIerrno\fP to \fBEILSEQ\fP and returns WEOF. Otherwise it returns \fIwc\fP. .PP For a non-locking counterpart, see .BR unlocked_stdio (3). .SH "RETURN VALUE" -The \fBputwchar\fP() function returns \fIwc\fP if no error occurred, or WEOF to -indicate an error. +The \fBputwchar\fP() function returns \fIwc\fP if no error occurred, +or WEOF to indicate an error. .SH "CONFORMING TO" C99. .SH NOTES diff --git a/man3/qecvt.3 b/man3/qecvt.3 index a6c555c38..c4095f022 100644 --- a/man3/qecvt.3 +++ b/man3/qecvt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -56,13 +56,15 @@ See and .BR gcvt (3). .SH NOTES -These functions are obsolete. Instead, +These functions are obsolete. +Instead, .BR sprintf () is recommended. .SH "CONFORMING TO" SVr4. Not seen in most common Unix implementations, -but occurs in SunOS. Not supported by libc4 and libc5. +but occurs in SunOS. +Not supported by libc4 and libc5. Supported by glibc. .SH "SEE ALSO" .BR ecvt (3), diff --git a/man3/qsort.3 b/man3/qsort.3 index 3be3ddec8..1ceafde9e 100644 --- a/man3/qsort.3 +++ b/man3/qsort.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,7 +43,8 @@ qsort \- sorts an array .fi .SH DESCRIPTION The \fBqsort\fP() function sorts an array with \fInmemb\fP elements of -size \fIsize\fP. The \fIbase\fP argument points to the start of the +size \fIsize\fP. +The \fIbase\fP argument points to the start of the array. .PP The contents of the array are sorted in ascending order according to a @@ -52,7 +53,8 @@ arguments that point to the objects being compared. .PP The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively -less than, equal to, or greater than the second. If two members compare +less than, equal to, or greater than the second. +If two members compare as equal, their order in the sorted array is undefined. .SH "RETURN VALUE" The \fBqsort\fP() function returns no value. @@ -65,14 +67,14 @@ argument include .BR alphasort () and .BR versionsort (). -To compare C strings, the comparison function can call -.BR strcmp (), +To compare C strings, the comparison function can call +.BR strcmp (), as shown in the example below. .SH EXAMPLE For one example of use, see the example under .BR bsearch (3). -Another example is the following example program, +Another example is the following example program, which sorts the strings given in its command-line arguments: .sp .nf diff --git a/man3/raise.3 b/man3/raise.3 index 68c524532..f9087c0f6 100644 --- a/man3/raise.3 +++ b/man3/raise.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -33,7 +33,7 @@ raise \- send a signal to the current process .BI "int raise(int " sig ); .fi .SH DESCRIPTION -The +The .BR raise () function sends a signal to the current process. It is equivalent to diff --git a/man3/rand.3 b/man3/rand.3 index a066282d2..933eba7be 100644 --- a/man3/rand.3 +++ b/man3/rand.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -57,20 +57,24 @@ sequence of pseudo-random integers to be returned by \fBrand\fP(). These sequences are repeatable by calling \fBsrand\fP() with the same seed value. .PP -If no seed value is provided, the \fBrand\fP() function is automatically +If no seed value is provided, the \fBrand\fP() function is automatically seeded with a value of 1. .PP The function .BR rand () is not reentrant or thread-safe, since it -uses hidden state that is modified on each call. This might just be +uses hidden state that is modified on each call. +This might just be the seed value to be used by the next call, or it might be something -more elaborate. In order to get reproducible behaviour in a threaded -application, this state must be made explicit. The function +more elaborate. +In order to get reproducible behaviour in a threaded +application, this state must be made explicit. +The function .BR rand_r () is supplied with a pointer to an unsigned int, to be used as state. This is a very small amount of state, so this function will be a weak -pseudo-random generator. Try +pseudo-random generator. +Try .BR drand48_r (3) instead. .SH "RETURN VALUE" @@ -130,7 +134,8 @@ j = 1 + (rand() % 10); (which uses lower-order bits)." .RE .PP -Random-number generation is a complex topic. The +Random-number generation is a complex topic. +The .I Numerical Recipes in C book (see reference above) provides an excellent discussion of practical random-number generation diff --git a/man3/random.3 b/man3/random.3 index b5fcb56fb..f2ab23087 100644 --- a/man3/random.3 +++ b/man3/random.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,18 +46,21 @@ random, srandom, initstate, setstate \- random number generator .SH DESCRIPTION The \fBrandom\fP() function uses a non-linear additive feedback random number generator employing a default table of size 31 long integers to -return successive pseudo-random numbers in the range from 0 to \fBRAND_MAX\fR. +return successive pseudo-random numbers in +the range from 0 to \fBRAND_MAX\fR. The period of this random number generator is very large, approximately 16*((2**31)\-1). .PP The \fBsrandom\fP() function sets its argument as the seed for a new sequence of pseudo-random integers to be returned by \fBrandom\fP(). These sequences are repeatable by calling \fBsrandom\fP() with the same -seed value. If no seed value is provided, the \fBrandom\fP() function +seed value. +If no seed value is provided, the \fBrandom\fP() function is automatically seeded with a value of 1. .PP The \fBinitstate\fP() function allows a state array \fIstate\fP to -be initialized for use by \fBrandom\fP(). The size of the state array +be initialized for use by \fBrandom\fP(). +The size of the state array \fIn\fP is used by \fBinitstate\fP() to decide how sophisticated a random number generator it should use \(em the larger the state array, the better the random numbers will be. \fIseed\fP is the seed for the @@ -65,15 +68,17 @@ initialization, which specifies a starting point for the random number sequence, and provides for restarting at the same point. .PP The \fBsetstate\fP() function changes the state array used by the -\fBrandom\fP() function. The state array \fIstate\fP is used for +\fBrandom\fP() function. +The state array \fIstate\fP is used for random number generation until the next call to \fBinitstate\fP() -or \fBsetstate\fP(). \fIstate\fP must first have been initialized +or \fBsetstate\fP(). \fIstate\fP must first have been initialized using \fBinitstate\fP() or be the result of a previous call of \fBsetstate\fP(). .SH "RETURN VALUE" The \fBrandom\fP() function returns a value between 0 and RAND_MAX. -The \fBsrandom\fP() function returns no value. The \fBinitstate\fP() -and \fBsetstate\fP() functions return a pointer to the previous state +The \fBsrandom\fP() function returns no value. +The \fBinitstate\fP() +and \fBsetstate\fP() functions return a pointer to the previous state array, or NULL on error. .SH ERRORS .TP @@ -82,7 +87,8 @@ A state array of less than 8 bytes was specified to \fBinitstate\fP(). .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 +the nearest known amount. +Using less than 8 bytes will cause an error. .SH "CONFORMING TO" 4.3BSD, POSIX.1-2001. diff --git a/man3/rcmd.3 b/man3/rcmd.3 index 2753d40a6..74e4f6149 100644 --- a/man3/rcmd.3 +++ b/man3/rcmd.3 @@ -97,7 +97,7 @@ If the connection succeeds, a socket in the Internet domain of type .Dv SOCK_STREAM is returned to the caller, and given to the remote -command as +command as .Em stdin and .Em stdout . @@ -115,10 +115,10 @@ signal numbers, to be forwarded to the process group of the command. If .Fa fd2p -is 0, then the +is 0, then the .Em stderr (unit 2 of the remote -command) will be made the same as the +command) will be made the same as the .Em stdout and no provision is made for sending arbitrary signals to the remote process, @@ -130,12 +130,12 @@ The protocol is described in detail in The .Fn rresvport function is used to obtain a socket with a privileged -address bound to it. This socket is suitable for use -by +address bound to it. +This socket is suitable for use by .Fn rcmd -and several other functions. Privileged Internet ports are those -in the range 0 to 1023. Only the superuser -is allowed to bind an address of this sort to a socket. +and several other functions. +Privileged Internet ports are those in the range 0 to 1023. +Only the superuser is allowed to bind an address of this sort to a socket. .Pp The .Fn iruserok @@ -196,7 +196,7 @@ is overloaded to mean ``All network ports in use.'' Not in POSIX.1-2001. Present on the BSDs, Solaris, and many other systems. These -functions appeared in +functions appeared in .Bx 4.2 . .Sh SEE ALSO .Xr rlogin 1 , diff --git a/man3/re_comp.3 b/man3/re_comp.3 index 08e1a8905..f94370515 100644 --- a/man3/re_comp.3 +++ b/man3/re_comp.3 @@ -64,7 +64,7 @@ returns 1 for a successful match, zero for failure. .SH "CONFORMING TO" 4.3BSD .SH NOTES -These functions are obsolete; the functions documented in +These functions are obsolete; the functions documented in .BR regcomp (3) should be used instead. .SH "SEE ALSO" diff --git a/man3/readdir.3 b/man3/readdir.3 index af62063d1..9addb31ab 100644 --- a/man3/readdir.3 +++ b/man3/readdir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -76,8 +76,8 @@ as an XSI extension. The data returned by \fBreaddir\fP() may be overwritten by subsequent calls to \fBreaddir\fP() for the same directory stream. .SH "RETURN VALUE" -The \fBreaddir\fP() function returns a pointer to a -.I dirent +The \fBreaddir\fP() function returns a pointer to a +.I dirent structure, or NULL if an error occurs or end-of-file is reached. On error, diff --git a/man3/realpath.3 b/man3/realpath.3 index a2b139b9a..89e45bbb6 100644 --- a/man3/realpath.3 +++ b/man3/realpath.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -31,15 +31,15 @@ realpath \- return the canonicalized absolute pathname .B #include .B #include .sp -.BI "char *realpath(const char *" path ", char *" resolved_path ); +.BI "char *realpath(const char *" path ", char *" resolved_path ); .SH DESCRIPTION .BR realpath () expands all symbolic links and resolves references to -.IR '/./' ", " '/../' -and extra -.I '/' -characters in the null terminated string named by +.IR '/./' ", " '/../' +and extra +.I '/' +characters in the null terminated string named by .I path and stores the canonicalized absolute pathname in the buffer of size .B PATH_MAX @@ -58,10 +58,11 @@ returns a pointer to the Otherwise it returns a NULL pointer, and the contents of the array -.I resolved_path -are undefined. The global variable -.I errno -is set to indicate the error. +.I resolved_path +are undefined. +The global variable +.I errno +is set to indicate the error. .SH ERRORS .TP .B EACCES @@ -82,9 +83,9 @@ An I/O error occurred while reading from the file system. Too many symbolic links were encountered in translating the pathname. .TP .B ENAMETOOLONG -A component of a pathname exceeded +A component of a pathname exceeded .B NAME_MAX -characters, or an entire pathname exceeded +characters, or an entire pathname exceeded .B PATH_MAX characters. .TP @@ -108,11 +109,12 @@ 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 +.\" 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 +Avoid using this function. +It is broken by design since (unless using the non-standard .I "resolved_path\ ==\ NULL" feature) it is @@ -127,7 +129,8 @@ And asking does not really help, since on the one hand POSIX warns that the result of .BR pathconf () -may be huge and unsuitable for mallocing memory. And on the other +may be huge and unsuitable for mallocing memory. +And on the other hand .BR pathconf () may return \-1 to signify that PATH_MAX is not bounded. @@ -144,11 +147,11 @@ In Linux this function appears in libc 4.5.21. 4.4BSD, POSIX.1-2001. In 4.4BSD and Solaris the limit on the pathname length is MAXPATHLEN -(found in ). +(found in ). SUSv2 prescribes PATH_MAX and NAME_MAX, as found in or provided by the .BR pathconf () -function. +function. A typical source fragment would be .LP .RS @@ -165,7 +168,8 @@ A typical source fragment would be (But see the BUGS section.) .LP The 4.4BSD, Linux and SUSv2 versions always return an absolute -pathname. Solaris may return a relative pathname when the +pathname. +Solaris may return a relative pathname when the .I path argument is relative. The prototype of diff --git a/man3/recno.3 b/man3/recno.3 index 8e1f01771..9c1a752c7 100644 --- a/man3/recno.3 +++ b/man3/recno.3 @@ -31,7 +31,7 @@ .\" .\" @(#)recno.3 8.5 (Berkeley) 8/18/94 .\" -.TH RECNO 3 1994-08-18 +.TH RECNO 3 1994-08-18 .UC 7 .SH NAME recno \- record number database access method diff --git a/man3/regex.3 b/man3/regex.3 index c2599d7f7..707541b76 100644 --- a/man3/regex.3 +++ b/man3/regex.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,77 +38,78 @@ regcomp, regexec, regerror, regfree \- POSIX regex functions .B #include .sp .xx \w'\fBint\ regcomp(\fR'u -.BI "int\ regcomp(regex_t *" preg ", const char *" regex , +.BI "int\ regcomp(regex_t *" preg ", const char *" regex , .BI "int " cflags ); .xx \w'\fBint\ regexec(\fR'u .BI "int\ regexec(const regex_t *" preg ", const char *" string , -.BI "size_t " nmatch ", regmatch_t " pmatch[] , +.BI "size_t " nmatch ", regmatch_t " pmatch[] , .BI "int " eflags ); .xx \w'\fBsize_t\ regerror(\fR'u -.BI "size_t\ regerror(int " errcode , -.BI "const regex_t *" preg ", char *" errbuf , +.BI "size_t\ regerror(int " errcode , +.BI "const regex_t *" preg ", char *" errbuf , .BI "size_t " errbuf_size ); .xx \w'\fBvoid\ regfree(\fR' .BI "void\ regfree(regex_t *" preg ); .SH "POSIX REGEX COMPILING" .BR regcomp () is used to compile a regular expression into a form that is suitable -for subsequent +for subsequent .BR regexec () searches. .BR regcomp () -is supplied with -.IR preg , -a pointer to a pattern buffer storage area; +is supplied with +.IR preg , +a pointer to a pattern buffer storage area; .IR regex , a pointer to the null-terminated string and .IR cflags , flags used to determine the type of compilation. All regular expression searching must be done via a compiled pattern -buffer, thus +buffer, thus .BR regexec () -must always be supplied with the address of a +must always be supplied with the address of a .BR regcomp () initialized pattern buffer. -.I cflags -may be the +.I cflags +may be the .RB bitwise- or of one or more of the following: -.TP +.TP .B REG_EXTENDED -Use +Use .B POSIX -Extended Regular Expression syntax when interpreting +Extended Regular Expression syntax when interpreting .IR regex . If not set, .B POSIX Basic Regular Expression syntax is used. -.TP +.TP .B REG_ICASE -Do not differentiate case. Subsequent +Do not differentiate case. +Subsequent .BR regexec () searches using this pattern buffer will be case insensitive. -.TP +.TP .B REG_NOSUB Support for substring addressing of matches is not required. The .I nmatch and .I pmatch -parameters to +parameters to .BR regexec () are ignored if the pattern buffer supplied was compiled with this flag set. -.TP +.TP .B REG_NEWLINE Match-any-character operators don't match a newline. -A non-matching list +A non-matching list .RB ( [^...] ) not containing a newline does not match a newline. - + Match-beginning-of-line operator .RB ( ^ ) matches the empty string immediately after a newline, regardless of @@ -116,40 +117,40 @@ whether .IR eflags , the execution flags of .BR regexec (), -contains +contains .BR REG_NOTBOL . -Match-end-of-line operator +Match-end-of-line operator .RB ( $ ) matches the empty string immediately before a newline, regardless of -whether -.IR eflags +whether +.IR eflags contains .BR REG_NOTEOL . .SH "POSIX REGEX MATCHING" .BR regexec () is used to match a null-terminated string -against the precompiled pattern buffer, +against the precompiled pattern buffer, .IR preg . .I nmatch and .I pmatch -are used to provide information regarding the location of any matches. +are used to provide information regarding the location of any matches. .I eflags -may be the +may be the .RB bitwise- or -of one or both of +of one or both of .B REG_NOTBOL and -.B REG_NOTEOL +.B REG_NOTEOL which cause changes in matching behaviour described below. .TP .B REG_NOTBOL The match-beginning-of-line operator always fails to match (but see the compilation flag -.B REG_NEWLINE +.B REG_NEWLINE above) -This flag may be used when different portions of a string are passed to +This flag may be used when different portions of a string are passed to .BR regexec () and the beginning of the string should not be interpreted as the beginning of the line. @@ -160,21 +161,21 @@ compilation flag .B REG_NEWLINE above) .SS "BYTE OFFSETS" -Unless +Unless .B REG_NOSUB was set for the compilation of the pattern buffer, it is possible to -obtain substring match addressing information. +obtain substring match addressing information. .I pmatch must be dimensioned to have at least .I nmatch elements. These are filled in by .BR regexec () -with substring match addresses. Any unused structure elements -will contain the value \-1. +with substring match addresses. +Any unused structure elements will contain the value \-1. -The -.B regmatch_t +The +.B regmatch_t structure which is the type of .I pmatch is defined in @@ -193,15 +194,16 @@ is defined in .B regmatch_t; .RE -Each +Each .I rm_so element that is not \-1 indicates the start offset of the next largest -substring match within the string. The relative -.I rm_eo +substring match within the string. +The relative +.I rm_eo element indicates the end offset of the match. .SH "POSIX ERROR REPORTING" .BR regerror () -is used to turn the error codes that can be returned by both +is used to turn the error codes that can be returned by both .BR regcomp () and .BR regexec () @@ -218,17 +220,18 @@ and the size of the string buffer, .IR errbuf_size . It returns the size of the .I errbuf -required to contain the null-terminated error message string. If both +required to contain the null-terminated error message string. +If both .I errbuf and .I errbuf_size -are non-zero, +are non-zero, .I errbuf -is filled in with the first +is filled in with the first .I "errbuf_size \- 1" characters of the error message and a terminating null. .SH "POSIX PATTERN BUFFER FREEING" -Supplying +Supplying .BR regfree () with a precompiled pattern buffer, .I preg @@ -240,11 +243,11 @@ process, returns zero for a successful compilation or an error code for failure. .BR regexec () -returns zero for a successful match or +returns zero for a successful match or .B REG_NOMATCH for failure. .SH ERRORS -The following errors can be returned by +The following errors can be returned by .BR regcomp (): .TP .B REG_BADBR @@ -254,7 +257,7 @@ Invalid use of back reference operator. Invalid use of pattern operators such as group or list. .TP .B REG_BADRPT -Invalid use of repetition operators such as using +Invalid use of repetition operators such as using .RB ` * ' as the first character. .TP @@ -271,7 +274,8 @@ Invalid collating element. Unknown character class name. .TP .B REG_EEND -Non specific error. This is not defined by POSIX.2. +Non specific error. +This is not defined by POSIX.2. .TP .B REG_EESCAPE Trailing backslash. @@ -297,4 +301,4 @@ POSIX.1-2001. .SH "SEE ALSO" .BR regex (7), GNU regex manual - + diff --git a/man3/remainder.3 b/man3/remainder.3 index eb7a3495e..2de66fcaa 100644 --- a/man3/remainder.3 +++ b/man3/remainder.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -26,7 +26,7 @@ .\" 386BSD man pages .\" .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) -.\" Modified 2002-08-10 Walter Harms +.\" Modified 2002-08-10 Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" Modified 2003-11-18, 2004-10-05 aeb .\" @@ -87,20 +87,20 @@ The denominator .I y is zero. .SH "CONFORMING TO" -IEC 60559. -The functions -.BR remainder (), -.BR remainderf (), -and +IEC 60559. +The functions +.BR remainder (), +.BR remainderf (), +and .BR remainderl () are from C99. The function .BR drem () -is from 4.3BSD. The +is from 4.3BSD. The .I float and .I "long double" -variants +variants .BR dremf () and .BR dreml () diff --git a/man3/remove.3 b/man3/remove.3 index ae6542686..746145f31 100644 --- a/man3/remove.3 +++ b/man3/remove.3 @@ -12,7 +12,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -20,7 +20,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" --snip-- @@ -58,7 +58,8 @@ If the name referred to a socket, fifo or device the name for it is removed but processes which have the object open may continue to use it. .SH "RETURN VALUE" -On success, zero is returned. On error, \-1 is returned, and +On success, zero is returned. +On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS diff --git a/man3/remquo.3 b/man3/remquo.3 index e07122253..2c789d6d5 100644 --- a/man3/remquo.3 +++ b/man3/remquo.3 @@ -4,7 +4,7 @@ .\" polished, aeb .TH REMQUO 3 2002-08-10 "gnu" "Linux Programmer's Manual" .SH NAME -remquo, remquof, remquol \- remainder and part of quotient +remquo, remquof, remquol \- remainder and part of quotient .SH SYNOPSIS .nf #define _ISOC99_SOURCE @@ -25,7 +25,8 @@ by .IR y . A few bits of the quotient are stored via the .I quo -pointer. The remainder is returned as function value. +pointer. +The remainder is returned as function value. The value of the remainder is the same as that computed by the .BR remainder (3) diff --git a/man3/resolver.3 b/man3/resolver.3 index b68ec89b1..01306e6b4 100644 --- a/man3/resolver.3 +++ b/man3/resolver.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -29,7 +29,7 @@ .\" .TH RESOLVER 3 2004-10-31 "BSD" "Linux Programmer's Manual" .SH NAME -res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, +res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, dn_comp, dn_expand \- resolver routines .SH SYNOPSIS .nf @@ -62,7 +62,7 @@ dn_comp, dn_expand \- resolver routines .BI "char *" buf ", int " buflen ); .RE .sp -.BI "int res_send(const char *" msg ", int " msglen ", char *" answer , +.BI "int res_send(const char *" msg ", int " msglen ", char *" answer , .RS .BI "int " anslen ); .RE @@ -87,7 +87,8 @@ domain name servers. .PP The \fBres_init\fP() function reads the configuration files (see resolv.conf(5)) to get the default domain name, search order and name -server address(es). If no server is given, the local host is tried. +server address(es). +If no server is given, the local host is tried. If no domain is given, that associated with the local host is used. It can be overridden with the environment variable LOCALDOMAIN. \fBres_init\fP() is normally executed by the first call to one of the @@ -95,7 +96,8 @@ other functions. .PP The \fBres_query\fP() function queries the name server for the fully-qualified domain name \fIname\fP of specified \fItype\fP and -\fIclass\fP. The reply is left in the buffer \fIanswer\fP of length +\fIclass\fP. +The reply is left in the buffer \fIanswer\fP of length \fIanslen\fP supplied by the caller. .PP The \fBres_search\fP() function makes a query and waits for the response @@ -109,34 +111,41 @@ on the concatenation of \fIname\fP and \fIdomain\fP. The following functions are lower-level routines used by \fBres_query\fP(). .PP The \fBres_mkquery\fP() function constructs a query message in \fIbuf\fP -of length \fIbuflen\fP for the domain name \fIdname\fP. The query type +of length \fIbuflen\fP for the domain name \fIdname\fP. +The query type \fIop\fP is usually QUERY, but can be any of the types defined in \fI\fP. \fInewrr\fP is currently unused. .PP The \fBres_send\fP() function sends a pre-formatted query given in \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP -which is of length \fIanslen\fP. It will call \fBres_init\fP(), if it +which is of length \fIanslen\fP. +It will call \fBres_init\fP(), if it has not already been called. .PP The \fBdn_comp\fP() function compresses the domain name \fIexp_dn\fP and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. The compression uses an array of pointers \fIdnptrs\fP to previously -compressed names in the current message. The first pointer points -to the beginning of the message and the list ends with NULL. The limit -of the array is specified by \fIlastdnptr\fP. if \fIdnptr\fP is NULL, -domain names are not compressed. If \fIlastdnptr\fP is NULL, the list +compressed names in the current message. +The first pointer points +to the beginning of the message and the list ends with NULL. +The limit of the array is specified by \fIlastdnptr\fP. +If \fIdnptr\fP is NULL, domain names are not compressed. +If \fIlastdnptr\fP is NULL, the list of labels is not updated. .PP The \fPdn_expand\fP() function expands the compressed domain name \fIcomp_dn\fP to a full domain name, which is placed in the buffer -\fIexp_dn\fP of size \fIlength\fP. The compressed name is contained +\fIexp_dn\fP of size \fIlength\fP. +The compressed name is contained in a query or reply message, and \fImsg\fP points to the beginning of the message. .PP The resolver routines use global configuration and state information -contained in the structure \fI_res\fP, which is defined in -\fI\fP. The only field that is normally manipulated by the -user is \fI_res.options\fP. This field can contain the bitwise ``or'' +contained in the structure \fI_res\fP, which is defined in +\fI\fP. +The only field that is normally manipulated by the +user is \fI_res.options\fP. +This field can contain the bitwise ``or'' of the following options: .TP .B RES_INIT @@ -157,13 +166,15 @@ Use TCP connections for queries rather than UDP datagrams. Query primary domain name server only. .TP .B RES_IGNTC -Ignore truncation errors. Don't retry with TCP. [Not currently +Ignore truncation errors. +Don't retry with TCP. [Not currently implemented]. .TP .B RES_RECURSE -Set the recursion desired bit in queries. Recursion is carried out -by the domain name server, not by \fBres_send\fP(). [Enabled by -default]. +Set the recursion desired bit in queries. +Recursion is carried out +by the domain name server, not by \fBres_send\fP(). +[Enabled by default]. .TP .B RES_DEFNAMES If set, \fBres_search\fP() will append the default domain name to @@ -175,7 +186,8 @@ Used with RES_USEVC to keep the TCP connection open between queries. .TP .B RES_DNSRCH If set, \fBres_search\fP() will search for host names in the current -domain and in parent domains. This option is used by +domain and in parent domains. +This option is used by .BR gethostbyname (3). [Enabled by default]. .SH "RETURN VALUE" diff --git a/man3/rewinddir.3 b/man3/rewinddir.3 index 3a3927ddf..ea2a02c83 100644 --- a/man3/rewinddir.3 +++ b/man3/rewinddir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/rint.3 b/man3/rint.3 index fadd51b74..8897be6f9 100644 --- a/man3/rint.3 +++ b/man3/rint.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -55,7 +55,8 @@ functions do the same, but will raise the .I inexact exception when the result differs in value from the argument. .SH "RETURN VALUE" -The rounded integer value. If \fIx\fP is integral or infinite, +The rounded integer value. +If \fIx\fP is integral or infinite, \fIx\fP itself is returned. .SH ERRORS No errors other than EDOM and ERANGE can occur. diff --git a/man3/round.3 b/man3/round.3 index a66dfc991..3e41f6bd9 100644 --- a/man3/round.3 +++ b/man3/round.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,10 +38,11 @@ Compile with \-std=c99; link with \-lm. .SH DESCRIPTION These functions round \fIx\fP to the nearest integer, but round halfway cases away from zero (regardless of the current rounding -direction), instead of to the nearest even integer like +direction), instead of to the nearest even integer like .BR rint (). .SH "RETURN VALUE" -The rounded integer value. If \fIx\fP is integral or infinite, +The rounded integer value. +If \fIx\fP is integral or infinite, \fIx\fP itself is returned. .SH ERRORS No errors other than EDOM and ERANGE can occur. diff --git a/man3/rpc.3 b/man3/rpc.3 index bad64f8d9..de0208ff7 100644 --- a/man3/rpc.3 +++ b/man3/rpc.3 @@ -1,7 +1,7 @@ .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) .\" .\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI -.TH RPC 3 1988-02-16 +.TH RPC 3 1988-02-16 .SH NAME rpc \- library routines for remote procedure calls .SH "SYNOPSIS AND DESCRIPTION" @@ -40,7 +40,8 @@ auth_destroy(auth) A macro that destroys the authentication information associated with .IR auth . Destruction usually involves deallocation of private data -structures. The use of +structures. +The use of .I auth is undefined after calling .BR auth_destroy (). @@ -58,7 +59,8 @@ authnone_create() Create and returns an .SM RPC authentication handle that passes nonusable authentication -information with each remote procedure call. This is the +information with each remote procedure call. +This is the default authentication used by .SM RPC. .if t .ne 10 @@ -169,7 +171,8 @@ resultproc_t eachresult; Like .BR callrpc (), except the call message is broadcast to all locally -connected broadcast nets. Each time it receives a +connected broadcast nets. +Each time it receives a response, this routine calls .BR eachresult (), whose form is: @@ -201,7 +204,8 @@ waits for more replies; otherwise it returns with appropriate status. .IP Warning: broadcast sockets are limited in size to the -maximum transfer unit of the data link. For ethernet, +maximum transfer unit of the data link. +For ethernet, this value is 1500 bytes. .br .if t .ne 13 @@ -252,10 +256,12 @@ clnt_destroy(clnt) .IP A macro that destroys the client's .SM RPC -handle. Destruction usually involves deallocation +handle. +Destruction usually involves deallocation of private data structures, including .I clnt -itself. Use of +itself. +Use of .I clnt is undefined after calling .BR clnt_destroy (). @@ -282,15 +288,16 @@ Generic client creation routine. identifies the name of the remote host where the server is located. .I proto -indicates which kind of transport protocol to use. The -currently supported values for this field are \(lqudp\(rq +indicates which kind of transport protocol to use. +The currently supported values for this field are \(lqudp\(rq and \(lqtcp\(rq. Default timeouts are set, but can be modified using .BR clnt_control (). .IP Warning: Using .SM UDP -has its shortcomings. Since +has its shortcomings. +Since .SM UDP\s0-based .SM RPC messages can only hold up to 8 Kbytes of encoded data, @@ -314,7 +321,8 @@ about a client object. .I req indicates the type of operation, and .I info -is a pointer to the information. For both +is a pointer to the information. +For both .SM UDP and .SM TCP\s0, @@ -371,8 +379,8 @@ A macro that frees any data allocated by the .SM RPC/XDR system when it decoded the results of an .SM RPC -call. The -parameter +call. +The parameter .I out is the address of the results, and .I outproc @@ -501,7 +509,8 @@ but instead of sending a message to the standard error indicating why an .SM RPC call failed, return a pointer to a string which contains -the message. The string ends with a +the message. +The string ends with a .SM NEWLINE\s0. .IP .BR clnt_sperrno () @@ -572,7 +581,8 @@ This allows simulation of and acquisition of .SM RPC overheads, such as round trip times, without any -kernel interference. This routine returns +kernel interference. +This routine returns .SM NULL if it fails. .br @@ -598,7 +608,8 @@ version .IR versnum ; the client uses .SM TCP/IP -as a transport. The remote program is located at Internet +as a transport. +The remote program is located at Internet address .IR *addr . If @@ -607,7 +618,8 @@ If is zero, then it is set to the actual port that the remote program is listening on (the remote .B portmap -service is consulted for this information). The parameter +service is consulted for this information). +The parameter .I sockp is a socket; if it is .BR \s-1RPC_ANYSOCK\s0 , @@ -650,7 +662,8 @@ version .IR versnum ; the client uses use .SM UDP/IP -as a transport. The remote program is located at Internet +as a transport. +The remote program is located at Internet address .IR addr . If @@ -658,7 +671,8 @@ If is zero, then it is set to actual port that the remote program is listening on (the remote .B portmap -service is consulted for this information). The parameter +service is consulted for this information). +The parameter .I sockp is a socket; if it is .BR \s-1RPC_ANYSOCK\s0 , @@ -704,7 +718,8 @@ on .IR versnum ; the client uses use .SM UDP/IP -as a transport. The remote program is located at Internet +as a transport. +The remote program is located at Internet address .IR addr . If @@ -712,7 +727,8 @@ If is zero, then it is set to actual port that the remote program is listening on (the remote .B portmap -service is consulted for this information). The parameter +service is consulted for this information). +The parameter .I sockp is a socket; if it is .BR \s-1RPC_ANYSOCK\s0 , @@ -727,7 +743,7 @@ out. The total time for the call to time out is specified by .BR clnt_call (). .IP -This allows the user to specify the maximum packet size for sending and receiving +This allows the user to specify the maximum packet size for sending and receiving .SM UDP\s0-based .SM RPC messages. @@ -804,7 +820,7 @@ The value of is most likely .B .SM IPPROTO_UDP -or +or .BR \s-1IPPROTO_TCP\s0 . A return value of zero means that the mapping does not exist or that @@ -812,7 +828,8 @@ the .SM RPC system failed to contact the remote .B portmap -service. In the latter case, the global variable +service. +In the latter case, the global variable .BR rpc_createerr () contains the .SM RPC @@ -849,7 +866,8 @@ The parameter .I *portp will be modified to the program's port number if the procedure -succeeds. The definitions of other parameters are discussed +succeeds. +The definitions of other parameters are discussed in .BR callrpc () and @@ -878,12 +896,13 @@ and .I port on the machine's .B portmap -service. The value of +service. +The value of .I protocol is most likely .B .SM IPPROTO_UDP -or +or .BR \s-1IPPROTO_TCP\s0 . This routine returns one if it succeeds, zero otherwise. Automatically done by @@ -907,7 +926,8 @@ and .B ports on the machine's .B portmap -service. This routine returns one if it succeeds, zero +service. +This routine returns one if it succeeds, zero otherwise. .br .if t .ne 15 @@ -926,7 +946,8 @@ Register procedure .I procname with the .SM RPC -service package. If a request arrives for program +service package. +If a request arrives for program .IR prognum , version .IR versnum , @@ -962,7 +983,8 @@ struct rpc_createerr rpc_createerr; A global variable whose value is set by any .SM RPC client creation routine -that does not succeed. Use the routine +that does not succeed. +Use the routine .BR clnt_pcreateerror () to print the reason why. .if t .ne 7 @@ -983,7 +1005,8 @@ service transport handle, Destruction usually involves deallocation of private data structures, including .I xprt -itself. Use of +itself. +Use of .I xprt is undefined after calling this routine. .br @@ -1002,7 +1025,8 @@ service side's read file descriptor bit mask; it is suitable as a parameter to the .BR select () -system call. This is only of interest +system call. +This is only of interest if a service implementor does not call .BR svc_run (), but rather does his own asynchronous event processing. @@ -1023,8 +1047,8 @@ int svc_fds; .IP Similar to .BR svc_fdset , -but limited to 32 descriptors. This -interface is obsoleted by +but limited to 32 descriptors. +This interface is obsoleted by .BR svc_fdset . .br .if t .ne 9 @@ -1134,7 +1158,8 @@ int rdfds; .IP Similar to .BR svc_getreqset (), -but limited to 32 descriptors. This interface is obsoleted by +but limited to 32 descriptors. +This interface is obsoleted by .BR svc_getreqset (). .br .if t .ne 17 @@ -1160,7 +1185,8 @@ If .I protocol is zero, the service is not registered with the .B portmap -service. If +service. +If .I protocol is non-zero, then a mapping of the triple .RI [ prognum , versnum , protocol\fR] @@ -1173,7 +1199,7 @@ service (generally is zero, .B .SM IPPROTO_UDP -or +or .B .SM IPPROTO_TCP ). @@ -1203,12 +1229,14 @@ svc_run() .fi .ft R .IP -This routine never returns. It waits for +This routine never returns. +It waits for .SM RPC requests to arrive, and calls the appropriate service procedure using .BR svc_getreq () -when one arrives. This procedure is usually waiting for a +when one arrives. +This procedure is usually waiting for a .BR select () system call to return. .br @@ -1227,7 +1255,8 @@ char *out; Called by an .SM RPC service's dispatch routine to send the results of a -remote procedure call. The parameter +remote procedure call. +The parameter .I xprt is the request's associated transport handle; .I outproc @@ -1282,7 +1311,8 @@ svcerr_decode(xprt) .ft R .IP Called by a service dispatch routine that cannot successfully -decode its parameters. See also +decode its parameters. +See also .BR svc_getargs (). .br .if t .ne 7 @@ -1312,7 +1342,8 @@ svcerr_noprog(xprt) .IP Called when the desired program is not registered with the .SM RPC -package. Service implementors usually do not need this routine. +package. +Service implementors usually do not need this routine. .br .if t .ne 7 .LP @@ -1328,7 +1359,8 @@ svcerr_progvers(xprt) Called when the desired version of a program is not registered with the .SM RPC -package. Service implementors usually do not need this routine. +package. +Service implementors usually do not need this routine. .br .if t .ne 7 .LP @@ -1360,7 +1392,8 @@ svcerr_weakauth(xprt) .IP Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient -authentication parameters. The routine calls +authentication parameters. +The routine calls .BR "svcerr_auth(xprt, \s-1AUTH_TOOWEAK\s0)" . .br .if t .ne 11 @@ -1376,15 +1409,15 @@ u_int recvsize; .fi .ft R .IP -Create a service on top of any open descriptor. Typically, -this -descriptor is a connected socket for a stream protocol such +Create a service on top of any open descriptor. +Typically, this descriptor is a connected socket for a stream protocol such as .SM TCP\s0. .I sendsize and .I recvsize -indicate sizes for the send and receive buffers. If they are +indicate sizes for the send and receive buffers. +If they are zero, a reasonable default is chosen. .br .if t .ne 11 @@ -1399,9 +1432,8 @@ svcraw_create() .IP This routine creates a toy .SM RPC -service transport, to which it returns a pointer. The -transport -is really a buffer within the process's address space, +service transport, to which it returns a pointer. +The transport is really a buffer within the process's address space, so the corresponding .SM RPC client should live in the same @@ -1441,15 +1473,16 @@ which may be in which case a new socket is created. If the socket is not bound to a local .SM TCP -port, then this routine binds it to an arbitrary port. Upon -completion, +port, then this routine binds it to an arbitrary port. +Upon completion, \fB\%xprt\->xp_sock\fR is the transport's socket descriptor, and \fB\%xprt\->xp_port\fR is the transport's port number. This routine returns .SM NULL -if it fails. Since +if it fails. +Since .SM TCP\s0-based .SM RPC uses buffered @@ -1479,8 +1512,8 @@ which may be in which case a new socket is created. If the socket is not bound to a local .SM UDP -port, then this routine binds it to an arbitrary port. Upon -completion, +port, then this routine binds it to an arbitrary port. +Upon completion, \fB\%xprt\->xp_sock\fR is the transport's socket descriptor, and \fB\%xprt\->xp_port\fR @@ -1489,7 +1522,7 @@ This routine returns .SM NULL if it fails. .IP -This allows the user to specify the maximum packet size for sending and +This allows the user to specify the maximum packet size for sending and receiving .SM UDP\s0-based .SM RPC messages. @@ -1522,8 +1555,8 @@ struct accepted_reply *ar; .IP Used for encoding .SM RPC -reply messages. This routine is useful for users who -wish to generate +reply messages. +This routine is useful for users who wish to generate \s-1RPC\s0-style messages without using the .SM RPC @@ -1542,7 +1575,8 @@ struct authunix_parms *aupp; .IP Used for describing .SM UNIX -credentials. This routine is useful for users +credentials. +This routine is useful for users who wish to generate these credentials without using the .SM RPC authentication package. diff --git a/man3/rpmatch.3 b/man3/rpmatch.3 index d8831bd1e..1f089f0ec 100644 --- a/man3/rpmatch.3 +++ b/man3/rpmatch.3 @@ -36,7 +36,7 @@ rpmatch \- determine if the answer to a question is affirmative or negative .fi .SH DESCRIPTION \fBrpmatch\fP() handles a user response to yes or no questions, with -support for internationalization. +support for internationalization. \fIresponse\fP should be a null-terminated string containing a user-supplied response, perhaps obtained with \fBfgets\fP(3) or @@ -46,19 +46,19 @@ The user's language preference is taken into account per the environment variables \fBLANG\fP, \fBLC_MESSAGES\fP, and \fBLC_ALL\fP, if the program has called \fBsetlocale\fP() to effect their changes. -Regardless of the locale, responses matching \fB^[Yy]\fP are always -accepted as affirmative, and those matching \fB^[Nn]\fP are always +Regardless of the locale, responses matching \fB^[Yy]\fP are always +accepted as affirmative, and those matching \fB^[Nn]\fP are always accepted as negative. .SH "RETURN VALUE" -After examining -.IR response , +After examining +.IR response , \fBrpmatch\fP() returns 0 for a recognized negative response ("no"), 1 for a recognized positive response ("yes"), and \-1 when the value of \fIresponse\fP is unrecognized. .SH ERRORS A return value of \-1 may indicate either an invalid input, or some -other error. It is incorrect to only test if the return value is -nonzero. +other error. +It is incorrect to only test if the return value is nonzero. \fBrpmatch\fP() can fail for any of the reasons that \fBregcomp\fP(3) or \fBregexec\fP(3) can fail; the cause of the error @@ -71,11 +71,12 @@ is available on a few other systems. .\" It is available on at least AIX 5.1 and FreeBSD 6.0. .SH BUGS The \fBrpmatch\fP() implementation looks at only the first character -of \fIresponse\fP. As a consequence, "nyes" returns 0, and +of \fIresponse\fP. +As a consequence, "nyes" returns 0, and "ynever; not in a million years" returns 1. It would be preferable to accept input strings much more -strictly, for example (using the extended regular -expression notation described in \fBregex\fP(7)): +strictly, for example (using the extended regular +expression notation described in \fBregex\fP(7)): \fB^([yY]|yes|YES)$\fP and \fB^([nN]|no|NO)$\fP. .SH EXAMPLE The following program displays the results when @@ -95,7 +96,7 @@ main(int argc, char *argv[]) if (argc != 2 || strcmp(argv[1], "--help") == 0) { fprintf(stderr, "%s response\\n", argv[0]); exit(EXIT_FAILURE); - } + } setlocale(LC_ALL, ""); printf("rpmatch() returns: %d\\n", rpmatch(argv[1])); diff --git a/man3/rtime.3 b/man3/rtime.3 index b9e4a99ce..61a95a94f 100644 --- a/man3/rtime.3 +++ b/man3/rtime.3 @@ -5,7 +5,7 @@ .\" .\" Slightly polished, aeb, 2003-04-06 .\" -.TH RTIME 3 2003-04-04 "sunrpc" "RPC time function" +.TH RTIME 3 2003-04-04 "sunrpc" "RPC time function" .SH NAME rtime \- get time from a remote machine .SH SYNOPSIS @@ -34,13 +34,14 @@ In case of error \-1 is returned, and .I errno is set appropriately. .SH ERRORS -All errors for underlying functions -.RB ( sendto (), -.BR poll (), -.BR recvfrom (), -.BR connect (), +All errors for underlying functions +.RB ( sendto (), +.BR poll (), +.BR recvfrom (), +.BR connect (), .BR read ()) -can occur. Moreover: +can occur. +Moreover: .TP .B EIO The number of returned bytes is not 4. @@ -48,7 +49,8 @@ The number of returned bytes is not 4. .B ETIMEDOUT The waiting time as defined in timeout has expired. .SH "EXAMPLE" -This example requires that port 37 is up and open. You may check +This example requires that port 37 is up and open. +You may check that the time entry within .I /etc/inetd.conf is not commented out. @@ -56,7 +58,7 @@ is not commented out. The program connects to a computer called 'linux'. Using 'localhost' does not work. The result is the localtime of the computer 'linux'. -.sp +.sp .nf #include #include @@ -68,8 +70,8 @@ The result is the localtime of the computer 'linux'. int use_tcp = 0; char *servername = "linux"; -int -main(void) +int +main(void) { struct sockaddr_in name; struct rpc_timeval time1 = {0,0}; @@ -80,7 +82,7 @@ main(void) memset((char *) &name, 0, sizeof(name)); sethostent(1); hent = gethostbyname(servername); - memcpy((char *) &name.sin_addr, hent->h_addr, hent->h_length); + memcpy((char *) &name.sin_addr, hent->h_addr, hent->h_length); ret = rtime(&name, &time1, use_tcp ? NULL : &timeout); if (ret < 0) @@ -96,7 +98,8 @@ Only IPV4 is supported. .LP Some .I in.timed -versions only support TCP. Try the above example program with +versions only support TCP. +Try the above example program with .I use_tcp set to 1. .LP @@ -109,7 +112,7 @@ and requires instead of .IR . .SH "BUGS" -.BR rtime () +.BR rtime () in glibc <= 2.2.5 does not work properly on 64bit machines. .SH "SEE ALSO" .BR netdate (1), diff --git a/man3/rtnetlink.3 b/man3/rtnetlink.3 index b995e0892..e9814462f 100644 --- a/man3/rtnetlink.3 +++ b/man3/rtnetlink.3 @@ -19,24 +19,25 @@ rtnetlink \- Macros to manipulate rtnetlink messages .BI "rtnetlink_socket = socket(PF_NETLINK, int " socket_type \ ", NETLINK_ROUTE);" .sp -.BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen ); +.BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen ); .sp -.BI "void *RTA_DATA(struct rtattr *" rta ); +.BI "void *RTA_DATA(struct rtattr *" rta ); .sp -.BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta ); +.BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta ); .sp .BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \ -", unsigned int " rtabuflen ); +", unsigned int " rtabuflen ); .sp -.BI "unsigned int RTA_LENGTH(unsigned int " length ); +.BI "unsigned int RTA_LENGTH(unsigned int " length ); .sp -.BI "unsigned int RTA_SPACE(unsigned int "length ); +.BI "unsigned int RTA_SPACE(unsigned int "length ); .SH DESCRIPTION -All +All .BR rtnetlink (7) -messages consist of a +messages consist of a .BR netlink (7) -message header and appended attributes. The attributes should be only +message header and appended attributes. +The attributes should be only manipulated using the macros provided here. .PP .BI RTA_OK( rta ", " attrlen ) @@ -86,25 +87,25 @@ Creating a rtnetlink message to set a MTU of a device. } req; struct rtattr *rta; - unsigned int mtu = 1000; + unsigned int mtu = 1000; - int rtnetlink_sk = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE); + int rtnetlink_sk = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE); memset(&req, 0, sizeof(req)); - req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(struct ifinfomsg)); - req.nh.nlmsg_flags = NLM_F_REQUEST; + req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(struct ifinfomsg)); + req.nh.nlmsg_flags = NLM_F_REQUEST; req.nh.nlmsg_type = RTML_NEWLINK; req.if.ifi_family = AF_UNSPEC; - req.if.ifi_index = INTERFACE_INDEX; + req.if.ifi_index = INTERFACE_INDEX; req.if.ifi_change = 0xffffffff; /* ???*/ - rta = (struct rtattr *)(((char *) &req) + + rta = (struct rtattr *)(((char *) &req) + NLMSG_ALIGN(n->nlmsg_len)); rta->rta_type = IFLA_MTU; rta->rta_len = sizeof(unsigned int); - req.n.nlmsg_len = NLMSG_ALIGN(req.n.nlmsg_len) + - RTA_LENGTH(sizeof(mtu)); + req.n.nlmsg_len = NLMSG_ALIGN(req.n.nlmsg_len) + + RTA_LENGTH(sizeof(mtu)); memcpy(RTA_DATA(rta), &mtu, sizeof(mtu)); - send(rtnetlink_sk, &req, req.n.nlmsg_len); + send(rtnetlink_sk, &req, req.n.nlmsg_len); .fi .SH BUGS This manual page is lacking and incomplete. diff --git a/man3/scalb.3 b/man3/scalb.3 index 4b9e8d4b4..b92c4331e 100644 --- a/man3/scalb.3 +++ b/man3/scalb.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -69,7 +69,7 @@ The and .BR scalbln () functions are from C99. -All three are in POSIX.1-2001. +All three are in POSIX.1-2001. The .BR scalb () function is marked obsolescent. diff --git a/man3/scandir.3 b/man3/scandir.3 index e2d106867..b458a79c4 100644 --- a/man3/scandir.3 +++ b/man3/scandir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,7 +50,8 @@ scandir, alphasort, versionsort \- scan a directory for matching entries .fi .SH DESCRIPTION The \fBscandir\fP() function scans the directory \fIdir\fP, calling -\fIfilter\fP() on each directory entry. Entries for which +\fIfilter\fP() on each directory entry. +Entries for which \fIfilter\fP() returns non-zero are stored in strings allocated via \fBmalloc\fP(), sorted using \fBqsort\fP() with the comparison function \fIcompar\fP(), and collected in array \fInamelist\fP @@ -76,18 +77,18 @@ The .BR alphasort () and .BR versionsort () -functions return an integer less than, equal to, -or greater than zero if the first argument is considered to be +functions return an integer less than, equal to, +or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. .SH ERRORS .TP .B ENOMEM Insufficient memory to complete the operation. .SH "CONFORMING TO" -None of these functions is in POSIX.1-2001, but +None of these functions is in POSIX.1-2001, but .BR alphasort () -and -.BR scandir () +and +.BR scandir () are under consideration for a future revision to POSIX.1. .LP The functions @@ -98,7 +99,7 @@ are from 4.3BSD, and have been available under Linux since libc4. Libc4 and libc5 use the more precise prototype .sp .nf - int alphasort(const struct dirent ** a, + int alphasort(const struct dirent ** a, const struct dirent **b); .fi .sp diff --git a/man3/scanf.3 b/man3/scanf.3 index 7c98c4cc8..34a0ad0bd 100644 --- a/man3/scanf.3 +++ b/man3/scanf.3 @@ -36,11 +36,11 @@ .\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 .\" .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu -.\" modified to resemble the GNU libio setup used in the Linux libc +.\" modified to resemble the GNU libio setup used in the Linux libc .\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de .\" Modified, aeb, 970121 -.\" 2005-07-14, mtk, added description of %n$ form; various text -.\" incorporated from the GNU C library documentation ((C) The +.\" 2005-07-14, mtk, added description of %n$ form; various text +.\" incorporated from the GNU C library documentation ((C) The .\" Free Software Foundation); other parts substantially rewritten. .\" .TH SCANF 3 1995-11-01 "LINUX MANPAGE" "Linux Programmer's Manual" @@ -68,16 +68,17 @@ The .BR scanf () family of functions scans input according to .I format -as described below. This format may contain +as described below. +This format may contain .IR "conversion specifications" ; the results from such conversions, if any, are stored in the locations pointed to by the -.I pointer +.I pointer arguments that follow .IR format . -Each +Each .I pointer -argument must be of a type that is appropriate for the value returned +argument must be of a type that is appropriate for the value returned by the corresponding conversion specification. If the number of conversion specifications in @@ -123,8 +124,8 @@ functions respectively. .PP The .I format -string consists of a sequence of -.IR directives +string consists of a sequence of +.IR directives which describe how to process the sequence of input characters. If processing of a directive fails, no further input is read, and .BR scanf () @@ -138,7 +139,7 @@ meaning that the input was inappropriate (see below). A directive is one of the following: .TP \(bu -A sequence of white-space characters (space, tab, newline, etc; see +A sequence of white-space characters (space, tab, newline, etc; see .BR isspace (3)). This directive matches any amount of white space, including none, in the input. @@ -149,7 +150,7 @@ This character must exactly match the next character of input. .TP \(bu A conversion specification, which commences with a '%' (percent) character. -A sequence of characters from the input is converted according to +A sequence of characters from the input is converted according to this specification, and the result is placed in the corresponding .I pointer argument. @@ -158,10 +159,10 @@ the conversion fails \(em this is a .IR "matching failure" . .PP Each -.I conversion specification +.I conversion specification in -.I format -begins with either the character '%' or the character sequence +.I format +begins with either the character '%' or the character sequence "\fB%\fP\fIn\fP\fB$\fP" (see below for the distinction) followed by: .TP @@ -178,10 +179,10 @@ included in the count of successful assignments returned by .TP \(bu An optional 'a' character. -This is used with string conversions, and relieves the caller of the +This is used with string conversions, and relieves the caller of the need to allocate a corresponding buffer to hold the input: instead, .BR scanf () -allocates a buffer of sufficient size, +allocates a buffer of sufficient size, and assigns the address of this buffer to the corresponding .I pointer argument, which should be a pointer to a @@ -197,45 +198,45 @@ it can also be used as such in the GNU implementation). \(bu An optional decimal integer which specifies the .IR "maximum field width" . -Reading of characters stops either when this maximum is reached or -when a non-matching character is found, whichever happens first. -Most conversions discard initial whitespace characters (the exceptions -are noted below), +Reading of characters stops either when this maximum is reached or +when a non-matching character is found, whichever happens first. +Most conversions discard initial whitespace characters (the exceptions +are noted below), and these discarded characters don't count towards the maximum field width. -String input conversions store a null terminator ('\\0') -to mark the end of the input; +String input conversions store a null terminator ('\\0') +to mark the end of the input; the maximum field width does not include this terminator. .TP \(bu -An optional -.IR "type modifier character" . +An optional +.IR "type modifier character" . For example, the .B l -type modifier is used with integer conversions such as -.I %d +type modifier is used with integer conversions such as +.I %d to specify that the corresponding .I pointer -argument refers to a +argument refers to a .I "long int" -rather than a pointer to an +rather than a pointer to an .IR int . .TP \(bu -A +A .I "conversion specifier" that specifies the type of input conversion to be performed. -.PP +.PP The conversion specifications in .I format -are of two forms, either beginning with '%' or beginning with +are of two forms, either beginning with '%' or beginning with "\fB%\fP\fIn\fP\fB$\fP". -The two forms should not be mixed in the same +The two forms should not be mixed in the same .I format -string, except that a string containing +string, except that a string containing "\fB%\fP\fIn\fP\fB$\fP" specifications can include .I %% -and +and .IR %* . If .I format @@ -247,7 +248,7 @@ In the "\fB%\fP\fIn\fP\fB$\fP" form (which is specified in POSIX.1-2001, but not C99), .I n -is a decimal integer that specifies that the converted input should +is a decimal integer that specifies that the converted input should be placed in the location referred to by the .IR n -th .I pointer @@ -255,7 +256,7 @@ argument following .IR format . .SH CONVERSIONS The following -.IR "type modifier characters" +.IR "type modifier characters" can appear in a conversion specification: .TP .B h @@ -304,37 +305,37 @@ and the next pointer is a pointer to .I double (rather than .IR float ). -Specifying two +Specifying two .B l characters is equivalent to .BR L . If used with -.I %c -or -.I %s -the corresponding parameter is considered -as a pointer to a wide character or wide character string respectively. +.I %c +or +.I %s +the corresponding parameter is considered +as a pointer to a wide character or wide character string respectively. .\" This use of l was introduced in Amendment 1 to ISO C90. .TP .B L Indicates that the conversion will be either .B efg and the next pointer is a pointer to -.IR "long double" -or the conversion will be +.IR "long double" +or the conversion will be .B dioux and the next pointer is a pointer to .IR "long long" . -.\" MTK, Jul 05: The following is no longer true for modern +.\" MTK, Jul 05: The following is no longer true for modern .\" ANSI C (i.e., C99): -.\" (Note that long long is not an -.\" ANSI C +.\" (Note that long long is not an +.\" ANSI C .\" type. Any program using this will not be portable to all .\" architectures). .TP .B q -equivalent to -.BR L . +equivalent to +.BR L . This specifier does not exist in ANSI C. .TP .B t @@ -351,15 +352,17 @@ but the next pointer is a pointer to a .IR size_t . This modifier was introduced in C99. .PP -The following +The following .I "conversion specifiers" are available: .TP .B % -Matches a literal '%'. That is, -.I %\&% +Matches a literal '%'. +That is, +.I %\&% in the format string matches a -single input '%' character. No conversion is done, and assignment does not +single input '%' character. +No conversion is done, and assignment does not occur. .TP .B d @@ -371,19 +374,20 @@ the next pointer must be a pointer to Equivalent to .IR ld ; this exists only for backwards compatibility. -(Note: thus only in libc4. In libc5 and glibc the -.I %D +(Note: thus only in libc4. +In libc5 and glibc the +.I %D is silently ignored, causing old programs to fail mysteriously.) .TP .B i Matches an optionally signed integer; the next pointer must be a pointer to .IR int . -The integer is read in base 16 if it begins with +The integer is read in base 16 if it begins with .I 0x -or -.IR 0X , -in base 8 if it begins with -.IR 0 , +or +.IR 0X , +in base 8 if it begins with +.IR 0 , and in base 10 otherwise. Only characters that correspond to the base are used. .TP @@ -428,8 +432,8 @@ Equivalent to .TP .B s Matches a sequence of non-white-space characters; -the next pointer must be a pointer to character array that is -long enough to hold the input sequence and the terminating null +the next pointer must be a pointer to character array that is +long enough to hold the input sequence and the terminating null character ('\\0'), which is added automatically. The input string stops at white space or at the maximum field width, whichever occurs first. @@ -441,8 +445,9 @@ Matches a sequence of characters whose length is specified by the .IR char , and there must be enough room for all the characters (no terminating null byte -is added). The usual skip of leading white space is suppressed. To skip -white space first, use an explicit space in the format. +is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. .TP .B \&[ Matches a nonempty sequence of characters from the specified set of @@ -450,13 +455,14 @@ accepted characters; the next pointer must be a pointer to .IR char , and there must be enough room for all the characters in the string, plus a terminating null byte. -The usual skip of leading white space is suppressed. The -string is to be made up of characters in (or not in) a particular set; the -set is defined by the characters between the open bracket +The usual skip of leading white space is suppressed. +The string is to be made up of characters in (or not in) a particular set; +the set is defined by the characters between the open bracket .B [ character and a close bracket .B ] -character. The set +character. +The set .I excludes those characters if the first character after the open bracket is a circumflex @@ -466,8 +472,10 @@ the open bracket or the circumflex; any other position will end the set. The hyphen character .B \- is also special; when placed between two other characters, it adds all -intervening characters to the set. To include a hyphen, make it the last -character before the final close bracket. For instance, +intervening characters to the set. +To include a hyphen, make it the last +character before the final close bracket. +For instance, .B [^]0\-9\-] means the set "everything except close bracket, zero through nine, and hyphen". @@ -475,7 +483,7 @@ The string ends with the appearance of a character not in the (or, with a circumflex, in) set or when the field width runs out. .TP .B p -Matches a pointer value (as printed by +Matches a pointer value (as printed by .I %p in .BR printf (3); @@ -492,26 +500,27 @@ This is a conversion, although it can be suppressed with the .B * assignment-suppression character. -The C standard says: "Execution of a -.I %n +The C standard says: "Execution of a +.I %n directive does not increment the assignment count returned at the completion of execution" -but the Corrigendum seems to contradict this. Probably it is wise +but the Corrigendum seems to contradict this. +Probably it is wise not to make any assumptions on the effect of -.I %n +.I %n conversions on the return value. .SH "RETURN VALUE" -These functions return the number of input items -successfully matched and assigned, -which can be fewer than provided for, +These functions return the number of input items +successfully matched and assigned, +which can be fewer than provided for, or even zero in the event of an early matching failure. The value .B EOF -is returned if the end of input is reached before either the first +is returned if the end of input is reached before either the first successful conversion or a matching failure occurs. .B EOF -is also returned if a read error occurs, +is also returned if a read error occurs, in which case the error indicator for the stream (see .BR ferror (3)) is set, and @@ -532,9 +541,9 @@ and .BR sscanf () conform to C89 and C99. .PP -The +The .B q -specifier is the 4.4BSD notation for +specifier is the 4.4BSD notation for .IR "long long" , while .B ll @@ -542,45 +551,48 @@ or the usage of .B L in integer conversions is the GNU notation. .PP -The Linux version of these functions is based on the -.I GNU +The Linux version of these functions is based on the +.I GNU .I libio -library. Take a look at the +library. +Take a look at the .I info -documentation of +documentation of .I GNU .I libc (glibc-1.08) -for a more concise description. +for a more concise description. .SH BUGS -All functions are fully C89 conformant, but provide the -additional specifiers +All functions are fully C89 conformant, but provide the +additional specifiers .B q and .B a as well as an additional behaviour of the .B L -and -.B l -specifiers. The latter may be considered to be a bug, as it changes the +and +.B l +specifiers. +The latter may be considered to be a bug, as it changes the behaviour of specifiers defined in C89. .PP -Some combinations of the type modifiers and conversion -specifiers defined by ANSI C do not make sense -(e.g. +Some combinations of the type modifiers and conversion +specifiers defined by ANSI C do not make sense +(e.g. .BR "%Ld" ). While they may have a well-defined behaviour on Linux, this need not -to be so on other architectures. Therefore it usually is better to use -modifiers that are not defined by ANSI C at all, i.e. use +to be so on other architectures. +Therefore it usually is better to use +modifiers that are not defined by ANSI C at all, i.e. use .B q -instead of +instead of .B L -in combination with +in combination with .B diouxX -conversions or +conversions or .BR ll . .PP The usage of .B q is not the same as on 4.4BSD, -as it may be used in float conversions equivalently to +as it may be used in float conversions equivalently to .BR L . diff --git a/man3/seekdir.3 b/man3/seekdir.3 index 33d1997ea..9beaf61be 100644 --- a/man3/seekdir.3 +++ b/man3/seekdir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/sem_close.3 b/man3/sem_close.3 index e411c95c4..ee8301a01 100644 --- a/man3/sem_close.3 +++ b/man3/sem_close.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,17 +33,17 @@ sem_close \- close a named semaphore .BR sem_close () closes the named semaphore referred to by .IR sem , -allowing any resources that the system has allocated to +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 +All open named semaphores are automatically closed on process termination, or upon .BR execve (2). .SH RETURN VALUE On success .BR sem_close () returns 0; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP diff --git a/man3/sem_destroy.3 b/man3/sem_destroy.3 index d5837a2aa..73e540096 100644 --- a/man3/sem_destroy.3 +++ b/man3/sem_destroy.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,7 +39,7 @@ Only a semaphore that has been initialised by should be destroyed using .BR sem_destroy (). -Destroying a semaphore that other processes or threads are +Destroying a semaphore that other processes or threads are currently blocked on (in .BR sem_wait (3)) produces undefined behaviour. @@ -49,9 +49,9 @@ until the semaphore has been reinitialised using .BR sem_init (3). .SH RETURN VALUE .BR sem_destroy () -returns 0 on success; +returns 0 on success; on error, \-1 is returned, and -.I errno +.I errno is set to indicate the error. .SH ERRORS .TP diff --git a/man3/sem_getvalue.3 b/man3/sem_getvalue.3 index 65800fc92..6e32b35b3 100644 --- a/man3/sem_getvalue.3 +++ b/man3/sem_getvalue.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,21 +36,21 @@ places the current value of the semaphore pointed to into the integer pointed to by .IR sval . -If one or more processes or threads are blocked +If one or more processes or threads are blocked waiting to lock the semaphore with .BR sem_wait (3), -POSIX.1-2001 permits two possibilities for the value returned in +POSIX.1-2001 permits two possibilities for the value returned in .IR sval : -either 0 is returned; -or a negative number whose absolute value is the count +either 0 is returned; +or a negative number whose absolute value is the count of the number of processes and threads currently blocked in .BR sem_wait (3). Linux adopts the former behaviour. .SH RETURN VALUE .BR sem_getvalue () -returns 0 on success; +returns 0 on success; on error, \-1 is returned and -.I errno +.I errno is set to indicate the error. .SH ERRORS .TP diff --git a/man3/sem_init.3 b/man3/sem_init.3 index d124545c7..1a88138e3 100644 --- a/man3/sem_init.3 +++ b/man3/sem_init.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,17 +37,17 @@ The .I value argument specifies the initial value for the semaphore. -The +The .I pshared argument indicates whether this semaphore is to be shared between the threads of a process, or between processes. If .I pshared -has the value 0, -then the semaphore is shared between the threads of a process, -and should be located at some address that is visible to all threads -(e.g., a global variable, or a variable allocated dynamically on +has the value 0, +then the semaphore is shared between the threads of a process, +and should be located at some address that is visible to all threads +(e.g., a global variable, or a variable allocated dynamically on the heap). If @@ -61,19 +61,19 @@ and (Since a child created by .BR fork (2) inherits its parent's memory mappings, it can also access the semaphore.) -Any process that can access the shared memory region +Any process that can access the shared memory region can operate on the semaphore using .BR sem_post (3), .BR sem_wait (3), etc. -Initialising a semaphore that has already been initialised +Initialising a semaphore that has already been initialised results in undefined behaviour. .SH RETURN VALUE .BR sem_init () -returns 0 on success; +returns 0 on success; on error, \-1 is returned, and -.I errno +.I errno is set to indicate the error. .SH ERRORS .TP @@ -84,7 +84,7 @@ exceeds .TP .B ENOSYS .I pshared -is non-zero, +is non-zero, but the system does not support process-shared semaphores (see .BR sem_overview (7)). .SH CONFORMING TO diff --git a/man3/sem_open.3 b/man3/sem_open.3 index 010eb3046..e73912e6f 100644 --- a/man3/sem_open.3 +++ b/man3/sem_open.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,8 +36,8 @@ sem_open \- initialise and open a named semaphore creates a new POSIX semaphore or opens an existing semaphore. The semaphore is identified by .IR name . -For details of the construction of -.IR name , +For details of the construction of +.IR name , see .BR sem_overview (7). @@ -46,13 +46,13 @@ The argument specifies flags that control the operation of the call. If .B O_CREAT -is specified in -.IR oflag , -then the semaphore is created if +is specified in +.IR oflag , +then the semaphore is created if it does not already exist. -The owner (user ID) of the semaphore is set to the effective -user ID of the calling process. -The group ownership (group ID) is set to the effective group ID +The owner (user ID) of the semaphore is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID of the calling process. .\" In reality the file system IDs are used on Linux. If both @@ -65,9 +65,9 @@ then an error is returned if a semaphore with the given .I name already exists. .PP -If +If .B O_CREAT -is specified in +is specified in .IR oflag , then two additional arguments must be supplied. The @@ -76,12 +76,12 @@ argument specifies the permissions to be placed on the new semaphore, as for .BR open (2). The permissions settings are masked against the process umask. -Both read and write permission should be granted to each class of +Both read and write permission should be granted to each class of user that will access the semaphore. -The +The .I value argument specifies the initial value for the new semaphore. -If +If .B O_CREAT is specified, and a semaphore with the given .I name @@ -93,11 +93,11 @@ are ignored. .SH RETURN VALUE On success, .BR sem_open () -returns the address of the new semaphore; +returns the address of the new semaphore; this address is used when calling other semaphore-related functions. -On error, +On error, .BR sem_open () -returns +returns .BR SEM_FAILED , with .I errno @@ -105,7 +105,7 @@ set to indicate the error. .SH ERRORS .TP .B EACCES -The semaphore exists, but the caller does not have permission to +The semaphore exists, but the caller does not have permission to open it. .TP .B EEXIST @@ -113,14 +113,14 @@ Both .B O_CREAT and .B O_EXCL -were specified in +were specified in .IR oflag , -but a semaphore with this +but a semaphore with this .I name already exists. .TP .B EINVAL -.I value +.I value was greater than .BR SEM_VALUE_MAX . .TP @@ -137,9 +137,9 @@ The system limit on the total number of open files has been reached. .B ENOENT The .B O_CREAT -flag was not specified in +flag was not specified in .IR oflag , -and no semaphore with this +and no semaphore with this .I name exists. .TP diff --git a/man3/sem_post.3 b/man3/sem_post.3 index 796ac9964..a8a280e55 100644 --- a/man3/sem_post.3 +++ b/man3/sem_post.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,15 +34,15 @@ sem_post \- unlock a semaphore increments (unlocks) the semaphore pointed to by .IR sem . If the semaphore's value consequently becomes greater than zero, -then another process or thread blocked in a +then another process or thread blocked in a .BR sem_wait (3) call will be woken up and proceed to lock the semaphore. .SH RETURN VALUE .BR sem_post () -returns 0 on success; +returns 0 on success; on error, the value of the semaphore is left unchanged, \-1 is returned, and -.I errno +.I errno is set to indicate the error. .SH ERRORS .TP diff --git a/man3/sem_unlink.3 b/man3/sem_unlink.3 index 92dd195c6..3c8b07dfa 100644 --- a/man3/sem_unlink.3 +++ b/man3/sem_unlink.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -34,13 +34,13 @@ sem_unlink \- remove a named semaphore removes the named semaphore referred to by .IR sem . The semaphore name is removed immediately. -The semaphore is destroyed once all other processes that have +The semaphore is destroyed once all other processes that have the semaphore open close it. .SH RETURN VALUE On success .BR sem_unlink () returns 0; on error, \-1 is returned, with -.I errno +.I errno set to indicate the error. .SH ERRORS .TP diff --git a/man3/sem_wait.3 b/man3/sem_wait.3 index 4b27d34aa..7a54d963d 100644 --- a/man3/sem_wait.3 +++ b/man3/sem_wait.3 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,7 +42,7 @@ decrements (locks) the semaphore pointed to by If the semaphore's value is greater than zero, then the decrement proceeds, and the function returns, immediately. If the semaphore currently has the value zero, -then the call blocks until either it becomes possible to perform +then the call blocks until either it becomes possible to perform the decrement (i.e., the semaphore value rises above zero), or a signal handler interrupts the call. @@ -50,22 +50,22 @@ or a signal handler interrupts the call. is the same as .BR sem_wait (), except that if the decrement cannot be immediately performed, -then call returns an error -.RI ( errno +then call returns an error +.RI ( errno set to .BR EAGAIN ) instead of blocking. .BR sem_timedwait () -is the same as +is the same as .BR sem_wait (), except that .I abs_timeout -specifies a limit on the amount of time that the call +specifies a limit on the amount of time that the call should block if the decrement cannot be immediately performed. -The +The .I abs_timeout -argument points to a structure that specifies an absolute timeout +argument points to a structure that specifies an absolute timeout in seconds and nanoseconds since the Epoch (00:00:00, 1 January 1970). This structure is defined as follows: @@ -80,7 +80,7 @@ struct timespec { .PP If the timeout has already expired by the time of the call, and the semaphore could not be locked immediately, -then +then .BR sem_timedwait () fails with a timeout error .RI ( errno @@ -91,14 +91,14 @@ If the operation can be performed immediately, then .BR sem_timedwait () never fails with a timeout error, regardless of the value of .IR abs_timeout . -Furthermore, the validity of +Furthermore, the validity of .I abs_timeout is not checked in this case. .SH RETURN VALUE -All of these functions return 0 on success; +All of these functions return 0 on success; on error, the value of the semaphore is left unchanged, \-1 is returned, and -.I errno +.I errno is set to indicate the error. .SH ERRORS .TP @@ -126,7 +126,7 @@ is less than 0, or greater than or equal to 1000 million. .TP .B ETIMEDOUT The call timed out before the semaphore could be locked. -.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition +.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition .\" was detected", but this does not occur on Linux(?). .SH NOTES A signal handler always interrupts a blocked call to @@ -140,7 +140,7 @@ flag. POSIX.1-2001. .SH EXAMPLE .PP -The (somewhat trivial) program shown below operates on an +The (somewhat trivial) program shown below operates on an unnamed semaphore. The program expects two command-line arguments. The first argument specifies a seconds value that is used to @@ -151,10 +151,10 @@ This handler performs a .BR sem_post () to increment the semaphore that is being waited on in .I main() -using +using .BR sem_timedwait (). The second command-line argument specifies the length -of the timeout, in seconds, for +of the timeout, in seconds, for .BR sem_timedwait (). The following shows what happens on two different runs of the program: @@ -193,10 +193,10 @@ handler(int sig) int sval; printf("sem_post() from handler\\n"); - if (sem_post(&sem) == -1) + if (sem_post(&sem) == -1) die("sem_post"); - if (sem_getvalue(&sem, &sval) == -1) + if (sem_getvalue(&sem, &sval) == -1) die("sem_getvalue"); printf("sem_getvalue() from handler; value = %d\\n", sval); } /* handler */ @@ -210,7 +210,7 @@ main(int argc, char *argv[]) assert(argc == 3); /* Usage: ./a.out alarm-secs wait-secs */ - if (sem_init(&sem, 0, 0) == -1) + if (sem_init(&sem, 0, 0) == -1) die("sem_init"); /* Establish SIGALRM handler; set alarm timer using argv[1] */ @@ -218,7 +218,7 @@ main(int argc, char *argv[]) sa.sa_handler = handler; sigemptyset(&sa.sa_mask); sa.sa_flags = 0; - if (sigaction(SIGALRM, &sa, NULL) == -1) + if (sigaction(SIGALRM, &sa, NULL) == -1) die("sigaction"); alarm(atoi(argv[1])); @@ -226,7 +226,7 @@ main(int argc, char *argv[]) /* Calculate relative interval as current time plus number of seconds given argv[2] */ - if (clock_gettime(CLOCK_REALTIME, &ts) == -1) + if (clock_gettime(CLOCK_REALTIME, &ts) == -1) die("clock_gettime"); ts.tv_sec += atoi(argv[2]); diff --git a/man3/setaliasent.3 b/man3/setaliasent.3 index 196d87a26..3c31d21c4 100644 --- a/man3/setaliasent.3 +++ b/man3/setaliasent.3 @@ -11,7 +11,7 @@ getaliasbyname, getaliasbyname_r \- read an alias entry .B #include .sp .BI "void setaliasent(void);" -.sp +.sp .BI "void endaliasent(void);" .sp .BI "struct aliasent *getaliasent(void);" @@ -27,28 +27,28 @@ getaliasbyname, getaliasbyname_r \- read an alias entry .BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); .SH DESCRIPTION One of the databases available with the Name Service Switch (NSS) -is the aliases database, that contains mail aliases. (To find out -which databases are supported, try getent \-\-help .) +is the aliases database, that contains mail aliases. +(To find out which databases are supported, try \fIgetent \-\-help\fP.) Six functions are provided to access the aliases database. .PP -The +The .BR getaliasent () function returns a pointer to a structure containing the group information from the aliases database. -The first time it is called it returns the first entry; +The first time it is called it returns the first entry; thereafter, it returns successive entries. .PP -The +The .BR setaliasent () function rewinds the file pointer to the beginning of the aliases database. .PP -The +The .BR endaliasent () function closes the aliases database. .PP .BR getaliasent_r () -is the reentrant version of the previous function. +is the reentrant version of the previous function. The requested structure is stored via the first argument but the programmer needs to fill the other arguments also. @@ -56,26 +56,26 @@ Not providing enough space causes the function to fail. .PP The function .BR getaliasbyname () -takes the name argument and searches the aliases database. -The entry is returned as a pointer to a -.IR "struct aliasent" . +takes the name argument and searches the aliases database. +The entry is returned as a pointer to a +.IR "struct aliasent" . .PP .BR getaliasbyname_r () -is the reentrant version of the previous function. +is the reentrant version of the previous function. The requested structure is stored via the second argument but the programmer needs to fill the other -arguments also. +arguments also. Not providing enough space causes the function to fail. .PP -The +The .I "struct aliasent" -is defined in +is defined in .IR : .nf struct aliasent { char *alias_name; /* alias name */ - size_t alias_members_len; + size_t alias_members_len; char **alias_members; /* alias name list */ int alias_local; }; @@ -93,7 +93,7 @@ and .BR getaliasbyname_r () return a non-zero value on error. .SH EXAMPLE -The following example compiles with +The following example compiles with .IR "gcc example.c \-o example" . It will dump all names in the alias database. .sp @@ -103,14 +103,14 @@ It will dump all names in the alias database. #include #include -int -main(void) +int +main(void) { struct aliasent *al; setaliasent(); for (;;) { al = getaliasent(); - if (al == NULL) + if (al == NULL) break; printf("Name: %s\\n", al->alias_name); } diff --git a/man3/setbuf.3 b/man3/setbuf.3 index 6f01b5b9b..a184b8624 100644 --- a/man3/setbuf.3 +++ b/man3/setbuf.3 @@ -41,7 +41,7 @@ .\" Correction, Sun, 11 Apr 1999 15:55:18, .\" Martin Vicente .\" Correction, 2000-03-03, Andreas Jaeger -.\" Added return value for setvbuf, aeb, +.\" Added return value for setvbuf, aeb, .\" .TH SETBUF 3 2001-06-09 "Linux" "Linux Programmer's Manual" .SH NAME @@ -61,22 +61,25 @@ setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations .ad .SH DESCRIPTION The three types of buffering available are unbuffered, block buffered, and -line buffered. When an output stream is unbuffered, information appears on +line buffered. +When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is -read from any stream attached to a terminal device (typically stdin). The -function +read from any stream attached to a terminal device (typically stdin). +The function .BR fflush (3) may be used to force the block out early. -(See +(See .BR fclose (3).) -Normally all files are block buffered. When the first I/O operation occurs -on a file, +Normally all files are block buffered. +When the first I/O operation occurs on a file, .BR malloc (3) -is called, and a buffer is obtained. If a stream refers to a terminal (as +is called, and a buffer is obtained. +If a stream refers to a terminal (as .I stdout -normally does) it is line buffered. The standard error stream +normally does) it is line buffered. +The standard error stream .I stderr is always unbuffered by default. .PP @@ -102,12 +105,13 @@ Except for unbuffered files, the .I buf argument should point to a buffer at least .I size -bytes long; this buffer will be used instead of the current buffer. If the -argument +bytes long; this buffer will be used instead of the current buffer. +If the argument .I buf is NULL, only the mode is affected; a new buffer will be allocated on the next read -or write operation. The +or write operation. +The .BR setvbuf () function may only be used after opening a stream and before any other operations have been performed on it. @@ -140,7 +144,8 @@ The function returns 0 on success. It can return any value on failure, but returns non-zero when .I mode -is invalid or the request cannot be honoured. It may set +is invalid or the request cannot be honoured. +It may set .I errno on failure. The other functions are void. @@ -156,13 +161,14 @@ The and .BR setlinebuf () functions are not portable to versions of BSD before 4.2BSD, and -are available under Linux since libc 4.5.21. On 4.2BSD and 4.3BSD systems, +are available under Linux since libc 4.5.21. +On 4.2BSD and 4.3BSD systems, .BR setbuf () always uses a suboptimal buffer size and should be avoided. .P You must make sure that both .I buf -and the space it points to still exist by the time +and the space it points to still exist by the time .I stream is closed, which also happens at program termination. .P @@ -171,7 +177,7 @@ For example, the following is illegal: .sp #include -int +int main(void) { char buf[BUFSIZ]; diff --git a/man3/setenv.3 b/man3/setenv.3 index 79dc85541..46cac244e 100644 --- a/man3/setenv.3 +++ b/man3/setenv.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,7 +45,8 @@ setenv \- change or add an environment variable .SH DESCRIPTION The \fBsetenv\fP() function adds the variable \fIname\fP to the environment with the value \fIvalue\fP, if \fIname\fP does not -already exist. If \fIname\fP does exist in the environment, then +already exist. +If \fIname\fP does exist in the environment, then its value is changed to \fIvalue\fP if \fIoverwrite\fP is non-zero; if \fIoverwrite\fP is zero, then the value of \fIname\fP is not changed. diff --git a/man3/setjmp.3 b/man3/setjmp.3 index c9a444a33..23a9f00db 100644 --- a/man3/setjmp.3 +++ b/man3/setjmp.3 @@ -39,10 +39,12 @@ setjmp, sigsetjmp \- save stack context for non-local goto \fBsetjmp\fP() and \fBlongjmp\fP() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. \fBsetjmp\fP() saves the stack context/environment in \fIenv\fP for -later use by \fBlongjmp\fP(). The stack context will be invalidated +later use by \fBlongjmp\fP(). +The stack context will be invalidated if the function which called \fBsetjmp\fP() returns. .P -\fBsigsetjmp\fP() is similar to \fBsetjmp\fP(). If \fIsavesigs\fP is non-zero, +\fBsigsetjmp\fP() is similar to \fBsetjmp\fP(). +If \fIsavesigs\fP is non-zero, the set of blocked signals is saved in \fIenv\fP and will be restored if a \fBsiglongjmp\fP() is later performed with this \fIenv\fP. .SH "RETURN VALUE" @@ -53,12 +55,15 @@ C89, C99, and POSIX.1-2001 specify \fBsetjmp\fP(). POSIX.1-2001 specifies \fBsigsetjmp\fP(). .SH NOTES POSIX does not specify whether \fBsetjmp\fP() will save the -signal context. (In System V it will not. In 4.3BSD it will, and there +signal context. +(In System V it will not. +In 4.3BSD it will, and there is a function \fB_setjmp\fP that will not.) If you want to save signal masks, use \fBsigsetjmp\fP(). .P \fBsetjmp\fP() and \fBsigsetjmp\fP() make programs hard to understand -and maintain. If possible an alternative should be used. +and maintain. +If possible an alternative should be used. .SH "SEE ALSO" .BR longjmp (3), .BR siglongjmp (3) diff --git a/man3/setlocale.3 b/man3/setlocale.3 index 35c2d0862..986f967f2 100644 --- a/man3/setlocale.3 +++ b/man3/setlocale.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -37,7 +37,7 @@ setlocale \- set the current locale .BI "char *setlocale(int " category ", const char *" locale ); .fi .SH DESCRIPTION -The +The .BR setlocale () function is used to set or query the program's current locale. .PP @@ -86,7 +86,8 @@ If is .BR """""" , each part of the locale that should be modified is set according to the -environment variables. The details are implementation dependent. +environment variables. +The details are implementation dependent. For glibc, first .\" [This is false on my system - must check which library versions do this] .\" if @@ -148,8 +149,8 @@ character functions for text processing if and by using .BR strcoll () , .BR wcscoll () -or -.BR strxfrm (), +or +.BR strxfrm (), .BR wcsxfrm () to compare strings. .SH "RETURN VALUE" @@ -159,7 +160,7 @@ returns an opaque string that corresponds to the locale set. This string may be allocated in static storage. The string returned is such that a subsequent call with that string and its associated category will restore that part of the process's -locale. +locale. The return value is NULL if the request cannot be honored. .SH "CONFORMING TO" C89, C99, POSIX.1-2001. @@ -167,14 +168,14 @@ C89, C99, POSIX.1-2001. Linux (that is, GNU libc) supports the portable locales .BR """C""" " and " """POSIX""" . In the good old days there used to be support for -the European Latin-1 +the European Latin-1 .B """ISO-8859-1""" locale (e.g. in libc-4.5.21 and libc-4.6.27), and the Russian .B """KOI-8""" (more precisely, "koi-8r") locale (e.g. in libc-4.6.27), so that having an environment variable LC_CTYPE=ISO-8859-1 -sufficed to make -.BR isprint () +sufficed to make +.BR isprint () return the right answer. These days non-English speaking Europeans have to work a bit harder, and must install actual locale files. diff --git a/man3/setlogmask.3 b/man3/setlogmask.3 index 53bfe0816..566bc96c9 100644 --- a/man3/setlogmask.3 +++ b/man3/setlogmask.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,7 +32,8 @@ setlogmask \- set log priority mask .SH DESCRIPTION A process has a log priority mask that determines which calls to .BR syslog (3) -may be logged. All other calls will be ignored. +may be logged. +All other calls will be ignored. Logging is enabled for the priorities that have the corresponding bit set in .IR mask . @@ -50,7 +51,7 @@ The bit corresponding to a priority \fIp\fP is LOG_MASK(\fIp\fP). Some systems also provide a macro LOG_UPTO(\fIp\fP) for the mask of all priorities in the above list up to and including \fIp\fP. .SH "RETURN VALUE" -This function returns the previous log priority mask. +This function returns the previous log priority mask. .SH ERRORS None. .\" .SH NOTES diff --git a/man3/setnetgrent.3 b/man3/setnetgrent.3 index 43da35618..4110a2e43 100644 --- a/man3/setnetgrent.3 +++ b/man3/setnetgrent.3 @@ -3,7 +3,7 @@ .\" based on glibc infopages .\" polished - aeb .TH SETNETGRENT 3 2002-08-20 "GNU" "Linux Programmer's Manual" -.SH NAME +.SH NAME setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \- handle network group entries .SH SYNOPSIS @@ -11,7 +11,7 @@ handle network group entries .sp .BI "int setnetgrent(const char *" netgroup ); .br -.BI "void endnetgrent(void);" +.BI "void endnetgrent(void);" .br .BI "int getnetgrent(char **" host ", char **" user ", char **" domain ); .sp @@ -24,12 +24,14 @@ handle network group entries .in +12 .BI "const char *" user ", const char *" domain ); .in -12 -.SH DESCRIPTION -The +.SH DESCRIPTION +The .B netgroup -is a SunOS invention. A netgroup database is a list of string triples +is a SunOS invention. +A netgroup database is a list of string triples .BR (hostname "," username "," domainname) -or other netgroup names. Any of the elements in a triple can be empty, +or other netgroup names. +Any of the elements in a triple can be empty, which means that anything matches. The functions described here allow access to the netgroup databases. The file @@ -40,7 +42,8 @@ The .BR setnetgrent () call defines the netgroup that will be searched by subsequent .BR getnetgrent () -calls. The +calls. +The .BR getnetgrent () function retrieves the next netgroup entry, and returns pointers in .IR host , @@ -57,7 +60,8 @@ To free all allocated buffers use .PP In most cases you only want to check if the triplet .BR (hostname "," username "," domainname) -is a member of a netgroup. The function +is a member of a netgroup. +The function .BR innetgr () can be used for this without calling the above three functions. Again, a NULL pointer is a wildcard and matches any string. diff --git a/man3/shm_open.3 b/man3/shm_open.3 index 8c15eab0f..3580124a1 100644 --- a/man3/shm_open.3 +++ b/man3/shm_open.3 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,12 +36,12 @@ shm_open, shm_unlink \- Create/open or unlink POSIX shared memory objects .BR shm_open () creates and opens a new, or opens an existing, POSIX shared memory object. A POSIX shared memory object is in effect a handle which can -be used by unrelated processes to +be used by unrelated processes to .BR mmap (2) -the same region of shared memory. -The +the same region of shared memory. +The .BR shm_unlink () -function performs the converse operation, +function performs the converse operation, removing an object previously created by .BR shm_open (). .LP @@ -50,8 +50,8 @@ The operation of is analogous to that of .BR open (2). .I name -specifies the shared memory object to be created or opened. -For portable use, +specifies the shared memory object to be created or opened. +For portable use, .I name should have an initial slash (/) and contain no embedded slashes. .\" The names used may or may not live in a file system, and may or may not @@ -60,28 +60,28 @@ should have an initial slash (/) and contain no embedded slashes. .LP .I oflag is a bit mask created by ORing together exactly one of -.B O_RDONLY +.B O_RDONLY or .B O_RDWR and any of the other flags listed here: .TP 1.1i .B O_RDONLY Open the object for read access. -A shared memory object opened in this way can only be -.BR mmap (2)ed +A shared memory object opened in this way can only be +.BR mmap (2)ed for read (\fBPROT_READ\fP) access. .TP .B O_RDWR Open the object for read-write access. .TP .B O_CREAT -Create the shared memory object if it does not exist. +Create the shared memory object if it does not exist. The user and group ownership of the object are taken from the corresponding effective IDs of the calling process, .\" In truth it is actually the file system IDs on Linux, but these .\" are nearly always the same as the effective IDs. (MTK, Jul 05) and the object's -permission bits are set according to the low-order 9 bits of +permission bits are set according to the low-order 9 bits of .IR mode , except that those bits set in the process file mode creation mask (see @@ -89,7 +89,7 @@ creation mask (see are cleared for the new object. A set of macro constants which can be used to define .I mode -is listed in +is listed in .BR open (2). .sp A new shared memory object initially has zero length \(em the size of the @@ -97,14 +97,14 @@ object can be set using .BR ftruncate (2). The newly allocated bytes of a shared memory object are automatically initialised to 0. -.TP +.TP .B O_EXCL -If +If .B O_CREAT was also specified, and a shared memory object with the given -.I name +.I name already exists, return an error. -The check for the existence of the object, and its creation if it +The check for the existence of the object, and its creation if it does not exist, are performed atomically. .TP .B O_TRUNC @@ -114,15 +114,15 @@ On successful completion .BR shm_open () returns a new file descriptor referring to the shared memory object. This file descriptor is guaranteed to be the lowest-numbered file descriptor -not previously opened within the process. +not previously opened within the process. The .B FD_CLOEXEC -flag (see +flag (see .BR fcntl (2)) is set for the file descriptor. -The file descriptor is normally used in subsequent calls -to +The file descriptor is normally used in subsequent calls +to .BR ftruncate (2) (for a newly created object) and .BR mmap (2). @@ -131,18 +131,18 @@ After a call to the file descriptor may be closed without affecting the memory mapping. The operation -of +of .BR shm_unlink () is analogous to .BR unlink (2): it removes a shared memory object name, and, once all processes -have unmapped the object, de-allocates and +have unmapped the object, de-allocates and destroys the contents of the associated memory region. -After a successful +After a successful .BR shm_unlink (), -attempts to +attempts to .BR shm_open () -an object with the same +an object with the same .I name will fail (unless .B O_CREAT @@ -150,7 +150,8 @@ was specified, in which case a new, distinct object is created). .SH "RETURN VALUE" On success, .BR shm_open () -returns a non-negative file descriptor. On failure, +returns a non-negative file descriptor. +On failure, .BR shm_open () returns \-1. .BR shm_unlink () @@ -158,30 +159,31 @@ returns 0 on success, or \-1 on error. .SH ERRORS On failure, .I errno -is set to indicate the cause of the error. Values which may appear in +is set to indicate the cause of the error. +Values which may appear in .I errno include the following: -.TP +.TP .B EACCES Permission to .BR shm_unlink () the shared memory object was denied. .TP .B EACCES -Permission was denied to +Permission was denied to .BR shm_open () .I name in the specified .IR mode , -or +or .B O_TRUNC was specified and the caller does not have write permission on the object. -.TP +.TP .B EEXIST Both .B O_CREAT and -.B O_EXCL +.B O_EXCL were specified to .BR shm_open () and the shared memory object specified by @@ -191,7 +193,7 @@ already exists. .B EINVAL The .I name -argument to +argument to .BR shm_open () was invalid. .TP @@ -199,9 +201,9 @@ was invalid. The process already has the maximum number of files open. .TP .B ENAMETOOLONG -The length of +The length of .I name -exceeds +exceeds .BR PATH_MAX . .TP .B ENFILE @@ -211,8 +213,8 @@ reached. .B ENOENT An attempt was made to .BR shm_open () -a -.I name +a +.I name that did not exist, and .B O_CREAT was not specified. @@ -220,33 +222,35 @@ was not specified. .B ENOENT An attempt was to made to .BR shm_unlink () -a -.I name +a +.I name that does not exist. .SH "NOTES" -These functions are provided in glibc 2.2 and later. Programs using these -functions must specify the +These functions are provided in glibc 2.2 and later. +Programs using these +functions must specify the .B \-lrt flag to .B cc in order to link against the required ("realtime") library. .LP -POSIX leaves the behavior of the combination of +POSIX leaves the behavior of the combination of .B O_RDONLY and .B O_TRUNC -unspecified. On Linux, this will successfully truncate an existing +unspecified. +On Linux, this will successfully truncate an existing shared memory object \(em this may not be so on other Unix systems. .LP The POSIX shared memory object implementation on Linux 2.4 makes use of a dedicated file system, which is normally -mounted under +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 +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), diff --git a/man3/siginterrupt.3 b/man3/siginterrupt.3 index 2c82eadf2..322704b46 100644 --- a/man3/siginterrupt.3 +++ b/man3/siginterrupt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,10 +37,12 @@ siginterrupt \- allow signals to interrupt system calls .fi .SH DESCRIPTION The \fBsiginterrupt\fP() function changes the restart behaviour when -a system call is interrupted by the signal \fIsig\fP. If the \fIflag\fP -argument is false (0), then system calls will be restarted if interrupted -by the specified signal \fIsig\fP. This is the default behaviour in -Linux. However, when a new signal handler is specified with the +a system call is interrupted by the signal \fIsig\fP. +If the \fIflag\fP +argument is false (0), then system calls will be restarted if interrupted +by the specified signal \fIsig\fP. +This is the default behaviour in Linux. +However, when a new signal handler is specified with the \fBsignal\fP(2) function, the system call is interrupted by default. .PP If the \fIflags\fP argument is true (1) and no data has been transferred, diff --git a/man3/signbit.3 b/man3/signbit.3 index 70ff57b6a..6c8dcfd3f 100644 --- a/man3/signbit.3 +++ b/man3/signbit.3 @@ -12,14 +12,16 @@ signbit \- test sign of a real floating point number Compile with \-std=c99; link with \-lm. .SH DESCRIPTION `signbit' is a generic macro which can work on all real floating-point -types. It returns a non-zero value if the value of X has its sign -bit set. +types. +It returns a non-zero value if the value of X has its sign bit set. .PP This is not the same as `x < 0.0', because IEEE 754 floating point -allows zero to be signed. The comparison `\-0.0 < 0.0' is false, +allows zero to be signed. +The comparison `\-0.0 < 0.0' is false, but `signbit (\-0.0)' will return a non-zero value. .SH "CONFORMING TO" -C99. This function is defined in IEC 559 (and the appendix with +C99. +This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854). .SH "SEE ALSO" .BR copysign (3) diff --git a/man3/significand.3 b/man3/significand.3 index 20174d741..27be2d43b 100644 --- a/man3/significand.3 +++ b/man3/significand.3 @@ -7,7 +7,7 @@ significand, significandf, significandl \- get mantissa of floating point number .SH SYNOPSIS .B #include -.sp +.sp .BI "double significand(double " x ); .br .BI "float significandf(float " x ); diff --git a/man3/sigpause.3 b/man3/sigpause.3 index fa6be38f5..f35cbf4ac 100644 --- a/man3/sigpause.3 +++ b/man3/sigpause.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,7 +32,8 @@ sigpause \- atomically release blocked signals and wait for interrupt .BI "int sigpause(int " sig "); /* System V / Unix95 */" .fi .SH DESCRIPTION -Don't use this function. Use +Don't use this function. +Use .BR sigsuspend (2) instead. .LP @@ -64,11 +65,12 @@ same name was solved by the .BR \%sigsuspend (2) function, that takes a .I "sigset_t *" -parameter (instead of an +parameter (instead of an .IR int ). .LP On Linux, this routine is a system call only on the Sparc (sparc64) -architecture. Libc4 and libc5 only know about the BSD version. +architecture. +Libc4 and libc5 only know about the BSD version. Glibc uses the BSD version unless _XOPEN_SOURCE is defined. .\" .SH NOTE .\" For the BSD version, one usually uses a zero diff --git a/man3/sigset.3 b/man3/sigset.3 index 6d507e01f..2112b7c18 100644 --- a/man3/sigset.3 +++ b/man3/sigset.3 @@ -38,8 +38,8 @@ sigset, sighold, sigrelse, sigignore \- System V signal API .SH DESCRIPTION These functions are provided in glibc as a compatibility interface for programs that make use of the historical System V signal API. -This API is obsolete: new applications should use the POSIX signal API -.RB ( sigaction (2), +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), .BR sigprocmask (2), etc.) @@ -47,7 +47,7 @@ The .BR sigset () function modifies the disposition of the signal .IR sig . -The +The .I disp argument can be the address of a signal handler function, or one of the following constants: @@ -61,14 +61,14 @@ to the default. Ignore .IR sig . .TP -.BR SIG_HOLD -Add +.BR SIG_HOLD +Add .I sig to the process's signal mask, but leave the disposition of .I sig unchanged. .PP -If +If .I disp specifies the address of a signal handler, then .I sig @@ -84,13 +84,13 @@ is removed from the process's signal mask. .PP The dispositions for .B SIGKILL -and +and .B SIGSTOP cannot be changed. .PP -The +The .BR sighold () -function adds +function adds .I sig to the calling process's signal mask. @@ -111,20 +111,20 @@ On success, .BR sigset () returns .B SIG_HOLD -if -.I sig +if +.I sig was blocked before the call, or the signal's previous disposition if it was not blocked before the call. On error, .BR sigset () -returns \-1, with +returns \-1, with .I errno set to indicate the error. -.\" FIXME But as at 2.3.5, glibc's sigset() is broken for the -.\" SIG_HOLD case: it will only return SIG_HOLD if 'disp' is -.\" SIG_HOLD; if the signal is blocked, then sigset() should return -.\" SIG_HOLD even if 'disp' is specified as something other than +.\" FIXME But as at 2.3.5, glibc's sigset() is broken for the +.\" SIG_HOLD case: it will only return SIG_HOLD if 'disp' is +.\" SIG_HOLD; if the signal is blocked, then sigset() should return +.\" SIG_HOLD even if 'disp' is specified as something other than .\" SIG_HOLD (I have tested this on Solaris 8 and HP-UX 11). .\" -- mtk, 29 Nov 05 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951 @@ -138,7 +138,7 @@ The and .BR sigignore () functions return 0 on success; on error, these functions return \-1 and set -.I errno +.I errno to indicate the error. .SH ERRORS For @@ -155,7 +155,7 @@ and see the ERRORS under .BR sigprocmask (2). -For +For .BR sigignore (), see the errors under .BR sigaction (2). @@ -170,7 +170,7 @@ prototype more easily readable. The .BR sigset () -function provides reliable signal handling semantics (as when calling +function provides reliable signal handling semantics (as when calling .BR sigaction () with .I sa_mask @@ -178,19 +178,19 @@ equal to 0). On System V, the .BR signal () -function provides unreliable semantics (as when calling +function provides unreliable semantics (as when calling .BR sigaction () with .I sa_mask -equal to +equal to .IR "SA_RESETHAND | SA_NODEFER" ). -On BSD, +On BSD, .BR signal () provides reliable semantics. -POSIX.1-2001 leaves these aspects of +POSIX.1-2001 leaves these aspects of .BR signal () unspecified. -See +See .BR signal (2) for further details. @@ -204,20 +204,20 @@ for details. .SH BUGS In versions of glibc before 2.2, .BR sigset () -did not unblock +did not unblock .I sig -if +if .I disp was specified as a value other than .BR SIG_HOLD . In all versions of glibc up to and including 2.3.5, .BR sigset () -does not correctly return the previous disposition of the signal +does not correctly return the previous disposition of the signal in two cases. First, if .I disp -is specified as +is specified as .BR SIG_HOLD , then a successful .BR sigset () @@ -237,10 +237,10 @@ Instead, the previous disposition of the signal is returned. .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951 .\" .\" The POSIX.1-2001 disposition of sigset() says: -.\" Upon successful completion, sigset() shall return -.\" SIG_HOLD if the signal had been blocked and the signal's -.\" previous disposition if it had not been blocked. -.\" Otherwise, SIG_ERR shall be returned and errno set to +.\" Upon successful completion, sigset() shall return +.\" SIG_HOLD if the signal had been blocked and the signal's +.\" 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. diff --git a/man3/sigsetops.3 b/man3/sigsetops.3 index aa749a160..c3e05e0b8 100644 --- a/man3/sigsetops.3 +++ b/man3/sigsetops.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,7 +51,7 @@ initializes the signal set given by to empty, with all signals excluded from the set. .PP .BR sigfillset () -initializes +initializes .I set to full, including all signals. .PP @@ -60,16 +60,16 @@ and .BR sigdelset () add and delete respectively signal .I signum -from +from .IR set . .PP .BR sigismember () tests whether .I signum -is a member of +is a member of .IR set . .SH "RETURN VALUE" -.BR sigemptyset (), +.BR sigemptyset (), .BR sigfillset (), .BR sigaddset (), and @@ -95,16 +95,16 @@ POSIX.1-2001. If the _GNU_SOURCE feature test macro is defined, then exposes three other functions for manipulating signal sets. -.TP +.TP .BI "int sigisemptyset(sigset_t *" set ); returns 1 if -.I set +.I set contains no signals, and 0 otherwise. .TP .BI "int sigorset(sigset_t *" dest ", sigset_t *" left \ ", sigset_t *" right ); places the union of the sets -.I left +.I left and .I right in @@ -113,7 +113,7 @@ in .BI "int sigandset(sigset_t *" dest ", sigset_t *" left \ ", sigset_t *" right ); places the intersection of the sets -.I left +.I left and .I right in @@ -124,7 +124,7 @@ and .BR sigandset () return 0 on success, and \-1 on failure. .PP -These functions are non-standard (a few other systems provide similar +These functions are non-standard (a few other systems provide similar functions) and their use should be avoided in portable applications. .SH "SEE ALSO" .BR sigaction (2), diff --git a/man3/sigvec.3 b/man3/sigvec.3 index a67eddac9..59766010b 100644 --- a/man3/sigvec.3 +++ b/man3/sigvec.3 @@ -38,39 +38,39 @@ sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API .SH DESCRIPTION These functions are provided in glibc as a compatibility interface for programs that make use of the historical BSD signal API. -This API is obsolete: new applications should use the POSIX signal API -.RB ( sigaction (2), +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), .BR sigprocmask (2), etc.) The .BR sigvec () function sets and/or gets the disposition of the signal -.I sig +.I sig (like the POSIX .BR sigaction (2)). -If +If .I vec is not NULL, it points to a .I sigvec -structure that defines the new disposition for +structure that defines the new disposition for .IR sig . If .I ovec -is not NULL, it points to a +is not NULL, it points to a .I sigvec structure that is used to return the previous disposition of .IR sig . -To obtain the current disposition of +To obtain the current disposition of .I sig without changing it, specify NULL for -.IR vec , +.IR vec , and a non-NULL pointer for .IR ovec . The dispositions for .B SIGKILL -and +and .B SIGSTOP cannot be changed. @@ -99,13 +99,13 @@ If .I sv_handler specifies the address of a signal handler, then .I sv_mask -specifies a mask of signals that are to be blocked while +specifies a mask of signals that are to be blocked while the handler is executing. -In addition, the signal for which the handler is invoked is +In addition, the signal for which the handler is invoked is also blocked by default. Attempts to block .B SIGKILL -or +or .B SIGSTOP are silently ignored. @@ -121,38 +121,38 @@ If the signal handler interrupts a blocking system call, then upon return from the handler the system call will not be restarted: instead it will fail with the error .IR EINTR . -If this flag is not specified, then system calls are restarted +If this flag is not specified, then system calls are restarted by default. .TP .B SV_RESETHAND -Reset the disposition of the signal to the default +Reset the disposition of the signal to the default before calling the signal handler. If this flag is not specified, then the handler remains established -until explicitly removed by a later call to +until explicitly removed by a later call to .BR sigvec () or until the process performs an .BR execve (2). .TP .B SV_ONSTACK -Handle the signal on the alternate signal stack -(historically established under BSD using the obsolete +Handle the signal on the alternate signal stack +(historically established under BSD using the obsolete .BR sigstack () -function; the POSIX replacement is +function; the POSIX replacement is .BR sigaltstack ()). .PP -The +The .BR sigmask () function constructs and returns a "signal mask" for .IR signum . -For example, we can initialise the -.I vec.sv_mask -field given to +For example, we can initialise the +.I vec.sv_mask +field given to .BR sigvec () using code such as the following: .nf vec.sv_mask = sigmask(SIGQUIT) | sigpause(SIGABRT); - /* Block SIGQUIT and SIGABRT during + /* Block SIGQUIT and SIGABRT during handler execution */ .fi .PP @@ -161,20 +161,20 @@ The function adds the signals in .I mask to the process's signal mask -(like POSIX +(like POSIX .IR sigprocmask(SIG_BLOCK) ), and returns the process's previous signal mask. Attempts to block .B SIGKILL -or +or .B SIGSTOP are silently ignored. .PP -The +The .BR sigsetmask () function sets the process's signal mask to the value given in -.I mask -(like POSIX +.I mask +(like POSIX .IR sigprocmask(SIG_SETMASK) ), and returns the process's previous signal mask. .PP @@ -184,10 +184,10 @@ function returns the process's current signal mask. This call is equivalent to .IR sigblock(0) . .SH RETURN VALUE -The +The .BR sigvec () function returns 0 on success; on error, it returns \-1 and sets -.I errno +.I errno to indicate the error. The @@ -208,7 +208,7 @@ and .SH NOTES On 4.3BSD, the .BR signal () -function provided reliable semantics (as when calling +function provided reliable semantics (as when calling .BR sigvec () with .I vec.sv_mask @@ -216,10 +216,10 @@ equal to 0). On System V, .BR signal () provides unreliable semantics. -POSIX.1-2001 leaves these aspects of +POSIX.1-2001 leaves these aspects of .BR signal () unspecified. -See +See .BR signal (2) for further details. @@ -231,7 +231,7 @@ See .BR sigpause (3) for details. .SH "CONFORMING TO" -All of these functions were in +All of these functions were in 4.3BSD, except .BR siggetmask (), whose origin is unclear. diff --git a/man3/sin.3 b/man3/sin.3 index 1dda03a1d..919c12145 100644 --- a/man3/sin.3 +++ b/man3/sin.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -49,7 +49,7 @@ given in radians. The \fBsin\fP() function returns a value between \-1 and 1. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/sinh.3 b/man3/sinh.3 index f900afd9d..39e67d001 100644 --- a/man3/sinh.3 +++ b/man3/sinh.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,11 +45,11 @@ sinh, sinhf, sinhl \- hyperbolic sine function .sp Link with \-lm. .SH DESCRIPTION -The \fBsinh\fP() function returns the hyperbolic sine of \fIx\fP, which +The \fBsinh\fP() function returns the hyperbolic sine of \fIx\fP, which is defined mathematically as (exp(x) \- exp(\-x)) / 2. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/sleep.3 b/man3/sleep.3 index 78d8cb465..30dc9988e 100644 --- a/man3/sleep.3 +++ b/man3/sleep.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -51,7 +51,7 @@ is a bad idea. .PP Using .BR longjmp () -from a signal handler or modifying the handling of +from a signal handler or modifying the handling of .B SIGALRM while sleeping will cause undefined results. .SH "SEE ALSO" diff --git a/man3/sockatmark.3 b/man3/sockatmark.3 index 2f95c3b73..b6be8beb9 100644 --- a/man3/sockatmark.3 +++ b/man3/sockatmark.3 @@ -26,7 +26,7 @@ sockatmark \- determine whether socket is at out-of-band mark .BI "int sockatmark(int " fd ); .SH DESCRIPTION .BR sockatmark () -returns a value indicating whether or not the socket referred +returns a value indicating whether or not the socket referred to by the file descriptor .I fd is at the out-of-band mark. @@ -46,14 +46,14 @@ is not a valid file descriptor. .TP .B EINVAL .\" POSIX.1 says ENOTTY for this case -.I fd +.I fd is not a file descriptor to which .BR sockatmark () can be applied. .SH NOTES If .BR sockatmark () -returns 1, then the out-of-band data can be read using the +returns 1, then the out-of-band data can be read using the .B MSG_OOB flag of .BR recv (2). @@ -64,21 +64,21 @@ Out-of-band data is only supported on some stream socket protocols. can safely be called from a handler for the SIGURG signal. .BR sockatmark () -is implemented using the -.B SIOCATMARK +is implemented using the +.B SIOCATMARK .BR ioctl () operation. .SH "CONFORMING TO" POSIX.1-2001 .SH VERSIONS -.BR sockatmark () +.BR sockatmark () was added to glibc in version 2.2.4. .SH BUGS Prior to glibc 2.4, -.BR sockatmark () +.BR sockatmark () did not work. .SH EXAMPLE -The following code can be used after receipt of a SIGURG signal +The following code can be used after receipt of a SIGURG signal to read (and discard) all data up to the mark, and then read the byte of data at the mark: .nf @@ -92,18 +92,18 @@ and then read the byte of data at the mark: if (atmark == \-1) { perror("sockatmark"); break; - } + } if (atmark) break; - + s = read(fd, buf, BUF_LEN) <= 0); if (s == -1) perror("read"); - if (s <= 0) + if (s <= 0) break; } - + if (atmark == 1) { if (recv(fd, &oobdata, 1, MSG_OOB) == \-1) { perror("recv"); diff --git a/man3/sqrt.3 b/man3/sqrt.3 index 480869331..d0128c496 100644 --- a/man3/sqrt.3 +++ b/man3/sqrt.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,7 +51,7 @@ It fails and sets \fIerrno\fP to EDOM, if \fIx\fP is negative. \fIx\fP is negative. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/stdarg.3 b/man3/stdarg.3 index dd56df80a..e48609767 100644 --- a/man3/stdarg.3 +++ b/man3/stdarg.3 @@ -53,7 +53,8 @@ stdarg \- variable argument lists .BI "void va_copy(va_list " dest ", va_list " src ); .SH DESCRIPTION A function may be called with a varying number of arguments of varying -types. The include file +types. +The include file .I declares a type .B va_list @@ -91,9 +92,10 @@ or as a function or an array type. The .BR va_arg () macro expands to an expression that has the type and value of the next -argument in the call. The parameter +argument in the call. +The parameter .I ap -is the +is the .B va_list .I ap initialized by @@ -102,7 +104,8 @@ Each call to .BR va_arg () modifies .I ap -so that the next call returns the next argument. The parameter +so that the next call returns the next argument. +The parameter .I type is a type name specified so that the type of a pointer to an object that has the specified type can be obtained simply by adding a * to @@ -110,9 +113,9 @@ has the specified type can be obtained simply by adding a * to .PP The first use of the .BR va_arg () -macro after that of the +macro after that of the .BR va_start () -macro returns the argument after +macro returns the argument after .IR last . Successive invocations return the values of the remaining arguments. .PP @@ -133,11 +136,13 @@ Each invocation of .BR va_start () must be matched by a corresponding invocation of .BR va_end () -in the same function. After the call +in the same function. +After the call .BI va_end( ap ) the variable .I ap -is undefined. Multiple transversals of the list, each +is undefined. +Multiple transversals of the list, each bracketed by .BR va_start () and @@ -171,7 +176,8 @@ it may be necessary for to allocate memory, store the parameters there, and also an indication of which parameter is next, so that .BR va_arg () -can step through the list. Now +can step through the list. +Now .BR va_end () can free the allocated memory again. To accommodate this situation, C99 adds a macro @@ -205,8 +211,8 @@ with each format character based on the type. #include #include -void -foo(char *fmt, ...) +void +foo(char *fmt, ...) { va_list ap; int d; @@ -247,8 +253,8 @@ macro. .SH COMPATIBILITY These macros are .I not -compatible with the historic macros they replace. A backward compatible -version can be found in the include file +compatible with the historic macros they replace. +A backward compatible version can be found in the include file .IR varargs.h . .SH COMPARISON The historic setup is: @@ -256,9 +262,9 @@ The historic setup is: .nf #include -void -foo(va_alist) - va_dcl +void +foo(va_alist) + va_dcl { va_list ap; @@ -284,7 +290,8 @@ Unlike the macros, the .B stdarg macros do not permit programmers to code a function with no fixed -arguments. This problem generates work mainly when converting +arguments. +This problem generates work mainly when converting .B varargs code to .B stdarg diff --git a/man3/stdin.3 b/man3/stdin.3 index 62cbf3e38..e514993c0 100644 --- a/man3/stdin.3 +++ b/man3/stdin.3 @@ -20,7 +20,8 @@ .Sh DESCRIPTION Under normal circumstances every Unix program has three streams opened for it when it starts up, one for input, one for output, and one for -printing diagnostic or error messages. These are typically attached to +printing diagnostic or error messages. +These are typically attached to the user's terminal (see .Xr tty 4 ) but might instead refer to files or other devices, depending on what @@ -29,7 +30,8 @@ the parent process chose to set up. (See also the ``Redirection'' section of .Pp The input stream is referred to as ``standard input''; the output stream is referred to as ``standard output''; and the error stream is referred to -as ``standard error''. These terms are abbreviated to form the symbols +as ``standard error''. +These terms are abbreviated to form the symbols used to refer to these files, namely .Nm stdin , .Nm stdout , @@ -48,7 +50,7 @@ same underlying files may also be accessed using the raw Unix file interface, that is, the functions like .Xr read 2 and -.Xr lseek 2 . +.Xr lseek 2 . .Pp On program startup, the integer file descriptors associated with the streams @@ -58,7 +60,7 @@ and .Nm stderr are 0, 1, and 2, respectively. The preprocessor symbols STDIN_FILENO, -STDOUT_FILENO, and STDERR_FILENO are defined with these values in +STDOUT_FILENO, and STDERR_FILENO are defined with these values in . (Applying .Xr freopen 3 @@ -70,10 +72,11 @@ unexpected results and should generally be avoided. (For the masochistic among you: POSIX.1, section 8.2.3, describes in detail how this interaction is supposed to work.) A general rule is that file descriptors are handled in the kernel, -while stdio is just a library. This means for example, that after an -.Fn exec , +while stdio is just a library. +This means for example, that after an +.Fn exec , the child inherits all open file descriptors, but all old streams -have become inaccessible. +have become inaccessible. .Pp Since the symbols .Nm stdin , @@ -101,14 +104,17 @@ and by normal program termination. .Sh CONSIDERATIONS The stream .Nm stderr -is unbuffered. The stream +is unbuffered. +The stream .Nm stdout -is line-buffered when it points to a terminal. Partial lines will not +is line-buffered when it points to a terminal. +Partial lines will not appear until .Xr fflush 3 or .Xr exit 3 -is called, or a newline is printed. This can produce unexpected +is called, or a newline is printed. +This can produce unexpected results, especially with debugging output. The buffering mode of the standard streams (or any other stream) can be changed using the diff --git a/man3/stdio.3 b/man3/stdio.3 index c94f5a4a6..c7212acf2 100644 --- a/man3/stdio.3 +++ b/man3/stdio.3 @@ -47,23 +47,29 @@ stdio \- standard input/output library functions .B FILE *stderr; .SH DESCRIPTION The standard I/O library provides a simple and efficient buffered stream -I/O interface. Input and output is mapped into logical data streams and the -physical I/O characteristics are concealed. The functions and macros are +I/O interface. +Input and output is mapped into logical data streams and the +physical I/O characteristics are concealed. +The functions and macros are listed below; more information is available from the individual man pages. .PP A stream is associated with an external file (which may be a physical device) by .I opening -a file, which may involve creating a new file. Creating an existing file -causes its former contents to be discarded. If a file can support -positioning requests (such as a disk file, as opposed to a terminal) then a +a file, which may involve creating a new file. +Creating an existing file +causes its former contents to be discarded. +If a file can support positioning requests (such as a disk file, +as opposed to a terminal) then a .I file position indicator associated with the stream is positioned at the start of the file (byte -zero), unless the file is opened with append mode. If append mode is used, +zero), unless the file is opened with append mode. +If append mode is used, it is unspecified whether the position indicator will be placed at the -start or the end of the file. The position indicator is maintained by -subsequent reads, writes and positioning requests. All input occurs -as if the characters were read by successive calls to the +start or the end of the file. +The position indicator is maintained by +subsequent reads, writes and positioning requests. +All input occurs as if the characters were read by successive calls to the .BR fgetc (3) function; all output takes place as if all characters were written by successive calls to the @@ -72,31 +78,36 @@ function. .PP A file is disassociated from a stream by .I closing -the file. Output streams are flushed (any unwritten buffer contents are +the file. +Output streams are flushed (any unwritten buffer contents are transferred to the host environment) before the stream is disassociated from -the file. The value of a pointer to a +the file. +The value of a pointer to a .B FILE object is indeterminate after a file is closed (garbage). .PP A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it can be -repositioned at the start). If the main function returns to its original +repositioned at the start). +If the main function returns to its original caller, or the .BR exit (3) function is called, all open files are closed (hence all output streams are -flushed) before program termination. Other methods of program termination, +flushed) before program termination. +Other methods of program termination, such as .BR abort (3) do not bother about closing files properly. .PP At program startup, three text streams are predefined and need not be opened explicitly \(em -.I standard input +.I standard input (for reading conventional input), \(em -.I standard output +.I standard output (for writing conventional input), and .I standard error -(for writing diagnostic output). These streams are abbreviated +(for writing diagnostic output). +These streams are abbreviated .IR stdin , stdout and .IR stderr . @@ -106,7 +117,8 @@ not to refer to an interactive device. .PP Output streams that refer to terminal devices are always line buffered by default; pending output to such streams is written automatically whenever -an input stream that refers to a terminal device is read. In cases where a +an input stream that refers to a terminal device is read. +In cases where a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .BR fflush (3) @@ -224,7 +236,7 @@ binary stream input/output .TP .B freopen stream open functions -.\" Not on Linux: +.\" Not on Linux: .\" .TP .\" .B fropen .\" open a stream diff --git a/man3/stdio_ext.3 b/man3/stdio_ext.3 index b9ecfff4a..58a2eac6c 100644 --- a/man3/stdio_ext.3 +++ b/man3/stdio_ext.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -94,13 +94,15 @@ operation, and zero otherwise. The .BR __fsetlocking () function can be used to select the desired type of locking on the stream. -It returns the current type. The +It returns the current type. +The .I type parameter can take the following three values: .TP .B FSETLOCKING_INTERNAL Perform implicit locking around every operation on the given stream -(except for the *_unlocked ones). This is the default. +(except for the *_unlocked ones). +This is the default. .TP .B FSETLOCKING_BYCALLER The caller will take care of the locking (possibly using @@ -109,11 +111,13 @@ in case there is more than one thread), and the stdio routines will not do locking until the state is reset to FSETLOCKING_INTERNAL. .TP .B FSETLOCKING_QUERY -Don't change the type of locking. (Only return it.) +Don't change the type of locking. +(Only return it.) .LP The .BR _flushlbf () -function flushes all line-buffered streams. (Presumably so that +function flushes all line-buffered streams. +(Presumably so that output to a terminal is forced out, say before reading keyboard input.) .LP The diff --git a/man3/stpcpy.3 b/man3/stpcpy.3 index 796c23faa..fefd07973 100644 --- a/man3/stpcpy.3 +++ b/man3/stpcpy.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,8 +35,8 @@ stpcpy \- copy a string returning a pointer to its end .fi .SH DESCRIPTION The \fBstpcpy\fP() function copies the string pointed to by \fIsrc\fP -(including the terminating `\\0' character) to the array pointed to by -\fIdest\fP. The strings may not overlap, and the destination string +(including the terminating `\\0' character) to the array pointed to by +\fIdest\fP. The strings may not overlap, and the destination string \fIdest\fP must be large enough to receive the copy. .SH "RETURN VALUE" \fBstpcpy\fP() returns a pointer to the \fBend\fP of the string diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 index 12f9703bd..47cb76490 100644 --- a/man3/stpncpy.3 +++ b/man3/stpncpy.3 @@ -23,10 +23,13 @@ stpncpy \- copy a fixed-size string, returning a pointer to its end .SH DESCRIPTION The \fBstpncpy\fP() function copies at most \fIn\fP characters from the string pointed to by \fIsrc\fP, including the terminating '\\0' character, to the -array pointed to by \fIdest\fP. Exactly \fIn\fP characters are written at -\fIdest\fP. If the length \fIstrlen(src)\fP is smaller than \fIn\fP, the +array pointed to by \fIdest\fP. +Exactly \fIn\fP characters are written at +\fIdest\fP. +If the length \fIstrlen(src)\fP is smaller than \fIn\fP, the remaining characters in the array pointed to by \fIdest\fP are filled -with '\\0' characters. If the length \fIstrlen(src)\fP is greater or equal to +with '\\0' characters. +If the length \fIstrlen(src)\fP is greater or equal to \fIn\fP, the string pointed to by \fIdest\fP will not be '\\0' terminated. .PP The strings may not overlap. diff --git a/man3/strcasecmp.3 b/man3/strcasecmp.3 index b71d4d1da..5e7327398 100644 --- a/man3/strcasecmp.3 +++ b/man3/strcasecmp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,16 +38,17 @@ strcasecmp, strncasecmp \- compare two strings ignoring case .fi .SH DESCRIPTION The \fBstrcasecmp\fP() function compares the two strings \fIs1\fP and -\fIs2\fP, ignoring the case of the characters. It returns an integer -less than, equal to, or greater than zero if \fIs1\fP is found, +\fIs2\fP, ignoring the case of the characters. +It returns an integer +less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .PP The \fBstrncasecmp\fP() function is similar, except it only compares the first \fIn\fP characters of \fIs1\fP. .SH "RETURN VALUE" The \fBstrcasecmp\fP() and \fBstrncasecmp\fP() functions return -an integer less than, equal to, or greater than zero if \fIs1\fP -(or the first \fIn\fP bytes thereof) is found, respectively, to be +an integer less than, equal to, or greater than zero if \fIs1\fP +(or the first \fIn\fP bytes thereof) is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .SH "CONFORMING TO" 4.4BSD, POSIX.1-2001 diff --git a/man3/strcat.3 b/man3/strcat.3 index fea81512a..01b3a4b3a 100644 --- a/man3/strcat.3 +++ b/man3/strcat.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,10 +37,10 @@ strcat, strncat \- concatenate two strings .BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBstrcat\fP() function appends the \fIsrc\fP string to the -\fIdest\fP string overwriting the `\\0' character at the end of -\fIdest\fP, and then adds a terminating `\\0' character. The -strings may not overlap, and the \fIdest\fP string must have +The \fBstrcat\fP() function appends the \fIsrc\fP string to the +\fIdest\fP string overwriting the `\\0' character at the end of +\fIdest\fP, and then adds a terminating `\\0' character. +The strings may not overlap, and the \fIdest\fP string must have enough space for the result. .PP The \fBstrncat\fP() function is similar, except that it will use diff --git a/man3/strchr.3 b/man3/strchr.3 index 9e8459f89..6b9e7be5e 100644 --- a/man3/strchr.3 +++ b/man3/strchr.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -27,7 +27,7 @@ .\" Modified Mon Apr 12 12:51:24 1993, David Metcalfe .\" 2006-05-19, Justin Pryzby .\" Document strchrnul(3). -.\" +.\" .TH STRCHR 3 2006-05-19 "GNU" "Linux Programmer's Manual" .SH NAME strchr, strrchr, strchrnul \- locate character in string @@ -52,8 +52,8 @@ The \fBstrrchr\fP() function returns a pointer to the last occurrence of the character \fIc\fP in the string \fIs\fP. .PP The \fBstrchrnul\fP() function is like \fBstrchr\fP() -except that if \fIc\fP is not found in \fIs\fP, -then it returns a pointer to the null byte +except that if \fIc\fP is not found in \fIs\fP, +then it returns a pointer to the null byte at the end of \fIs\fP, rather than NULL. .PP Here "character" means "byte"; these functions do not work with @@ -63,8 +63,8 @@ The \fBstrchr\fP() and \fBstrrchr\fP() functions return a pointer to the matched character or NULL if the character is not found. The \fBstrchrnul\fP() function returns a pointer to -the matched character, -or a pointer to the null +the matched character, +or a pointer to the null byte at the end of \fIs\fP (i.e., \fIs+strlen(s)\fP) if the character is not found. .SH "CONFORMING TO" diff --git a/man3/strcmp.3 b/man3/strcmp.3 index 623effc05..7fe2bfa95 100644 --- a/man3/strcmp.3 +++ b/man3/strcmp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,16 +40,16 @@ strcmp, strncmp \- compare two strings .fi .SH DESCRIPTION The \fBstrcmp\fP() function compares the two strings \fIs1\fP and -\fIs2\fP. It returns an integer less than, equal to, or greater -than zero if \fIs1\fP is found, respectively, to be less than, +\fIs2\fP. It returns an integer less than, equal to, or greater +than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .PP The \fBstrncmp\fP() function is similar, except it only compares the first (at most) \fIn\fP characters of \fIs1\fP and \fIs2\fP. .SH "RETURN VALUE" -The \fBstrcmp\fP() and \fBstrncmp\fP() functions return an integer -less than, equal to, or greater than zero if \fIs1\fP (or the first -\fIn\fP bytes thereof) is found, respectively, to be less than, to +The \fBstrcmp\fP() and \fBstrncmp\fP() functions return an integer +less than, equal to, or greater than zero if \fIs1\fP (or the first +\fIn\fP bytes thereof) is found, respectively, to be less than, to match, or be greater than \fIs2\fP. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99. diff --git a/man3/strcoll.3 b/man3/strcoll.3 index 1826bd209..ded1c4ea3 100644 --- a/man3/strcoll.3 +++ b/man3/strcoll.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,14 +36,14 @@ strcoll \- compare two strings using the current locale .fi .SH DESCRIPTION The \fBstrcoll\fP() function compares the two strings \fIs1\fP and -\fIs2\fP. It returns an integer less than, equal to, or greater -than zero if \fIs1\fP is found, respectively, to be less than, +\fIs2\fP. It returns an integer less than, equal to, or greater +than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP. The comparison is based on -strings interpreted as appropriate for the program's current locale +strings interpreted as appropriate for the program's current locale for category \fILC_COLLATE\fP. (See \fBsetlocale\fP(3)). .SH "RETURN VALUE" -The \fBstrcoll\fP() function returns an integer less than, equal to, -or greater than zero if \fIs1\fP is found, respectively, to be less +The \fBstrcoll\fP() function returns an integer less than, equal to, +or greater than zero if \fIs1\fP is found, respectively, to be less than, to match, or be greater than \fIs2\fP, when both are interpreted as appropriate for the current locale. .SH "CONFORMING TO" diff --git a/man3/strcpy.3 b/man3/strcpy.3 index 03bc4781a..7534c9c9b 100644 --- a/man3/strcpy.3 +++ b/man3/strcpy.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,12 +41,13 @@ strcpy, strncpy \- copy a string .fi .SH DESCRIPTION The \fBstrcpy\fP() function copies the string pointed to by \fIsrc\fP -(including the terminating `\\0' character) to the array pointed to by -\fIdest\fP. The strings may not overlap, and the destination string +(including the terminating `\\0' character) to the array pointed to by +\fIdest\fP. The strings may not overlap, and the destination string \fIdest\fP must be large enough to receive the copy. .PP The \fBstrncpy\fP() function is similar, except that not more than -\fIn\fP bytes of \fIsrc\fP are copied. Thus, if there is no null byte +\fIn\fP bytes of \fIsrc\fP are copied. +Thus, if there is no null byte among the first \fIn\fP bytes of \fIsrc\fP, the result will not be null-terminated. .PP diff --git a/man3/strdup.3 b/man3/strdup.3 index 9136c2853..c2635793a 100644 --- a/man3/strdup.3 +++ b/man3/strdup.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,11 +51,13 @@ is a duplicate of the string \fIs\fP. Memory for the new string is obtained with \fBmalloc\fP(3), and can be freed with \fBfree\fP(3). The \fBstrndup\fP() function is similar, but only copies at most -\fIn\fP characters. If \fIs\fP is longer than \fIn\fP, only \fIn\fP +\fIn\fP characters. +If \fIs\fP is longer than \fIn\fP, only \fIn\fP characters are copied, and a terminating null byte ('\\0') is added. \fBstrdupa\fP() and \fBstrndupa\fP() are similar, but use \fBalloca(3)\fP -to allocate the buffer. They are only available when using the GNU +to allocate the buffer. +They are only available when using the GNU GCC suite, and suffer from the same limitations described in \fBalloca(3)\fP. .SH "RETURN VALUE" The \fBstrdup\fP() function returns a pointer to the duplicated diff --git a/man3/strerror.3 b/man3/strerror.3 index eb1de25f1..6c2cd5b5f 100644 --- a/man3/strerror.3 +++ b/man3/strerror.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -46,7 +46,7 @@ strerror, strerror_r \- return string describing error number .BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen ); /* GNU-specific strerror_r() */ .sp -.B #define _XOPEN_SOURCE 600 +.B #define _XOPEN_SOURCE 600 .B #include .sp .BI "int strerror_r(int " errnum ", char *" buf ", size_t " buflen ); @@ -61,32 +61,32 @@ modified by a subsequent call to \fBperror\fP() or \fBstrerror\fP(). No library function will modify this string. The \fBstrerror_r\fP() function is similar to \fBstrerror\fP(), but is -thread safe. -This function is available in two versions: -an XSI-compliant version specified in POSIX.1-2001, +thread safe. +This function is available in two versions: +an XSI-compliant version specified in POSIX.1-2001, and a GNU-specific version (available since glibc 2.0). -If _XOPEN_SOURCE is defined with the value 600, -then the XSI-compliant version is provided, +If _XOPEN_SOURCE is defined with the value 600, +then the XSI-compliant version is provided, otherwise the GNU-specific version is provided. -The XSI-compliant -.BR strerror_r () +The XSI-compliant +.BR strerror_r () is preferred for portable applications. It returns the error string in the user-supplied buffer .I buf of length .IR buflen . -The GNU-specific -.BR strerror_r () +The GNU-specific +.BR strerror_r () returns a pointer to a string containing the error message. This may be either a pointer to a string that the function stores in .IR buf , or a pointer to some (immutable) static string (in which case -.I buf +.I buf is unused). -If the function stores a string in +If the function stores a string in .IR buf , then at most .I buflen @@ -95,7 +95,7 @@ bytes are stored (the string may be truncated if is too small) and the string always includes a terminating null byte. .SH "RETURN VALUE" The \fBstrerror\fP() and \fBstrerror_r\fP() functions return -the appropriate error description string, +the appropriate error description string, or an "Unknown error nnn" message if the error number is unknown. The XSI-compliant \fBstrerror_r\fP() function returns 0 on success; @@ -115,26 +115,26 @@ Insufficient storage was supplied to contain the error description string. \fBstrerror\fP() is specified by POSIX.1-2001, C89, C99. \fBstrerror_r\fP() is specified by POSIX.1-2001. -The GNU-specific +The GNU-specific .BR strerror_r () function is a non-standard extension. POSIX.1-2001 permits .BR strerror () -to set +to set .I errno -if the call encounters an error, but does not specify what +if the call encounters an error, but does not specify what value should be returned as the function result in the event of an error. On some systems, .\" e.g., Solaris 8, HP-UX 11 .BR strerror () returns NULL if the error number is unknown. -On other systems, +On other systems, .\" e.g., FreeBSD 5.4, Tru64 5.1B .BR strerror () -returns a string something like "Error nnn occurred" and sets +returns a string something like "Error nnn occurred" and sets .I errno -to +to .B EINVAL if the error number is unknown. .SH "SEE ALSO" diff --git a/man3/strfmon.3 b/man3/strfmon.3 index 79df038b7..f35c3feef 100644 --- a/man3/strfmon.3 +++ b/man3/strfmon.3 @@ -34,8 +34,10 @@ according to the format specification \fIformat\fP and places the result in the character array \fIs\fP of size \fImax\fP. .PP Ordinary characters in \fIformat\fP are copied to \fIs\fP -without conversion. Conversion specifiers are introduced by a `%' -character. Immediately following it there can be zero or more +without conversion. +Conversion specifiers are introduced by a `%' +character. +Immediately following it there can be zero or more of the following flags: .TP .BI = f @@ -47,11 +49,13 @@ When not specified, the space character is used. .TP .B ^ Do not use any grouping characters that might be defined -for the current locale. By default, grouping is enabled. +for the current locale. +By default, grouping is enabled. .TP .BR ( " or " + The ( flag indicates that negative amounts should be enclosed between -parentheses. The + flag indicates that signs should be handled +parentheses. +The + flag indicates that signs should be handled in the default way, that is, amounts are preceded by the locale's sign indication, e.g., nothing for positive, "\-" for negative. .TP @@ -59,21 +63,25 @@ sign indication, e.g., nothing for positive, "\-" for negative. Omit the currency symbol. .TP .BR \- -Left justify all fields. The default is right justification. +Left justify all fields. +The default is right justification. .LP Next, there may be a field width: a decimal digit string specifying -a minimum field width in bytes. The default is 0. +a minimum field width in bytes. +The default is 0. A result smaller than this width is padded with spaces (on the left, unless the left-justify flag was given). .LP Next, there may be a left precision of the form "#" followed by -a decimal digit string. If the number of digits left of the +a decimal digit string. +If the number of digits left of the radix character is smaller than this, the representation is padded on the left with the numeric fill character. Grouping characters are not counted in this field width. .LP Next, there may be a right precision of the form "." followed by -a decimal digit string. The amount being formatted is rounded to +a decimal digit string. +The amount being formatted is rounded to the specified number of digits prior to formatting. The default is specified in the .I frac_digits @@ -85,7 +93,8 @@ If the right precision is 0, no radix character is printed. differ from that specified by LC_NUMERIC.) .LP Finally, the conversion specification must be ended with a -conversion character. The three conversion characters are +conversion character. +The three conversion characters are .TP .B % (In this case the entire specification must be exactly "%%".) @@ -127,7 +136,8 @@ as a digit, while it should not take more than half that, and will no doubt cause confusion. Surprisingly, the "fl" is preceded and followed by a space, and "NLG" is preceded by one and followed by two spaces. -This may be a bug in the locale files. The Italian, Australian, Swiss +This may be a bug in the locale files. +The Italian, Australian, Swiss and Portuguese locales yield .RS diff --git a/man3/strfry.3 b/man3/strfry.3 index bf5c79b3d..6ceb7a04a 100644 --- a/man3/strfry.3 +++ b/man3/strfry.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,13 +38,13 @@ strfry \- randomize a string .fi .SH DESCRIPTION The \fBstrfry\fP() function randomizes the contents of \fIstring\fP by -using \fBrand\fP(3) to randomly swap characters in the string. The -result is an anagram of \fIstring\fP. +using \fBrand\fP(3) to randomly swap characters in the string. +The result is an anagram of \fIstring\fP. .SH "RETURN VALUE" The \fBstrfry\fP() functions returns a pointer to the randomized string. .SH "CONFORMING TO" -The \fBstrfry\fP() function is unique to the +The \fBstrfry\fP() function is unique to the GNU C Library. .SH "SEE ALSO" .BR memfrob (3), diff --git a/man3/strftime.3 b/man3/strftime.3 index e3965e4b3..66825796e 100644 --- a/man3/strftime.3 +++ b/man3/strftime.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -29,7 +29,7 @@ .\" Applied fix by Wolfgang Franke, aeb, 961011 .\" Corrected return value, aeb, 970307 .\" Added Single Unix Spec conversions and %z, aeb/esr, 990329. -.\" 2005-11-22 mtk, added GLIBC NOTES covering optional 'flag' and +.\" 2005-11-22 mtk, added GLIBC NOTES covering optional 'flag' and .\" 'width' components of conversion specifications. .\" .TH STRFTIME 3 2005-11-23 "GNU" "Linux Programmer's Manual" @@ -48,10 +48,10 @@ according to the format specification \fIformat\fP and places the result in the character array \fIs\fP of size \fImax\fP. .PP Ordinary characters placed in the format string are copied to \fIs\fP -without conversion. +without conversion. .I "Conversion specifications" are introduced by a `%' -character, and terminated by a +character, and terminated by a .IR "conversion specifier character" , and are replaced in \fIs\fP as follows: .TP @@ -79,7 +79,8 @@ The day of the month as a decimal number (range 01 to 31). .B %D Equivalent to %m/%d/%y. (Yecch \(em for Americans only. Americans should note that in other countries %d/%m/%y is rather -common. This means that in international context this format is +common. +This means that in international context this format is ambiguous and should not be used.) (SU) .TP .B %e @@ -135,7 +136,7 @@ A newline character. (SU) Modifier: use alternative format, see below. (SU) .TP .B %p -Either `AM' or `PM' according to the given time value, or the +Either `AM' or `PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as `pm' and midnight as `am'. .TP @@ -172,13 +173,15 @@ See also %w. (SU) .B %U The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day -of week 01. See also %V and %W. +of week 01. +See also %V and %W. .TP .B %V The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of -the week. See also %U and %W. (SU) +the week. +See also %U and %W. (SU) .TP .B %w The day of the week as a decimal, range 0 to 6, Sunday being 0. @@ -209,19 +212,19 @@ Required to emit RFC\ 822-conformant dates The time zone or name or abbreviation. .TP .B %+ -.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to +.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to .\" their man pages) -The date and time in -.BR date (1) +The date and time in +.BR date (1) format. (TZ) (Not supported in glibc2.) .TP .B %% A literal `%' character. .PP -Some conversion specifications can be modified by preceding the -conversion specifier character by the E or O -.I modifier +Some conversion specifications can be modified by preceding the +conversion specifier character by the E or O +.I modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behaviour will be as if the unmodified @@ -253,7 +256,8 @@ There are strict inclusions between the set of conversions given in ANSI C (unmarked), those given in the Single Unix Specification (marked SU), those given in Olson's timezone package (marked TZ), and those given in glibc (marked GNU), except that %+ is not supported -in glibc2. On the other hand glibc2 has several more extensions. +in glibc2. +On the other hand glibc2 has several more extensions. POSIX.1 only refers to ANSI C; POSIX.2 describes under .BR date (1) several extensions that could apply to @@ -270,12 +274,12 @@ Glibc provides some extensions for conversion specifications. (These extensions are not specified in POSIX.1-2001, but a few other systems provide similar features.) .\" HP-UX and Tru64 also have features like this. -Between the % character and the conversion specifier character, -an optional -.I flag +Between the % character and the conversion specifier character, +an optional +.I flag and field -.I width -may be specified. +.I width +may be specified. (These precede the E or O modifiers, if present.) The following flag characters are permitted: @@ -284,20 +288,20 @@ The following flag characters are permitted: (underscore) Pad a numeric result string with spaces. .TP -.B \- +.B \- (dash) Do not pad a numeric result string. .TP .B 0 -Pad a numeric result string with zeros even if the conversion +Pad a numeric result string with zeros even if the conversion specifier character uses space-padding by default. .TP .B ^ Convert alphabetic characters in result string to upper case. .TP .B # -Swap the case of the result string. -(This flag only works with certain conversion specifier characters, +Swap the case of the result string. +(This flag only works with certain conversion specifier characters, and of these, it is only really useful with %Z). .PP An optional decimal width specifier may follow the (possibly absent) flag. @@ -307,22 +311,24 @@ then the result string is padded (on the left) to the specified width. Some buggy versions of gcc complain about the use of %c: .IR "warning: `%c' yields only last 2 digits of year in some locales" . Of course programmers are encouraged to use %c, it gives the preferred -date and time representation. One meets all kinds of strange obfuscations -to circumvent this gcc problem. A relatively clean one is to add an +date and time representation. +One meets all kinds of strange obfuscations +to circumvent this gcc problem. +A relatively clean one is to add an intermediate function .in +0.5i .nf -size_t -my_strftime(char *s, size_t max, const char *fmt, - const struct tm *tm) +size_t +my_strftime(char *s, size_t max, const char *fmt, + const struct tm *tm) { return strftime(s, max, fmt, tm); } .fi .in -0.5i .SH EXAMPLE -The program below can be used to experiment with +The program below can be used to experiment with .BR strftime (). .nf @@ -355,7 +361,7 @@ main(int argc, char *argv[]) .fi .PP Some examples of the result string produced by the glibc implementation of -.BR strftime () +.BR strftime () are as follows: .nf diff --git a/man3/string.3 b/man3/string.3 index e5243c0ac..89d60e1c9 100644 --- a/man3/string.3 +++ b/man3/string.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -85,8 +85,8 @@ strrchr, strsep, strspn, strstr, strtok, strxfrm, index, rindex .fi .SH DESCRIPTION The string functions perform string operations on null-terminated -strings. See the individual man pages for descriptions of each -function. +strings. +See the individual man pages for descriptions of each function. .SH "SEE ALSO" .BR index (3), .BR rindex (3), diff --git a/man3/strlen.3 b/man3/strlen.3 index e13946e78..606b7e9e5 100644 --- a/man3/strlen.3 +++ b/man3/strlen.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -35,7 +35,7 @@ strlen \- calculate the length of a string .BI "size_t strlen(const char *" s ); .fi .SH DESCRIPTION -The \fBstrlen\fP() function calculates the length of the string +The \fBstrlen\fP() function calculates the length of the string \fIs\fP, not including the terminating `\\0' character. .SH "RETURN VALUE" The \fBstrlen\fP() function returns the number of characters in \fIs\fP. diff --git a/man3/strpbrk.3 b/man3/strpbrk.3 index dcc42e245..6152c5f7f 100644 --- a/man3/strpbrk.3 +++ b/man3/strpbrk.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/strptime.3 b/man3/strptime.3 index b1997541e..6c8e2c99c 100644 --- a/man3/strptime.3 +++ b/man3/strptime.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -58,8 +58,8 @@ Each field descriptor consists of a .B % character followed by another character that specifies the replacement for the field descriptor. -All other characters in the -.I format +All other characters in the +.I format string must have a matching character in the input string, except for whitespace, which matches zero or more whitespace characters in the input string. @@ -67,10 +67,11 @@ There should be white\%space or other alphanumeric characters between any two field descriptors. .PP The \fBstrptime\fP() function processes the input string from left -to right. Each of the three possible input elements (whitespace, -literal, or format) are handled one after the other. If the input -cannot be matched to the format string the function stops. The -remainder of the format and input strings are not processed. +to right. +Each of the three possible input elements (whitespace, +literal, or format) are handled one after the other. +If the input cannot be matched to the format string the function stops. +The remainder of the format and input strings are not processed. .PP The supported input field descriptors are listed below. In case a text string (such as a weekday or month name) @@ -101,7 +102,8 @@ The century number (0-99). The day of month (1-31). .TP .B %D -Equivalent to %m/%d/%y. (This is the American style date, very confusing +Equivalent to %m/%d/%y. +(This is the American style date, very confusing to non-Americans, especially since %d/%m/%y is widely used in Europe. The ISO 8601 standard format is %Y-%m-%d.) .TP @@ -136,7 +138,8 @@ then the behaviour is undefined. Equivalent to %H:%M. .TP .B %S -The second (0-60; 60 may occur for leap seconds; earlier also 61 was allowed). +The second (0-60; 60 may occur for leap seconds; +earlier also 61 was allowed). .TP .B %t Arbitrary whitespace. @@ -171,7 +174,8 @@ range 00-68 refer to years in the twenty-first century (2000-2068). The year, including century (for example, 1991). .LP Some field descriptors can be modified by the E or O modifier characters -to indicate that an alternative format or specification should be used. If the +to indicate that an alternative format or specification should be used. +If the alternative format or specification does not exist in the current locale, the unmodified field descriptor is used. .LP @@ -231,7 +235,7 @@ The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. .TP .B %Oy -The year (offset from %C) using the locale's alternative numeric symbols. +The year (offset from %C) using the locale's alternative numeric symbols. .LP The broken-down time structure \fItm\fP is defined in \fI\fP as follows: @@ -253,11 +257,14 @@ struct tm { .in -0.5i .SH "RETURN VALUE" The return value of the function is a pointer to the first character -not processed in this function call. In case the input string +not processed in this function call. +In case the input string contains more characters than required by the format string the return -value points right after the last consumed input character. In case +value points right after the last consumed input character. +In case the whole input string is consumed the return value points to the null -byte at the end of the string. If \fBstrptime\fP() fails to match all +byte at the end of the string. +If \fBstrptime\fP() fails to match all of the format string and therefore an error occurred the function returns NULL. .SH "CONFORMING TO" @@ -270,8 +277,8 @@ and \fBstrftime\fP(). #include #include -int -main(void) +int +main(void) { struct tm tm; char buf[255]; @@ -307,7 +314,8 @@ The day of the week as a decimal number (1-7, where Monday = 1). .B %V The ISO 8601:1988 week number as a decimal number (1-53). If the week (starting on Monday) containing 1 January has four or more days -in the new year, then it is considered week 1. Otherwise, it is the last week +in the new year, then it is considered week 1. +Otherwise, it is the last week of the previous year, and the next week is week 1. .TP .B %z @@ -337,7 +345,7 @@ The GNU libc implementation does not touch those fields which are not explicitly specified, except that it recomputes the .IR tm_wday and -.IR tm_yday +.IR tm_yday field if any of the year, month, or day elements changed. .PP This function is available since libc 4.6.8. @@ -350,8 +358,10 @@ was not handled, no 'E' and 'O' locale modifier characters were accepted, and the 'C' specification was a synonym for the 'c' specification. .PP The 'y' (year in century) specification is taken to specify a year -in the 20th century by libc4 and libc5. It is taken to be a year -in the range 1950-2049 by glibc 2.0. It is taken to be a year in +in the 20th century by libc4 and libc5. +It is taken to be a year +in the range 1950-2049 by glibc 2.0. +It is taken to be a year in 1969-2068 since glibc 2.1. .\" In libc4 and libc5 the code for %I is broken (fixed in glibc; .\" %OI was fixed in glibc 2.2.4). diff --git a/man3/strsep.3 b/man3/strsep.3 index ea23106e6..f28fac171 100644 --- a/man3/strsep.3 +++ b/man3/strsep.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,7 +39,8 @@ strsep \- extract token from string .fi .SH DESCRIPTION If *\fIstringp\fP is NULL, the \fBstrsep\fP() function returns NULL -and does nothing else. Otherwise, this function finds the first token +and does nothing else. +Otherwise, this function finds the first token in the string *\fIstringp\fP, where tokens are delimited by symbols in the string \fIdelim\fP. This token is terminated with a `\\0' character @@ -56,7 +57,8 @@ The \fBstrsep\fP() function was introduced as a replacement for However, \fBstrtok\fP() conforms to C89/C99 and hence is more portable. .SH BUGS This function suffers from the same problems as \fBstrtok\fP(). -In particular, it modifies the original string. Avoid it. +In particular, it modifies the original string. +Avoid it. .SH "CONFORMING TO" 4.4BSD .SH "SEE ALSO" diff --git a/man3/strsignal.3 b/man3/strsignal.3 index 19104f45b..529b0a3a3 100644 --- a/man3/strsignal.3 +++ b/man3/strsignal.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -40,11 +40,13 @@ strsignal \- return string describing signal .fi .SH DESCRIPTION The \fBstrsignal\fP() function returns a string describing the signal -number passed in the argument \fIsig\fP. The string can only be used +number passed in the argument \fIsig\fP. +The string can only be used until the next call to \fBstrsignal\fP(). .PP The array \fIsys_siglist\fP holds the signal description strings -indexed by signal number. The \fBstrsignal\fP() function should be +indexed by signal number. +The \fBstrsignal\fP() function should be used if possible instead of this array. .SH "RETURN VALUE" The \fBstrsignal\fP() function returns the appropriate description diff --git a/man3/strspn.3 b/man3/strspn.3 index 1fec24c0b..33430caec 100644 --- a/man3/strspn.3 +++ b/man3/strspn.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/strstr.3 b/man3/strstr.3 index a6ca12c5f..122b5d4e6 100644 --- a/man3/strstr.3 +++ b/man3/strstr.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/strtod.3 b/man3/strtod.3 index ae9caaab3..238196838 100644 --- a/man3/strtod.3 +++ b/man3/strtod.3 @@ -67,7 +67,7 @@ to .IR double , .IR float , and -.I long double +.I long double representation, respectively. The expected form of the (initial portion of the) string is @@ -80,8 +80,8 @@ A .I "decimal number" consists of a nonempty sequence of decimal digits possibly containing a radix character (decimal point, locale dependent, -usually ``.''), optionally followed by a decimal exponent. A -decimal exponent consists of an ``E'' or ``e'', followed by an +usually ``.''), optionally followed by a decimal exponent. +A decimal exponent consists of an ``E'' or ``e'', followed by an optional plus or minus sign, followed by a non-empty sequence of decimal digits, and indicates multiplication by a power of 10. .LP @@ -89,7 +89,8 @@ A .I "hexadecimal number" consists of a ``0x'' or ``0X'' followed by a nonempty sequence of hexadecimal digits possibly containing a radix character, -optionally followed by a binary exponent. A binary exponent +optionally followed by a binary exponent. +A binary exponent consists of a ``P'' or ``p'', followed by an optional plus or minus sign, followed by a non-empty sequence of decimal digits, and indicates multiplication by a power of 2. @@ -131,7 +132,7 @@ is stored in If the correct value would cause underflow, zero is returned and .B ERANGE -is stored in +is stored in .IR errno . .SH ERRORS .TP @@ -143,18 +144,18 @@ C89 describes C99 describes the other two functions. .SH NOTES -Since -0 can legitimately be returned +Since +0 can legitimately be returned on both success and failure, the calling program should set .I errno -to 0 before the call, +to 0 before the call, and then determine if an error occurred by checking whether .I errno has a non-zero value after the call. .SH EXAMPLE See the example on the .BR strtol (3) -manual page; +manual page; the use of the functions described in this manual page is similar. .SH "SEE ALSO" .BR atof (3), diff --git a/man3/strtoimax.3 b/man3/strtoimax.3 index 5f623bee3..8a3a6a7d0 100644 --- a/man3/strtoimax.3 +++ b/man3/strtoimax.3 @@ -29,10 +29,10 @@ strtoimax, strtoumax \- convert string to integer .sp .BI "intmax_t strtoimax(const char *" nptr ", char **" endptr ", int " base ); .br -.BI "uintmax_t strtoumax(const char *" nptr ", char **" endptr ", int " base ); +.BI "uintmax_t strtoumax(const char *" nptr ", char **" endptr ", int " base ); .fi .SH DESCRIPTION -These functions are just like +These functions are just like .BR strtol () and .BR strtoul (), diff --git a/man3/strtok.3 b/man3/strtok.3 index 4127e80ec..371e3d384 100644 --- a/man3/strtok.3 +++ b/man3/strtok.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,42 +37,42 @@ strtok, strtok_r \- extract tokens from strings .BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr ); .fi .SH DESCRIPTION -The \fBstrtok\fP() function parses a string into a sequence of tokens. +The \fBstrtok\fP() function parses a string into a sequence of tokens. On the first call to \fBstrtok\fP() the string to be parsed should be specified in \fIstr\fP. -In each subsequent call that should parse the same string, +In each subsequent call that should parse the same string, \fIstr\fP should be NULL. The \fIdelim\fP argument specifies a set of characters that delimit the tokens in the parsed string. -The caller may specify different strings in \fIdelim\fP in successive +The caller may specify different strings in \fIdelim\fP in successive calls that parse the same string. -Each call to \fBstrtok\fP() returns a pointer to a +Each call to \fBstrtok\fP() returns a pointer to a null-terminated string containing the next token. This string does not include the delimiting character. If no more tokens are found, \fBstrtok\fP() returns NULL. -A sequence of two or more contiguous delimiter characters in +A sequence of two or more contiguous delimiter characters in the parsed string is considered to be a single delimiter. Delimiter characters at the start or end of the string are ignored. -Put another way: the tokens returned by \fBstrtok\fP() +Put another way: the tokens returned by \fBstrtok\fP() are always non-empty strings. -The +The .BR strtok_r () function is a reentrant version .BR strtok (). -The \fIsaveptr\fP argument is a pointer to a +The \fIsaveptr\fP argument is a pointer to a \fIchar *\fP variable that is used internally by .BR strtok_r () in order to maintain context between successive calls that parse the same string. -On the first call to +On the first call to .BR strtok_r (), .I str -should point to the string to be parsed, and the value of +should point to the string to be parsed, and the value of .I saveptr is ignored. In subsequent calls, \fIstr\fP should be NULL, and @@ -104,10 +104,10 @@ main(int argc, char *argv[]) int j; if (argc != 4) { - fprintf(stderr, "Usage: %s string delim subdelim\\n", + fprintf(stderr, "Usage: %s string delim subdelim\\n", argv[0]); exit(EXIT_FAILURE); - } + } for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) { token = strtok_r(str1, argv[2], &saveptr1); @@ -120,8 +120,8 @@ main(int argc, char *argv[]) if (subtoken == NULL) break; printf("\t --> %s\\n", subtoken); - } - } + } + } exit(EXIT_SUCCESS); } /* main */ @@ -153,12 +153,13 @@ 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 +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 \fBstrtok\fP() and \fBstrtok_r\fP() functions return a pointer to +The \fBstrtok\fP() and \fBstrtok_r\fP() functions return a pointer to the next token, or NULL if there are no more tokens. .SH "CONFORMING TO" .TP diff --git a/man3/strtol.3 b/man3/strtol.3 index 41e112771..9945675f5 100644 --- a/man3/strtol.3 +++ b/man3/strtol.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -47,22 +47,24 @@ which must be between 2 and 36 inclusive, or be the special value 0. The string may begin with an arbitrary amount of white space (as determined by .BR isspace (3)) -followed by a single optional `+' or `\-' -sign. If \fIbase\fP is zero or 16, the string may then include a -`0x' prefix, and the number will be read in base 16; otherwise, a +followed by a single optional `+' or `\-' sign. +If \fIbase\fP is zero or 16, the string may then include a +`0x' prefix, and the number will be read in base 16; otherwise, a zero \fIbase\fP is taken as 10 (decimal) unless the next character is `0', in which case it is taken as 8 (octal). .PP -The remainder of the string is converted to a +The remainder of the string is converted to a .I long int value in the obvious manner, stopping at the first character which is not a -valid digit in the given base. (In bases above 10, the letter `A' in +valid digit in the given base. +(In bases above 10, the letter `A' in either upper or lower case represents 10, `B' represents 11, and so forth, with `Z' representing 35.) .PP If \fIendptr\fP is not NULL, \fBstrtol\fP() stores the address of the -first invalid character in \fI*endptr\fP. If there were no digits at +first invalid character in \fI*endptr\fP. +If there were no digits at all, \fBstrtol\fP() stores the original value of \fInptr\fP in \fI*endptr\fP (and returns 0). In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP @@ -75,9 +77,12 @@ function works just like the function but returns a long long integer value. .SH "RETURN VALUE" The \fBstrtol\fP() function returns the result of the conversion, -unless the value would underflow or overflow. If an underflow occurs, -\fBstrtol\fP() returns LONG_MIN. If an overflow occurs, \fBstrtol\fP() -returns LONG_MAX. In both cases, \fIerrno\fP is set to ERANGE. +unless the value would underflow or overflow. +If an underflow occurs, +\fBstrtol\fP() returns LONG_MIN. +If an overflow occurs, \fBstrtol\fP() +returns LONG_MAX. +In both cases, \fIerrno\fP is set to ERANGE. Precisely the same holds for .BR strtoll () (with LLONG_MIN and LLONG_MAX instead of LONG_MIN and LONG_MAX). @@ -95,14 +100,14 @@ The resulting value was out of range. The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case no conversion was performed (no digits seen, and 0 returned). .SH NOTES -Since +Since .BR strtol () -can legitimately return 0, +can legitimately return 0, LONG_MAX, or LONG_MIN (LLONG_MAX or LLONG_MIN for .BR strtoll ()) on both success and failure, the calling program should set .I errno -to 0 before the call, +to 0 before the call, and then determine if an error occurred by checking whether .I errno has a non-zero value after the call. @@ -134,14 +139,14 @@ to C99 and POSIX.1-2001. .SH EXAMPLE The program shown below demonstrates the use of .BR strtol (). -The first command line argument specifies a string from which +The first command line argument specifies a string from which .BR strtol () should parse a number. -The second (optional) argument specifies the base to be used for +The second (optional) argument specifies the base to be used for the conversion. (This argument is converted to numeric form using .BR atoi (3), -a function that performs no error checking and +a function that performs no error checking and has a simpler interface than .BR strtol ().) Some examples of the results produced by this program are the following: @@ -182,7 +187,7 @@ main(int argc, char *argv[]) if (argc < 2) { fprintf(stderr, "Usage: %s str [base]\\n", argv[0]); exit(EXIT_FAILURE); - } + } str = argv[1]; base = (argc > 2) ? atoi(argv[2]) : 10; @@ -196,12 +201,12 @@ main(int argc, char *argv[]) || (errno != 0 && val == 0)) { perror("strtol"); exit(EXIT_FAILURE); - } + } if (endptr == str) { fprintf(stderr, "No digits were found\\n"); exit(EXIT_FAILURE); - } + } /* If we got here, strtol() successfully parsed a number */ diff --git a/man3/strtoul.3 b/man3/strtoul.3 index f0eff87d1..85b8bf875 100644 --- a/man3/strtoul.3 +++ b/man3/strtoul.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -51,19 +51,22 @@ The string may begin with an arbitrary amount of white space (as determined by .BR isspace (3)) followed by a single optional `+' or `\-' -sign. If \fIbase\fP is zero or 16, the string may then include a -`0x' prefix, and the number will be read in base 16; otherwise, a +sign. +If \fIbase\fP is zero or 16, the string may then include a +`0x' prefix, and the number will be read in base 16; otherwise, a zero \fIbase\fP is taken as 10 (decimal) unless the next character is `0', in which case it is taken as 8 (octal). .PP The remainder of the string is converted to an unsigned long int value -in the obvious manner, stopping at the first character which is not a -valid digit in the given base. (In bases above 10, the letter `A' in +in the obvious manner, stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter `A' in either upper or lower case represents 10, `B' represents 11, and so forth, with `Z' representing 35.) .PP If \fIendptr\fP is not NULL, \fBstrtoul\fP() stores the address of the -first invalid character in \fI*endptr\fP. If there were no digits at +first invalid character in \fI*endptr\fP. +If there were no digits at all, \fBstrtoul\fP() stores the original value of \fInptr\fP in \fI*endptr\fP (and returns 0). In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP @@ -77,7 +80,7 @@ function but returns an unsigned long long integer value. .SH "RETURN VALUE" The \fBstrtoul\fP() function returns either the result of the conversion or, if there was a leading minus sign, the negation of the result of the -conversion represented as an unsigned value, +conversion represented as an unsigned value, unless the original (non-negated) value would overflow; in the latter case, \fBstrtoul\fP() returns ULONG_MAX and sets the global variable \fIerrno\fP to ERANGE. @@ -98,13 +101,13 @@ The resulting value was out of range. The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case no conversion was performed (no digits seen, and 0 returned). .SH NOTES -Since +Since .BR strtoul () can legitimately return 0 or LONG_MAX (LLONG_MAX for .BR strtoull ()) on both success and failure, the calling program should set .I errno -to 0 before the call, +to 0 before the call, and then determine if an error occurred by checking whether .I errno has a non-zero value after the call. @@ -139,7 +142,7 @@ to C99 and POSIX.1-2001. .SH EXAMPLE See the example on the .BR strtol (3) -manual page; +manual page; the use of the functions described in this manual page is similar. .SH "SEE ALSO" .BR atof (3), diff --git a/man3/strverscmp.3 b/man3/strverscmp.3 index 77103ea11..32b4dd0d8 100644 --- a/man3/strverscmp.3 +++ b/man3/strverscmp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -52,16 +52,19 @@ Thus, the task of .BR strverscmp () is to compare two strings and find the "right" order, while .BR strcmp () -only finds the lexicographic order. This function does not use +only finds the lexicographic order. +This function does not use the locale category LC_COLLATE, so is meant mostly for situations where the strings are expected to be in ASCII. What this function does is the following. -If both strings are equal, return 0. Otherwise find the position +If both strings are equal, return 0. +Otherwise find the position between two bytes with the property that before it both strings are equal, while directly after it there is a difference. Find the largest consecutive digit strings containing (or starting at, -or ending at) this position. If one or both of these is empty, +or ending at) this position. +If one or both of these is empty, then return what .BR strcmp () would have returned (numerical ordering of byte values). @@ -72,7 +75,7 @@ come before digit strings with fewer leading zeroes). Thus, the ordering is .IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 . .SH "RETURN VALUE" -The \fBstrverscmp\fP() function returns an integer +The \fBstrverscmp\fP() function returns an integer less than, equal to, or greater than zero if \fIs1\fP is found, respectively, to be earlier than, equal to, or later than \fIs2\fP. diff --git a/man3/strxfrm.3 b/man3/strxfrm.3 index ba63964ec..7efadb874 100644 --- a/man3/strxfrm.3 +++ b/man3/strxfrm.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,14 +38,16 @@ strxfrm \- string transformation The \fBstrxfrm\fP() function transforms the \fIsrc\fP string into a form such that the result of \fBstrcmp\fP() on two strings that have been transformed with \fBstrxfrm\fP() is the same as the result of -\fBstrcoll\fP() on the two strings before their transformation. The -first \fIn\fP characters of the transformed string are placed in -\fIdest\fP. The transformation is based on the program's current +\fBstrcoll\fP() on the two strings before their transformation. +The first \fIn\fP characters of the transformed string are placed in +\fIdest\fP. +The transformation is based on the program's current locale for category \fILC_COLLATE\fP. (See \fBsetlocale\fP(3)). .SH "RETURN VALUE" The \fBstrxfrm\fP() function returns the number of bytes required to store the transformed string in \fIdest\fP excluding the terminating -`\\0' character. If the value returned is \fIn\fP or more, the +`\\0' character. +If the value returned is \fIn\fP or more, the contents of \fIdest\fP are indeterminate. .SH "CONFORMING TO" SVr4, 4.3BSD, C89, C99 diff --git a/man3/swab.3 b/man3/swab.3 index a3b5abfae..1f2b29784 100644 --- a/man3/swab.3 +++ b/man3/swab.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -39,7 +39,8 @@ swab \- swap adjacent bytes .SH DESCRIPTION The \fBswab\fP() function copies \fIn\fP bytes from the array pointed to by \fIfrom\fP to the array pointed to by \fIto\fP, exchanging -adjacent even and odd bytes. This function is used to exchange data +adjacent even and odd bytes. +This function is used to exchange data between machines that have different low/high byte ordering. .LP This function does nothing when \fIn\fP is negative. diff --git a/man3/sysconf.3 b/man3/sysconf.3 index 261274340..38fd96c0c 100644 --- a/man3/sysconf.3 +++ b/man3/sysconf.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -66,8 +66,10 @@ If it is defined to \-1, then the option is not supported. If it is defined to 0, then relevant functions and headers exist, but one has to ask at runtime what degree of support is available. If it is defined to a value other than \-1 or 0, then the option is -supported. Usually the value (such as 200112L) indicates the year and month -of the POSIX revision describing the option. Glibc uses the value 1 +supported. +Usually the value (such as 200112L) indicates the year and month +of the POSIX revision describing the option. +Glibc uses the value 1 to indicate support as long as the POSIX revision has not been published yet. .\" and 999 to indicate support for options no longer present in the latest .\" standard. (?) @@ -93,7 +95,7 @@ If an application wants to take advantage of values which may change between systems, a call to .BR sysconf () can be made. -The +The .BR sysconf () argument will be .BR _SC_FOO . @@ -133,7 +135,7 @@ The max number of simultaneous processes per user ID. Must not be less than _POSIX_CHILD_MAX (25). .TP .BR HOST_NAME_MAX " - " _SC_HOST_NAME_MAX -Max length of a hostname, not including the terminating null byte, +Max length of a hostname, not including the terminating null byte, as returned by .BR gethostname (2). Must not be less than _POSIX_HOST_NAME_MAX (255). @@ -144,7 +146,8 @@ Must not be less than _POSIX_LOGIN_NAME_MAX (9). .TP .BR "" "clock ticks - " _SC_CLK_TCK The number of clock ticks per second. -The corresponding variable is obsolete. It was of course called +The corresponding variable is obsolete. +It was of course called .BR CLK_TCK . (Note: the macro .B CLOCKS_PER_SEC @@ -155,7 +158,8 @@ The maximum number of files that a process can have open at any time. Must not be less than _POSIX_OPEN_MAX (20). .TP .BR PAGESIZE " - " _SC_PAGESIZE -Size of a page in bytes. Must not be less than 1. +Size of a page in bytes. +Must not be less than 1. (Some systems use PAGE_SIZE instead.) .TP .BR RE_DUP_MAX " - " _SC_RE_DUP_MAX @@ -167,16 +171,18 @@ Must not be less than _POSIX2_RE_DUP_MAX (255). .TP .BR STREAM_MAX " - " _SC_STREAM_MAX The maximum number of streams that a process can have open at any -time. If defined, it has the same value as the standard C macro +time. +If defined, it has the same value as the standard C macro .BR FOPEN_MAX . Must not be less than _POSIX_STREAM_MAX (8). .TP .BR SYMLOOP_MAX The maximum number of symbolic links seen in a pathname before resolution -returns ELOOP. Must not be less than _POSIX_SYMLOOP_MAX (8). +returns ELOOP. +Must not be less than _POSIX_SYMLOOP_MAX (8). .TP .BR TTY_NAME_MAX " - " _SC_TTY_NAME_MAX -The maximum length of terminal device name, +The maximum length of terminal device name, including the terminating null byte. Must not be less than _POSIX_TTY_NAME_MAX (9). .TP @@ -228,7 +234,8 @@ parentheses by .TP .BR LINE_MAX " - " _SC_LINE_MAX The maximum length of a utility's input line length, either from -standard input or from a file. This includes length for a trailing +standard input or from a file. +This includes length for a trailing newline. .TP .BR RE_DUP_MAX " - " _SC_RE_DUP_MAX @@ -264,7 +271,8 @@ supported. These values also exist, but may not be standard. .TP .BR "" " - " _SC_PHYS_PAGES -The number of pages of physical memory. Note that it is possible +The number of pages of physical memory. +Note that it is possible for the product of this value and the value of .B _SC_PAGE_SIZE to overflow. diff --git a/man3/syslog.3 b/man3/syslog.3 index 2b1b5a906..a2236bfe2 100644 --- a/man3/syslog.3 +++ b/man3/syslog.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,13 +50,14 @@ closelog, openlog, syslog \- send messages to the system logger .BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); .SH DESCRIPTION .BR closelog () -closes the descriptor being used to write to the system logger. The use of +closes the descriptor being used to write to the system logger. +The use of .BR closelog () is optional. .sp .BR openlog () -opens a connection to the system logger for a program. The string pointed -to by +opens a connection to the system logger for a program. +The string pointed to by .I ident is prepended to every message, and is typically set to the program name. The @@ -74,32 +75,34 @@ Values for .I option and .I facility -are given below. The use of +are given below. +The use of .BR openlog () is optional; it will automatically be called by .BR syslog () -if necessary, in which case +if necessary, in which case .I ident will default to NULL. .sp .BR syslog () -generates a log message, which will be distributed by +generates a log message, which will be distributed by .BR syslogd (8). The .I priority argument is formed by ORing the .I facility -and the +and the .I level -values (explained below). The remaining arguments -are a +values (explained below). +The remaining arguments +are a .IR format , -as in +as in .BR printf (3) -and any arguments required by the -.IR format , +and any arguments required by the +.IR format , except that the two character sequence %m will be replaced by -the error message string +the error message string .IR strerror ( errno ). A trailing newline may be added if needed. @@ -112,12 +115,12 @@ been obtained using the .BR stdarg (3) variable argument list macros. .SH PARAMETERS -This section lists the parameters used to set the values of +This section lists the parameters used to set the values of .IR option , " facility" ", and " priority . .SS option The .I option -argument to +argument to .BR openlog () is an OR of any of these: .TP @@ -131,7 +134,8 @@ the first message is logged). .TP .B LOG_NOWAIT Don't wait for child processes that may have been created while logging -the message. (The GNU C library does not create a child process, so this +the message. +(The GNU C library does not create a child process, so this option has no effect on Linux.) .TP .B LOG_ODELAY @@ -139,30 +143,32 @@ The converse of .BR LOG_NDELAY ; opening of the connection is delayed until .BR syslog () -is called. (This is the default, and need not be specified.) +is called. +(This is the default, and need not be specified.) .TP .B LOG_PERROR -(Not in POSIX.1-2001.) Print to stderr as well. +(Not in POSIX.1-2001.) +Print to \fIstderr\fP as well. .TP .B LOG_PID Include PID with each message. -.SS facility -The +.SS facility +The .I facility argument is used to specify what type of program is logging the message. This lets the configuration file specify that messages from different facilities will be handled differently. .TP .B LOG_AUTH -security/authorization messages (DEPRECATED Use -.B LOG_AUTHPRIV +security/authorization messages (DEPRECATED Use +.B LOG_AUTHPRIV instead) .TP .B LOG_AUTHPRIV -security/authorization messages (private) +security/authorization messages (private) .TP .B LOG_CRON -clock daemon +clock daemon .RB ( cron " and " at ) .TP .B LOG_DAEMON @@ -188,16 +194,16 @@ USENET news subsystem .TP .B LOG_SYSLOG messages generated internally by -.B syslogd +.B syslogd .TP .BR LOG_USER " (default)" -generic user-level messages +generic user-level messages .TP .B LOG_UUCP UUCP subsystem .SS level -This determines the importance of the message. The levels are, in order -of decreasing importance: +This determines the importance of the message. +The levels are, in order of decreasing importance: .TP .B LOG_EMERG system is unusable @@ -242,7 +248,7 @@ and values for .IR facility . However, with the exception of -.BR LOG_AUTHPRIV +.BR LOG_AUTHPRIV and .BR LOG_FTP , the other @@ -275,7 +281,8 @@ The parameter .I ident in the call of .BR openlog () -is probably stored as-is. Thus, if the string it points to +is probably stored as-is. +Thus, if the string it points to is changed, .BR syslog () may start prepending the changed string, and if the string diff --git a/man3/system.3 b/man3/system.3 index c26b89e8a..87deca388 100644 --- a/man3/system.3 +++ b/man3/system.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -50,7 +50,7 @@ and .B SIGQUIT will be ignored. .SH "RETURN VALUE" -The value returned is \-1 on error (e.g. +The value returned is \-1 on error (e.g. .BR fork () failed), and the return status of the command otherwise. @@ -83,13 +83,14 @@ feature test macro is defined, then the macros described in .BR wait (2) .RB ( WEXITSTATUS (), etc.) are made available when including -.IR . +.IR . .PP As mentioned, .BR system () ignores SIGINT and SIGQUIT. This may make programs that call it from a loop uninterruptible, unless they take care themselves -to check the exit status of the child. E.g. +to check the exit status of the child. +E.g. .br .nf @@ -114,7 +115,7 @@ family of functions instead, but not or .BR execvp (3). .BR system () -will not, in fact, work properly from programs with set-user-ID or +will not, in fact, work properly from programs with set-user-ID or set-group-ID privileges on systems on which .I /bin/sh is bash version 2, since bash 2 drops privileges on startup. diff --git a/man3/tan.3 b/man3/tan.3 index 2dd183722..590f52e3d 100644 --- a/man3/tan.3 +++ b/man3/tan.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -48,7 +48,7 @@ The \fBtan\fP() function returns the tangent of \fIx\fP, where \fIx\fP is given in radians. .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/tanh.3 b/man3/tanh.3 index 2c65bcd76..ff23e1a90 100644 --- a/man3/tanh.3 +++ b/man3/tanh.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -44,11 +44,11 @@ tanh, tanhf, tanhl \- hyperbolic tangent function .sp Link with \-lm. .SH DESCRIPTION -The \fBtanh\fP() function returns the hyperbolic tangent of \fIx\fP, which +The \fBtanh\fP() function returns the hyperbolic tangent of \fIx\fP, which is defined mathematically as sinh(x) / cosh(x). .SH "CONFORMING TO" SVr4, 4.3BSD, C89. -The +The .I float and .I "long double" diff --git a/man3/tcgetpgrp.3 b/man3/tcgetpgrp.3 index 2e843b5c3..fa3cc058a 100644 --- a/man3/tcgetpgrp.3 +++ b/man3/tcgetpgrp.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/tcgetsid.3 b/man3/tcgetsid.3 index 89e6a82ad..1b4b2efe1 100644 --- a/man3/tcgetsid.3 +++ b/man3/tcgetsid.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -57,8 +57,8 @@ The calling process does not have a controlling terminal, or it has one but it is not described by .IR fd . .SH NOTES -This function is implemented via the TIOCGSID -.BR ioctl (), +This function is implemented via the TIOCGSID +.BR ioctl (), present since Linux 2.1.71. .SH "CONFORMING TO" diff --git a/man3/telldir.3 b/man3/telldir.3 index 126144abe..c12747cff 100644 --- a/man3/telldir.3 +++ b/man3/telldir.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/tempnam.3 b/man3/tempnam.3 index e26880b15..d4ff556b5 100644 --- a/man3/tempnam.3 +++ b/man3/tempnam.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -45,7 +45,7 @@ The directory prefix part of the pathname generated is required to be `appropriate' (often that at least implies writable). Attempts to find an appropriate directory go through the following -steps: +steps: .TP a) In case the environment variable TMPDIR exists and @@ -65,7 +65,7 @@ is used when appropriate. .TP d) Finally an implementation-defined directory may be used. -.PP +.PP The string returned by .BR tempnam () is allocated using @@ -75,27 +75,28 @@ and hence should be freed by .SH "RETURN VALUE" The .BR tempnam () -function returns a pointer to a unique temporary +function returns a pointer to a unique temporary filename, or NULL if a unique name cannot be generated. .SH ERRORS .TP .B ENOMEM Allocation of storage failed. .SH NOTES -Although +Although .BR tempnam (3) generates names that are difficult to guess, it is nevertheless possible that between the time that .BR tempnam (3) returns a pathname, and the time that the program opens it, another program might create that pathname using -.BR open (2), +.BR open (2), or create it as a symbolic link. This can lead to security holes. -To avoid such possibilities, use the +To avoid such possibilities, use the .BR open (2) .B O_EXCL -flag to open the pathname. Or better yet, use +flag to open the pathname. +Or better yet, use .BR mkstemp (3) or .BR tmpfile (3). @@ -103,7 +104,7 @@ or SUSv2 does not mention the use of TMPDIR; glibc will use it only when the program is not set-user-ID. On SVr4, the directory used under \fBd)\fP is -.IR /tmp +.IR /tmp (and this is what glibc does). .LP Because it dynamically allocates memory used to return the pathname, @@ -116,7 +117,8 @@ The function generates a different string each time it is called, up to TMP_MAX (defined in .IR ) -times. If it is called more than TMP_MAX times, +times. +If it is called more than TMP_MAX times, the behaviour is implementation defined. .LP .BR tempnam () @@ -125,14 +127,15 @@ uses at most the first five bytes from The glibc implementation of .BR tempnam () -will fail with the error +will fail with the error .B EEXIST upon failure to find a unique name. .SH BUGS The precise meaning of `appropriate' is undefined; it is unspecified how accessibility of a directory is determined. -Never use this function. Use +Never use this function. +Use .BR mkstemp (3) or .BR tmpfile (3) diff --git a/man3/termios.3 b/man3/termios.3 index 6a5204cc5..8ed19a2b3 100644 --- a/man3/termios.3 +++ b/man3/termios.3 @@ -79,8 +79,8 @@ provided to control asynchronous communications ports. .SS "The termios structure" .LP Many of the functions described here have a \fItermios_p\fP argument -that is a pointer to a \fItermios\fP structure. This structure contains -at least the following members: +that is a pointer to a \fItermios\fP structure. +This structure contains at least the following members: .ne 9 .sp .RS @@ -94,15 +94,15 @@ cc_t \fIc_cc\fP[\fBNCCS\fP]; /* control chars */ .RE .PP The values that may be assigned to these fields are described below. -In the case of the first four bit-mask fields, -the definitions of some of the associated flags that may be set are +In the case of the first four bit-mask fields, +the definitions of some of the associated flags that may be set are only exposed if a specific feature test macro (see .BR feature_test_macros (7)) is defined, as noted in brackets ("[]"). .PP In the descriptions below, "not in POSIX" means that the -value is not specified in POSIX.1-2001, -and "XSI" means that the value is specified in POSIX.1-2001 +value is not specified in POSIX.1-2001, +and "XSI" means that the value is specified in POSIX.1-2001 as part of the XSI extension. .PP \fIc_iflag\fP flag constants: @@ -111,7 +111,8 @@ as part of the XSI extension. Ignore BREAK condition on input. .TP .B BRKINT -If \fBIGNBRK\fP is set, a BREAK is ignored. If it is not set +If \fBIGNBRK\fP is set, a BREAK is ignored. +If it is not set but \fBBRKINT\fP is set, then a BREAK causes the input and output queues to be flushed, and if the terminal is the controlling terminal of a foreground process group, it will cause a @@ -124,8 +125,9 @@ in which case it reads as the sequence \\377 \\0 \\0. Ignore framing errors and parity errors. .TP .B PARMRK -If \fBIGNPAR\fP is not set, prefix a character with a parity error or -framing error with \\377 \\0. If neither \fBIGNPAR\fP nor \fBPARMRK\fP +If \fBIGNPAR\fP is not set, prefix a character with a parity error or +framing error with \\377 \\0. +If neither \fBIGNPAR\fP nor \fBPARMRK\fP is set, read a character with a parity error or framing error as \\0. .TP @@ -151,7 +153,7 @@ Translate carriage return to newline on input (unless \fBIGNCR\fP is set). Enable XON/XOFF flow control on output. .TP .B IXANY -(XSI) Typing any character will restart stopped output. +(XSI) Typing any character will restart stopped output. (The default is to allow just the START character to restart output.) .TP .B IXOFF @@ -162,7 +164,7 @@ Enable XON/XOFF flow control on input. Linux does not implement this bit, and acts as if it is always set. .TP .BR IUTF8 " (since Linux 2.6.4)" -(not in POSIX) Input is UTF8; +(not in POSIX) Input is UTF8; this allows character-erase to be correctly performed in cooked mode. .PP \fIc_oflag\fP flag constants defined in POSIX.1: @@ -197,7 +199,8 @@ If unset, fill character is ASCII NUL ('\\0'). (Not implemented on Linux.) .TP .B NLDLY -Newline delay mask. Values are \fBNL0\fP and \fBNL1\fP. +Newline delay mask. +Values are \fBNL0\fP and \fBNL1\fP. [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE] .TP .B CRDLY @@ -213,15 +216,18 @@ A value of TAB3, that is, XTABS, expands tabs to spaces [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE] .TP .B BSDLY -Backspace delay mask. Values are \fBBS0\fP or \fBBS1\fP. +Backspace delay mask. +Values are \fBBS0\fP or \fBBS1\fP. (Has never been implemented.) [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE] .TP .B VTDLY -Vertical tab delay mask. Values are \fBVT0\fP or \fBVT1\fP. +Vertical tab delay mask. +Values are \fBVT0\fP or \fBVT1\fP. .TP .B FFDLY -Form feed delay mask. Values are \fBFF0\fP or \fBFF1\fP. +Form feed delay mask. +Values are \fBFF0\fP or \fBFF1\fP. [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE] .PP \fIc_cflag\fP flag constants: @@ -234,13 +240,14 @@ Form feed delay mask. Values are \fBFF0\fP or \fBFF1\fP. (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD. [requires _BSD_SOURCE or _SVID_SOURCE] .sp -(POSIX says that the baud speed is stored in the -.I termios +(POSIX says that the baud speed is stored in the +.I termios structure without specifying where precisely, and provides .BR cfgetispeed () and .BR cfsetispeed () -for getting at it. Some systems use bits selected by CBAUD in +for getting at it. +Some systems use bits selected by CBAUD in .IR c_cflag , other systems use separate fields, e.g. .I sg_ispeed @@ -261,7 +268,7 @@ Enable receiver. Enable parity generation on output and parity checking for input. .TP .B PARODD -If set, then parity for input and output is odd; +If set, then parity for input and output is odd; otherwise even parity is used. .TP .B HUPCL @@ -277,17 +284,17 @@ For use by \fBshl\fP (shell layers). (Not implemented on Linux.) .B CIBAUD (not in POSIX) Mask for input speeds. The values for the CIBAUD bits are -the same as the values for the CBAUD bits, shifted left IBSHIFT bits. +the same as the values for the CBAUD bits, shifted left IBSHIFT bits. [requires _BSD_SOURCE or _SVID_SOURCE] (Not implemented on Linux.) .TP .B CMSPAR (not in POSIX) -Use "stick" (mark/space) parity (supported on certain serial +Use "stick" (mark/space) parity (supported on certain serial devices): if -.B PARODD +.B PARODD is set, the parity bit is always 1; if -.B PARODD +.B PARODD is not set, then the parity bit is always 0). [requires _BSD_SOURCE or _SVID_SOURCE] .TP @@ -302,7 +309,7 @@ When any of the characters INTR, QUIT, SUSP, or DSUSP are received, generate the corresponding signal. .TP .B ICANON -Enable canonical mode (described below). +Enable canonical mode (described below). .TP .B XCASE (not in POSIX; not supported under Linux) @@ -329,7 +336,8 @@ If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. .B ECHOCTL (not in POSIX) If \fBECHO\fP is also set, ASCII control signals other than TAB, NL, START, and STOP are echoed as ^X, where X is the character with -ASCII code 0x40 greater than the control signal. For example, character +ASCII code 0x40 greater than the control signal. +For example, character 0x08 (BS) is echoed as ^H. [requires _BSD_SOURCE or _SVID_SOURCE] .TP @@ -349,7 +357,8 @@ each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. .TP .B FLUSHO (not in POSIX; not supported under Linux) -Output is being flushed. This flag is toggled by typing +Output is being flushed. +This flag is toggled by typing the DISCARD character. [requires _BSD_SOURCE or _SVID_SOURCE] .TP @@ -365,7 +374,8 @@ which tries to write to its controlling terminal. .B PENDIN (not in POSIX; not supported under Linux) All characters in the input queue are reprinted when -the next character is read. (\fBbash\fP handles typeahead this way.) +the next character is read. +(\fBbash\fP handles typeahead this way.) [requires _BSD_SOURCE or _SVID_SOURCE] .TP .B IEXTEN @@ -379,23 +389,26 @@ The symbolic indices (initial values) and meaning are: .TP .B VINTR (003, ETX, Ctrl-C, or also 0177, DEL, rubout) -Interrupt character. Send a SIGINT signal. +Interrupt character. +Send a SIGINT signal. Recognized when ISIG is set, and then not passed as input. .TP .B VQUIT (034, FS, Ctrl-\e) -Quit character. Send SIGQUIT signal. +Quit character. +Send SIGQUIT signal. Recognized when ISIG is set, and then not passed as input. .TP .B VERASE (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) -Erase character. This erases the previous not-yet-erased character, +Erase character. +This erases the previous not-yet-erased character, but does not erase past EOF or beginning-of-line. Recognized when ICANON is set, and then not passed as input. .TP .B VKILL (025, NAK, Ctrl-U, or Ctrl-X, or also @) -Kill character. +Kill character. This erases the input since the last EOF or beginning-of-line. Recognized when ICANON is set, and then not passed as input. .TP @@ -426,21 +439,25 @@ Recognized when ICANON is set. .TP .B VSWTCH (not in POSIX; not supported under Linux; 0, NUL) -Switch character. (Used by \fBshl\fP only.) +Switch character. +(Used by \fBshl\fP only.) .TP .B VSTART (021, DC1, Ctrl-Q) -Start character. Restarts output stopped by the Stop character. +Start character. +Restarts output stopped by the Stop character. Recognized when IXON is set, and then not passed as input. .TP .B VSTOP (023, DC3, Ctrl-S) -Stop character. Stop output until Start character typed. +Stop character. +Stop output until Start character typed. Recognized when IXON is set, and then not passed as input. .TP .B VSUSP (032, SUB, Ctrl-Z) -Suspend character. Send SIGTSTP signal. +Suspend character. +Send SIGTSTP signal. Recognized when ISIG is set, and then not passed as input. .TP .B VDSUSP @@ -452,7 +469,8 @@ job control, and then not passed as input. .TP .B VLNEXT (not in POSIX; 026, SYN, Ctrl-V) -Literal next. Quotes the next input character, depriving it of +Literal next. +Quotes the next input character, depriving it of a possible special meaning. Recognized when IEXTEN is set, and then not passed as input. .TP @@ -478,29 +496,31 @@ status request: 024, DC4, Ctrl-T). These symbolic subscript values are all different, except that VTIME, VMIN may have the same value as VEOL, VEOF, respectively. In non-canonical mode the special character meaning is replaced -by the timeout meaning. -For an explanation of VMIN and VTIME, see the description of +by the timeout meaning. +For an explanation of VMIN and VTIME, see the description of non-canonical mode below. .SS "Retrieving and changing terminal settings" .PP .BR tcgetattr () gets the parameters associated with the object referred by \fIfd\fP and stores them in the \fItermios\fP structure referenced by -\fItermios_p\fP. This function may be invoked from a background process; +\fItermios_p\fP. +This function may be invoked from a background process; however, the terminal attributes may be subsequently changed by a foreground process. .LP .BR tcsetattr () sets the parameters associated with the terminal (unless support is required from the underlying hardware that is not available) from the -\fItermios\fP structure referred to by \fItermios_p\fP. +\fItermios\fP structure referred to by \fItermios_p\fP. \fIoptional_actions\fP specifies when the changes take effect: .IP \fBTCSANOW\fP the change occurs immediately. .IP \fBTCSADRAIN\fP the change occurs after all output written to .I fd -has been transmitted. This function should be used when changing +has been transmitted. +This function should be used when changing parameters that affect output. .IP \fBTCSAFLUSH\fP the change occurs after all output written to the object referred by @@ -516,7 +536,7 @@ determines whether the terminal is operating in canonical mode .RB ( ICANON set) or non-canonical mode -.RB ( ICANON +.RB ( ICANON unset). By default, .B ICANON @@ -531,11 +551,11 @@ Except in the case of EOF, the line delimiter is included in the buffer returned by .BR read (2). .IP * 2 -Line editing is enabled (ERASE, KILL; -and if the +Line editing is enabled (ERASE, KILL; +and if the .B IEXTEN flag is set: WERASE, REPRINT, LNEXT). -A +A .BR read () returns at most one line of input; if the .BR read () @@ -544,10 +564,10 @@ then only as many bytes as requested are read, and the remaining characters will be available for a future .BR read (). .PP -In non-canonical mode input is available immediately (without +In non-canonical mode input is available immediately (without the user having to type a line-delimiter character), and line editing is disabled. -The settings of MIN +The settings of MIN .RI ( c_cc[VMIN] ) and .RI ( c_cc[VTIME] ) @@ -571,8 +591,8 @@ are available, and returns the lesser of these two values. .IP * 2 MIN == 0; TIME > 0: TIME specifies the limit for a timer in tenths of a second. -The timer is started when -.BR read () +The timer is started when +.BR read () is called. .BR read () returns either when at least one byte of data is available, @@ -586,17 +606,17 @@ TIME specifies the limit for a timer in tenths of a second. Once an initial byte of input becomes available, the timer is restarted after each further byte is received. .BR read () -returns either when the lesser of the number of bytes requested or +returns either when the lesser of the number of bytes requested or MIN byte have been read, or when the inter-byte timeout expires. -Because the timer is only started after the initial byte +Because the timer is only started after the initial byte becomes available, at least one byte will be read. .SS "Raw mode" .LP -\fBcfmakeraw\fP() sets the terminal to something like the +\fBcfmakeraw\fP() sets the terminal to something like the "raw" mode of the old Version 7 terminal driver: input is available character by character, -echoing is disabled, and all special processing of +echoing is disabled, and all special processing of terminal input and output characters is disabled. The terminal attributes are set as follows: .nf @@ -613,9 +633,10 @@ The terminal attributes are set as follows: .BR tcsendbreak () transmits a continuous stream of zero-valued bits for a specific duration, if the terminal is using asynchronous serial data -transmission. If \fIduration\fP is zero, it transmits zero-valued bits -for at least 0.25 seconds, and not more that 0.5 seconds. If -\fIduration\fP is not zero, it sends zero-valued bits for some +transmission. +If \fIduration\fP is zero, it transmits zero-valued bits +for at least 0.25 seconds, and not more that 0.5 seconds. +If \fIduration\fP is not zero, it sends zero-valued bits for some implementation-defined length of time. .LP If the terminal is not using asynchronous serial data transmission, @@ -650,18 +671,18 @@ suspends output. .IP \fBTCOON\fP restarts suspended output. .IP \fBTCIOFF\fP -transmits a STOP character, which stops the terminal device from +transmits a STOP character, which stops the terminal device from transmitting data to the system. .IP \fBTCION\fP -transmits a START character, which starts the terminal device +transmits a START character, which starts the terminal device transmitting data to the system. .LP The default on open of a terminal file is that neither its input nor its output is suspended. .SS "Line speed" The baud rate functions are provided for getting and setting the values -of the input and output baud rates in the \fItermios\fP structure. The -new values do not take effect +of the input and output baud rates in the \fItermios\fP structure. +The new values do not take effect until \fBtcsetattr\fP() is successfully called. Setting the speed to \fBB0\fP instructs the modem to "hang up". @@ -705,9 +726,9 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: .fi The zero baud rate, \fBB0\fP, -is used to terminate the connection. If B0 -is specified, the modem control lines shall no longer be asserted. -Normally, this will disconnect the line. \fBCBAUDEX\fP is a mask +is used to terminate the connection. +If B0 is specified, the modem control lines shall no longer be asserted. +Normally, this will disconnect the line. \fBCBAUDEX\fP is a mask for the speeds beyond those defined in POSIX.1 (57600 and above). Thus, \fBB57600\fP & \fBCBAUDEX\fP is non-zero. .LP @@ -716,15 +737,15 @@ returns the input baud rate stored in the \fItermios\fP structure. .LP .BR cfsetispeed () sets the input baud rate stored in the \fItermios\fP structure to -.IR speed , +.IR speed , which must be specified as one of the \fBBnnn\fP constants listed above for .BR cfsetospeed (). If the input baud rate is set to zero, the input baud rate will be equal to the output baud rate. .LP .BR cfsetspeed () -is a 4.4BSD extension. -It takes the same arguments as +is a 4.4BSD extension. +It takes the same arguments as .BR cfsetispeed (), and sets both input and output speed. .SH "RETURN VALUE" @@ -748,7 +769,8 @@ to indicate the error. Note that .BR tcsetattr () returns success if \fIany\fP of the requested changes could be -successfully carried out. Therefore, when making multiple changes +successfully carried out. +Therefore, when making multiple changes it may be necessary to follow this call with a further call to .BR tcgetattr () to check that all changes have been performed successfully. @@ -759,7 +781,7 @@ two constants EXTA, EXTB ("External A" and "External B"). Many systems extend the list with much higher baud rates. .LP The effect of a non-zero \fIduration\fP with \fBtcsendbreak\fP() varies. -SunOS specifies a break of +SunOS specifies a break of .IB duration * N seconds, where \fIN\fP is at least 0.25, and not more than 0.5. Linux, AIX, DU, Tru64 send a break of diff --git a/man3/tgamma.3 b/man3/tgamma.3 index b0bcb0bd4..a7ff222c9 100644 --- a/man3/tgamma.3 +++ b/man3/tgamma.3 @@ -36,7 +36,8 @@ outside the poles: Gamma(x) * Gamma(1\-x) = PI/sin(PI*x) .PP This function returns the value of the Gamma function for the -argument \fIx\fP. It had to be called "true gamma function" +argument \fIx\fP. +It had to be called "true gamma function" since there is already a function .BR gamma () that returns something else. @@ -45,7 +46,8 @@ In order to check for errors, set .I errno to zero and call .I feclearexcept(FE_ALL_EXCEPT) -before calling these functions. On return, if +before calling these functions. +On return, if .I errno is non-zero or .I fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) diff --git a/man3/timegm.3 b/man3/timegm.3 index 4cdbb7029..a0c596cab 100644 --- a/man3/timegm.3 +++ b/man3/timegm.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -62,8 +62,8 @@ Something like #include #include -time_t -my_timegm(struct tm *tm) +time_t +my_timegm(struct tm *tm) { time_t ret; char *tz; diff --git a/man3/tmpfile.3 b/man3/tmpfile.3 index 769a26f60..ec2ebf5a9 100644 --- a/man3/tmpfile.3 +++ b/man3/tmpfile.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,9 +43,10 @@ program terminates. .SH "RETURN VALUE" The \fBtmpfile\fP() function returns a stream descriptor, or NULL if a unique filename cannot be generated or the unique file cannot be -opened. In the latter case, \fIerrno\fP is set to indicate the error. +opened. +In the latter case, \fIerrno\fP is set to indicate the error. .SH ERRORS -.TP +.TP .B EACCES Search permission denied for directory in file's path prefix. .TP @@ -73,7 +74,8 @@ An error message may be written to \fIstdout\fP if the stream cannot be opened. .LP The standard does not specify the directory that \fItmpfile\fP() -will use. Glibc will try the path prefix \fIP_tmpdir\fP defined +will use. +Glibc will try the path prefix \fIP_tmpdir\fP defined in \fI\fP, and if that fails the directory \fI/tmp\fP. .SH "SEE ALSO" .BR exit (3), diff --git a/man3/tmpnam.3 b/man3/tmpnam.3 index 597562501..46e023420 100644 --- a/man3/tmpnam.3 +++ b/man3/tmpnam.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,7 +37,8 @@ The function returns a pointer to a string that is a valid filename, and such that a file with this name did not exist at some point in time, so that naive programmers may think it -a suitable name for a temporary file. If the argument +a suitable name for a temporary file. +If the argument .I s is NULL this name is generated in an internal static buffer and may be overwritten by the next call to @@ -65,7 +66,7 @@ just like the TMP_MAX mentioned below.) .SH "RETURN VALUE" The .BR tmpnam () -function returns a pointer to a unique temporary +function returns a pointer to a unique temporary filename, or NULL if a unique name cannot be generated. .SH ERRORS No errors are defined. @@ -73,23 +74,25 @@ No errors are defined. The .BR tmpnam () function generates a different string each time it is called, -up to TMP_MAX times. If it is called more than TMP_MAX times, +up to TMP_MAX times. +If it is called more than TMP_MAX times, the behaviour is implementation defined. .LP -Although +Although .BR tmpnam (3) generates names that are difficult to guess, it is nevertheless possible that between the time that .BR tmpnam (3) returns a pathname, and the time that the program opens it, another program might create that pathname using -.BR open (2), +.BR open (2), or create it as a symbolic link. This can lead to security holes. -To avoid such possibilities, use the +To avoid such possibilities, use the .BR open (2) .B O_EXCL -flag to open the pathname. Or better yet, use +flag to open the pathname. +Or better yet, use .BR mkstemp (3) or .BR tmpfile (3). @@ -114,12 +117,13 @@ tmpnam_r(char *s) .fi .sp apparently as a warning not to use NULL. -A few systems implement it. +A few systems implement it. To get a glibc prototype for this function, define _SVID_SOURCE or _BSD_SOURCE before including .IR "" . .SH BUGS -Never use this function. Use +Never use this function. +Use .BR mkstemp (3) or .BR tmpfile (3) diff --git a/man3/toascii.3 b/man3/toascii.3 index dff031bac..9e447dde9 100644 --- a/man3/toascii.3 +++ b/man3/toascii.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. diff --git a/man3/toupper.3 b/man3/toupper.3 index 498a46ea8..49b5d646f 100644 --- a/man3/toupper.3 +++ b/man3/toupper.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -56,7 +56,8 @@ if the conversion was not possible. C89, C99, 4.3BSD .SH BUGS The details of what constitutes an uppercase or lowercase letter depend -on the current locale. For example, the default +on the current locale. +For example, the default .B """C""" locale does not know about umlauts, so no conversion is done for them. .PP diff --git a/man3/towlower.3 b/man3/towlower.3 index b96223e99..67f6f4f25 100644 --- a/man3/towlower.3 +++ b/man3/towlower.3 @@ -22,8 +22,10 @@ towlower \- convert a wide character to lowercase .fi .SH DESCRIPTION The \fBtowlower\fP() function is the wide-character equivalent of the -\fBtolower\fP() function. If \fIwc\fP is a wide character, it is converted to -lowercase. Characters which do not have case are returned unchanged. +\fBtolower\fP() function. +If \fIwc\fP is a wide character, it is converted to +lowercase. +Characters which do not have case are returned unchanged. If \fIwc\fP is WEOF, WEOF is returned. .SH "RETURN VALUE" The \fBtowlower\fP() function returns the lowercase equivalent of \fIwc\fP, diff --git a/man3/towupper.3 b/man3/towupper.3 index 85eec96f8..6d0680c86 100644 --- a/man3/towupper.3 +++ b/man3/towupper.3 @@ -22,8 +22,10 @@ towupper \- convert a wide character to uppercase .fi .SH DESCRIPTION The \fBtowupper\fP() function is the wide-character equivalent of the -\fBtoupper\fP() function. If \fIwc\fP is a wide character, it is converted to -uppercase. Characters which do not have case are returned unchanged. +\fBtoupper\fP() function. +If \fIwc\fP is a wide character, it is converted to +uppercase. +Characters which do not have case are returned unchanged. If \fIwc\fP is WEOF, WEOF is returned. .SH "RETURN VALUE" The \fBtowupper\fP() function returns the uppercase equivalent of \fIwc\fP, diff --git a/man3/trunc.3 b/man3/trunc.3 index c1fe1b0d1..e9ff9fa86 100644 --- a/man3/trunc.3 +++ b/man3/trunc.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/tsearch.3 b/man3/tsearch.3 index d5323fbfd..ba9555815 100644 --- a/man3/tsearch.3 +++ b/man3/tsearch.3 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -50,73 +50,82 @@ tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary tree .fi .SH DESCRIPTION \fBtsearch\fP(), \fBtfind\fP(), \fBtwalk\fP(), and \fBtdelete\fP() manage a -binary tree. They are generalized from Knuth (6.2.2) Algorithm T. +binary tree. +They are generalized from Knuth (6.2.2) Algorithm T. The first field in each node of the tree is a pointer to the -corresponding data item. (The calling program must store the actual -data.) \fIcompar\fP points to a comparison routine, which takes -pointers to two items. It should return an integer which is negative, +corresponding data item. +(The calling program must store the actual data.) +\fIcompar\fP points to a comparison routine, which takes +pointers to two items. +It should return an integer which is negative, zero, or positive, depending on whether the first item is less than, equal to, or greater than the second. .PP -\fBtsearch\fP() searches the tree for an item. \fIkey\fP -points to the item to be searched for. \fIrootp\fP points to a -variable which points to the root of the tree. If the tree is empty, +\fBtsearch\fP() searches the tree for an item. +\fIkey\fP points to the item to be searched for. +\fIrootp\fP points to a variable which points to the root of the tree. +If the tree is empty, then the variable that \fIrootp\fP points to should be set to NULL. If the item is found in the tree, then \fBtsearch\fP() returns a pointer -to it. If it is not found, then \fBtsearch\fP() adds it, and returns a +to it. +If it is not found, then \fBtsearch\fP() adds it, and returns a pointer to the newly added item. .PP \fBtfind\fP() is like \fBtsearch\fP(), except that if the item is not found, then \fBtfind\fP() returns NULL. .PP -\fBtdelete\fP() deletes an item from the tree. Its arguments are the -same as for \fBtsearch\fP(). +\fBtdelete\fP() deletes an item from the tree. +Its arguments are the same as for \fBtsearch\fP(). .PP \fBtwalk\fP() performs depth-first, left-to-right traversal of a binary -tree. \fIroot\fP points to the starting node for the traversal. If -that node is not the root, then only part of the tree will be visited. +tree. \fIroot\fP points to the starting node for the traversal. +If that node is not the root, then only part of the tree will be visited. \fBtwalk\fP() calls the user function \fIaction\fP each time a node is visited (that is, three times for an internal node, and once for a -leaf). \fIaction\fP, in turn, takes three arguments. The first is a -pointer to the node being visited. The second is an integer which +leaf). \fIaction\fP, in turn, takes three arguments. +The first is a pointer to the node being visited. +The second is an integer which takes on the values \fBpreorder\fP, \fBpostorder\fP, and \fBendorder\fP depending on whether this is the first, second, or third visit to the internal node, or \fBleaf\fP if it is the single -visit to a leaf node. (These symbols are defined in -\fI\fP.) The third argument is the depth of the node, with +visit to a leaf node. +(These symbols are defined in \fI\fP.) +The third argument is the depth of the node, with zero being the root. .PP (More commonly, \fBpreorder\fP, \fBpostorder\fP, and \fBendorder\fP are known as \fBpreorder\fP, \fBinorder\fP, and \fBpostorder\fP: before visiting the children, after the first and before the second, -and after visiting the children. Thus, the choice of name \fBpost\%order\fP +and after visiting the children. +Thus, the choice of name \fBpost\%order\fP is rather confusing.) .PP \fBtdestroy\fP() removes the whole tree pointed to by \fIroot\fP, -freeing all resources allocated by the \fBtsearch\fP() function. For -the data in each tree node the function \fIfree_node\fP is called. -The pointer to the data is passed as the argument to the function. If -no such work is necessary \fIfree_node\fP must point to a function +freeing all resources allocated by the \fBtsearch\fP() function. +For the data in each tree node the function \fIfree_node\fP is called. +The pointer to the data is passed as the argument to the function. +If no such work is necessary \fIfree_node\fP must point to a function doing nothing. .SH "RETURN VALUE" \fBtsearch\fP() returns a pointer to a matching item in the tree, or to the newly added item, or NULL if there was insufficient memory to add the item. \fBtfind\fP() returns a pointer to the item, or -NULL if no match is found. If there -are multiple elements that match the key, the element returned is -unspecified. +NULL if no match is found. +If there are multiple elements that match the key, +the element returned is unspecified. .PP \fBtdelete\fP() returns a pointer to the parent of the item deleted, or NULL if the item was not found. .PP \fBtsearch\fP(), \fBtfind\fP(), and \fBtdelete\fP() also -return NULL if \fIrootp\fP was NULL on entry. +return NULL if \fIrootp\fP was NULL on entry. .SH WARNINGS \fBtwalk\fP() takes a pointer to the root, while the other functions take a pointer to a variable which points to the root. .PP \fBtwalk\fP() uses \fBpostorder\fP to mean "after the left subtree, but -before the right subtree". Some authorities would call this +before the right subtree". +Some authorities would call this "inorder", and reserve "postorder" to mean "after both subtrees". .PP \fBtdelete\fP() frees the memory required for the node in the tree. @@ -125,8 +134,9 @@ data. .PP The example program depends on the fact that \fBtwalk\fP() makes no further reference to a node after calling the user function with -argument "endorder" or "leaf". This works with the GNU library -implementation, but is not in the SysV documentation. +argument "endorder" or "leaf". +This works with the GNU library +implementation, but is not in the SysV documentation. .SH EXAMPLE The following program inserts twelve random numbers into a binary tree, where duplicate numbers are collapsed, then prints the numbers @@ -137,35 +147,35 @@ in order. #include #include #include - + void *root = NULL; - + void * -xmalloc(unsigned n) +xmalloc(unsigned n) { void *p; p = malloc(n); - if (p) + if (p) return p; fprintf(stderr, "insufficient memory\\n"); exit(1); } - -int -compare(const void *pa, const void *pb) + +int +compare(const void *pa, const void *pb) { - if (*(int *) pa < *(int *) pb) + if (*(int *) pa < *(int *) pb) return \-1; if (*(int *) pa > *(int *) pb) return 1; return 0; } - -void -action(const void *nodep, const VISIT which, const int depth) + +void +action(const void *nodep, const VISIT which, const int depth) { int *datap; - + switch(which) { case preorder: break; @@ -181,19 +191,19 @@ action(const void *nodep, const VISIT which, const int depth) break; } } - -int -main(void) + +int +main(void) { int i, *ptr; void *val; - srand(time(NULL)); + srand(time(NULL)); for (i = 0; i < 12; i++) { ptr = (int *) xmalloc(sizeof(int)); *ptr = rand() & 0xff; val = tsearch((void *) ptr, &root, compare); - if (val == NULL) + if (val == NULL) exit(1); } twalk(root, action); diff --git a/man3/ttyname.3 b/man3/ttyname.3 index 064ca9b7f..6fd18e555 100644 --- a/man3/ttyname.3 +++ b/man3/ttyname.3 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified 2001-12-13, Martin Schulze .\" Added ttyname_r, aeb, 2002-07-20 .\" @@ -51,7 +51,7 @@ of length .SH "RETURN VALUE" The function .BR ttyname () -returns a pointer to a pathname on success. +returns a pointer to a pathname on success. On error, NULL is returned, and .I errno is set appropriately. diff --git a/man3/ttyslot.3 b/man3/ttyslot.3 index f1ee5f351..dfcfc3a38 100644 --- a/man3/ttyslot.3 +++ b/man3/ttyslot.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -38,7 +38,8 @@ The legacy function .BR ttyslot () returns the index of the current user's entry in some file. .LP -Now "What file?" you ask. Well, let's first look at some history. +Now "What file?" you ask. +Well, let's first look at some history. .SS "Ancient History" There used to be a file .I /etc/ttys @@ -51,7 +52,8 @@ The second character denoted the terminal: '8' stood for "/dev/tty8". The third character was an argument to .BR getty (8) indicating the sequence of line speeds to try ('\-' was: start trying -110 baud). Thus a typical line was "18\-". +110 baud). +Thus a typical line was "18\-". A hang on some line was solved by changing the '1' to a '0', signalling init, changing back again, and signalling init again. .LP @@ -70,7 +72,8 @@ instead. .SS "Ancient History (2)" On the other hand, there is the file .I /etc/utmp -listing the people currently logged in. It is maintained by +listing the people currently logged in. +It is maintained by .BR login (8). It has a fixed size, and the appropriate index in the file was determined by @@ -111,7 +114,8 @@ The glibc2 implementation of this function reads the file .BR _PATH_TTYS , defined in .I -as "/etc/ttys". It returns 0 on error. +as "/etc/ttys". +It returns 0 on error. Since Linux systems do not usually have "/etc/ttys", it will always return 0. .LP diff --git a/man3/tzset.3 b/man3/tzset.3 index 168a3f38d..4edfd8647 100644 --- a/man3/tzset.3 +++ b/man3/tzset.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -43,7 +43,8 @@ tzset, tzname, timezone, daylight \- initialize time conversion information .fi .SH DESCRIPTION The \fBtzset\fP() function initializes the \fItzname\fP variable from the -TZ environment variable. This function is automatically called by the +TZ environment variable. +This function is automatically called by the other time conversion functions that depend on the time zone. In a SysV-like environment it will also set the variables \fItimezone\fP (seconds West of GMT) and \fIdaylight\fP (0 if this time zone does not @@ -64,19 +65,23 @@ If the TZ variable does appear in the environment but its value is empty or its value cannot be interpreted using any of the formats specified below, Coordinated Universal Time (UTC) is used. .PP -The value of TZ can be one of three formats. The first format is used +The value of TZ can be one of three formats. +The first format is used when there is no daylight saving time in the local time zone: .sp .RS .I std offset .RE .sp -The \fIstd\fP string specifies the name of the time zone and must be -three or more alphabetic characters. The \fIoffset\fP string immediately +The \fIstd\fP string specifies the name of the time zone and must be +three or more alphabetic characters. +The \fIoffset\fP string immediately follows \fIstd\fP and specifies the time value to be added to the local -time to get Coordinated Universal Time (UTC). The \fIoffset\fP is positive +time to get Coordinated Universal Time (UTC). +The \fIoffset\fP is positive if the local time zone is west of the Prime Meridian and negative if it is -east. The hour must be between 0 and 24, and the minutes and seconds +east. +The hour must be between 0 and 24, and the minutes and seconds 0 and 59. .PP The second format is used when there is daylight saving time: @@ -85,38 +90,42 @@ The second format is used when there is daylight saving time: .I std offset dst [offset],start[/time],end[/time] .RE .sp -There are no spaces in the specification. -The initial \fIstd\fP and -\fIoffset\fP specify the standard time zone, as described above. -The \fIdst\fP string and \fIoffset\fP specify the name and offset for the -corresponding daylight saving time zone. -If the offset is omitted, +There are no spaces in the specification. +The initial \fIstd\fP and +\fIoffset\fP specify the standard time zone, as described above. +The \fIdst\fP string and \fIoffset\fP specify the name and offset for the +corresponding daylight saving time zone. +If the offset is omitted, it default to one hour ahead of standard time. .PP The \fIstart\fP field specifies when daylight saving time goes into effect and the \fIend\fP field specifies when the change is made back to -standard time. These fields may have the following formats: +standard time. +These fields may have the following formats: .TP J\fIn\fP -This specifies the Julian day with \fIn\fP between 1 and 365. February -29 is never counted even in leap years. -.TP +This specifies the Julian day with \fIn\fP between 1 and 365. +February 29 is never counted even in leap years. +.TP .I n -This specifies the Julian day with \fIn\fP between 1 and 365. February -29 is counted in leap years. -.TP +This specifies the Julian day with \fIn\fP between 1 and 365. +February 29 is counted in leap years. +.TP M\fIm\fP.\fIw\fP.\fId\fP -This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP -(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12). Week 1 is -the first week in which day \fId\fP occurs and week 5 is the last week -in which day \fId\fP occurs. Day 0 is a Sunday. +This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP +(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12). +Week 1 is +the first week in which day \fId\fP occurs and week 5 is the last week +in which day \fId\fP occurs. +Day 0 is a Sunday. .PP The \fItime\fP fields specify when, in the local time currently in effect, -the change to the other time occurs. If omitted, the default is 02:00:00. +the change to the other time occurs. +If omitted, the default is 02:00:00. -Here is an example for New Zealand, -where the standard time (NZST) is 12 hours ahead of UTC, -and daylight saving time (NZDT), 13 hours ahead of UTC, +Here is an example for New Zealand, +where the standard time (NZST) is 12 hours ahead of UTC, +and daylight saving time (NZDT), 13 hours ahead of UTC, runs from the first Sunday in October to the third Sunday in March, and the changeovers happen at the default time of 02:00:00: .nf @@ -138,10 +147,11 @@ in the system timezone directory, which nowadays usually is .IR /usr/share/zoneinfo . This file is in .BR tzfile (5) -format. If \fIfilespec\fP is given, it specifies another +format. +If \fIfilespec\fP is given, it specifies another .BR tzfile (5)-format -file to read the time zone information from. If -\fIfilespec\fP does not begin with a `/', the file specification is +file to read the time zone information from. +If \fIfilespec\fP does not begin with a `/', the file specification is relative to the system timezone directory. .PP Here's an example, once more for New Zealand: @@ -175,7 +185,8 @@ or to the correct time zone file in the system time zone directory. SVr4, POSIX.1-2001, 4.3BSD .SH NOTES Note that the variable \fIdaylight\fP does not indicate that daylight -saving time applies right now. It used to give the number of some +saving time applies right now. +It used to give the number of some algorithm (see the variable \fItz_dsttime\fP in .BR gettimeofday (2)). It has been obsolete for many years but is required by SUSv2. @@ -184,7 +195,8 @@ It has been obsolete for many years but is required by SUSv2. .BI "char *timezone(" zone ", " dst ) that returned the name of the time zone corresponding to its first argument (minutes -West of GMT). If the second argument was 0, the standard name was used, +West of GMT). +If the second argument was 0, the standard name was used, otherwise the daylight saving time version. .SH "SEE ALSO" .BR date (1), diff --git a/man3/ualarm.3 b/man3/ualarm.3 index b6469978e..756166af5 100644 --- a/man3/ualarm.3 +++ b/man3/ualarm.3 @@ -58,7 +58,7 @@ EINVAL \fIusecs\fP or \fIinterval\fP is not smaller than 1000000. (On systems where that is considered an error.) .SH "CONFORMING TO" -4.3BSD, POSIX.1-2001. +4.3BSD, POSIX.1-2001. POSIX.1-2001 marks .BR ualarm () as obsolete. @@ -69,11 +69,11 @@ The type is an unsigned integer type capable of holding integers in the range [0,1000000]. On the original BSD implementation, and in glibc before version 2.1, -the arguments to +the arguments to .BR ualarm () were instead typed as .IR "unsigned int" . -Programs will be more portable if they never mention +Programs will be more portable if they never mention .I useconds_t explicitly. .LP @@ -91,7 +91,8 @@ other timer functions such as .BR usleep () is unspecified. .LP -This function is obsolete. Use +This function is obsolete. +Use .BR setitimer (2) or POSIX interval timers .RB ( timer_create (), diff --git a/man3/ulimit.3 b/man3/ulimit.3 index 72f309567..cda3f09fc 100644 --- a/man3/ulimit.3 +++ b/man3/ulimit.3 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,11 +32,13 @@ ulimit \- get and set user limits .sp .BI "long ulimit(int " cmd ", long " newlimit ); .SH DESCRIPTION -Warning: This routine is obsolete. The include file is no longer -provided by glibc. Use -.BR getrlimit (2), -.BR setrlimit (2) -and +Warning: This routine is obsolete. +The include file is no longer +provided by glibc. +Use +.BR getrlimit (2), +.BR setrlimit (2) +and .BR sysconf (3) instead. For the shell command @@ -51,7 +53,7 @@ The .I cmd argument can have one of the following values. .TP -.B UL_GETFSIZE +.B UL_GETFSIZE Return the limit on the size of a file, in units of 512 bytes. .TP .B UL_SETFSIZE diff --git a/man3/undocumented.3 b/man3/undocumented.3 index 8e995b9f9..4529e3454 100644 --- a/man3/undocumented.3 +++ b/man3/undocumented.3 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,13 +19,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" 1996-11-08, meem@sherilyn.wustl.edu, corrections .\" 2004-10-31, aeb, changed maintainer address, updated list -.\" +.\" .TH UNDOCUMENTED 3 2004-10-31 "Linux" "Linux Programmer's Manual" .SH NAME none \- undocumented library functions diff --git a/man3/ungetwc.3 b/man3/ungetwc.3 index 143ef6f67..1b924fbe1 100644 --- a/man3/ungetwc.3 +++ b/man3/ungetwc.3 @@ -22,15 +22,19 @@ ungetwc \- push back a wide character onto a FILE stream .fi .SH DESCRIPTION The \fBungetwc\fP() function is the wide-character equivalent of the \fBungetc\fP() -function. It pushes back a wide character onto \fIstream\fP and returns it. +function. +It pushes back a wide character onto \fIstream\fP and returns it. .PP -If \fIwc\fP is WEOF, it returns WEOF. If \fIwc\fP is an invalid wide character, +If \fIwc\fP is WEOF, it returns WEOF. +If \fIwc\fP is an invalid wide character, it sets \fIerrno\fP to \fBEILSEQ\fP and returns WEOF. .PP If \fIwc\fP is a valid wide character, it is pushed back onto the stream and thus becomes available for future wide character read operations. -The file-position indicator is decremented by one or more. The end-of-file -indicator is cleared. The backing storage of the file is not affected. +The file-position indicator is decremented by one or more. +The end-of-file +indicator is cleared. +The backing storage of the file is not affected. .PP Note: \fIwc\fP need not be the last wide character read from the stream; it can be any other valid wide character. diff --git a/man3/unlocked_stdio.3 b/man3/unlocked_stdio.3 index a1c9a4ca1..777f54559 100644 --- a/man3/unlocked_stdio.3 +++ b/man3/unlocked_stdio.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" diff --git a/man3/updwtmp.3 b/man3/updwtmp.3 index a3bb03af3..f25c66489 100644 --- a/man3/updwtmp.3 +++ b/man3/updwtmp.3 @@ -43,9 +43,11 @@ Then it calls \fBupdwtmp\fR() to append the structure to the utmp file. Both functions are available under glibc2, but not under libc5. However, .BR logwtmp () -used to occur in the old libbsd. These days, the +used to occur in the old libbsd. +These days, the .BR logwtmp () -function is included in libutil. (Hence you'll need to add +function is included in libutil. +(Hence you'll need to add .B \-lutil to your compiler command line to get it.) .SH "CONFORMING TO" diff --git a/man3/usleep.3 b/man3/usleep.3 index 03f34fe84..8ba1caa94 100644 --- a/man3/usleep.3 +++ b/man3/usleep.3 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -41,7 +41,8 @@ usleep \- suspend execution for microsecond intervals .fi .SH DESCRIPTION The \fBusleep\fP() function suspends execution of the calling process for -(at least) \fIusec\fP microseconds. The sleep may be lengthened slightly +(at least) \fIusec\fP microseconds. +The sleep may be lengthened slightly by any system activity or by the time spent processing the call or by the granularity of system timers. .SH "RETURN VALUE" @@ -60,11 +61,11 @@ POSIX.1-2001 declares this function obsolete; use .BR nanosleep (2) instead. -On the original BSD implementation, +On the original BSD implementation, and in glibc before version 2.2.2, the return type of this function is .IR void . -The POSIX version returns -.IR int , +The POSIX version returns +.IR int , and this is also the prototype used since glibc 2.2.2. Only the EINVAL error return is documented by SUSv2. @@ -72,8 +73,10 @@ Only the EINVAL error return is documented by SUSv2. The type .B useconds_t is an unsigned integer type capable of holding integers -in the range [0,1000000]. Programs will be more portable -if they never mention this type explicitly. Use +in the range [0,1000000]. +Programs will be more portable +if they never mention this type explicitly. +Use .RS .nf .ta 8 @@ -81,7 +84,7 @@ if they never mention this type explicitly. Use #include \&... unsigned int usecs; -\&. +\&. usleep(usecs); .fi .RE diff --git a/man3/wcpcpy.3 b/man3/wcpcpy.3 index 61c58cbed..5757ddf43 100644 --- a/man3/wcpcpy.3 +++ b/man3/wcpcpy.3 @@ -23,7 +23,8 @@ wcpcpy \- copy a wide character string, returning a pointer to its end .fi .SH DESCRIPTION The \fBwcpcpy\fP() function is the wide-character equivalent of the \fBstpcpy\fP() -function. It copies the wide character string pointed to by \fIsrc\fP, +function. +It copies the wide character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the array pointed to by \fIdest\fP. .PP diff --git a/man3/wcpncpy.3 b/man3/wcpncpy.3 index f921858bd..e3a37da83 100644 --- a/man3/wcpncpy.3 +++ b/man3/wcpncpy.3 @@ -12,7 +12,7 @@ .\" .TH WCPNCPY 3 2003-11-01 "GNU" "Linux Programmer's Manual" .SH NAME -wcpncpy \- copy a fixed-size string of wide characters, +wcpncpy \- copy a fixed-size string of wide characters, returning a pointer to its end .SH SYNOPSIS .nf @@ -23,14 +23,19 @@ returning a pointer to its end .BI "wchar_t *wcpncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcpncpy\fP() function is the wide-character equivalent of the \fBstpncpy\fP() -function. It copies at most \fIn\fP wide characters from the wide-character +The \fBwcpncpy\fP() function is the wide-character equivalent +of the \fBstpncpy\fP() function. +It copies at most \fIn\fP wide characters from the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, -to the array pointed to by \fIdest\fP. Exactly \fIn\fP wide characters are -written at \fIdest\fP. If the length \fIwcslen(src)\fP is smaller than \fIn\fP, -the remaining wide characters in the array pointed to by \fIdest\fP are filled -with L'\\0' characters. If the length \fIwcslen(src)\fP is greater or equal -to \fIn\fP, the string pointed to by \fIdest\fP will not be L'\\0' terminated. +to the array pointed to by \fIdest\fP. +Exactly \fIn\fP wide characters are +written at \fIdest\fP. +If the length \fIwcslen(src)\fP is smaller than \fIn\fP, +the remaining wide characters in the array pointed to +by \fIdest\fP are filled with L'\\0' characters. +If the length \fIwcslen(src)\fP is greater or equal +to \fIn\fP, the string pointed to by \fIdest\fP will +not be L'\\0' terminated. .PP The strings may not overlap. .PP diff --git a/man3/wcrtomb.3 b/man3/wcrtomb.3 index 22bcbdd25..8567374f7 100644 --- a/man3/wcrtomb.3 +++ b/man3/wcrtomb.3 @@ -21,30 +21,43 @@ wcrtomb \- convert a wide character to a multibyte sequence .BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps ); .fi .SH DESCRIPTION -The main case for this function is when \fIs\fP is not NULL and \fIwc\fP is not +The main case for this function is when \fIs\fP is +not NULL and \fIwc\fP is not L'\\0'. -In this case, the \fBwcrtomb\fP() function converts the wide character \fIwc\fP -to its multibyte representation and stores it at the beginning of the character -array pointed to by \fIs\fP. It updates the shift state \fI*ps\fP, and -returns the length of said multibyte representation, i.e. the number of bytes +In this case, the \fBwcrtomb\fP() function +converts the wide character \fIwc\fP +to its multibyte representation and stores it +at the beginning of the character +array pointed to by \fIs\fP. +It updates the shift state \fI*ps\fP, and +returns the length of said multibyte representation, +i.e. the number of bytes written at \fIs\fP. .PP -A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. In this -case the \fBwcrtomb\fP() function stores at the character array pointed to by -\fIs\fP the shift sequence needed to bring \fI*ps\fP back to the initial state, -followed by a '\\0' byte. It updates the shift state \fI*ps\fP (i.e. brings -it into the initial state), and returns the length of the shift sequence plus +A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. +In this +case the \fBwcrtomb\fP() function stores at +the character array pointed to by +\fIs\fP the shift sequence needed to +bring \fI*ps\fP back to the initial state, +followed by a '\\0' byte. +It updates the shift state \fI*ps\fP (i.e. brings +it into the initial state), +and returns the length of the shift sequence plus one, i.e. the number of bytes written at \fIs\fP. .PP -A third case is when \fIs\fP is NULL. In this case \fIwc\fP is ignored, +A third case is when \fIs\fP is NULL. +In this case \fIwc\fP is ignored, and the function effectively returns wcrtomb(buf,L'\\0',\fIps\fP) where buf is an internal anonymous buffer. .PP In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous state only known to the \fBwcrtomb\fP() function is used instead. .SH "RETURN VALUE" -The \fBwcrtomb\fP() function returns the number of bytes that have been or would -have been written to the byte array at \fIs\fP. If \fIwc\fP can not be +The \fBwcrtomb\fP() function returns the number of +bytes that have been or would +have been written to the byte array at \fIs\fP. +If \fIwc\fP can not be represented as a multibyte sequence (according to the current locale), (size_t)(\-1) is returned, and \fIerrno\fP set to \fBEILSEQ\fP. .SH "CONFORMING TO" diff --git a/man3/wcscasecmp.3 b/man3/wcscasecmp.3 index 089d86365..5c30f2198 100644 --- a/man3/wcscasecmp.3 +++ b/man3/wcscasecmp.3 @@ -21,14 +21,18 @@ wcscasecmp \- compare two wide-character strings, ignoring case .fi .SH DESCRIPTION The \fBwcscasecmp\fP() function is the wide-character equivalent of the -\fBstrcasecmp\fP() function. It compares the wide-character string pointed to +\fBstrcasecmp\fP() function. +It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, ignoring case differences (\fBtowupper\fP(), \fBtowlower\fP()). .SH "RETURN VALUE" The \fBwcscasecmp\fP() function returns zero if the wide-character strings at -\fIs1\fP and \fIs2\fP are equal except for case distinctions. It returns a -positive integer if \fIs1\fP is greater than \fIs2\fP, ignoring case. It -returns a negative integer if \fIs1\fP is smaller than \fIs2\fP, ignoring case. +\fIs1\fP and \fIs2\fP are equal except for case distinctions. +It returns a +positive integer if \fIs1\fP is greater than \fIs2\fP, ignoring case. +It +returns a negative integer if \fIs1\fP is smaller +than \fIs2\fP, ignoring case. .SH "CONFORMING TO" This function is a GNU extension. .SH "SEE ALSO" diff --git a/man3/wcscat.3 b/man3/wcscat.3 index 5536ea2fa..0b1ec619e 100644 --- a/man3/wcscat.3 +++ b/man3/wcscat.3 @@ -21,8 +21,9 @@ wcscat \- concatenate two wide-character strings .BI "wchar_t *wcscat(wchar_t *" dest ", const wchar_t *" src ); .fi .SH DESCRIPTION -The \fBwcscat\fP() function is the wide-character equivalent of the \fBstrcat\fP() -function. It copies the wide-character string pointed to by \fIsrc\fP, +The \fBwcscat\fP() function is the wide-character equivalent +of the \fBstrcat\fP() function. +It copies the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the end of the wide-character string pointed to by \fIdest\fP. .PP diff --git a/man3/wcschr.3 b/man3/wcschr.3 index d11b77a70..c377c672a 100644 --- a/man3/wcschr.3 +++ b/man3/wcschr.3 @@ -21,8 +21,9 @@ wcschr \- search a wide character in a wide-character string .BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); .fi .SH DESCRIPTION -The \fBwcschr\fP() function is the wide-character equivalent of the \fBstrchr\fP() -function. It searches the first occurrence of \fIwc\fP in the wide-character +The \fBwcschr\fP() function is the wide-character equivalent +of the \fBstrchr\fP() function. +It searches the first occurrence of \fIwc\fP in the wide-character string pointed to by \fIwcs\fP. .SH "RETURN VALUE" The \fBwcschr\fP() function returns a pointer to the first occurrence of diff --git a/man3/wcscmp.3 b/man3/wcscmp.3 index 7a4b2ceb8..efa751d05 100644 --- a/man3/wcscmp.3 +++ b/man3/wcscmp.3 @@ -21,14 +21,17 @@ wcscmp \- compare two wide-character strings .BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); .fi .SH DESCRIPTION -The \fBwcscmp\fP() function is the wide-character equivalent of the \fBstrcmp\fP() -function. It compares the wide-character string pointed to by \fIs1\fP and the +The \fBwcscmp\fP() function is the wide-character equivalent +of the \fBstrcmp\fP() function. +It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP. .SH "RETURN VALUE" The \fBwcscmp\fP() function returns zero if the wide-character strings at -\fIs1\fP and \fIs2\fP are equal. It returns an integer greater than zero if +\fIs1\fP and \fIs2\fP are equal. +It returns an integer greater than zero if at the first differing position \fIi\fP, the corresponding wide-character -\fIs1[i]\fP is greater than \fIs2[i]\fP. It returns an integer less than zero if +\fIs1[i]\fP is greater than \fIs2[i]\fP. +It returns an integer less than zero if at the first differing position \fIi\fP, the corresponding wide-character \fIs1[i]\fP is less than \fIs2[i]\fP. .SH "CONFORMING TO" diff --git a/man3/wcscpy.3 b/man3/wcscpy.3 index e1603da6b..a7ad85ec3 100644 --- a/man3/wcscpy.3 +++ b/man3/wcscpy.3 @@ -21,14 +21,16 @@ wcscpy \- copy a wide character string .BI "wchar_t *wcscpy(wchar_t *" dest ", const wchar_t *" src ); .fi .SH DESCRIPTION -The \fBwcscpy\fP() function is the wide-character equivalent of the \fBstrcpy\fP() -function. It copies the wide character string pointed to by \fIsrc\fP, +The \fBwcscpy\fP() function is the wide-character equivalent +of the \fBstrcpy\fP() function. +It copies the wide character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, to the array pointed to by \fIdest\fP. .PP The strings may not overlap. .PP -The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP +The programmer must ensure that there is +room for at least \fIwcslen(src)+1\fP wide characters at \fIdest\fP. .SH "RETURN VALUE" \fBwcscpy\fP() returns \fIdest\fP. diff --git a/man3/wcscspn.3 b/man3/wcscspn.3 index 2257198ea..c213626f1 100644 --- a/man3/wcscspn.3 +++ b/man3/wcscspn.3 @@ -21,18 +21,24 @@ wcscspn \- search a wide-character string for any of a set of wide characters .BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); .fi .SH DESCRIPTION -The \fBwcscspn\fP() function is the wide-character equivalent of the \fBstrcspn\fP() -function. It determines the length of the longest initial segment of \fIwcs\fP -which consists entirely of wide-characters not listed in \fIreject\fP. In +The \fBwcscspn\fP() function is the wide-character equivalent +of the \fBstrcspn\fP() function. +It determines the length of the longest initial segment of \fIwcs\fP +which consists entirely of wide-characters not listed in \fIreject\fP. +In other words, it searches for the first occurrence in the wide-character string \fIwcs\fP of any of the characters in the wide-character string \fIreject\fP. .SH "RETURN VALUE" -The \fBwcscspn\fP() function returns the number of wide characters in the longest +The \fBwcscspn\fP() function returns the number of +wide characters in the longest initial segment of \fIwcs\fP which consists entirely of wide-characters not -listed in \fIreject\fP. In other words, it returns the position of the first -occurrence in the wide-character string \fIwcs\fP of any of the characters in -the wide-character string \fIreject\fP, or \fIwcslen(wcs)\fP if there is none. +listed in \fIreject\fP. +In other words, it returns the position of the first +occurrence in the wide-character string \fIwcs\fP +of any of the characters in +the wide-character string \fIreject\fP, +or \fIwcslen(wcs)\fP if there is none. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wcsdup.3 b/man3/wcsdup.3 index bb72fc77a..c50d77c92 100644 --- a/man3/wcsdup.3 +++ b/man3/wcsdup.3 @@ -22,14 +22,17 @@ wcsdup \- duplicate a wide-character string .BI "wchar_t *wcsdup(const wchar_t *" s ); .fi .SH DESCRIPTION -The \fBwcsdup\fP() function is the wide-character equivalent of the \fBstrdup\fP() -function. It allocates and returns a new wide-character string whose initial +The \fBwcsdup\fP() function is the wide-character equivalent +of the \fBstrdup\fP() function. +It allocates and returns a new wide-character string whose initial contents is a duplicate of the wide-character string pointed to by \fIs\fP. .PP -Memory for the new wide-character string is obtained with \fBmalloc\fP(3), and +Memory for the new wide-character string is +obtained with \fBmalloc\fP(3), and can be freed with \fBfree\fP(3). .SH "RETURN VALUE" -The \fBwcsdup\fP() function returns a pointer to the new wide-character string, +The \fBwcsdup\fP() function returns a pointer +to the new wide-character string, or NULL if sufficient memory was not available. .SH ERRORS .TP diff --git a/man3/wcslen.3 b/man3/wcslen.3 index 17969c164..b4fd81896 100644 --- a/man3/wcslen.3 +++ b/man3/wcslen.3 @@ -21,11 +21,13 @@ wcslen \- determine the length of a wide-character string .BI "size_t wcslen(const wchar_t *" s ); .fi .SH DESCRIPTION -The \fBwcslen\fP() function is the wide-character equivalent of the \fBstrlen\fP() -function. It determines the length of the wide-character string pointed to +The \fBwcslen\fP() function is the wide-character equivalent +of the \fBstrlen\fP() function. +It determines the length of the wide-character string pointed to by \fIs\fP, not including the terminating L'\\0' character. .SH "RETURN VALUE" -The \fBwcslen\fP() function returns the number of wide characters in \fIs\fP. +The \fBwcslen\fP() function returns the +number of wide characters in \fIs\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wcsncasecmp.3 b/man3/wcsncasecmp.3 index ee9717743..cd29b47c9 100644 --- a/man3/wcsncasecmp.3 +++ b/man3/wcsncasecmp.3 @@ -21,15 +21,21 @@ wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case .fi .SH DESCRIPTION The \fBwcsncasecmp\fP() function is the wide-character equivalent of the -\fBstrncasecmp\fP() function. It compares the wide-character string pointed to -by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, but at most +\fBstrncasecmp\fP() function. +It compares the wide-character string pointed to +by \fIs1\fP and the wide-character string +pointed to by \fIs2\fP, but at most \fIn\fP wide characters from each string, ignoring case differences (\fBtowupper\fP(), \fBtowlower\fP()). .SH "RETURN VALUE" -The \fBwcsncasecmp\fP() function returns zero if the wide-character strings at -\fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal except -for case distinctions. It returns a positive integer if truncated \fIs1\fP is -greater than truncated \fIs2\fP, ignoring case. It returns a negative integer +The \fBwcsncasecmp\fP() function returns zero +if the wide-character strings at +\fIs1\fP and \fIs2\fP, +truncated to at most length \fIn\fP, are equal except +for case distinctions. +It returns a positive integer if truncated \fIs1\fP is +greater than truncated \fIs2\fP, ignoring case. +It returns a negative integer if truncated \fIs1\fP is smaller than truncated \fIs2\fP, ignoring case. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/wcsncat.3 b/man3/wcsncat.3 index 60a9056e8..e588d83c6 100644 --- a/man3/wcsncat.3 +++ b/man3/wcsncat.3 @@ -21,8 +21,8 @@ wcsncat \- concatenate two wide-character strings .BI "wchar_t *wcsncat(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncat\fP() function is the wide-character equivalent of the -\fBstrncat\fP() function. +The \fBwcsncat\fP() function is the wide-character equivalent of the +\fBstrncat\fP() function. It copies at most \fIn\fP wide characters from the wide-character string pointed to by \fIsrc\fP to the end of the wide-character string pointed to by \fIdest\fP, and adds a terminating L'\\0' character. diff --git a/man3/wcsncmp.3 b/man3/wcsncmp.3 index 4c3335deb..e3b4e500e 100644 --- a/man3/wcsncmp.3 +++ b/man3/wcsncmp.3 @@ -21,18 +21,21 @@ wcsncmp \- compare two fixed-size wide-character strings .BI "int wcsncmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncmp\fP() function is the wide-character equivalent of the -\fBstrncmp\fP() function. +The \fBwcsncmp\fP() function is the wide-character equivalent of the +\fBstrncmp\fP() function. It compares the wide-character string pointed to by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, but at most \fIn\fP wide -characters from each string. In each string, the comparison extends only up +characters from each string. +In each string, the comparison extends only up to the first occurrence of a L'\\0' character, if any. .SH "RETURN VALUE" The \fBwcsncmp\fP() function returns zero if the wide-character strings at \fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal. It returns an integer greater than zero if at the first differing position -\fIi\fP (\fIi\fP < \fIn\fP), the corresponding wide-character \fIs1[i]\fP is -greater than \fIs2[i]\fP. It returns an integer less than zero if at the first +\fIi\fP (\fIi\fP < \fIn\fP), +the corresponding wide-character \fIs1[i]\fP is +greater than \fIs2[i]\fP. +It returns an integer less than zero if at the first differing position \fIi\fP (\fIi\fP < \fIn\fP), the corresponding wide-character \fIs1[i]\fP is less than \fIs2[i]\fP. .SH "CONFORMING TO" diff --git a/man3/wcsncpy.3 b/man3/wcsncpy.3 index f372352a6..a8a2eaa71 100644 --- a/man3/wcsncpy.3 +++ b/man3/wcsncpy.3 @@ -21,15 +21,20 @@ wcsncpy \- copy a fixed-size string of wide characters .BI "wchar_t *wcsncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcsncpy\fP() function is the wide-character equivalent of the -\fBstrncpy\fP() function. +The \fBwcsncpy\fP() function is the wide-character equivalent of the +\fBstrncpy\fP() function. It copies at most \fIn\fP wide characters from the wide-character string pointed to by \fIsrc\fP, including the terminating L'\\0' character, -to the array pointed to by \fIdest\fP. Exactly \fIn\fP wide characters are -written at \fIdest\fP. If the length \fIwcslen(src)\fP is smaller than \fIn\fP, -the remaining wide characters in the array pointed to by \fIdest\fP are filled -with L'\\0' characters. If the length \fIwcslen(src)\fP is greater or equal -to \fIn\fP, the string pointed to by \fIdest\fP will not be L'\\0' terminated. +to the array pointed to by \fIdest\fP. +Exactly \fIn\fP wide characters are +written at \fIdest\fP. +If the length \fIwcslen(src)\fP is smaller than \fIn\fP, +the remaining wide characters in the array +pointed to by \fIdest\fP are filled +with L'\\0' characters. +If the length \fIwcslen(src)\fP is greater or equal +to \fIn\fP, the string pointed to by \fIdest\fP +will not be L'\\0' terminated. .PP The strings may not overlap. .PP diff --git a/man3/wcsnlen.3 b/man3/wcsnlen.3 index 0f12cd70d..dff1f553a 100644 --- a/man3/wcsnlen.3 +++ b/man3/wcsnlen.3 @@ -20,10 +20,12 @@ wcsnlen \- determine the length of a fixed-size wide-character string .BI "size_t wcsnlen(const wchar_t *" s ", size_t " maxlen ); .fi .SH DESCRIPTION -The \fBwcsnlen\fP() function is the wide-character equivalent of the \fBstrnlen\fP() -function. It returns the number of wide-characters in the string pointed to by +The \fBwcsnlen\fP() function is the wide-character equivalent +of the \fBstrnlen\fP() function. +It returns the number of wide-characters in the string pointed to by \fIs\fP, not including the terminating L'\\0' character, but at most -\fImaxlen\fP. In doing this, \fBwcsnlen\fP() looks only at the first \fImaxlen\fP +\fImaxlen\fP. +In doing this, \fBwcsnlen\fP() looks only at the first \fImaxlen\fP wide-characters at \fIs\fP and never beyond \fIs+maxlen\fP. .SH "RETURN VALUE" The \fBwcsnlen\fP() function returns \fIwcslen(s)\fP, if that is less than diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 index e214c5634..b82dc6618 100644 --- a/man3/wcsnrtombs.3 +++ b/man3/wcsnrtombs.3 @@ -21,48 +21,64 @@ wcsnrtombs \- convert a wide character string to a multibyte string .BI " size_t " len ", mbstate_t *" ps ); .fi .SH DESCRIPTION -The \fBwcsnrtombs\fP() function is like the \fBwcsrtombs\fP() function, -except that the number of wide characters to be converted, +The \fBwcsnrtombs\fP() function is like the \fBwcsrtombs\fP() function, +except that the number of wide characters to be converted, starting at \fI*src\fP, is limited to \fInwc\fP. .PP -If \fIdest\fP is not a NULL pointer, the \fBwcsnrtombs\fP() function converts +If \fIdest\fP is not a NULL pointer, +the \fBwcsnrtombs\fP() function converts at most \fInwc\fP wide characters from the wide-character string \fI*src\fP to a multibyte string starting at -\fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. The shift state -\fI*ps\fP is updated. The conversion is effectively performed by repeatedly -calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), as long as this call succeeds, -and then incrementing \fIdest\fP by the number of bytes written and \fI*src\fP -by one. The conversion can stop for three reasons: +\fIdest\fP. +At most \fIlen\fP bytes are written to \fIdest\fP. +The shift state +\fI*ps\fP is updated. +The conversion is effectively performed by repeatedly +calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), +as long as this call succeeds, +and then incrementing \fIdest\fP by the +number of bytes written and \fI*src\fP +by one. +The conversion can stop for three reasons: .PP 1. A wide character has been encountered that can not be represented as a -multibyte sequence (according to the current locale). In this case \fI*src\fP +multibyte sequence (according to the current locale). +In this case \fI*src\fP is left pointing to the invalid wide character, (size_t)(\-1) is returned, and \fIerrno\fP is set to \fBEILSEQ\fP. .PP -2. \fInwc\fP wide characters have been converted without encountering a L'\\0', -or the length limit forces a stop. In this case \fI*src\fP is left pointing +2. \fInwc\fP wide characters have been +converted without encountering a L'\\0', +or the length limit forces a stop. +In this case \fI*src\fP is left pointing to the next wide character to be converted, and the number of bytes written to \fIdest\fP is returned. .PP 3. The wide-character string has been completely converted, including the terminating L'\\0' (which has the side effect of bringing back \fI*ps\fP -to the initial state). In this case \fI*src\fP is set to NULL, and the number +to the initial state). +In this case \fI*src\fP is set to NULL, and the number of bytes written to \fIdest\fP, excluding the terminating '\\0' byte, is returned. .PP -If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as -above, except that the converted bytes are not written out to memory, and that +If \fIdest\fP is NULL, \fIlen\fP is ignored, +and the conversion proceeds as above, +except that the converted bytes are not written out to memory, and that no destination length limit exists. .PP -In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +In both of the above cases, +if \fIps\fP is a NULL pointer, a static anonymous state only known to the wcsnrtombs function is used instead. .PP The programmer must ensure that there is room for at least \fIlen\fP bytes at \fIdest\fP. .SH "RETURN VALUE" -The \fBwcsnrtombs\fP() function returns the number of bytes that make up the -converted part of multibyte sequence, not including the terminating null byte. -If a wide character was encountered which could not be converted, (size_t)(\-1) +The \fBwcsnrtombs\fP() function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which +could not be converted, (size_t)(\-1) is returned, and \fIerrno\fP set to \fBEILSEQ\fP. .SH "CONFORMING TO" This function is a GNU extension. diff --git a/man3/wcspbrk.3 b/man3/wcspbrk.3 index 9c8f92957..e5dca5e31 100644 --- a/man3/wcspbrk.3 +++ b/man3/wcspbrk.3 @@ -21,13 +21,16 @@ wcspbrk \- search a wide-character string for any of a set of wide characters .BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); .fi .SH DESCRIPTION -The \fBwcspbrk\fP() function is the wide-character equivalent of the \fBstrpbrk\fP() -function. It searches for the first occurrence in the wide-character -string pointed to by \fIwcs\fP of any of the characters in the wide-character +The \fBwcspbrk\fP() function is the wide-character equivalent +of the \fBstrpbrk\fP() function. +It searches for the first occurrence in the wide-character +string pointed to by \fIwcs\fP of any of the +characters in the wide-character string pointed to by \fIaccept\fP. .SH "RETURN VALUE" The \fBwcspbrk\fP() function returns a pointer to the first occurrence in -\fIwcs\fP of any of the characters listed in \fIaccept\fP. If \fIwcs\fP +\fIwcs\fP of any of the characters listed in \fIaccept\fP. +If \fIwcs\fP contains none of these characters, NULL is returned. .SH "CONFORMING TO" C99. diff --git a/man3/wcsrchr.3 b/man3/wcsrchr.3 index 3de370c39..88c4cc317 100644 --- a/man3/wcsrchr.3 +++ b/man3/wcsrchr.3 @@ -21,8 +21,9 @@ wcsrchr \- search a wide character in a wide-character string .BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); .fi .SH DESCRIPTION -The \fBwcsrchr\fP() function is the wide-character equivalent of the \fBstrrchr\fP() -function. It searches the last occurrence of \fIwc\fP in the wide-character +The \fBwcsrchr\fP() function is the wide-character equivalent +of the \fBstrrchr\fP() function. +It searches the last occurrence of \fIwc\fP in the wide-character string pointed to by \fIwcs\fP. .SH "RETURN VALUE" The \fBwcsrchr\fP() function returns a pointer to the last occurrence of diff --git a/man3/wcsrtombs.3 b/man3/wcsrtombs.3 index 1953773ec..726a19240 100644 --- a/man3/wcsrtombs.3 +++ b/man3/wcsrtombs.3 @@ -22,48 +22,60 @@ wcsrtombs \- convert a wide character string to a multibyte string .BI " size_t " len ", mbstate_t *" ps ); .fi .SH DESCRIPTION -If \fIdest\fP is not a NULL pointer, the \fBwcsrtombs\fP() function converts +If \fIdest\fP is not a NULL pointer, +the \fBwcsrtombs\fP() function converts the wide-character string \fI*src\fP to a multibyte string starting at -\fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. +\fIdest\fP. +At most \fIlen\fP bytes are written to \fIdest\fP. The shift state -\fI*ps\fP is updated. +\fI*ps\fP is updated. The conversion is effectively performed by repeatedly -calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), +calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), as long as this call succeeds, -and then incrementing \fIdest\fP by the number of bytes written and \fI*src\fP -by one. +and then incrementing \fIdest\fP by the +number of bytes written and \fI*src\fP +by one. The conversion can stop for three reasons: .PP 1. A wide character has been encountered that can not be represented as a -multibyte sequence (according to the current locale). In this case \fI*src\fP +multibyte sequence (according to the current locale). +In this case \fI*src\fP is left pointing to the invalid wide character, (size_t)(\-1) is returned, and .I errno is set to \fBEILSEQ\fP. .PP -2. The length limit forces a stop. In this case \fI*src\fP is left pointing -to the next wide character to be converted, and the number of bytes written to +2. The length limit forces a stop. +In this case \fI*src\fP is left pointing +to the next wide character to be converted, +and the number of bytes written to \fIdest\fP is returned. .PP 3. The wide-character string has been completely converted, including the terminating L'\\0' (which has the side effect of bringing back \fI*ps\fP -to the initial state). In this case \fI*src\fP is set to NULL, and the number +to the initial state). +In this case \fI*src\fP is set to NULL, and the number of bytes written to \fIdest\fP, excluding the terminating '\\0' byte, is returned. .PP -If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as -above, except that the converted bytes are not written out to memory, and that +If \fIdest\fP is NULL, \fIlen\fP is ignored, +and the conversion proceeds as above, except that the converted bytes +are not written out to memory, and that no length limit exists. .PP -In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +In both of the above cases, +if \fIps\fP is a NULL pointer, a static anonymous state only known to the wcsrtombs function is used instead. .PP The programmer must ensure that there is room for at least \fIlen\fP bytes at \fIdest\fP. .SH "RETURN VALUE" -The \fBwcsrtombs\fP() function returns the number of bytes that make up the -converted part of multibyte sequence, not including the terminating null byte. -If a wide character was encountered which could not be converted, (size_t)(\-1) +The \fBwcsrtombs\fP() function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered +which could not be converted, (size_t)(\-1) is returned, and .I errno set to \fBEILSEQ\fP. diff --git a/man3/wcsspn.3 b/man3/wcsspn.3 index 773d2c951..23e22c797 100644 --- a/man3/wcsspn.3 +++ b/man3/wcsspn.3 @@ -13,7 +13,7 @@ .\" .TH WCSSPN 3 1999-07-25 "GNU" "Linux Programmer's Manual" .SH NAME -wcsspn \- advance in a wide-character string, skipping +wcsspn \- advance in a wide-character string, skipping any of a set of wide characters .SH SYNOPSIS .nf @@ -22,19 +22,19 @@ any of a set of wide characters .BI "wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); .fi .SH DESCRIPTION -The \fBwcsspn\fP() function is the wide-character equivalent of the -\fBstrspn\fP() function. +The \fBwcsspn\fP() function is the wide-character equivalent of the +\fBstrspn\fP() function. It determines the length of the longest initial segment of \fIwcs\fP -which consists entirely of wide-characters listed in \fIaccept\fP. +which consists entirely of wide-characters listed in \fIaccept\fP. In other words, it searches for the first occurrence in the wide-character string \fIwcs\fP of a wide-character not contained in the wide-character string \fIaccept\fP. .SH "RETURN VALUE" -The \fBwcsspn\fP() function returns the number of +The \fBwcsspn\fP() function returns the number of wide characters in the longest initial segment of \fIwcs\fP which consists entirely of wide-characters listed -in \fIaccept\fP. +in \fIaccept\fP. In other words, it returns the position of the first occurrence in the wide-character string \fIwcs\fP of a wide-character not contained in the wide-character string \fIaccept\fP, or \fIwcslen(wcs)\fP diff --git a/man3/wcsstr.3 b/man3/wcsstr.3 index 8e3c339be..6205da426 100644 --- a/man3/wcsstr.3 +++ b/man3/wcsstr.3 @@ -21,18 +21,18 @@ wcsstr \- locate a substring in a wide-character string .BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); .fi .SH DESCRIPTION -The \fBwcsstr\fP() function is the wide-character equivalent of the -\fBstrstr\fP() function. +The \fBwcsstr\fP() function is the wide-character equivalent of the +\fBstrstr\fP() function. It searches for the first occurrence of the wide-character string \fIneedle\fP (without its terminating L'\\0' character) as a substring in the wide-character string \fIhaystack\fP. .SH "RETURN VALUE" The \fBwcsstr\fP() function returns a pointer to the first occurrence of -\fIneedle\fP in \fIhaystack\fP. +\fIneedle\fP in \fIhaystack\fP. It returns NULL if \fIneedle\fP does not occur as a substring in \fIhaystack\fP. .PP -Note the special case: +Note the special case: If \fIneedle\fP is the empty wide-character string, the return value is always \fIhaystack\fP itself. .SH "CONFORMING TO" diff --git a/man3/wcstoimax.3 b/man3/wcstoimax.3 index 4c06a63fb..73819a973 100644 --- a/man3/wcstoimax.3 +++ b/man3/wcstoimax.3 @@ -31,10 +31,10 @@ wcstoimax, wcstoumax \- convert wide-character string to integer .sp .BI "intmax_t wcstoimax(const wchar_t *" nptr ", wchar_t **" endptr ", int " base ); .br -.BI "uintmax_t wcstoumax(const wchar_t *" nptr ", wchar_t **" endptr ", int " base ); +.BI "uintmax_t wcstoumax(const wchar_t *" nptr ", wchar_t **" endptr ", int " base ); .fi .SH DESCRIPTION -These functions are just like +These functions are just like .BR wcstol () and .BR wcstoul (), diff --git a/man3/wcstok.3 b/man3/wcstok.3 index cf47c6de2..d8990c40a 100644 --- a/man3/wcstok.3 +++ b/man3/wcstok.3 @@ -21,9 +21,9 @@ wcstok \- split wide-character string into tokens .BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim ", wchar_t **" ptr ); .fi .SH DESCRIPTION -The \fBwcstok\fP() function is the wide-character equivalent of the -\fBstrtok\fP() function, -with an added argument to make it multithread-safe. +The \fBwcstok\fP() function is the wide-character equivalent of the +\fBstrtok\fP() function, +with an added argument to make it multithread-safe. It can be used to split a wide-character string \fIwcs\fP into tokens, where a token is defined as a substring not containing any wide-characters from \fIdelim\fP. @@ -33,8 +33,8 @@ The search starts at \fIwcs\fP, if \fIwcs\fP is not NULL, or at \fI*ptr\fP, if pointer is advanced beyond any wide-characters which occur in \fIdelim\fP. If the end of the wide-character string is now reached, \fBwcstok\fP() returns NULL, to indicate that no tokens were found, and stores an appropriate value -in \fI*ptr\fP, -so that subsequent calls to \fBwcstok\fP() will continue to return NULL. +in \fI*ptr\fP, +so that subsequent calls to \fBwcstok\fP() will continue to return NULL. Otherwise, the \fBwcstok\fP() function recognizes the beginning of a token and returns a pointer to it, but before doing that, it zero-terminates the token by replacing the next wide-character which occurs in \fIdelim\fP with diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 index bd93e2f0e..33c7a16cf 100644 --- a/man3/wcstombs.3 +++ b/man3/wcstombs.3 @@ -23,18 +23,24 @@ wcstombs \- convert a wide character string to a multibyte string .SH DESCRIPTION If \fIdest\fP is not a NULL pointer, the \fBwcstombs\fP() function converts the wide-character string \fIsrc\fP to a multibyte string starting at -\fIdest\fP. At most \fIn\fP bytes are written to \fIdest\fP. The conversion -starts in the initial state. The conversion can stop for three reasons: +\fIdest\fP. +At most \fIn\fP bytes are written to \fIdest\fP. +The conversion +starts in the initial state. +The conversion can stop for three reasons: .PP 1. A wide character has been encountered that can not be represented as a -multibyte sequence (according to the current locale). In this case +multibyte sequence (according to the current locale). +In this case (size_t)(\-1) is returned. .PP -2. The length limit forces a stop. In this case the number of bytes written to +2. The length limit forces a stop. +In this case the number of bytes written to \fIdest\fP is returned, but the shift state at this point is lost. .PP 3. The wide-character string has been completely converted, including the -terminating L'\\0'. In this case the conversion ends in the initial state. +terminating L'\\0'. +In this case the conversion ends in the initial state. The number of bytes written to \fIdest\fP, excluding the terminating '\\0' byte, is returned. .PP diff --git a/man3/wcswidth.3 b/man3/wcswidth.3 index e528c6ac2..ab6b11dfe 100644 --- a/man3/wcswidth.3 +++ b/man3/wcswidth.3 @@ -20,12 +20,15 @@ wcswidth \- determine columns needed for a fixed-size wide character string .BI "int wcswidth(const wchar_t *" s ", size_t " n ); .fi .SH DESCRIPTION -The \fBwcswidth\fP() function returns the number of columns needed to represent +The \fBwcswidth\fP() function returns the +number of columns needed to represent the wide-character string pointed to by \fIs\fP, but at most \fIn\fP wide -characters. If a non-printable wide character occurs among these characters, +characters. +If a non-printable wide character occurs among these characters, -1 is returned. .SH "RETURN VALUE" -The \fBwcswidth\fP() function returns the number of column positions for the +The \fBwcswidth\fP() function +returns the number of column positions for the wide-character string \fIs\fP, truncated to at most length \fIn\fP. .SH "CONFORMING TO" POSIX.1-2001. diff --git a/man3/wctob.3 b/man3/wctob.3 index 9cf400c3c..a163c3844 100644 --- a/man3/wctob.3 +++ b/man3/wctob.3 @@ -21,12 +21,16 @@ wctob \- try to represent a wide character as a single byte .BI "int wctob(wint_t " c ); .fi .SH DESCRIPTION -The \fBwctob\fP() function tests whether the multi-byte representation of the +The \fBwctob\fP() function tests whether +the multi-byte representation of the wide character \fIc\fP, starting in the initial state, consists of a single -byte. If so, it is returned as an unsigned char. +byte. +If so, it is returned as an unsigned char. .PP -Never use this function. It cannot help you in writing internationalized -programs. Internationalized programs must never distinguish single-byte and +Never use this function. +It cannot help you in writing internationalized +programs. +Internationalized programs must never distinguish single-byte and multi-byte characters. .SH "RETURN VALUE" The \fBwctob\fP() function returns the single-byte representation of \fIc\fP, @@ -39,6 +43,8 @@ C99. The behaviour of \fBwctob\fP() depends on the LC_CTYPE category of the current locale. .PP -This function should never be used. Internationalized programs must never -distinguish single-byte and multi-byte characters. Use the function +This function should never be used. +Internationalized programs must never +distinguish single-byte and multi-byte characters. +Use the function \fBwctomb\fP() instead. diff --git a/man3/wctomb.3 b/man3/wctomb.3 index 136e9ca57..6f55ba484 100644 --- a/man3/wctomb.3 +++ b/man3/wctomb.3 @@ -21,27 +21,35 @@ wctomb \- convert a wide character to a multibyte sequence .BI "int wctomb(char *" s ", wchar_t " wc ); .fi .SH DESCRIPTION -If \fIs\fP is not NULL, the \fBwctomb\fP() function converts the wide character +If \fIs\fP is not NULL, +the \fBwctomb\fP() function converts the wide character \fIwc\fP to its multibyte representation and stores it at the beginning of -the character array pointed to by \fIs\fP. It updates the shift state, which -is stored in a static anonymous variable only known to the wctomb function, -and returns the length of said multibyte representation, i.e. the number of +the character array pointed to by \fIs\fP. +It updates the shift state, which +is stored in a static anonymous variable +only known to the wctomb function, +and returns the length of said multibyte representation, +i.e. the number of bytes written at \fIs\fP. .PP -The programmer must ensure that there is room for at least \fBMB_CUR_MAX\fP +The programmer must ensure that there is +room for at least \fBMB_CUR_MAX\fP bytes at \fIs\fP. .PP If \fIs\fP is NULL, the \fBwctomb\fP() function .\" The Dinkumware doc and the Single Unix specification say this, but .\" glibc doesn't implement this. -resets the shift state, only known to this function, to the initial state, and -returns non-zero if the encoding has non-trivial shift state, or zero if the -encoding is stateless. +resets the shift state, only known to this function, +to the initial state, and +returns non-zero if the encoding has non-trivial shift state, +or zero if the encoding is stateless. .SH "RETURN VALUE" -If \fIs\fP is not NULL, the \fBwctomb\fP() function returns the number of bytes -that have been written to the byte array at \fIs\fP. If \fIwc\fP can not be -represented as a multibyte sequence (according to the current locale), \-1 is -returned. +If \fIs\fP is not NULL, the \fBwctomb\fP() function +returns the number of bytes +that have been written to the byte array at \fIs\fP. +If \fIwc\fP can not be +represented as a multibyte sequence (according +to the current locale), \-1 is returned. .PP If \fIs\fP is NULL, the \fBwctomb\fP() function returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. @@ -55,5 +63,6 @@ C99. The behaviour of \fBwctomb\fP() depends on the LC_CTYPE category of the current locale. .PP -This function is not multi-thread safe. The function \fBwcrtomb\fP() provides +This function is not multi-thread safe. +The function \fBwcrtomb\fP() provides a better interface to the same functionality. diff --git a/man3/wctrans.3 b/man3/wctrans.3 index 945d74059..3d7b5f69a 100644 --- a/man3/wctrans.3 +++ b/man3/wctrans.3 @@ -21,13 +21,17 @@ wctrans \- wide character translation mapping .BI "wctrans_t wctrans(const char *" name ); .fi .SH DESCRIPTION -The \fBwctrans_t\fP type represents a mapping which can map a wide character to -another wide character. Its nature is implementation dependent, but the special -value \fI(wctrans_t)\ 0\fP denotes an invalid mapping. Nonzero \fBwctrans_t\fP +The \fBwctrans_t\fP type represents a mapping +which can map a wide character to +another wide character. +Its nature is implementation dependent, but the special +value \fI(wctrans_t)\ 0\fP denotes an invalid mapping. +Nonzero \fBwctrans_t\fP values can be passed to the \fBtowctrans\fP() function to actually perform the wide character mapping. .PP -The \fBwctrans\fP() function returns a mapping, given by its name. The set of +The \fBwctrans\fP() function returns a mapping, given by its name. +The set of valid names depends on the LC_CTYPE category of the current locale, but the following names are valid in all locales. .nf @@ -36,7 +40,8 @@ following names are valid in all locales. .fi .SH "RETURN VALUE" The \fBwctrans\fP() function returns a mapping descriptor if the \fIname\fP -is valid. Otherwise it returns \fI(wctrans_t)0\fP. +is valid. +Otherwise it returns \fI(wctrans_t)0\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wctype.3 b/man3/wctype.3 index ba20c8e07..e115ffaa2 100644 --- a/man3/wctype.3 +++ b/man3/wctype.3 @@ -22,13 +22,17 @@ wctype \- wide character classification .fi .SH DESCRIPTION The \fBwctype_t\fP type represents a property which a wide character may or -may not have. In other words, it represents a class of wide characters. +may not have. +In other words, it represents a class of wide characters. This type's nature is implementation dependent, but the special value -\fI(wctype_t)0\fP denotes an invalid property. Nonzero \fBwctype_t\fP values -can be passed to the \fBiswctype\fP() function to actually test whether a given +\fI(wctype_t)0\fP denotes an invalid property. +Nonzero \fBwctype_t\fP values +can be passed to the \fBiswctype\fP() function +to actually test whether a given wide character has the property. .PP -The \fBwctype\fP() function returns a property, given by its name. The set of +The \fBwctype\fP() function returns a property, given by its name. +The set of valid names depends on the LC_CTYPE category of the current locale, but the following names are valid in all locales. .nf @@ -46,8 +50,9 @@ following names are valid in all locales. "xdigit" \- realizes the \fBisxdigit\fP() classification function .fi .SH "RETURN VALUE" -The \fBwctype\fP() function returns a property descriptor if the \fIname\fP is -valid. Otherwise it returns \fI(wctype_t)0\fP. +The \fBwctype\fP() function returns a property descriptor +if the \fIname\fP is valid. +Otherwise it returns \fI(wctype_t)0\fP. .SH "CONFORMING TO" C99. .SH "SEE ALSO" diff --git a/man3/wmemchr.3 b/man3/wmemchr.3 index 66e0cf7ec..7b4274229 100644 --- a/man3/wmemchr.3 +++ b/man3/wmemchr.3 @@ -21,8 +21,8 @@ wmemchr \- search a wide character in a wide-character array .BI "wchar_t *wmemchr(const wchar_t *" s ", wchar_t " c ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemchr\fP() function is the wide-character equivalent of the -\fBmemchr\fP() function. +The \fBwmemchr\fP() function is the wide-character equivalent of the +\fBmemchr\fP() function. It searches the \fIn\fP wide characters starting at \fIs\fP for the first occurrence of the wide character \fIc\fP. .SH "RETURN VALUE" diff --git a/man3/wmemcmp.3 b/man3/wmemcmp.3 index e52cf2e9e..c46e9a87a 100644 --- a/man3/wmemcmp.3 +++ b/man3/wmemcmp.3 @@ -20,17 +20,21 @@ wmemcmp \- compare two arrays of wide-characters .BI "int wmemcmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemcmp\fP() function is the wide-character equivalent of the -\fBmemcmp\fP() function. +The \fBwmemcmp\fP() function is the wide-character equivalent of the +\fBmemcmp\fP() function. It compares the \fIn\fP wide-characters starting at \fIs1\fP and the \fIn\fP wide-characters starting at \fIs2\fP. .SH "RETURN VALUE" -The \fBwmemcmp\fP() function returns zero if the wide-character arrays of size -\fIn\fP at \fIs1\fP and \fIs2\fP are equal. It returns an integer greater than +The \fBwmemcmp\fP() function returns +zero if the wide-character arrays of size +\fIn\fP at \fIs1\fP and \fIs2\fP are equal. +It returns an integer greater than zero if at the first differing position \fIi\fP (\fIi\fP < \fIn\fP), the -corresponding wide-character \fIs1[i]\fP is greater than \fIs2[i]\fP. It -returns an integer less than zero if at the first differing position \fIi\fP -(\fIi\fP < \fIn\fP), the corresponding wide-character \fIs1[i]\fP is less than +corresponding wide-character \fIs1[i]\fP is greater than \fIs2[i]\fP. +It returns an integer less than zero if +at the first differing position \fIi\fP +(\fIi\fP < \fIn\fP), the corresponding +wide-character \fIs1[i]\fP is less than \fIs2[i]\fP. .SH "CONFORMING TO" C99. diff --git a/man3/wmemcpy.3 b/man3/wmemcpy.3 index aad0c9454..03daa8c5b 100644 --- a/man3/wmemcpy.3 +++ b/man3/wmemcpy.3 @@ -21,8 +21,8 @@ wmemcpy \- copy an array of wide-characters .BI "wchar_t *wmemcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemcpy\fP() function is the wide-character equivalent of the -\fBmemcpy\fP() function. +The \fBwmemcpy\fP() function is the wide-character equivalent of the +\fBmemcpy\fP() function. It copies \fIn\fP wide characters from the array starting at \fIsrc\fP to the array starting at \fIdest\fP. .PP diff --git a/man3/wmemmove.3 b/man3/wmemmove.3 index 5fd486d48..3d7e04431 100644 --- a/man3/wmemmove.3 +++ b/man3/wmemmove.3 @@ -22,8 +22,10 @@ wmemmove \- copy an array of wide-characters .fi .SH DESCRIPTION The \fBwmemmove\fP() function is the wide-character equivalent of the -\fBmemmove\fP() function. It copies \fIn\fP wide characters from the array -starting at \fIsrc\fP to the array starting at \fIdest\fP. The arrays may +\fBmemmove\fP() function. +It copies \fIn\fP wide characters from the array +starting at \fIsrc\fP to the array starting at \fIdest\fP. +The arrays may overlap. .PP The programmer must ensure that there is room for at least \fIn\fP wide diff --git a/man3/wmemset.3 b/man3/wmemset.3 index 92a50ba8d..c5eb3c925 100644 --- a/man3/wmemset.3 +++ b/man3/wmemset.3 @@ -21,8 +21,8 @@ wmemset \- fill an array of wide-characters with a constant wide character .BI "wchar_t *wmemset(wchar_t *" wcs ", wchar_t " wc ", size_t " n ); .fi .SH DESCRIPTION -The \fBwmemset\fP() function is the wide-character equivalent of the -\fBmemset\fP() function. +The \fBwmemset\fP() function is the wide-character equivalent of the +\fBmemset\fP() function. It fills the array of \fIn\fP wide-characters starting at \fIwcs\fP with \fIn\fP copies of the wide character \fIwc\fP. .SH "RETURN VALUE" diff --git a/man3/wordexp.3 b/man3/wordexp.3 index 28bf85c18..c13fad748 100644 --- a/man3/wordexp.3 +++ b/man3/wordexp.3 @@ -64,21 +64,23 @@ see below) used to indicate the number of initial elements in the .I we_wordv array that should be filled with NULLs. .LP -The function +The function .BR wordfree () -frees the allocated memory again. More precisely, it does not free +frees the allocated memory again. +More precisely, it does not free its argument, but it frees the array .I we_wordv and the strings that points to. .SH EXAMPLE -First a small example. The output is approximately that of "ls [a-c]*.c". +First a small example. +The output is approximately that of "ls [a-c]*.c". .LP .nf #include #include -int -main(int argc, char **argv) +int +main(int argc, char **argv) { wordexp_t p; char **w; @@ -99,7 +101,8 @@ Since the expansion is the same as the expansion by the shell (see of the parameters to a command, the string .I s must not contain characters that would be illegal in shell command -parameters. In particular, there must not be any non-escaped +parameters. +In particular, there must not be any non-escaped newline or |, &, ;, <, >, (, ), {, } characters outside a command substitution or parameter substitution context. .LP @@ -151,7 +154,8 @@ resulted from a previous call to .BR wordexp (), and .BR wordfree () -was not called. Reuse the allocated storage. +was not called. +Reuse the allocated storage. .TP .B WRDE_SHOWERR Normally during command substitution @@ -165,10 +169,11 @@ is not to be redirected. .B WRDE_UNDEF Consider it an error if an undefined shell variable is expanded. .SH "RETURN VALUE" -In case of success 0 is returned. In case of error +In case of success 0 is returned. +In case of error one of the following five values is returned. .TP -.B WRDE_BADCHAR +.B WRDE_BADCHAR Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }. .TP .B WRDE_BADVAL diff --git a/man3/wprintf.3 b/man3/wprintf.3 index 086eaf2da..7090880e4 100644 --- a/man3/wprintf.3 +++ b/man3/wprintf.3 @@ -13,7 +13,7 @@ .\" .TH WPRINTF 3 1999-11-20 "GNU" "Linux Programmer's Manual" .SH NAME -wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted +wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted wide character output conversion .SH SYNOPSIS .nf @@ -33,28 +33,33 @@ wide character output conversion .BI " const wchar_t *" format ", va_list " args ); .fi .SH DESCRIPTION -The \fBwprintf\fP() family of functions is the wide-character equivalent of the -\fBprintf\fP() family of functions. It performs formatted output of wide +The \fBwprintf\fP() family of functions is +the wide-character equivalent of the +\fBprintf\fP() family of functions. +It performs formatted output of wide characters. .PP -The \fBwprintf\fP() and \fBvwprintf\fP() functions -perform wide character output to \fBstdout\fP. +The \fBwprintf\fP() and \fBvwprintf\fP() functions +perform wide character output to \fBstdout\fP. \fBstdout\fP must not be byte oriented; see function \fBfwide\fP() for more information. .PP -The \fBfwprintf\fP() and \fBvfwprintf\fP() functions -perform wide character output to \fIstream\fP. +The \fBfwprintf\fP() and \fBvfwprintf\fP() functions +perform wide character output to \fIstream\fP. \fIstream\fP must not be byte oriented; see function \fBfwide\fP() for more information. .PP -The \fBswprintf\fP() and \fBvswprintf\fP() functions +The \fBswprintf\fP() and \fBvswprintf\fP() functions perform wide character output to an array of wide characters. -The programmer must ensure that there is room for at least \fImaxlen\fP wide +The programmer must ensure that there is +room for at least \fImaxlen\fP wide characters at \fIwcs\fP. .PP -These functions are like the \fBprintf\fP(), \fBvprintf\fP(), \fBfprintf\fP(), -\fBvfprintf\fP(), \fBsprintf\fP(), \fBvsprintf\fP() functions except for the +These functions are like +the \fBprintf\fP(), \fBvprintf\fP(), \fBfprintf\fP(), +\fBvfprintf\fP(), \fBsprintf\fP(), \fBvsprintf\fP() +functions except for the following differences: .TP .B \(bu @@ -65,7 +70,7 @@ The output consists of wide characters, not bytes. .TP .B \(bu \fBswprintf\fP() and \fBvswprintf\fP() take a \fImaxlen\fP argument, -\fBsprintf\fP() and \fBvsprintf\fP() do not. +\fBsprintf\fP() and \fBvsprintf\fP() do not. (\fBsnprintf\fP() and \fBvsnprintf\fP() take a \fImaxlen\fP argument, but these functions do not return \-1 upon buffer overflow on Linux.) @@ -93,12 +98,15 @@ modifier is present: The .IR "" `` "const char *" '' argument is expected to be a pointer to an array of character type (pointer to a string) containing a multibyte character sequence beginning -in the initial shift state. Characters from the array are converted to +in the initial shift state. +Characters from the array are converted to wide characters (each by a call to the .BR mbrtowc () function with a conversion state starting in the initial state before -the first byte). The resulting wide characters are written up to -(but not including) the terminating null wide character. If a precision is +the first byte). +The resulting wide characters are written up to +(but not including) the terminating null wide character. +If a precision is specified, no more wide characters than the number specified are written. Note that the precision determines the number of .I wide characters @@ -108,20 +116,25 @@ or .IR "screen positions" . The array must contain a terminating null byte, unless a precision is given and it is so small that the number of converted wide characters reaches it -before the end of the array is reached. If an +before the end of the array is reached. +If an .B l modifier is present: The .IR "" `` "const wchar_t *" '' argument is expected to be a pointer to an array of wide characters. Wide characters from the array are written up to (but not including) a -terminating null wide character. If a precision is specified, no more than -the number specified are written. The array must contain a terminating null +terminating null wide character. +If a precision is specified, no more than +the number specified are written. +The array must contain a terminating null wide character, unless a precision is given and it is smaller than or equal to the number of wide characters in the array. .SH "RETURN VALUE" The functions return the number of wide characters written, excluding the -terminating null wide character in case of the functions \fBswprintf\fP() and -\fBvswprintf\fP(). They return \-1 when an error occurs. +terminating null wide character in +case of the functions \fBswprintf\fP() and +\fBvswprintf\fP(). +They return \-1 when an error occurs. .SH "CONFORMING TO" C99. .SH "SEE ALSO" @@ -132,19 +145,23 @@ C99. .BR snprintf (3), .BR wscanf (3) .SH NOTES -The behaviour of \fBwprintf\fP() et al. depends on the LC_CTYPE category of the +The behaviour of \fBwprintf\fP() et al. depends +on the LC_CTYPE category of the current locale. .PP If the \fIformat\fP string contains non-ASCII wide characters, the program will only work correctly if the LC_CTYPE category of the current locale at run time is the same as the LC_CTYPE category of the current locale at -compile time. This is because the +compile time. +This is because the .I wchar_t -representation is platform and locale dependent. (The GNU libc represents +representation is platform and locale dependent. +(The GNU libc represents wide characters using their Unicode (ISO-10646) code point, but other -platforms don't do this. +platforms don't do this. Also, the use of C99 universal character names -of the form \\unnnn does not solve this problem.) Therefore, in +of the form \\unnnn does not solve this problem.) +Therefore, in internationalized programs, the \fIformat\fP string should consist of ASCII wide characters only, or should be constructed at run time in an internationalized way (e.g. using diff --git a/man3/xcrypt.3 b/man3/xcrypt.3 index 1ef2ac58d..5e3576af4 100644 --- a/man3/xcrypt.3 +++ b/man3/xcrypt.3 @@ -6,7 +6,7 @@ .\" 3. xencrypt() a hexstring .\" to bad to be true :( .\" -.TH XCRYPT 3 2003-04-04 "" "RPC cryptography" +.TH XCRYPT 3 2003-04-04 "" "RPC cryptography" .SH NAME xencrypt, xdecrypt, passwd2des \- RFS password encryption .SH SYNOPSIS @@ -24,15 +24,17 @@ takes a character string .I passwd of arbitrary length and fills a character array .I key -of length 8. The array +of length 8. +The array .I key -is suitable for use as DES key. It has odd parity set in bit 0 of each byte. +is suitable for use as DES key. +It has odd parity set in bit 0 of each byte. Both other functions described here use this function to turn their argument .I passwd into a DES key. .LP -The +The .BR xencrypt () function takes the ASCII character string .I secret diff --git a/man3/xdr.3 b/man3/xdr.3 index 14f307a8a..582954413 100644 --- a/man3/xdr.3 +++ b/man3/xdr.3 @@ -1,7 +1,7 @@ .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) .\" .\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI -.TH XDR 3 1988-02-16 +.TH XDR 3 1988-02-16 .SH NAME xdr \- library routines for external data representation .SH "SYNOPSIS AND DESCRIPTION" @@ -24,8 +24,8 @@ xdrproc_t elproc; .IP A filter primitive that translates between variable-length arrays -and their corresponding external representations. The -parameter +and their corresponding external representations. +The parameter .I arrp is the address of the pointer to the array, while .I sizep @@ -58,7 +58,8 @@ bool_t *bp; .IP A filter primitive that translates between booleans (C integers) -and their external representations. When encoding data, this +and their external representations. +When encoding data, this filter produces values of either one or zero. This routine returns one if it succeeds, zero otherwise. .br @@ -78,7 +79,8 @@ A filter primitive that translates between counted byte strings and their external representations. The parameter .I sp -is the address of the string pointer. The length of the +is the address of the string pointer. +The length of the string is located at address .IR sizep ; strings cannot be longer than @@ -99,8 +101,8 @@ char *cp; A filter primitive that translates between C characters and their external representations. This routine returns one if it succeeds, zero otherwise. -Note: encoded characters are not packed, and occupy 4 bytes -each. For arrays of characters, it is worthwhile to +Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to consider .BR xdr_bytes (), .BR xdr_opaque () @@ -123,7 +125,8 @@ A macro that invokes the destroy routine associated with the stream, .IR xdrs . Destruction usually involves freeing private data structures -associated with the stream. Using +associated with the stream. +Using .I xdrs after invoking .BR xdr_destroy () @@ -189,10 +192,13 @@ char *objp; .fi .ft R .IP -Generic freeing routine. The first argument is the +Generic freeing routine. +The first argument is the .SM XDR -routine for the object being freed. The second argument -is a pointer to the object itself. Note: the pointer passed +routine for the object being freed. +The second argument +is a pointer to the object itself. +Note: the pointer passed to this routine is .I not freed, but what it points to @@ -313,7 +319,8 @@ a chunk of memory at location .I addr whose length is no more than .I size -bytes long. The +bytes long. +The .I op determines the direction of the .SM XDR @@ -364,7 +371,8 @@ except that it serializes .SM NULL pointers, whereas .BR xdr_reference () -does not. Thus, +does not. +Thus, .BR xdr_pointer () can represent recursive data structures, such as binary trees or @@ -391,15 +399,18 @@ stream object pointed to by The stream's data is written to a buffer of size .IR sendsize ; a value of zero indicates the system should use a suitable -default. The stream's data is read from a buffer of size +default. +The stream's data is read from a buffer of size .IR recvsize ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .I writeit -is called. Similarly, when a stream's input buffer is empty, +is called. +Similarly, when a stream's input buffer is empty, .I readit -is called. The behavior of these two routines is similar to +is called. +The behavior of these two routines is similar to the system calls .BR read () @@ -438,8 +449,8 @@ The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow -is non-zero. This routine returns one if it succeeds, zero -otherwise. +is non-zero. +This routine returns one if it succeeds, zero otherwise. .br .if t .ne 8 .LP @@ -510,7 +521,8 @@ This routine returns one if it succeeds, zero otherwise. .IP Warning: this routine does not understand .SM NULL -pointers. Use +pointers. +Use .BR xdr_pointer () instead. .br @@ -620,7 +632,7 @@ their corresponding external representations. Strings cannot be longer than .IR maxsize . -Note: +Note: .I sp is the address of the string's pointer. This routine returns one if it succeeds, zero otherwise. @@ -705,24 +717,28 @@ bool_t (*defaultarm) (); /* may equal \s-1NULL\s0 */ .IP A filter primitive that translates between a discriminated C .B union -and its corresponding external representation. It first +and its corresponding external representation. +It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp -is translated. The parameter +is translated. +The parameter .I choices is a pointer to an array of .BR xdr_discrim () -structures. Each structure contains an ordered pair of +structures. +Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to the associated .IR value , then the .I proc -is called to translate the union. The end of the +is called to translate the union. +The end of the .BR xdr_discrim () structure array is denoted by a routine of value .SM NULL\s0. @@ -749,12 +765,13 @@ xdrproc_t elproc; .IP A filter primitive that translates between fixed-length arrays -and their corresponding external representations. The -parameter +and their corresponding external representations. +The parameter .I arrp is the address of the pointer to the array, while .I size -is is the element count of the array. The parameter +is is the element count of the array. +The parameter .I elsize is the .I sizeof diff --git a/man4/console.4 b/man4/console.4 index ebcddce16..c60dc9429 100644 --- a/man4/console.4 +++ b/man4/console.4 @@ -49,7 +49,7 @@ Ctrl+Alt+F\fIn\fP to switch to console \fIn\fP; AltGr+F\fIn\fP might bring you to console \fIn\fP+12 [here Alt and AltGr refer to the left and right Alt keys, respectively]; (b) use Alt+RightArrow or Alt+LeftArrow to cycle through -the presently allocated consoles; (c) use the program +the presently allocated consoles; (c) use the program .BR chvt (1). (The key mapping is user settable, see .BR loadkeys (1); @@ -61,7 +61,8 @@ The command will free the memory taken by the screen buffers for consoles that no longer have any associated process. .SH PROPERTIES -Consoles carry a lot of state. I hope to document that some other time. +Consoles carry a lot of state. +I hope to document that some other time. The most important fact is that the consoles simulate vt100 terminals. In particular, a console is reset to the initial state by printing the two characters ESC c. diff --git a/man4/console_codes.4 b/man4/console_codes.4 index dc1ad8532..e68895751 100644 --- a/man4/console_codes.4 +++ b/man4/console_codes.4 @@ -35,8 +35,8 @@ printing, the first thing that happens is a translation from the code used for processing to the code used for printing. .LP If the console is in UTF-8 mode, then the incoming bytes are -first assembled into 16-bit Unicode codes. Otherwise -each byte is transformed according to the current mapping table +first assembled into 16-bit Unicode codes. +Otherwise each byte is transformed according to the current mapping table (which translates it to a Unicode value). See the \fBCHARACTER SETS\fP section below for discussion. .LP @@ -48,24 +48,26 @@ allows us to use 512 different glyphs simultaneously. .LP If the current Unicode value is a control character, or we are currently processing an escape sequence, the value will treated -specially. Instead of being turned into a font index and rendered as +specially. +Instead of being turned into a font index and rendered as a glyph, it may trigger cursor movement or other control functions. See the \fBLINUX CONSOLE CONTROLS\fP section below for discussion. .LP It is generally not good practice to hard-wire terminal controls into -programs. Linux supports a +programs. +Linux supports a .BR terminfo (5) -database of terminal capabilities. +database of terminal capabilities. Rather than emitting console escape sequences by hand, you will almost always want to use a terminfo-aware screen library or utility such as .BR ncurses (3), -.BR tput (1), +.BR tput (1), or .BR reset (1). .SH "LINUX CONSOLE CONTROLS" This section describes all the control characters and escape sequences that invoke special functions (i.e. anything other than writing a -glyph at the current cursor location) on the Linux console. +glyph at the current cursor location) on the Linux console. .SS "Control characters" A character is a control character if (before transformation according to the mapping table) it has one of the 14 codes @@ -84,7 +86,8 @@ and the escape sequence continues with the next character. (However, ESC starts a new escape sequence, possibly aborting a previous unfinished one, and CAN and SUB abort any escape sequence.) The recognized control characters are BEL, BS, HT, LF, VT, FF, -CR, SO, SI, CAN, SUB, ESC, DEL, CSI. They do what one would expect: +CR, SO, SI, CAN, SUB, ESC, DEL, CSI. +They do what one would expect: .HP BEL (0x07, ^G) beeps; .HP @@ -149,19 +152,20 @@ ESC ] OSC T{ ESC ] P \fInrrggbb\fP: set palette, with parameter given in 7 hexadecimal digits after the final P :-(. Here \fIn\fP is the color (0-15), and \fIrrggbb\fP indicates -the red/green/blue values (0-255). +the red/green/blue values (0-255). ESC ] R: reset palette T} .TE .SS "ECMA-48 CSI sequences" CSI (or ESC [) is followed by a sequence of parameters, at most NPAR (16), that are decimal numbers separated by -semicolons. An empty or absent parameter is taken to be 0. +semicolons. +An empty or absent parameter is taken to be 0. The sequence of parameters may be preceded by a single question mark. .PP However, after CSI [ (or ESC [ [) a single character is read -and this entire sequence is ignored. (The idea is to ignore -an echoed function key.) +and this entire sequence is ignored. +(The idea is to ignore an echoed function key.) .PP The action of a CSI sequence is determined by its final character. .TS @@ -207,11 +211,11 @@ u ? Restore cursor location. ` HPA Move cursor to indicated column in current row. .TE .SS ECMA-48 Set Graphics Rendition -The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display +The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display attributes. -Several attributes can be set in the same sequence, separated by +Several attributes can be set in the same sequence, separated by semicolons. -An empty parameter (between semicolons or string initiator or +An empty parameter (between semicolons or string initiator or terminator) is interpreted as a zero. .TS l l. @@ -289,7 +293,8 @@ where \fIx,y\fP is the cursor location. .\" .SS DEC Private Mode (DECSET/DECRST) sequences. .\" -These are not described in ECMA-48. We list the Set Mode sequences; +These are not described in ECMA-48. +We list the Set Mode sequences; the Reset Mode sequences are obtained by replacing the final `h' by `l'. .TP @@ -298,8 +303,8 @@ DECCKM (default off): When set, the cursor keys send an ESC O prefix, rather than ESC [. .TP ESC [ ? 3 h -DECCOLM (default off = 80 columns): 80/132 col mode switch. The -driver sources note that this alone does not suffice; some user-mode +DECCOLM (default off = 80 columns): 80/132 col mode switch. +The driver sources note that this alone does not suffice; some user-mode utility such as .BR resizecons (8) has to change the hardware registers on the console video card. @@ -312,7 +317,8 @@ DECOM (default off): When set, cursor addressing is relative to the upper left corner of the scrolling region. .TP ESC [ ? 7 h -DECAWM (default on): Set autowrap on. In this mode, a graphic +DECAWM (default on): Set autowrap on. +In this mode, a graphic character emitted after column 80 (or column 132 of DECCOLM is on) forces a wrap to the beginning of the following line first. .TP @@ -332,8 +338,9 @@ to 0) \(em see below. .\" .SS Linux Console Private CSI Sequences .\" -The following sequences are neither ECMA-48 nor native VT102. They -are native to the Linux console driver. Colors are in SGR parameters: +The following sequences are neither ECMA-48 nor native VT102. +They are native to the Linux console driver. +Colors are in SGR parameters: 0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 = cyan, 7 = white. .TS @@ -349,7 +356,7 @@ ESC [ 13 ] Unblank the screen. ESC [ 14 ; \fIn\fP ] Set the VESA powerdown interval in minutes. .TE .SH "CHARACTER SETS" -The kernel knows about 4 translations of bytes into console-screen +The kernel knows about 4 translations of bytes into console-screen symbols. The four tables are: a) Latin1 \-> PC, b) VT100 graphics \-> PC, c) PC \-> PC, d) user-defined. @@ -358,62 +365,71 @@ There are two character sets, called G0 and G1, and one of them is the current character set. (Initially G0.) Typing ^N causes G1 to become current, ^O causes G0 to become current. .PP -These variables G0 and G1 point at a translation table, and can be -changed by the user. +These variables G0 and G1 point at a translation table, and can be +changed by the user. Initially they point at tables a) and b), respectively. -The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to +The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point at translation table a), b), c) and d), respectively. -The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to +The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point at translation table a), b), c) and d), respectively. .PP The sequence ESC c causes a terminal reset, which is what you want if the -screen is all garbled. +screen is all garbled. The oft-advised "echo ^V^O" will only make G0 current, but there is no guarantee that G0 points at table a). In some distributions there is a program .BR reset (1) that just does "echo ^[c". -If your terminfo entry for the console is correct +If your terminfo entry for the console is correct (and has an entry rs1=\\Ec), then "tput reset" will also work. .PP The user-defined mapping table can be set using .BR mapscrn (8). The result of the mapping is that if a symbol c is printed, the symbol -s = map[c] is sent to the video memory. The bitmap that corresponds to +s = map[c] is sent to the video memory. +The bitmap that corresponds to s is found in the character ROM, and can be changed using .BR setfont (8). .SH "MOUSE TRACKING" The mouse tracking facility is intended to return xterm-compatible -mouse status reports. Because the console driver has no way to know -the device or type of the mouse, these reports are returned in the -console input stream only when the virtual terminal driver receives -a mouse update ioctl. These ioctls must be generated by a mouse-aware +mouse status reports. +Because the console driver has no way to know +the device or type of the mouse, these reports are returned in the +console input stream only when the virtual terminal driver receives +a mouse update ioctl. +These ioctls must be generated by a mouse-aware user-mode application such as the \fBgpm(8)\fR daemon. .PP The mouse tracking escape sequences generated by \fIxterm\fP encode numeric parameters in a single character as -\fIvalue\fP+040. For example, `!' is 1. The screen -coordinate system is 1-based. +\fIvalue\fP+040. +For example, `!' is 1. +The screen coordinate system is 1-based. .PP The X10 compatibility mode sends an escape sequence on button press encoding the location and the mouse button pressed. It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l. On button press, \fIxterm\fP sends -ESC [ M \fIbxy\fP (6 characters). Here \fIb\fP is button\-1, +ESC [ M \fIbxy\fP (6 characters). +Here \fIb\fP is button\-1, and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse when the button was pressed. This is the same code the kernel also produces. .PP Normal tracking mode (not implemented in Linux 2.0.24) sends an escape -sequence on both button press and release. Modifier information is -also sent. It is enabled by sending ESC [ ? 1000 h and disabled with -ESC [ 1000 l. On button press or release, \fIxterm\fP sends ESC [ M -\fIbxy\fP. The low two bits of \fIb\fP encode button information: -0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. The upper -bits encode what modifiers were down when the button was pressed and -are added together: 4=Shift, 8=Meta, 16=Control. Again \fIx\fP and -\fIy\fP are the x and y coordinates of the mouse event. The upper -left corner is (1,1). +sequence on both button press and release. +Modifier information is also sent. +It is enabled by sending ESC [ ? 1000 h and disabled with +ESC [ 1000 l. +On button press or release, \fIxterm\fP sends ESC [ M +\fIbxy\fP. +The low two bits of \fIb\fP encode button information: +0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. +The upper bits encode what modifiers were down when the button was +pressed and are added together: 4=Shift, 8=Meta, 16=Control. +Again \fIx\fP and +\fIy\fP are the x and y coordinates of the mouse event. +The upper left corner is (1,1). .SH "COMPARISONS WITH OTHER TERMINALS" Many different terminal types are described, like the Linux console, as being `VT100-compatible'. @@ -435,9 +451,9 @@ all codes except XOFF and XON. .LP VT100-like DC1/DC3 processing may be enabled by the tty driver. .LP -The +The .I xterm -program (in VT100 mode) recognizes the control characters +program (in VT100 mode) recognizes the control characters BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. .\" .SS Escape sequences @@ -460,7 +476,7 @@ The program .I xterm (in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =, ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \, -ESC Z (it answers ESC [ ? 1 ; 2 c, `I am a VT100 with +ESC Z (it answers ESC [ ? 1 ; 2 c, `I am a VT100 with advanced video option') and ESC ^ ... ESC \ with the same meanings as indicated above. It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for @@ -510,13 +526,13 @@ ESC } LS2R Invoke the G2 character set as GR. ESC ~ LS1R Invoke the G1 character set as GR. .TE .PP -It also recognizes ESC % and provides a more complete UTF-8 +It also recognizes ESC % and provides a more complete UTF-8 implementation than Linux console. .\" .SS CSI Sequences Old versions of \fIxterm\fP, e.g., from X11R5, interpret the blink SGR as a bold SGR. -Later versions which implemented ANSI colors, e.g., +Later versions which implemented ANSI colors, e.g., XFree86 3.1.2A in 1995, improved this by allowing the blink attribute to be displayed as a color. Modern versions of xterm implement blink SGR as blinking text @@ -548,7 +564,7 @@ http://invisible-island.net/xterm/xterm.log.html .PP details changes to xterm. .PP -The \fIvttest\fP program +The \fIvttest\fP program .PP .RS http://invisible-island.net/vttest/ @@ -561,16 +577,16 @@ scripts which exercise other features. ESC 8 (DECRC) is not able to restore the character set changed with ESC %. .SH BUGS -In 2.0.23, CSI is broken, and NUL is not ignored inside +In 2.0.23, CSI is broken, and NUL is not ignored inside escape sequences. .PP Some older kernel versions (after 2.0) interpret 8-bit control sequences. These "C1 controls" use codes between 128 and 159 to replace ESC [, ESC ] and similar two-byte control sequence initiators. -There are fragments of that in modern kernels (either overlooked or +There are fragments of that in modern kernels (either overlooked or broken by changes to support UTF-8), -but the implementation is incomplete and should be regarded +but the implementation is incomplete and should be regarded as unreliable. .PP Linux "private mode" sequences do not follow the rules in ECMA-48 @@ -582,7 +598,7 @@ since \fIxterm\fP may interpret this as a control sequence which requires a string terminator (ST). Unlike the \fIsetterm\fP sequences which will be ignored (since they are invalid control sequences), the palette sequence will make -\fIxterm\fP appear to hang (though pressing the return-key +\fIxterm\fP appear to hang (though pressing the return-key will fix that). To accommodate applications which have been hardcoded to use Linux control sequences, diff --git a/man4/console_ioctl.4 b/man4/console_ioctl.4 index 2e20b91ad..7dd4ac467 100644 --- a/man4/console_ioctl.4 +++ b/man4/console_ioctl.4 @@ -29,24 +29,28 @@ .SH NAME console ioctl \- ioctl's for console terminal and virtual consoles .SH DESCRIPTION -The following Linux-specific \fBioctl\fP() requests are supported. +The following Linux-specific \fBioctl\fP() requests are supported. Each requires a third argument, assumed here to be \fIargp\fP. .IP \fBKDGETLED\fP -Get state of LEDs. \fIargp\fP points to a long int. The lower three bits +Get state of LEDs. \fIargp\fP points to a long int. +The lower three bits of \fI*argp\fP are set to the state of the LEDs, as follows: LED_CAP 0x04 caps lock led LEC_NUM 0x02 num lock led LED_SCR 0x01 scroll lock led .IP \fBKDSETLED\fP -Set the LEDs. The LEDs are set to correspond to the lower three bits of -\fIargp\fP. However, if a higher order bit is set, +Set the LEDs. +The LEDs are set to correspond to the lower three bits of +\fIargp\fP. +However, if a higher order bit is set, the LEDs revert to normal: displaying the state of the keyboard functions of caps lock, num lock, and scroll lock. .LP Before 1.1.54, the LEDs just reflected the state of the corresponding keyboard flags, and KDGETLED/KDSETLED would also change the keyboard -flags. Since 1.1.54 the leds can be made to display arbitrary +flags. +Since 1.1.54 the leds can be made to display arbitrary information, but by default they display the keyboard flags. The following two ioctl's are used to access the keyboard flags. .IP \fBKDGKBLED\fP @@ -62,15 +66,20 @@ The low order three bits (mask 0x7) have the flag state, and the low order bits of the next nibble (mask 0x70) have the default flag state. (Since 1.1.54.) .IP \fBKDGKBTYPE\fP -Get keyboard type. This returns the value KB_101, defined as 0x02. +Get keyboard type. +This returns the value KB_101, defined as 0x02. .IP \fBKDADDIO\fP -Add I/O port as valid. Equivalent to ioperm(arg,1,1). +Add I/O port as valid. +Equivalent to ioperm(arg,1,1). .IP \fBKDDELIO\fP -Delete I/O port as valid. Equivalent to ioperm(arg,1,0). +Delete I/O port as valid. +Equivalent to ioperm(arg,1,0). .IP \fBKDENABIO\fP -Enable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 1). +Enable I/O to video board. +Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 1). .IP \fBKDDISABIO\fP -Disable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 0). +Disable I/O to video board. +Equivalent to ioperm(0x3b4, 0x3df-0x3b4+1, 0). .IP \fBKDSETMODE\fP Set text/graphics mode. \fIargp\fP is one of these: @@ -80,39 +89,44 @@ Set text/graphics mode. \fIargp\fP is one of these: Get text/graphics mode. \fIargp\fP points to a long which is set to one of the above values. .IP \fBKDMKTONE\fP -Generate tone of specified length. +Generate tone of specified length. The lower 16 bits of \fIargp\fP specify the period in clock cycles, and the upper 16 bits give the duration in msec. -If the duration is zero, the sound is turned off. +If the duration is zero, the sound is turned off. Control returns immediately. For example, \fIargp\fP = (125<<16) + 0x637 would specify the beep normally associated with a ctrl-G. (Thus since 0.99pl1; broken in 2.1.49-50.) .IP \fBKIOCSOUND\fP -Start or stop sound generation. The lower 16 bits of +Start or stop sound generation. +The lower 16 bits of \fIargp\fP specify the period in clock cycles -(that is, \fIargp\fP = 1193180/frequency). +(that is, \fIargp\fP = 1193180/frequency). \fIargp\fP = 0 turns sound off. In either case, control returns immediately. .IP \fBGIO_CMAP\fP Get the current default colour map from kernel. \fIargp\fP points to -a 48-byte array. (Since 1.3.3.) +a 48-byte array. +(Since 1.3.3.) .IP \fBPIO_CMAP\fP Change the default text-mode colour map. \fIargp\fP points to a 48-byte array which contains, in order, the Red, Green, and Blue values for the 16 available screen colours: 0 is off, and 255 is full -intensity. The default colours are, in order: black, dark red, dark +intensity. +The default colours are, in order: black, dark red, dark green, brown, dark blue, dark purple, dark cyan, light grey, dark grey, bright red, bright green, yellow, bright blue, bright purple, bright cyan and white. (Since 1.3.3.) .IP \fBGIO_FONT\fP Gets 256-character screen font in expanded form. \fIargp\fP points to -an 8192 byte array. Fails with error code \fBEINVAL\fP if the +an 8192 byte array. +Fails with error code \fBEINVAL\fP if the currently loaded font is a 512-character font, or if the console is not in text mode. .IP \fBGIO_FONTX\fP Gets screen font and associated information. \fIargp\fP points to a -\fIstruct consolefontdesc\fP (see \fBPIO_FONTX\fP). On call, the +\fIstruct consolefontdesc\fP (see \fBPIO_FONTX\fP). +On call, the \fIcharcount\fP field should be set to the maximum number of characters that would fit in the buffer pointed to by \fIchardata\fP. On return, the \fIcharcount\fP and \fIcharheight\fP are filled with @@ -122,10 +136,13 @@ the respective data for the currently loaded font, and the buffer is untouched and \fIerrno\fP is set to \fBENOMEM\fP. (Since 1.3.1.) .IP \fBPIO_FONT\fP -Sets 256-character screen font. Load font into the EGA/VGA character +Sets 256-character screen font. +Load font into the EGA/VGA character generator. \fIargp\fP points to a 8192 byte map, with 32 bytes per -character. Only first \fIN\fP of them are used for an 8x\fIN\fP font -(0 < \fIN\fP <= 32). This call also invalidates the Unicode mapping. +character. +Only first \fIN\fP of them are used for an 8x\fIN\fP font +(0 < \fIN\fP <= 32). +This call also invalidates the Unicode mapping. .IP \fBPIO_FONTX\fP Sets screen font and associated rendering information. \fIargp\fP points to a @@ -139,21 +156,26 @@ struct consolefontdesc { .fi If necessary, the screen will be appropriately resized, and -\fBSIGWINCH\fP sent to the appropriate processes. This call also -invalidates the Unicode mapping. (Since 1.3.1.) +\fBSIGWINCH\fP sent to the appropriate processes. +This call also invalidates the Unicode mapping. +(Since 1.3.1.) .IP \fBPIO_FONTRESET\fP Resets the screen font, size and Unicode mapping to the bootup -defaults. \fIargp\fP is unused, but should be set to NULL to +defaults. +\fIargp\fP is unused, but should be set to NULL to ensure compatibility with future versions of Linux. (Since 1.3.28.) .IP \fBGIO_SCRNMAP\fP -Get screen mapping from kernel. \fIargp\fP points to an area of size +Get screen mapping from kernel. +\fIargp\fP points to an area of size E_TABSZ, which is loaded with the font positions used to display each -character. This call is likely to return useless information if the +character. +This call is likely to return useless information if the currently loaded font is more than 256 characters. .IP \fBGIO_UNISCRNMAP\fP Get full Unicode screen mapping from kernel. \fIargp\fP points to an area of size E_TABSZ*sizeof(unsigned short), which is loaded with the -Unicodes each character represent. A special set of Unicodes, +Unicodes each character represent. +A special set of Unicodes, starting at U+F000, are used to represent ``direct to font'' mappings. (Since 1.3.1.) .IP \fBPIO_SCRNMAP\fP @@ -163,9 +185,10 @@ size E_TABSZ. .IP \fBPIO_UNISCRNMAP\fP Loads the ``user definable'' (fourth) table in the kernel which maps bytes into Unicodes, which are then translated into screen symbols -according to the currently loaded Unicode-to-font map. Special -Unicodes starting at U+F000 can be used to map directly to the font -symbols. (Since 1.3.1.) +according to the currently loaded Unicode-to-font map. +Special Unicodes starting at U+F000 can be used to map directly to the font +symbols. +(Since 1.3.1.) .IP \fBGIO_UNIMAP\fP Get Unicode-to-font mapping from kernel. \fIargp\fP points to a @@ -192,7 +215,7 @@ Put unicode-to-font mapping in kernel. \fIargp\fP points to a .IP \fBPIO_UNIMAPCLR\fP Clear table, possibly advise hash algorithm. \fIargp\fP points to a -.nf +.nf struct unimapinit { u_short \fIadvised_hashsize\fP; /* 0 if no opinion */ u_short \fIadvised_hashstep\fP; /* 0 if no opinion */ @@ -205,9 +228,9 @@ struct unimapinit { Gets current keyboard mode. \fIargp\fP points to a long which is set to one of these: - K_RAW 0x00 - K_XLATE 0x01 - K_MEDIUMRAW 0x02 + K_RAW 0x00 + K_XLATE 0x01 + K_MEDIUMRAW 0x02 K_UNICODE 0x03 .IP \fBKDSKBMODE\fP Sets current keyboard mode. @@ -216,13 +239,13 @@ Sets current keyboard mode. Gets meta key handling mode. \fIargp\fP points to a long which is set to one of these: - K_METABIT 0x03 set high order bit + K_METABIT 0x03 set high order bit K_ESCPREFIX 0x04 escape prefix .IP \fBKDSKBMETA\fP Sets meta key handling mode. \fIargp\fP is a long equal to one of the above values. .IP \fBKDGKBENT\fP -Gets one entry in key translation table (keycode to action code). +Gets one entry in key translation table (keycode to action code). \fIargp\fP points to a .nf @@ -233,14 +256,14 @@ struct kbentry { }; .fi -with the first two members filled in: +with the first two members filled in: \fIkb_table\fP selects the key table (0 <= \fIkb_table\fP < MAX_NR_KEYMAPS), -and \fIkb_index\fP is the keycode (0 <= \fIkb_index\fP < NR_KEYS). +and \fIkb_index\fP is the keycode (0 <= \fIkb_index\fP < NR_KEYS). \fIkb_value\fP is set to the corresponding action code, -or K_HOLE if there is no such key, +or K_HOLE if there is no such key, or K_NOSUCHMAP if \fIkb_table\fP is invalid. .IP \fBKDSKBENT\fP -Sets one entry in translation table. \fIargp\fP points to +Sets one entry in translation table. \fIargp\fP points to a \fIstruct kbentry\fP. .IP \fBKDGKBSENT\fP Gets one function key string. \fIargp\fP points to a @@ -252,16 +275,16 @@ struct kbsentry { }; .fi -\fIkb_string\fP is set to the (NULL terminated) string corresponding to +\fIkb_string\fP is set to the (NULL terminated) string corresponding to the \fIkb_func\fPth function key action code. .IP \fBKDSKBSENT\fP -Sets one function key string entry. \fIargp\fP points to +Sets one function key string entry. \fIargp\fP points to a \fIstruct kbsentry\fP. .IP \fBKDGKBDIACR\fP Read kernel accent table. \fIargp\fP points to a .nf -struct kbdiacrs { +struct kbdiacrs { unsigned int \fIkb_cnt\fP; struct kbdiacr \fIkbdiacr\fP[256]; }; @@ -271,38 +294,38 @@ where \fIkb_cnt\fP is the number of entries in the array, each of which is a .nf -struct kbdiacr { +struct kbdiacr { u_char \fIdiacr\fP; u_char \fIbase\fP; u_char \fIresult\fP; }; .IP \fBKDGETKEYCODE\fP -Read kernel keycode table entry (scan code to keycode). +Read kernel keycode table entry (scan code to keycode). \fIargp\fP points to a .nf -struct kbkeycode { +struct kbkeycode { unsigned int \fIscancode\fP; - unsigned int \fIkeycode\fP; + unsigned int \fIkeycode\fP; }; .fi \fIkeycode\fP is set to correspond to the given \fIscancode\fP. -(89 <= \fIscancode\fP <= 255 only. +(89 <= \fIscancode\fP <= 255 only. For 1 <= \fIscancode\fP <= 88, \fIkeycode\fP==\fIscancode\fP.) (Since 1.1.63.) .IP \fBKDSETKEYCODE\fP -Write kernel keycode table entry. \fIargp\fP points to +Write kernel keycode table entry. \fIargp\fP points to a \fIstruct kbkeycode\fP. (Since 1.1.63.) .IP \fBKDSIGACCEPT\fP The calling process indicates its willingness to accept the signal \fIargp\fP when it is generated by pressing an appropriate key combination. -(1 <= \fIargp\fP <= NSIG). +(1 <= \fIargp\fP <= NSIG). (See spawn_console() in linux/drivers/char/keyboard.c.) .IP \fBVT_OPENQRY\fP Returns the first available (non-opened) console. -\fIargp\fP points to an int which is set to the +\fIargp\fP points to an int which is set to the number of the vt (1 <= \fI*argp\fP <= MAX_NR_CONSOLES). .IP \fBVT_GETMODE\fP Get mode of active vt. \fIargp\fP points to a @@ -317,17 +340,17 @@ struct vt_mode { }; .fi -which is set to the mode of the active vt. -\fImode\fP is set to one of these values: +which is set to the mode of the active vt. +\fImode\fP is set to one of these values: - VT_AUTO auto vt switching - VT_PROCESS process controls switching - VT_ACKACQ acknowledge switch + VT_AUTO auto vt switching + VT_PROCESS process controls switching + VT_ACKACQ acknowledge switch .IP \fBVT_SETMODE\fP -Set mode of active vt. \fIargp\fP points to +Set mode of active vt. \fIargp\fP points to a \fIstruct vt_mode\fP. .IP \fBVT_GETSTATE\fP -Get global vt state info. \fIargp\fP points to a +Get global vt state info. \fIargp\fP points to a .nf struct vt_stat { @@ -360,9 +383,9 @@ struct vt_sizes { .fi Note that this does not change the videomode. -See +See .BR resizecons (8). -(Since 1.1.54.) +(Since 1.1.54.) .IP \fBVT_RESIZEX\fP Set the kernel's idea of various screen parameters. \fIargp\fP points to a @@ -379,20 +402,22 @@ struct vt_consize { .fi Any parameter may be set to zero, indicating ``no change'', but if -multiple parameters are set, they must be self-consistent. Note that -this does not change the videomode. See +multiple parameters are set, they must be self-consistent. +Note that this does not change the videomode. +See .BR resizecons(8). (Since 1.3.3.) .PP -The action of the following ioctls depends on the first byte in the struct +The action of the following ioctls depends on the first byte in the struct pointed to by \fIargp\fP, referred to here as the \fIsubcode\fP. These are legal only for the superuser or the owner of the current tty. .IP "\fBTIOCLINUX, subcode=0\fP" Dump the screen. Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from -/dev/vcsN or /dev/vcsaN instead.) +/dev/vcsN or /dev/vcsaN instead.) .IP "\fBTIOCLINUX, subcode=1\fP" -Get task information. Disappeared in 1.1.92. +Get task information. +Disappeared in 1.1.92. .IP "\fBTIOCLINUX, subcode=2\fP" Set selection. \fIargp\fP points to a @@ -407,11 +432,12 @@ struct { .fi \fIxs\fP and \fIys\fP are the starting column and row. \fIxe\fP and \fIye\fP are the ending -column and row. (Upper left corner is row=column=1.) -\fIsel_mode\fP is 0 for character-by-character selection, -1 for word-by-word selection, +column and row. +(Upper left corner is row=column=1.) +\fIsel_mode\fP is 0 for character-by-character selection, +1 for word-by-word selection, or 2 for line-by-line selection. -The indicated screen characters are highlighted and saved +The indicated screen characters are highlighted and saved in the static array sel_buffer in devices/char/console.c. .IP "\fBTIOCLINUX, subcode=3\fP" Paste selection. @@ -429,18 +455,18 @@ variable \fIshift_state\fP. (Since 1.1.32.) \fIargp\fP points to a char which is set to the value of the kernel variable \fIreport_mouse\fP. (Since 1.1.33.) .IP "\fBTIOCLINUX, subcode=8\fP" -Dump screen width and height, cursor position, and all the +Dump screen width and height, cursor position, and all the character-attribute pairs. -(Kernels 1.1.67 through 1.1.91 only. +(Kernels 1.1.67 through 1.1.91 only. With kernel 1.1.92 or later, read from /dev/vcsa* instead.) .IP "\fBTIOCLINUX, subcode=9\fP" -Restore screen width and height, cursor position, and all the +Restore screen width and height, cursor position, and all the character-attribute pairs. -(Kernels 1.1.67 through 1.1.91 only. -With kernel 1.1.92 or later, write to /dev/vcsa* instead.) +(Kernels 1.1.67 through 1.1.91 only. +With kernel 1.1.92 or later, write to /dev/vcsa* instead.) .IP "\fBTIOCLINUX, subcode=10\fP" Handles the Power Saving -feature of the new generation of monitors. +feature of the new generation of monitors. VESA screen blanking mode is set to \fIargp\fP[1], which governs what screen blanking does: @@ -448,23 +474,24 @@ screen blanking does: \fI1\fP: The current video adapter register settings are saved, then the controller is programmed to turn off -the vertical synchronization pulses. +the vertical synchronization pulses. This puts the monitor into "standby" mode. -If your monitor has an Off_Mode timer, then +If your monitor has an Off_Mode timer, then it will eventually power down by itself. - \fI2\fP: The current -settings are saved, then both the vertical and horizontal -synchronization pulses are turned off. + \fI2\fP: The current +settings are saved, then both the vertical and horizontal +synchronization pulses are turned off. This puts the monitor into "off" mode. If your monitor has no Off_Mode timer, or if you want your monitor to power down immediately when the -blank_timer times out, then you choose this option. -(\fICaution:\fP Powering down frequently will damage the monitor.) +blank_timer times out, then you choose this option. +(\fICaution:\fP Powering down frequently will damage the monitor.) (Since 1.1.76.) .SH "RETURN VALUE" -On success, 0 is returned. On error \-1 is returned, and \fIerrno\fP is set. +On success, 0 is returned. +On error \-1 is returned, and \fIerrno\fP is set. .SH ERRORS \fIerrno\fP may take on these values: .TP @@ -484,11 +511,14 @@ Insufficient permission. .SH WARNING Do not regard this man page as documentation of the Linux console ioctl's. This is provided for the curious only, as an alternative to reading the -source. Ioctl's are undocumented Linux internals, liable to be changed -without warning. (And indeed, this page more or less describes the -situation as of kernel version 1.1.94; there are many minor and not-so-minor +source. +Ioctl's are undocumented Linux internals, liable to be changed +without warning. +(And indeed, this page more or less describes the +situation as of kernel version 1.1.94; +there are many minor and not-so-minor differences with earlier versions.) - + Very often, ioctl's are introduced for communication between the kernel and one particular well-known program (fdisk, hdparm, setserial, tunelp, loadkeys, selection, setfont, etc.), and their behavior will be diff --git a/man4/dsp56k.4 b/man4/dsp56k.4 index 56e929e8e..754bef70d 100644 --- a/man4/dsp56k.4 +++ b/man4/dsp56k.4 @@ -43,17 +43,18 @@ The dsp56k device is a character device with major number 55 and minor number 0. .SH DESCRIPTION The Motorola DSP56001 is a fully programmable 24-bit digital signal -processor found in Atari Falcon030-compatible computers. The -\fBdsp56k\fP special file is used to control the DSP56001, and +processor found in Atari Falcon030-compatible computers. +The \fBdsp56k\fP special file is used to control the DSP56001, and to send and receive data using the bi-directional handshaked host port. .PP -To send a data stream to the signal processor, use -.BR write () +To send a data stream to the signal processor, use +.BR write () to the -device, and -.BR read () -to receive processed data. The data can be sent or +device, and +.BR read () +to receive processed data. +The data can be sent or received in 8, 16, 24, or 32-bit quantities on the host side, but will always be seen as 24-bit quantities in the DSP56001. .PP @@ -62,37 +63,47 @@ The following calls are used to control the \fBdsp56k\fP device: .IP \fBDSP56K_UPLOAD\fP -resets the DSP56001 and uploads a program. The third -.BR ioctl () +resets the DSP56001 and uploads a program. +The third +.BR ioctl () argument must be a pointer to a \fBstruct dsp56k_binary\fP with members \fBbin\fP pointing to a DSP56001 binary program, and \fBlen\fP set to the length of the program, counted in 24-bit words. .IP \fBDSP56K_SET_TX_WSIZE\fP -sets the transmit word size. Allowed values are in the range 1 to 4, +sets the transmit word size. +Allowed values are in the range 1 to 4, and is the number of bytes that will be sent at a time to the -DSP56001. These data quantities will either be padded with zero +DSP56001. +These data quantities will either be padded with zero bytes, or truncated to fit the native 24-bit data format of the DSP56001. .IP \fBDSP56K_SET_RX_WSIZE\fP -sets the receive word size. Allowed values are in the range 1 to 4, +sets the receive word size. +Allowed values are in the range 1 to 4, and is the number of bytes that will be received at a time from the -DSP56001. These data quantities will either truncated, or padded with +DSP56001. +These data quantities will either truncated, or padded with a null byte ('\\0') to fit the native 24-bit data format of the DSP56001. .IP \fBDSP56K_HOST_FLAGS\fP -read and write the host flags. The host flags are four +read and write the host flags. +The host flags are four general-purpose bits that can be read by both the hosting computer and -the DSP56001. Bits 0 and 1 can be written by the host, and bits 2 and +the DSP56001. +Bits 0 and 1 can be written by the host, and bits 2 and 3 can be written by the DSP56001. -To access the host flags, the third -.BR ioctl () +To access the host flags, the third +.BR ioctl () argument must be a pointer -to a \fBstruct dsp56k_host_flags\fP. If bit 0 or 1 is set in the +to a \fBstruct dsp56k_host_flags\fP. +If bit 0 or 1 is set in the \fBdir\fP member, the corresponding bit in \fBout\fP will be written -to the host flags. The state of all host flags will be returned in +to the host flags. +The state of all host flags will be returned in the lower four bits of the \fBstatus\fP member. .IP \fBDSP56K_HOST_CMD\fP -sends a host command. Allowed values are in the range 0 to 31, and is a +sends a host command. +Allowed values are in the range 0 to 31, and is a user-defined command handled by the program running in the DSP56001. .SH FILES /dev/dsp56k diff --git a/man4/fd.4 b/man4/fd.4 index 6fabf9526..c110d0bec 100644 --- a/man4/fd.4 +++ b/man4/fd.4 @@ -28,21 +28,26 @@ .SH NAME fd \- floppy disk device .SH CONFIGURATION -Floppy drives are block devices with major number 2. Typically they +Floppy drives are block devices with major number 2. +Typically they are owned by root.floppy (i.e., user root, group floppy) and have either mode 0660 (access checking via group membership) or mode 0666 -(everybody has access). The minor +(everybody has access). +The minor numbers encode the device type, drive number, and controller number. For each device type (that is, combination of density and track count) -there is a base minor number. To this base number, add the drive's +there is a base minor number. +To this base number, add the drive's number on its controller and 128 if the drive is on the secondary -controller. In the following device tables, \fIn\fP represents the +controller. +In the following device tables, \fIn\fP represents the drive number. .PP \fBWarning: If you use formats with more tracks -than supported by your drive, you may cause it mechanical damage.\fP Trying -once if more tracks than the usual 40/80 are supported should not -damage it, but no warranty is given for that. Don't create device +than supported by your drive, you may cause it mechanical damage.\fP +Trying once if more tracks than the usual 40/80 are supported should not +damage it, but no warranty is given for that. +Don't create device entries for those formats to prevent their usage if you are not sure. .PP Drive independent device files which automatically detect the media @@ -129,15 +134,18 @@ calls are supported by \fBfd\fP devices: .IP \fBFDCLRPRM\fP clears the media information of a drive (geometry of disk in drive). .IP \fBFDSETPRM\fP -sets the media information of a drive. The media information will be +sets the media information of a drive. +The media information will be lost when the media is changed. .IP \fBFDDEFPRM\fP -sets the media information of a drive (geometry of disk in drive). The -media information will not be lost when the media is changed. This -will disable autodetection. In order to re-enable autodetection, you +sets the media information of a drive (geometry of disk in drive). +The media information will not be lost when the media is changed. +This will disable autodetection. +In order to re-enable autodetection, you have to issue an \fBFDCLRPRM\fP. .IP \fBFDGETDRVTYP\fP -returns the type of a drive (name parameter). For formats which work +returns the type of a drive (name parameter). +For formats which work in several drive types, \fBFDGETDRVTYP\fP returns a name which is appropriate for the oldest drive type which supports this format. .IP \fBFDFLUSH\fP @@ -152,12 +160,15 @@ gets the internal name of the drive. .IP \fBFDWERRORCLR\fP clears the write error statistics. .IP \fBFDWERRORGET\fP -reads the write error statistics. These include the total number of +reads the write error statistics. +These include the total number of write errors, the location and disk of the first write error, and the -location and disk of the last write error. Disks are identified by a +location and disk of the last write error. +Disks are identified by a generation number which is incremented at (almost) each disk change. .IP \fBFDTWADDLE\fP -Switch the drive motor off for a few microseconds. This might be +Switch the drive motor off for a few microseconds. +This might be needed in order to access a disk whose sectors are too close together. .IP \fBFDSETDRVPRM\fP sets various drive parameters. @@ -181,12 +192,14 @@ floppycontrol. 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, performance may drop, up to needing a few seconds to access an entire -track. To prevent this, use interleaved formats. It is not possible to +track. +To prevent this, use interleaved formats. +It is not possible to read floppies which are formatted using GCR (group code recording), 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. +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 diff --git a/man4/full.4 b/man4/full.4 index e4e46fb48..e1d73ac71 100644 --- a/man4/full.4 +++ b/man4/full.4 @@ -1,6 +1,6 @@ -.\" -*- nroff -*- +.\" -*- nroff -*- .\" -.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" This man-page is Copyright (C) 1997 John S. Kallal .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -27,9 +27,9 @@ .SH NAME full \- always full device .SH DESCRIPTION -File \fI/dev/full\fP has major device number 1 +File \fI/dev/full\fP has major device number 1 and minor device number 7. -.LP +.LP Writes to the \fI/dev/full\fP device will fail with an ENOSPC error. This can be used to test how a program handles disk-full errors. @@ -37,7 +37,7 @@ Reads from the \fI/dev/full\fP device will return \\0 characters. Seeks on \fI/dev/full\fP will always succeed. .SH CONFIGURING -If your system does not have \fI/dev/full\fP created already, it +If your system does not have \fI/dev/full\fP created already, it can be created with the following commands: .nf diff --git a/man4/hd.4 b/man4/hd.4 index e2ca6e899..841aa7787 100644 --- a/man4/hd.4 +++ b/man4/hd.4 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 16:56:20 1993 by Rik Faith .\" Modified Mon Oct 21 21:38:51 1996 by Eric S. Raymond .\" (and some more by aeb) @@ -29,10 +29,11 @@ hd \- MFM/IDE hard disk devices .SH DESCRIPTION The \fBhd*\fP devices are block devices to access MFM/IDE hard disk drives -in raw mode. The master drive on the primary IDE controller (major device -number 3) is \fBhda\fR; the slave drive is \fBhdb\fR. The master -drive of the second controller (major device number 22) is \fBhdc\fR -and the slave \fBhdd\fR. +in raw mode. +The master drive on the primary IDE controller (major device +number 3) is \fBhda\fR; the slave drive is \fBhdb\fR. +The master drive of the second controller (major device number 22) +is \fBhdc\fR and the slave \fBhdd\fR. .LP General IDE block device names have the form .BI hd X\c @@ -48,7 +49,8 @@ The first form, is used to address the whole drive. Partition numbers are assigned in the order the partitions are discovered, and only non-empty, non-extended partitions -get a number. However, partition numbers 1-4 are given to the +get a number. +However, partition numbers 1-4 are given to the four partitions described in the MBR (the `primary' partitions), regardless of whether they are unused or extended. Thus, the first logical partition will be diff --git a/man4/initrd.4 b/man4/initrd.4 index 91099368a..eb534adf7 100644 --- a/man4/initrd.4 +++ b/man4/initrd.4 @@ -1,4 +1,4 @@ -.\" -*- nroff -*- +.\" -*- nroff -*- .\" This man-page is Copyright (C) 1997 John S. Kallal .\" .\" Permission is granted to make and distribute verbatim copies of this @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,199 +17,199 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and author(s) of this work. .\" .\" If the you wish to distribute versions of this work under other -.\" conditions than the above, please contact the author(s) at the following +.\" conditions than the above, please contact the author(s) at the following .\" for permission: .\" -.\" John S. Kallal - +.\" John S. Kallal - .\" email: .\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA .\" phone: (302)654-5478 -.\" +.\" .\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ .TH INITRD 4 1997-11-06 "Linux 2.0" "Linux Programmer's Manual" .SH NAME initrd \- boot loader initialized RAM disk .SH DESCRIPTION -The special file -.I /dev/initrd -is a read-only block device. -Device +The special file +.I /dev/initrd +is a read-only block device. +Device .I /dev/initrd is a RAM disk that is initialized (e.g. loaded) by the boot loader before the kernel is started. The kernel then can use the block device -.IR /dev/initrd "'s " +.IR /dev/initrd "'s " contents for a two phased system boot-up. .PP -In the first boot-up phase, the kernel starts up -and mounts an initial root file-system from the contents -of -.I /dev/initrd -(e.g. RAM disk initialized by the boot loader). -In the second phase, additional drivers or other modules -are loaded from the initial root device's contents. -After loading the additional modules, a new root file system -(i.e. the normal root file system) is mounted from a +In the first boot-up phase, the kernel starts up +and mounts an initial root file-system from the contents +of +.I /dev/initrd +(e.g. RAM disk initialized by the boot loader). +In the second phase, additional drivers or other modules +are loaded from the initial root device's contents. +After loading the additional modules, a new root file system +(i.e. the normal root file system) is mounted from a different device. .\" .\" .\" .SH "BOOT-UP OPERATION" -When booting up with +When booting up with .BR initrd ", the system boots as follows:" .RS 0.2i .PP -1. The boot loader loads the kernel program and +1. The boot loader loads the kernel program and .IR /dev/initrd "'s contents into memory." .PP -2. On kernel startup, -the kernel uncompresses and copies the contents of the device +2. On kernel startup, +the kernel uncompresses and copies the contents of the device .I /dev/initrd -onto device -.I /dev/ram0 -and then frees the memory used by +onto device +.I /dev/ram0 +and then frees the memory used by .IR /dev/initrd "." .PP 3. The kernel then read-write mounts device -.I /dev/ram0 +.I /dev/ram0 as the initial root file system. .PP 4. If the indicated normal root file system is also the initial root file-system -(e.g. +(e.g. .I /dev/ram0 ) then the kernel skips to the last step for the usual boot sequence. .PP -5. If the executable file +5. If the executable file .IR /linuxrc " is present in the initial root file-system, " /linuxrc -is executed with UID 0. -(The file +is executed with UID 0. +(The file .I /linuxrc -must have executable permission. -The file +must have executable permission. +The file .I /linuxrc -can be any valid executable, including a shell script.) +can be any valid executable, including a shell script.) .PP -6. If +6. If .I /linuxrc -is not executed or when +is not executed or when .I /linuxrc -terminates, the normal root file system is mounted. +terminates, the normal root file system is mounted. (If -.IR /linuxrc -exits with any file-systems mounted on the initial root -file-system, then the behavior of the kernel is +.IR /linuxrc +exits with any file-systems mounted on the initial root +file-system, then the behavior of the kernel is .BR UNSPECIFIED "." -See the -.BR NOTES +See the +.BR NOTES section for the current kernel behavior.) .PP -7. If the normal root file has directory +7. If the normal root file has directory .IR /initrd ", device" .I /dev/ram0 -is moved from +is moved from .IR / " to " /initrd "." -Otherwise if directory -.IR /initrd " does not exist device " /dev/ram0 " is unmounted." -(When moved from -.IR / " to " /initrd ", " /dev/ram0 -is not unmounted and therefore processes can remain running from -.IR /dev/ram0 "." -If directory -.IR /initrd -does not exist on the normal root file-system -and any processes remain running from -.IR /dev/ram0 " when " /linuxrc -exits, the behavior of the kernel is -.BR UNSPECIFIED "." -See the -.BR NOTES +Otherwise if directory +.IR /initrd " does not exist device " /dev/ram0 " is unmounted." +(When moved from +.IR / " to " /initrd ", " /dev/ram0 +is not unmounted and therefore processes can remain running from +.IR /dev/ram0 "." +If directory +.IR /initrd +does not exist on the normal root file-system +and any processes remain running from +.IR /dev/ram0 " when " /linuxrc +exits, the behavior of the kernel is +.BR UNSPECIFIED "." +See the +.BR NOTES section for the current kernel behavior.) .PP -8. The usual boot sequence (e.g. invocation of +8. The usual boot sequence (e.g. invocation of .IR /sbin/init ) is performed on the normal root file system. -.\" -.\" -.\" +.\" +.\" +.\" .SH OPTIONS -The following boot loader options when used with +The following boot loader options when used with .BR initrd ", affect the kernel's boot-up operation:" .TP .BI initrd= "filename" -Specifies the file to load as the contents of +Specifies the file to load as the contents of .IR /dev/initrd "." For -.B LOADLIN +.B LOADLIN this is a command line option. -For -.B LILO -you have to use this command in the -.B LILO -configuration file +For +.B LILO +you have to use this command in the +.B LILO +configuration file .IR /etc/lilo.config . The filename specified with this option will typically be a gzipped file-system image. .TP .I noinitrd This boot time option disables the two phase boot-up operation. -The kernel performs the usual boot sequence as if -.I /dev/initrd -was not initialized. -With this option, any contents of -.I /dev/initrd -loaded into memory by the boot loader contents are preserved. -This option permits the contents of +The kernel performs the usual boot sequence as if +.I /dev/initrd +was not initialized. +With this option, any contents of +.I /dev/initrd +loaded into memory by the boot loader contents are preserved. +This option permits the contents of +.I /dev/initrd +to be any data and need not be limited to a file system image. +However, device .I /dev/initrd -to be any data and need not be limited to a file system image. -However, device -.I /dev/initrd is read-only and can be read only one time after system startup. .TP .BI root= "device-name" -Specifies the device to be used as the normal root file system. +Specifies the device to be used as the normal root file system. .RB "For " LOADLIN this is a command line option. .RB "For " LILO " this is a boot time option or -can be used as an option line in the +can be used as an option line in the .BR LILO " configuration file " /etc/lilo.config "." -The device specified by the this option must be a mountable +The device specified by the this option must be a mountable device having a suitable root file-system. -.\" -.\" -.\" +.\" +.\" +.\" .SH "CHANGING THE NORMAL ROOT FILE SYSTEM" -By default, +By default, the kernel's settings -(e.g. set in the kernel file with +(e.g. set in the kernel file with .BR rdev (8) or compiled into the kernel file), or the boot loader option setting is used for the normal root file systems. -For a NFS-mounted normal root file system, one has to use the -.BR nfs_root_name " and " nfs_root_addrs -boot options to give the NFS settings. +For a NFS-mounted normal root file system, one has to use the +.BR nfs_root_name " and " nfs_root_addrs +boot options to give the NFS settings. For more information on NFS-mounted root see the kernel documentation file .BR nfsroot.txt "." For more information on setting the root file system also see the .BR LILO " and " LOADLIN " documentation." .PP -It is also possible for the +It is also possible for the .IR /linuxrc executable to change the normal root device. -For +For .IR /linuxrc -to change the normal root device, +to change the normal root device, .IR /proc " must be mounted." -After mounting -.IR /proc ", " /linuxrc +After mounting +.IR /proc ", " /linuxrc changes the normal root device by writing into the proc files .IR /proc/sys/kernel/real-root-dev ", " -.IR /proc/sys/kernel/nfs-root-name ", and " +.IR /proc/sys/kernel/nfs-root-name ", and " .IR /proc/sys/kernel/nfs-root-addrs "." For a physical root device, the root device is changed by having .IR /linuxrc @@ -219,21 +219,21 @@ For a NFS root file system, the root device is changed by having .IR /linuxrc write the NFS setting into files .IR /proc/sys/kernel/nfs-root-name " and " -.IR /proc/sys/kernel/nfs-root-addrs +.IR /proc/sys/kernel/nfs-root-addrs and then writing 0xff (e.g. the pseudo-NFS-device number) into file .IR /proc/sys/kernel/real-root-dev "." For example, the following shell command line would change -the normal root device to +the normal root device to .IR /dev/hdb1 : .nf echo 0x365 >/proc/sys/kernel/real-root-dev .fi -For a NFS example, the following shell command lines would change the -normal root device to the NFS directory -.IR /var/nfsroot -on a local networked NFS server with IP number 193.8.232.7 for a system with +For a NFS example, the following shell command lines would change the +normal root device to the NFS directory +.IR /var/nfsroot +on a local networked NFS server with IP number 193.8.232.7 for a system with IP number 193.8.232.7 and named 'idefix': .nf @@ -253,45 +253,45 @@ as well as .BR pivot_root (2) and .BR pivot_root (8) -for information on the modern method of changing the root file system. +for information on the modern method of changing the root file system. .\" FIXME the manual page should describe the pivot_root mechanism. -.\" -.\" -.\" +.\" +.\" +.\" .SH USAGE -The main motivation for implementing -.BR initrd -was to allow for modular kernel configuration at system installation. +The main motivation for implementing +.BR initrd +was to allow for modular kernel configuration at system installation. .PP A possible system installation scenario is as follows: .RS 0.2i .PP 1. The loader program boots from floppy or other media with a minimal kernel -(e.g. support for -.IR /dev/ram ", " /dev/initrd ", and the ext2 file-system) and loads " +(e.g. support for +.IR /dev/ram ", " /dev/initrd ", and the ext2 file-system) and loads " .IR /dev/initrd " with a gzipped version of the initial file-system. .PP -2. The executable -.IR /linuxrc +2. The executable +.IR /linuxrc determines what is needed to (1) mount the normal root file-system (i.e. device type, device drivers, file system) and (2) the distribution media (e.g. CD-ROM, network, tape, ...). This can be done by asking the user, by auto-probing, or by using a hybrid approach. -.PP -3. The executable -.IR /linuxrc +.PP +3. The executable +.IR /linuxrc loads the necessary modules from the initial root file-system. .PP -4. The executable -.IR /linuxrc -creates and populates the root file system. (At this stage the normal -root file system does not have to be a +4. The executable +.IR /linuxrc +creates and populates the root file system. +(At this stage the normal root file system does not have to be a completed system yet.) .PP -5. The executable +5. The executable .IR /linuxrc " sets " /proc/sys/kernel/real-root-dev, -unmount +unmount .IR /proc ", " the normal root file system and any other file systems it has mounted, and then terminates. @@ -303,67 +303,67 @@ the boot loader can be installed. .PP 8. The boot loader is configured to load into .IR /dev/initrd -a file system with the set of modules that was used to bring up the system. +a file system with the set of modules that was used to bring up the system. (e.g. Device -.IR /dev/ram0 +.IR /dev/ram0 can be modified, then unmounted, and finally, the image is written from -.IR /dev/ram0 +.IR /dev/ram0 to a file.) .PP 9. The system is now bootable and additional installation tasks can be performed. .RE .PP -The key role of -.IR /dev/initrd -in the above is to re-use the configuration data during normal system operation +The key role of +.IR /dev/initrd +in the above is to re-use the configuration data during normal system operation without requiring initial kernel selection, a large generic kernel or, recompiling the kernel. .PP A second scenario is for installations where Linux runs on systems with -different hardware configurations in a single administrative network. +different hardware configurations in a single administrative network. In such cases, it may be desirable to use only a small set of kernels (ideally only one) and to keep the system-specific part of configuration -information as small as possible. -In this case, create a common file -with all needed modules. -Then, only the +information as small as possible. +In this case, create a common file +with all needed modules. +Then, only the .I /linuxrc file or a file executed by .I /linuxrc would be different. .PP -A third scenario is more convenient recovery disks. -Because information like the location of the root file-system -partition is not needed at boot time, the system loaded from -.I /dev/initrd -can use a dialog and/or auto-detection followed by a +A third scenario is more convenient recovery disks. +Because information like the location of the root file-system +partition is not needed at boot time, the system loaded from +.I /dev/initrd +can use a dialog and/or auto-detection followed by a possible sanity check. .PP -Last but not least, Linux distributions on CD-ROM may use +Last but not least, Linux distributions on CD-ROM may use .BR initrd -for easy installation from the CD-ROM. -The distribution can use -.BR LOADLIN -to directly load +for easy installation from the CD-ROM. +The distribution can use +.BR LOADLIN +to directly load .IR /dev/initrd from CD-ROM without the need of any floppies. -The distribution could also use a -.BR LILO +The distribution could also use a +.BR LILO boot floppy and then bootstrap a bigger ram disk via .IR /dev/initrd " from the CD-ROM." -.\" -.\" -.\" +.\" +.\" +.\" .SH CONFIGURATION -The -.I /dev/initrd -is a read-only block device assigned -major number 1 and minor number 250. -Typically +The .I /dev/initrd -is owned by -.I root.disk +is a read-only block device assigned +major number 1 and minor number 250. +Typically +.I /dev/initrd +is owned by +.I root.disk with mode 0400 (read access by root only). If the Linux system does not have .I /dev/initrd @@ -374,17 +374,17 @@ already created, it can be created with the following commands: chown root:disk /dev/initrd \fP .fi -Also, support for both "RAM disk" and "Initial RAM disk" -(e.g. +Also, support for both "RAM disk" and "Initial RAM disk" +(e.g. .BR CONFIG_BLK_DEV_RAM=y " and " CONFIG_BLK_DEV_INITRD=y -) support must be compiled directly into the Linux kernel to use +) support must be compiled directly into the Linux kernel to use .IR /dev/initrd "." -When using +When using .IR /dev/initrd ", " the RAM disk driver cannot be loaded as a module. -.\" -.\" -.\" +.\" +.\" +.\" .SH FILES .I /dev/initrd .br @@ -404,40 +404,41 @@ The documentation file .I initrd.txt in the kernel source package, the LILO documentation, the LOADLIN documentation, the SYSLINUX documentation. -.\" -.\" -.\" +.\" +.\" +.\" .SH NOTES 1. With the current kernel, any file systems that remain mounted when -.IR /dev/ram0 " is moved from " / " to " /initrd -continue to be accessible. However, the -.IR /proc/mounts -entries are not updated. +.IR /dev/ram0 " is moved from " / " to " /initrd +continue to be accessible. +However, the +.IR /proc/mounts +entries are not updated. .PP -2. With the current kernel, if directory -.IR /initrd " does not exist, then " -.I /dev/ram0 -will NOT be fully unmounted if -.IR /dev/ram0 +2. With the current kernel, if directory +.IR /initrd " does not exist, then " +.I /dev/ram0 +will NOT be fully unmounted if +.IR /dev/ram0 is used by any process or has any file-system mounted on it. -If -.IR /dev/ram0 " is NOT fully unmounted, " -then +If +.IR /dev/ram0 " is NOT fully unmounted, " +then .IR /dev/ram0 will remain in memory. .PP -3. Users of -.IR /dev/initrd -should not depend on the behavior give in the above notes. +3. Users of +.IR /dev/initrd +should not depend on the behavior give in the above notes. The behavior may change in future versions of the Linux kernel. -.\" -.\" -.\" +.\" +.\" +.\" .SH AUTHOR -The kernel code for device -.BR initrd -was written by Werner Almesberger and +The kernel code for device +.BR initrd +was written by Werner Almesberger and Hans Lermen . The code for -.BR initrd +.BR initrd was added to the baseline Linux kernel in development version 1.3.73. diff --git a/man4/intro.4 b/man4/intro.4 index 599f38f58..6b25fe00a 100644 --- a/man4/intro.4 +++ b/man4/intro.4 @@ -30,6 +30,7 @@ This chapter describes special files. /dev/* \(em device files .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! .SH "SEE ALSO" .BR standards (7) diff --git a/man4/lp.4 b/man4/lp.4 index dd3b1e2ff..433f3048e 100644 --- a/man4/lp.4 +++ b/man4/lp.4 @@ -29,60 +29,70 @@ lp \- line printer devices .B #include .SH CONFIGURATION \fBlp\fP[0\(en2] are character devices for the parallel line printers; -they have major number 6 and minor number 0\(en2. The minor numbers +they have major number 6 and minor number 0\(en2. +The minor numbers correspond to the printer port base addresses 0x03bc, 0x0378 and 0x0278. -Usually they have mode 220 and are owned by root and group lp. You can -use printer ports either with polling or with interrupts. Interrupts -are recommended when high traffic is expected, e.g.\& for laser -printers. For usual dot matrix printers polling will usually be -enough. The default is polling. +Usually they have mode 220 and are owned by root and group lp. +You can use printer ports either with polling or with interrupts. +Interrupts are recommended when high traffic is expected, e.g.\& for laser +printers. +For usual dot matrix printers polling will usually be enough. +The default is polling. .SH DESCRIPTION The following .BR ioctl (2) calls are supported: .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPTIME, int \fP\fIarg\fP\fB)\fP" Sets the amount of time that the driver sleeps before rechecking the printer -when the printer's buffer appears to be filled to \fIarg\fP. If you -have a fast printer, decrease this number; if you have a slow printer -then increase it. This is in hundredths of a second, the default 2 -being 0.02 seconds. It only influences the polling driver. +when the printer's buffer appears to be filled to \fIarg\fP. +If you have a fast printer, decrease this number; +if you have a slow printer then increase it. +This is in hundredths of a second, the default 2 +being 0.02 seconds. +It only influences the polling driver. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCHAR, int \fP\fIarg\fP\fB)\fP" Sets the maximum number of busy-wait iterations which the polling driver does while waiting for the printer to get ready for receiving a character to -\fIarg\fP. If printing is too slow, increase this number; if the -system gets too slow, decrease this number. The default is 1000. +\fIarg\fP. +If printing is too slow, increase this number; if the +system gets too slow, decrease this number. +The default is 1000. It only influences the polling driver. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORT, int \fP\fIarg\fP\fB)\fP" If \fIarg\fP is 0, the printer driver will retry on errors, otherwise -it will abort. The default is 0. +it will abort. +The default is 0. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORTOPEN, int \fP\fIarg\fP\fB)\fP" If \fIarg\fP is 0, .BR open (2) -will be aborted on error, otherwise error will be ignored. The default is -to ignore it. +will be aborted on error, otherwise error will be ignored. +The default is to ignore it. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCAREFUL, int \fP\fIarg\fP\fB)\fP" If \fIarg\fP is 0, then the out-of-paper, offline and error signals are -required to be false on all writes, otherwise they are ignored. The -default is to ignore them. +required to be false on all writes, otherwise they are ignored. +The default is to ignore them. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPWAIT, int \fP\fIarg\fP\fB)\fP" Sets the number of busy waiting iterations to wait before strobing the printer to accept a just-written character, and the number of iterations to wait before turning the strobe off again, -to \fIarg\fP. The specification says this time should be 0.5 +to \fIarg\fP. +The specification says this time should be 0.5 microseconds, but experience has shown the delay caused by the code is -already enough. For that reason, the default value is 0. This is -used for both the polling and the interrupt driver. +already enough. +For that reason, the default value is 0. +This is used for both the polling and the interrupt driver. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPSETIRQ, int \fP\fIarg\fP\fB)\fP" -This -.BR ioctl () -requires superuser privileges. It takes an int containing the -new IRQ as argument. As a side effect, the printer will be reset. When -\fIarg\fP is 0, the polling driver will be used, which is also default. +This +.BR ioctl () +requires superuser privileges. +It takes an int containing the new IRQ as argument. +As a side effect, the printer will be reset. +When \fIarg\fP is 0, the polling driver will be used, which is also default. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETIRQ, int *\fP\fIarg\fP\fB)\fP" Stores the currently used IRQ in \fIarg\fP. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETSTATUS, int *\fP\fIarg\fP\fB)\fP" -Stores the value of the status port in \fIarg\fP. The bits have the following -meaning: +Stores the value of the status port in \fIarg\fP. +The bits have the following meaning: .TS l l. LP_PBUSY inverted busy input, active high @@ -95,13 +105,16 @@ LP_PERRORP unchanged error input, active low Refer to your printer manual for the meaning of the signals. Note that undocumented bits may also be set, depending on your printer. .IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPRESET)\fP" -Resets the printer. No argument is used. +Resets the printer. +No argument is used. .SH FILES /dev/lp* .SH AUTHORS The printer driver was originally written by Jim Weigand and Linus -Torvalds. It was further improved by Michael K.\& Johnson. The -interrupt code was written by Nigel Gamble. Alan Cox modularised it. +Torvalds. +It was further improved by Michael K.\& Johnson. +The interrupt code was written by Nigel Gamble. +Alan Cox modularised it. LPCAREFUL, LPABORT, LPGETSTATUS were added by Chris Metcalf. .SH "SEE ALSO" .BR chmod (1), diff --git a/man4/mem.4 b/man4/mem.4 index e51f1593a..54a8748bb 100644 --- a/man4/mem.4 +++ b/man4/mem.4 @@ -26,12 +26,11 @@ mem, kmem, port \- system memory, kernel memory and system ports .SH DESCRIPTION \fBmem\fP is a character device file -that is an image of the main memory of the -computer. It may be used, for example, to examine (and even patch) the -system. +that is an image of the main memory of the computer. +It may be used, for example, to examine (and even patch) the system. .LP -Byte addresses in -.B mem +Byte addresses in +.B mem are interpreted as physical memory addresses. References to non-existent locations cause errors to be returned. .LP @@ -46,10 +45,10 @@ mknod \-m 660 /dev/mem c 1 1 chown root:kmem /dev/mem .RE .LP -The file -.B kmem -is the same as -.BR mem , +The file +.B kmem +is the same as +.BR mem , except that the kernel virtual memory rather than physical memory is accessed. .LP @@ -61,8 +60,8 @@ mknod \-m 640 /dev/kmem c 1 2 chown root:kmem /dev/kmem .RE .LP -\fBport\fP is similar to -.BR mem , +\fBport\fP is similar to +.BR mem , but the I/O ports are accessed. .LP It is typically created by: diff --git a/man4/mouse.4 b/man4/mouse.4 index 9dd78af52..053108c0d 100644 --- a/man4/mouse.4 +++ b/man4/mouse.4 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .TH MOUSE 4 1996-02-10 "Special files" "Linux Programmer's Manual" @@ -46,16 +46,18 @@ pin name used for This is the specification, in fact 9 V suffices with most mice. .PP The mouse driver can recognize a mouse by dropping RTS to low and raising -it again. About 14 ms later the mouse will send 0x4D ('M') on the data line. +it again. +About 14 ms later the mouse will send 0x4D ('M') on the data line. After a further 63 ms, a Microsoft-compatible 3-button mouse will send 0x33 ('3'). .PP The relative mouse movement is sent as \fIdx\fP (positive means right) -and \fIdy\fP (positive means down). Various mice can operate at different -speeds. To select speeds, cycle through the +and \fIdy\fP (positive means down). +Various mice can operate at different speeds. +To select speeds, cycle through the speeds 9600, 4800, 2400 and 1200 bit/s, each time writing the two characters -from the table below and waiting 0.1 seconds. The following table shows -available speeds and the strings that select them: +from the table below and waiting 0.1 seconds. +The following table shows available speeds and the strings that select them: .TS center; l l. @@ -69,8 +71,9 @@ bit/s string The first byte of a data packet can be used to synchronisation purposes. .SS "Microsoft protocol" The \fBMicrosoft\fP protocol uses 1 start bit, 7 data bits, no parity -and one stop bit at the speed of 1200 bits/sec. Data is sent to RxD in -3-byte packets. The \fIdx\fP and \fIdy\fP movements are sent as +and one stop bit at the speed of 1200 bits/sec. +Data is sent to RxD in 3-byte packets. +The \fIdx\fP and \fIdy\fP movements are sent as two's-complement, \fIlb\fP (\fIrb\fP) are set when the left (right) button is pressed: .TS @@ -82,8 +85,10 @@ byte d6 d5 d4 d3 d2 d1 d0 3 0 dy5 dy4 dy3 dy2 dy1 dy0 .TE .SS "3-button Microsoft protocol" -Original Microsoft mice only have two buttons. However, there are some -three button mice which also use the Microsoft protocol. Pressing or +Original Microsoft mice only have two buttons. +However, there are some +three button mice which also use the Microsoft protocol. +Pressing or releasing the middle button is reported by sending a packet with zero movement and no buttons pressed. (Thus, unlike for the other two buttons, the status of the middle @@ -91,13 +96,16 @@ button is not reported in each packet.) .SS "Logitech protocol" Logitech serial 3-button mice use a different extension of the Microsoft protocol: when the middle button is up, the above 3-byte -packet is sent. When the middle button is down a 4-byte packet is +packet is sent. +When the middle button is down a 4-byte packet is sent, where the 4th byte has value 0x20 (or at least has the 0x20 -bit set). In particular, a press of the middle button is reported +bit set). +In particular, a press of the middle button is reported as 0,0,0,0x20 when no other buttons are down. .SS "Mousesystems protocol" The \fBMousesystems\fP protocol uses 1 start bit, 8 data bits, no parity -and two stop bits at the speed of 1200 bits/sec. Data is sent to RxD in +and two stop bits at the speed of 1200 bits/sec. +Data is sent to RxD in 5-byte packets. \fIdx\fP is sent as the sum of the two two's-complement values, \fIdy\fP is send as negated sum of the two two's-complement values. \fIlb\fP (\fImb\fP, \fIrb\fP) are cleared when the left (middle, @@ -120,9 +128,11 @@ The \fBSun\fP protocol is the 3-byte version of the above 5-byte Mousesystems protocol: the last two bytes are not sent. .SS "MM protocol" The \fBMM\fP protocol uses 1 start bit, 8 data bits, odd parity and one -stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 3-byte +stop bit at the speed of 1200 bits/sec. +Data is sent to RxD in 3-byte packets. \fIdx\fP and \fIdy\fP are sent as single signed values, the -sign bit indicating a negative value. \fIlb\fP (\fImb\fP, \fIrb\fP) are +sign bit indicating a negative value. +\fIlb\fP (\fImb\fP, \fIrb\fP) are set when the left (middle, right) button is pressed: .TS center; diff --git a/man4/null.4 b/man4/null.4 index cc9dce2cc..c282bab8c 100644 --- a/man4/null.4 +++ b/man4/null.4 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu) .TH NULL 4 1992-11-21 "Linux" "Linux Programmer's Manual" .SH NAME diff --git a/man4/pts.4 b/man4/pts.4 index e58f7c7a9..c7469d962 100644 --- a/man4/pts.4 +++ b/man4/pts.4 @@ -15,7 +15,8 @@ When a process opens \fI/dev/ptmx\fP, it gets a file descriptor for a pseudo-terminal master (PTM), and a pseudo-terminal slave (PTS) device is created in the .I /dev/pts -directory. Each file descriptor obtained by opening \fI/dev/ptmx\fP +directory. +Each file descriptor obtained by opening \fI/dev/ptmx\fP is an independent PTM with its own associated PTS, whose path can be found by passing the descriptor to .BR ptsname (3). @@ -33,7 +34,7 @@ Data written to the slave is presented on the master descriptor as input. Data written to the master is presented to the slave as input. .PP In practice, pseudo-terminals are used for implementing terminal emulators -such as +such as .BR xterm (1), in which data read from the pseudo-terminal master is interpreted by the application in the same way diff --git a/man4/random.4 b/man4/random.4 index b524c7118..116aa1e56 100644 --- a/man4/random.4 +++ b/man4/random.4 @@ -14,38 +14,39 @@ .SH NAME random, urandom \- kernel random number source devices .SH DESCRIPTION -The character special files \fI/dev/random\fP and +The character special files \fI/dev/random\fP and \fI/dev/urandom\fP (present since Linux 1.3.30) -provide an interface to the kernel's random number generator. -File \fI/dev/random\fP has major device number 1 -and minor device number 8. File \fI/dev/urandom\fP -has major device number 1 and minor device number 9. +provide an interface to the kernel's random number generator. +File \fI/dev/random\fP has major device number 1 +and minor device number 8. +File \fI/dev/urandom\fP has major device number 1 and minor device number 9. .LP -The random number generator gathers environmental noise -from device drivers and other sources into an entropy pool. -The generator also keeps an estimate of the +The random number generator gathers environmental noise +from device drivers and other sources into an entropy pool. +The generator also keeps an estimate of the number of bits of noise in the entropy pool. From this entropy pool random numbers are created. -.LP -When read, the \fI/dev/random\fP device will only return random bytes -within the estimated number of bits of noise in the entropy -pool. \fI/dev/random\fP should be suitable for uses that need very -high quality randomness such as one-time pad or key generation. -When the entropy pool is empty, reads from \fI/dev/random\fP will block +.LP +When read, the \fI/dev/random\fP device will only return random bytes +within the estimated number of bits of noise in the entropy +pool. \fI/dev/random\fP should be suitable for uses that need very +high quality randomness such as one-time pad or key generation. +When the entropy pool is empty, reads from \fI/dev/random\fP will block until additional environmental noise is gathered. -.LP +.LP A read from the \fI/dev/urandom\fP device will not block waiting for more entropy. As a result, if there is not sufficient entropy in the entropy pool, the returned values are theoretically vulnerable to a -cryptographic attack on the algorithms used by the driver. Knowledge of -how to do this is not available in the current non-classified +cryptographic attack on the algorithms used by the driver. +Knowledge of how to do this is not available in the current non-classified literature, but it is theoretically possible that such an attack may -exist. If this is a concern in your application, use \fI/dev/random\fP +exist. +If this is a concern in your application, use \fI/dev/random\fP instead. .SH CONFIGURING If your system does not have -\fI/dev/random\fP and \fI/dev/urandom\fP created already, they +\fI/dev/random\fP and \fI/dev/urandom\fP created already, they can be created with the following commands: .nf @@ -53,14 +54,15 @@ can be created with the following commands: mknod \-m 644 /dev/urandom c 1 9 chown root:root /dev/random /dev/urandom .fi - -When a Linux system starts up without much operator interaction, + +When a Linux system starts up without much operator interaction, the entropy pool may be in a fairly predictable state. -This reduces the actual amount of noise in the entropy pool -below the estimate. In order to counteract this effect, it helps to carry -entropy pool information across shut-downs and start-ups. -To do this, add the following lines to an appropriate script -which is run during the Linux system start-up sequence: +This reduces the actual amount of noise in the entropy pool +below the estimate. +In order to counteract this effect, it helps to carry +entropy pool information across shut-downs and start-ups. +To do this, add the following lines to an appropriate script +which is run during the Linux system start-up sequence: .nf echo "Initializing random number generator..." @@ -78,9 +80,9 @@ which is run during the Linux system start-up sequence: dd if=/dev/urandom of=$random_seed count=1 bs=$bytes .fi -Also, add the following lines in an appropriate script which is +Also, add the following lines in an appropriate script which is run during the Linux system shutdown: - + .nf # Carry a random seed from shut-down to start-up # Save the whole entropy pool @@ -101,12 +103,14 @@ device. .LP The read-only file .I entropy_avail -gives the available entropy. Normally, this will be 4096 (bits), +gives the available entropy. +Normally, this will be 4096 (bits), a full entropy pool. .LP The file .I poolsize -gives the size of the entropy pool. Normally, this will be 512 (bytes). +gives the size of the entropy pool. +Normally, this will be 512 (bytes). It can be changed to any value for which an algorithm is available. Currently the choices are 32, 64, 128, 256, 512, 1024, 2048. .LP @@ -139,7 +143,7 @@ generated once. .br /dev/urandom .SH AUTHOR -The kernel's random number generator was written by +The kernel's random number generator was written by Theodore Ts'o (tytso@athena.mit.edu). .SH "SEE ALSO" mknod (1) diff --git a/man4/rtc.4 b/man4/rtc.4 index 54005fb31..fcc70e0c7 100644 --- a/man4/rtc.4 +++ b/man4/rtc.4 @@ -117,7 +117,7 @@ while the remaining 3 bytes contain the number of interrupts since the last .BR read (2). .SS ioctl() interface -The following +The following .BR ioctl (2) requests are defined on file descriptors connected to RTC devices: .TP @@ -151,9 +151,9 @@ A pointer to this structure should be passed as the third argument. .TP .B RTC_SET_TIME -Sets this RTC's time to the time specified by the +Sets this RTC's time to the time specified by the .I rtc_time -structure pointed to by the third +structure pointed to by the third .BR ioctl () argument. To set the @@ -167,9 +167,9 @@ The alarm interrupt must be separately enabled or disabled using the .BR RTC_AIE_ON ", " RTC_AIE_OFF requests. The third \fBioctl\fP() argument is a pointer to an -.I rtc_time -structure. -Only the +.I rtc_time +structure. +Only the .IR tm_sec , .IR tm_min , and @@ -184,11 +184,11 @@ The periodic interrupt must be separately enabled or disabled using the requests. The third \fBioctl\fP() argument is a .I "unsigned long\ *" -or a -.IR "unsigned long" , +or a +.IR "unsigned long" , respectively. -The value is the frequency in interrupts per second. -The set of allowable frequencies is the multiples of two +The value is the frequency in interrupts per second. +The set of allowable frequencies is the multiples of two in the range 2 to 8192. Only a privileged process (i.e., one having the .B CAP_SYS_RESOURCE @@ -211,26 +211,26 @@ for RTCs that support these periodic interrupts. The third \fBioctl\fP() argument is ignored. Only a privileged process (i.e., one having the .B CAP_SYS_RESOURCE -capability) can enable the periodic interrupt if the frequency is +capability) can enable the periodic interrupt if the frequency is currently set above the value specified in .IR /proc/sys/dev/rtc/max-user-freq . .TP .BR RTC_EPOCH_READ ", " RTC_EPOCH_SET Many RTCs encode the year in an 8-bit register which is either -interpreted as an 8-bit binary number or as a BCD number. +interpreted as an 8-bit binary number or as a BCD number. In both cases, -the number is interpreted relative to this RTC's Epoch. +the number is interpreted relative to this RTC's Epoch. The RTC's Epoch is initialized to 1900 on most systems but on Alpha and MIPS it might also be initialized to 1952, 1980, or 2000, depending on the value of -an RTC register for the year. +an RTC register for the year. With some RTCs, these operations can be used to read or to set the RTC's Epoch, respectively. The third \fBioctl\fP() argument is a .I "unsigned long\ *" -or a -.IR "unsigned long" , +or a +.IR "unsigned long" , respectively, and the value returned (or assigned) is the epoch. To set the RTC's Epoch the process must be privileged (i.e., have the .B CAP_SYS_TIME @@ -257,7 +257,8 @@ The flag is used to enable or disable the alarm interrupt, or to read its current status; when using these calls, .BR RTC_AIE_ON " and " RTC_AIE_OFF -are not used. The +are not used. +The .I pending flag is used by RTC_WKALM_RD to report a pending interrupt (so it's mostly useless on Linux, except when talking @@ -289,7 +290,7 @@ status of the (first) RTC. When the kernel's system time is synchronized with an external reference using .BR adjtimex (2) -it will update a designated RTC periodically every 11 minutes. +it will update a designated RTC periodically every 11 minutes. To do so, the kernel has to briefly turn off periodic interrupts; this might affect programs using that RTC. @@ -302,7 +303,8 @@ and 2069. Some RTCs support "wildcard" values in alarm fields, to support scenarios like periodic alarms at fifteen minutes after every hour, -or on the first day of each month. Such usage is non portable; +or on the first day of each month. +Such usage is non portable; portable user space code only expects a single alarm interrupt, and will either disable or reinitialize the alarm after receiving it. diff --git a/man4/sd.4 b/man4/sd.4 index 980070b9d..6f78ff2b6 100644 --- a/man4/sd.4 +++ b/man4/sd.4 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -36,8 +36,8 @@ where .I l is a letter denoting the physical drive, and .I p -is a number denoting the partition on that physical drive. Often, the -partition number, +is a number denoting the partition on that physical drive. +Often, the partition number, .IR p , will be left off when the device corresponds to the whole drive. @@ -64,8 +64,8 @@ in the system; and will have major 8, minor 19, and will refer to the third DOS "primary" partition on the second SCSI drive in the system. -At this time, only block devices are provided. Raw devices have not yet -been implemented. +At this time, only block devices are provided. +Raw devices have not yet been implemented. .SH DESCRIPTION The following .IR ioctl s @@ -95,7 +95,8 @@ The information returned in the parameter is the disk geometry of the drive .I "as understood by DOS!" This geometry is .I not -the physical geometry of the drive. It is used when constructing the +the physical geometry of the drive. +It is used when constructing the drive's partition table, however, and is needed for convenient operation of .BR fdisk (1), @@ -107,18 +108,21 @@ of the parameters. .RE .TP BLKGETSIZE -Returns the device size in sectors. The +Returns the device size in sectors. +The .BR ioctl (2) parameter should be a pointer to a .IR long . .TP BLKRRPART -Forces a re-read of the SCSI disk partition tables. No parameter is needed. +Forces a re-read of the SCSI disk partition tables. +No parameter is needed. The .BR scsi (4) .BR ioctl (2) -operations are also supported. If the +operations are also supported. +If the .BR ioctl () parameter is required, and it is NULL, then .BR ioctl () diff --git a/man4/sk98lin.4 b/man4/sk98lin.4 index f8fb7d99d..f993b1aa5 100644 --- a/man4/sk98lin.4 +++ b/man4/sk98lin.4 @@ -59,14 +59,17 @@ sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21 .IR i,j,... ] .SH DESCRIPTION .B sk98lin -is the Gigabit Ethernet driver for Marvell and SysKonnect network adapter cards. -It supports SysKonnect SK-98xx/SK-95xx compliant Gigabit Ethernet Adapter and +is the Gigabit Ethernet driver for +Marvell and SysKonnect network adapter cards. +It supports SysKonnect SK-98xx/SK-95xx +compliant Gigabit Ethernet Adapter and any Yukon compliant chipset. -When loading the driver using insmod, parameters for the network adapter cards -might be stated as a sequence of comma separated commands. -If for instance two network adapters are installed and AutoNegotiation on -Port A of the first adapter should be ON, +When loading the driver using insmod, +parameters for the network adapter cards +might be stated as a sequence of comma separated commands. +If for instance two network adapters are installed and AutoNegotiation on +Port A of the first adapter should be ON, but on the Port A of the second adapter switched OFF, one must enter: insmod sk98lin.o AutoNeg_A=On,Off @@ -75,40 +78,41 @@ After .B sk98lin is bound to one or more adapter cards and the .IR /proc -filesystem is mounted on your system, a dedicated statistics file +filesystem is mounted on your system, a dedicated statistics file will be created in folder .IR /proc/net/sk98lin -for all ports of the installed network adapter cards. +for all ports of the installed network adapter cards. Those files are named .IR eth[x] whereas .IR x -is the number of the interface that has been assigned to a +is the number of the interface that has been assigned to a dedicated port by the system. -If loading is finished, any desired IP address can be +If loading is finished, any desired IP address can be assigned to the respective .IR eth[x] interface using the .BR ifconfig (8) -command. -This causes the adapter to connect to the Ethernet and to display a status -message on the console saying "ethx: network connection up using port y" +command. +This causes the adapter to connect to the Ethernet and to display a status +message on the console saying "ethx: network connection up using port y" followed by the configured or detected connection parameters. The .B sk98lin -also supports large frames (also called jumbo frames). -Using jumbo frames can improve throughput tremendously when -transferring large amounts of data. -To enable large frames, the MTU (maximum transfer unit) size -for an interface is to be set to a high value. -The default MTU size is 1500 and can be changed up to 9000 (bytes). -Setting the MTU size can be done when assigning the IP address +also supports large frames (also called jumbo frames). +Using jumbo frames can improve throughput tremendously when +transferring large amounts of data. +To enable large frames, the MTU (maximum transfer unit) size +for an interface is to be set to a high value. +The default MTU size is 1500 and can be changed up to 9000 (bytes). +Setting the MTU size can be done when assigning the IP address to the interface or later by using the .BR ifconfig (8) -command with the mtu parameter. If for instance eth0 needs an IP -address and a large frame MTU size, +command with the mtu parameter. +If for instance eth0 needs an IP +address and a large frame MTU size, the following two commands might be used: ifconfig eth0 10.1.1.1 @@ -118,17 +122,17 @@ Those two commands might even be combined into one: ifconfig eth0 10.1.1.1 mtu 9000 -Note that large frames can only be used if your network infrastructure -allows to do so. -This means, that any switch being used in your Ethernet must -also support large frames. -Quite some switches support large frames, +Note that large frames can only be used if your network infrastructure +allows to do so. +This means, that any switch being used in your Ethernet must +also support large frames. +Quite some switches support large frames, but need to be configured to do so. -Most of the times, their default setting is to support only -standard frames with an MTU size of 1500 (bytes). -In addition to the switches inside the network, -all network adapters that are to be used must also be -enabled regarding jumbo frames. +Most of the times, their default setting is to support only +standard frames with an MTU size of 1500 (bytes). +In addition to the switches inside the network, +all network adapters that are to be used must also be +enabled regarding jumbo frames. If an adapter is not set to receive large frames it will simply drop them. Switching back to the standard Ethernet frame size can be done by using the @@ -137,9 +141,9 @@ command again: ifconfig eth0 mtu 1500 -The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to -support VLAN and Link Aggregation according to -IEEE standards 802.1, 802.1q, and 802.3ad. +The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to +support VLAN and Link Aggregation according to +IEEE standards 802.1, 802.1q, and 802.3ad. Those features are only available after installation of open source modules which can be found on the Internet: @@ -151,15 +155,15 @@ which can be found on the Internet: : http://www.st.rim.or.jp/~yumo .br -Note that Marvell/SysKonnect does not offer any support for these -open source modules and does not take the responsibility for any +Note that Marvell/SysKonnect does not offer any support for these +open source modules and does not take the responsibility for any kind of failures or problems arising when using these modules. .SH PARAMETERS .TP .BI Speed_A= i,j,... -This parameter is used to set the speed capabilities of port A of an -adapter card. -It is only valid for Yukon copper adapters. +This parameter is used to set the speed capabilities of port A of an +adapter card. +It is only valid for Yukon copper adapters. Possible values are: .IR 10 , .IR 100 , @@ -168,15 +172,16 @@ or .IR Auto whereas .IR Auto -is the default. -Usually, the speed is negotiated between the two ports -during link establishment. -If this fails, a port can be forced to a specific setting with this parameter. +is the default. +Usually, the speed is negotiated between the two ports +during link establishment. +If this fails, +a port can be forced to a specific setting with this parameter. .TP .BI Speed_B= i,j,... -This parameter is used to set the speed capabilities of port B of -an adapter card. -It is only valid for Yukon copper adapters. +This parameter is used to set the speed capabilities of port B of +an adapter card. +It is only valid for Yukon copper adapters. Possible values are: .IR 10 , .IR 100 , @@ -185,13 +190,14 @@ or .IR Auto whereas .IR Auto -is the default. -Usually, the speed is negotiated between the two ports during link -establishment. -If this fails, a port can be forced to a specific setting with this parameter. +is the default. +Usually, the speed is negotiated between the two ports during link +establishment. +If this fails, +a port can be forced to a specific setting with this parameter. .TP .BI AutoNeg_A= i,j,... -Enables or disables the use of autonegotiation of port A of an adapter card. +Enables or disables the use of autonegotiation of port A of an adapter card. Possible values are: .IR On , .IR Off @@ -199,13 +205,14 @@ or .IR Sense whereas .IR On -is the default. The +is the default. +The .IR Sense -mode automatically detects whether the link partner supports +mode automatically detects whether the link partner supports auto-negotiation or not. .TP .BI AutoNeg_B= i,j,... -Enables or disables the use of autonegotiation of port B of an adapter card. +Enables or disables the use of autonegotiation of port B of an adapter card. Possible values are: .IR On , .IR Off @@ -213,14 +220,15 @@ or .IR Sense whereas .IR On -is the default. The +is the default. +The .IR Sense -mode automatically detects whether the link partner supports +mode automatically detects whether the link partner supports auto-negotiation or not. .TP .BI DupCap_A= i,j,... -This parameter indicates the duplex mode to be used for port A -of an adapter card. +This parameter indicates the duplex mode to be used for port A +of an adapter card. Possible values are: .IR Half , .IR Full @@ -238,19 +246,20 @@ all three values of DupCap_A ( .IR Full or .IR Both ) -might be stated. If AutoNeg_A is set to +might be stated. +If AutoNeg_A is set to .IR Off , only DupCap_A values .IR Full and .IR Half -are allowed. -This DupCap_A parameter is useful if your link partner does not +are allowed. +This DupCap_A parameter is useful if your link partner does not support all possible duplex combinations. .TP .BI DupCap_B= i,j,... -This parameter indicates the duplex mode to be used for port B -of an adapter card. +This parameter indicates the duplex mode to be used for port B +of an adapter card. Possible values are: .IR Half , .IR Full @@ -258,7 +267,7 @@ or .IR Both whereas .IR Both -is the default. +is the default. This parameter is only relevant if AutoNeg_B of port B is not set to .IR Sense . If AutoNeg_B is set to @@ -268,19 +277,20 @@ all three values of DupCap_B ( .IR Full or .IR Both ) -might be stated. If AutoNeg_B is set to +might be stated. +If AutoNeg_B is set to .IR Off , only DupCap_B values .IR Full and .IR Half -are allowed. -This DupCap_B parameter is useful if your link partner does not +are allowed. +This DupCap_B parameter is useful if your link partner does not support all possible duplex combinations. .TP .BI FlowCtrl_A= i,j,... -This parameter can be used to set the flow control capabilities the -port reports during auto-negotiation. +This parameter can be used to set the flow control capabilities the +port reports during auto-negotiation. Possible values are: .IR Sym , .IR SymOrRem , @@ -289,7 +299,8 @@ or .IR None whereas .IR SymOrRem -is the default. The different modes have the following meaning: +is the default. +The different modes have the following meaning: .br .IR Sym @@ -312,8 +323,8 @@ Note that this parameter is ignored if AutoNeg_A is set to .IR Off . .TP .BI FlowCtrl_B= i,j,... -This parameter can be used to set the flow control capabilities the -port reports during auto-negotiation. +This parameter can be used to set the flow control capabilities the +port reports during auto-negotiation. Possible values are: .IR Sym , .IR SymOrRem , @@ -322,7 +333,8 @@ or .IR None whereas .IR SymOrRem -is the default. The different modes have the following meaning: +is the default. +The different modes have the following meaning: .IR Sym = Symmetric @@ -345,10 +357,10 @@ Note that this parameter is ignored if AutoNeg_B is set to .IR Off . .TP .BI Role_A= i,j,... -This parameter is only valid for 1000Base-T adapter cards. -For two 1000Base-T ports to communicate, -one must take the role of the master (providing timing information), -while the other must be the slave. +This parameter is only valid for 1000Base-T adapter cards. +For two 1000Base-T ports to communicate, +one must take the role of the master (providing timing information), +while the other must be the slave. Possible values are: .IR Auto , .IR Master @@ -356,16 +368,16 @@ or .IR Slave whereas .IR Auto -is the default. -Usually, the role of a port is negotiated between two ports during -link establishment, but if that fails the port A of an adapter card +is the default. +Usually, the role of a port is negotiated between two ports during +link establishment, but if that fails the port A of an adapter card can be forced to a specific setting with this parameter. .TP .BI Role_B= i,j,... -This parameter is only valid for 1000Base-T adapter cards. -For two 1000Base-T ports to communicate, one must take -the role of the master (providing timing information), -while the other must be the slave. +This parameter is only valid for 1000Base-T adapter cards. +For two 1000Base-T ports to communicate, one must take +the role of the master (providing timing information), +while the other must be the slave. Possible values are: .IR Auto , .IR Master @@ -373,18 +385,18 @@ or .IR Slave whereas .IR Auto -is the default. -Usually, the role of a port is negotiated between -two ports during link establishment, but if that fails -the port B of an adapter card can be forced to a +is the default. +Usually, the role of a port is negotiated between +two ports during link establishment, but if that fails +the port B of an adapter card can be forced to a specific setting with this parameter. .TP .BI ConType= i,j,... -This parameter is a combination of all five per-port parameters -within one single parameter. -This simplifies the configuration of both ports of an adapter card. -The different values of this variable reflect the -most meaningful combinations of port parameters. +This parameter is a combination of all five per-port parameters +within one single parameter. +This simplifies the configuration of both ports of an adapter card. +The different values of this variable reflect the +most meaningful combinations of port parameters. Possible values and their corresponding combination of per-port parameters: .br @@ -410,7 +422,7 @@ ConType | DupCap AutoNeg FlowCtrl Role Speed .ad b Stating any other port parameter together with this .IR ConType -parameter will result in a merged configuration of those settings. +parameter will result in a merged configuration of those settings. This is due to the fact, that the per-port parameters (e.g. .IR Speed_A ) @@ -418,60 +430,62 @@ have a higher priority than the combined variable .IR ConType . .TP .BI Moderation= i,j,... -Interrupt moderation is employed to limit the maximum number of interrupts -the driver has to serve. -That is, one or more interrupts (which indicate any transmit or -receive packet to be processed) are queued until the driver processes them. +Interrupt moderation is employed to limit the maximum number of interrupts +the driver has to serve. +That is, one or more interrupts (which indicate any transmit or +receive packet to be processed) are queued until the driver processes them. When queued interrupts are to be served, is determined by the .IR IntsPerSec -parameter, which is explained later below. Possible moderation modes are: +parameter, which is explained later below. +Possible moderation modes are: .IR None , .IR Static or .IR Dynamic whereas .IR None -is the default. The different modes have the following meaning: +is the default. +The different modes have the following meaning: .IR None -No interrupt moderation is applied on the adapter card. -Therefore, each transmit or receive interrupt is served immediately +No interrupt moderation is applied on the adapter card. +Therefore, each transmit or receive interrupt is served immediately as soon as it appears on the interrupt line of the adapter card. .br .IR Static -Interrupt moderation is applied on the adapter card. -All transmit and receive interrupts are queued until -a complete moderation interval ends. -If such a moderation interval ends, all queued interrupts -are processed in one big bunch without any delay. +Interrupt moderation is applied on the adapter card. +All transmit and receive interrupts are queued until +a complete moderation interval ends. +If such a moderation interval ends, all queued interrupts +are processed in one big bunch without any delay. The term .IR Static -reflects the fact, that interrupt moderation is always enabled, -regardless how much network load is currently passing via a -particular interface. -In addition, the duration of the moderation interval has a fixed +reflects the fact, that interrupt moderation is always enabled, +regardless how much network load is currently passing via a +particular interface. +In addition, the duration of the moderation interval has a fixed length that never changes while the driver is operational. .br .IR Dynamic -Interrupt moderation might be applied on the adapter card, -depending on the load of the system. -If the driver detects that the system load is too high, -the driver tries to shield the system against too much network -load by enabling interrupt moderation. -If \(em at a later time \(em the CPU utilization decreases -again (or if the network load is negligible) the interrupt +Interrupt moderation might be applied on the adapter card, +depending on the load of the system. +If the driver detects that the system load is too high, +the driver tries to shield the system against too much network +load by enabling interrupt moderation. +If \(em at a later time \(em the CPU utilization decreases +again (or if the network load is negligible) the interrupt moderation will automatically be disabled. -Interrupt moderation should be used when the driver has to -handle one or more interfaces with a high network load, -which \(em as a consequence \(em leads also to a high CPU utilization. -When moderation is applied in such high network load situations, +Interrupt moderation should be used when the driver has to +handle one or more interfaces with a high network load, +which \(em as a consequence \(em leads also to a high CPU utilization. +When moderation is applied in such high network load situations, CPU load might be reduced by 20-30% on slow computers. -Note that the drawback of using interrupt moderation is an increase of -the round-trip-time (RTT), due to the queuing and serving of +Note that the drawback of using interrupt moderation is an increase of +the round-trip-time (RTT), due to the queuing and serving of interrupts at dedicated moderation times. .TP .BI IntsPerSec= i,j,... @@ -479,26 +493,27 @@ This parameter determines the length of any interrupt moderation interval. Assuming that static interrupt moderation is to be used, an .IR IntsPerSec parameter value of 2000 will lead to an interrupt moderation interval of -500 microseconds. -Possible values for this parameter are in the range of -30...40000 (interrupts per second). +500 microseconds. +Possible values for this parameter are in the range of +30...40000 (interrupts per second). The default value is 2000. This parameter is only used, if either static or dynamic interrupt moderation -is enabled on a network adapter card. +is enabled on a network adapter card. This parameter is ignored if no moderation is applied. Note that the duration of the moderation interval is to be chosen with care. At first glance, selecting a very long duration (e.g. only 100 interrupts per second) seems to be meaningful, but the increase of packet-processing delay -is tremendous. On the other hand, selecting a very short moderation time might +is tremendous. +On the other hand, selecting a very short moderation time might compensate the use of any moderation being applied. .TP .BI PrefPort= i,j,... -This parameter is used to force the preferred port to -A or B (on dual-port network adapters). -The preferred port is the one that is used if both ports A and B are -detected as fully functional. +This parameter is used to force the preferred port to +A or B (on dual-port network adapters). +The preferred port is the one that is used if both ports A and B are +detected as fully functional. Possible values are: .IR A or @@ -508,11 +523,11 @@ whereas is the default. .TP .BI RlmtMode= i,j,... -RLMT monitors the status of the port. -If the link of the active port fails, -RLMT switches immediately to the standby link. +RLMT monitors the status of the port. +If the link of the active port fails, +RLMT switches immediately to the standby link. The virtual link is maintained as long as at least one 'physical' link is up. -This parameters states how RLMT should monitor both ports. +This parameters states how RLMT should monitor both ports. Possible values are: .IR CheckLinkState , .IR CheckLocalPort , @@ -521,53 +536,55 @@ or .IR DualNet whereas .IR CheckLinkState -is the default. The different modes have the following meaning: +is the default. +The different modes have the following meaning: .IR CheckLinkState -Check link state only: RLMT uses the link state reported by the adapter -hardware for each individual port to determine whether a port can be used +Check link state only: RLMT uses the link state reported by the adapter +hardware for each individual port to determine whether a port can be used for all network traffic or not. .br .IR CheckLocalPort -In this mode, RLMT monitors the network path between the two -ports of an adapter by regularly exchanging packets between them. -This mode requires a network configuration in which the -two ports are able to "see" each other (i.e. there +In this mode, RLMT monitors the network path between the two +ports of an adapter by regularly exchanging packets between them. +This mode requires a network configuration in which the +two ports are able to "see" each other (i.e. there must not be any router between the ports). .br .IR CheckSeg -Check local port and segmentation: -This mode supports the same functions as the CheckLocalPort -mode and additionally checks network segmentation between the ports. -Therefore, this mode is only to be used if Gigabit Ethernet -switches are installed on the network that have been +Check local port and segmentation: +This mode supports the same functions as the CheckLocalPort +mode and additionally checks network segmentation between the ports. +Therefore, this mode is only to be used if Gigabit Ethernet +switches are installed on the network that have been configured to use the Spanning Tree protocol. .br .IR DualNet -In this mode, ports A and B are used as separate devices. +In this mode, ports A and B are used as separate devices. If you have a dual port adapter, port A will be configured as .IR eth[x] and port B as .IR eth[x+1] . Both ports can be used independently with distinct IP addresses. -The preferred port setting is not used. RLMT is turned off. +The preferred port setting is not used. +RLMT is turned off. Note that RLMT modes .IR CheckLocalPort and .IR CheckLinkState -are designed to operate in configurations where a -network path between the ports on one adapter exists. -Moreover, they are not designed to work where adapters are +are designed to operate in configurations where a +network path between the ports on one adapter exists. +Moreover, they are not designed to work where adapters are connected back-to-back. .SH FILES .TP .I /proc/net/sk98lin/eth[x] .br -The statistics file of a particular interface of an adapter card. -It contains generic information about the adapter card plus a detailed +The statistics file of a particular interface of an adapter card. +It contains generic information about the adapter card plus a detailed summary of all transmit and receive counters. .TP .I /usr/src/linux/Documentation/network/sk98lin.txt @@ -576,9 +593,9 @@ This is the .IR README file of the .IR sk98lin -driver. -It contains a detailed installation HOWTO and describes all parameters -of the driver. +driver. +It contains a detailed installation HOWTO and describes all parameters +of the driver. It denotes also common problems and provides the solution to them. .SH BUGS Report any bugs to linux@syskonnect.de diff --git a/man4/st.4 b/man4/st.4 index 7f19c70d2..65e79d540 100644 --- a/man4/st.4 +++ b/man4/st.4 @@ -42,9 +42,11 @@ The .B st driver uses major device number 9. .PP -Each device uses eight minor device numbers. The lowermost five bits +Each device uses eight minor device numbers. +The lowermost five bits in the minor numbers are assigned sequentially in the order of -detection. In the 2.6 kernel, the bits above the eight lowermost bits are +detection. +In the 2.6 kernel, the bits above the eight lowermost bits are concatenated to the five lowermost bits to form the tape number. The minor numbers can be grouped into two sets of four numbers: the principal (auto-rewind) minor device numbers, @@ -61,12 +63,14 @@ beginning of the tape). .PP Within each group, four minor numbers are available to define devices with different characteristics (block size, compression, -density, etc.) When the system starts up, only the first device is -available. The other three are activated when the default +density, etc.) +When the system starts up, only the first device is available. +The other three are activated when the default characteristics are defined (see below). (By changing compile-time constants, it is possible to change the balance between the maximum number of tape drives and the number of minor numbers for each -drive. The default allocation allows control of 32 tape drives. +drive. +The default allocation allows control of 32 tape drives. For instance, it is possible to control up to 64 tape drives with two minor numbers for different options.) .PP @@ -88,28 +92,36 @@ mknod \-m 666 /dev/nst0a c 9 224 There is no corresponding block device. .PP The driver uses an internal buffer that has to be large enough to hold -at least one tape block. In kernels before 2.1.121, the buffer is -allocated as one contiguous block. This limits the block size to the +at least one tape block. +In kernels before 2.1.121, the buffer is +allocated as one contiguous block. +This limits the block size to the largest contiguous block of memory the kernel allocator can provide. The limit is currently 128 kB for 32-bit architectures and -256 kB for 64-bit architectures. In newer kernels the driver -allocates the buffer in several parts if necessary. By default, the -maximum number of parts is 16. This means that the maximum block size +256 kB for 64-bit architectures. +In newer kernels the driver +allocates the buffer in several parts if necessary. +By default, the +maximum number of parts is 16. +This means that the maximum block size is very large (2 MB if allocation of 16 blocks of 128 kB succeeds). .PP The driver's internal buffer size is determined by a compile-time constant which can be overridden with a kernel startup option. In addition to this, the driver tries to allocate a larger temporary -buffer at run-time if necessary. However, run-time allocation of large +buffer at run-time if necessary. +However, run-time allocation of large contiguous blocks of memory may fail and it is advisable not to rely too much on dynamic buffer allocation with kernels older than 2.1.121 (this applies also to demand-loading the driver with kerneld or kmod). .PP The driver does not specifically support any tape drive brand or -model. After system start-up the tape device options are defined by +model. +After system start-up the tape device options are defined by the drive firmware. For example, if the drive firmware selects fixed-block mode, -the tape device uses fixed-block mode. The options can +the tape device uses fixed-block mode. +The options can be changed with explicit .BR ioctl () calls and remain in effect when the device is closed and reopened. @@ -117,28 +129,34 @@ Setting the options affects both the auto-rewind and the non-rewind device. .PP Different options can be specified for the different devices within -the subgroup of four. The options take effect when the device is -opened. For example, the system administrator can define +the subgroup of four. +The options take effect when the device is +opened. +For example, the system administrator can define one device that writes in fixed-block mode with a certain block size, and one which writes in variable-block mode (if the drive supports both modes). .PP The driver supports .B tape partitions -if they are supported by the drive. (Note that the tape partitions -have nothing to do with disk partitions. A partitioned tape can be -seen as several logical tapes within one medium.) Partition -support has to be enabled with an -.BR ioctl (). +if they are supported by the drive. +(Note that the tape partitions +have nothing to do with disk partitions. +A partitioned tape can be +seen as several logical tapes within one medium.) +Partition support has to be enabled with an +.BR ioctl (). The tape location is preserved within each partition across partition changes. The partition used for subsequent tape operations is -selected with an -.BR ioctl (). +selected with an +.BR ioctl (). The partition switch is executed together with the next tape operation in order to avoid unnecessary tape -movement. The maximum number of partitions on a tape is defined by a -compile-time constant (originally four). The driver contains an +movement. +The maximum number of partitions on a tape is defined by a +compile-time constant (originally four). +The driver contains an .BR ioctl () that can format a tape with either one or two partitions. .PP @@ -158,28 +176,35 @@ writes blocks of the specified size and the block size is not dependent on the byte counts of the write system calls. In variable-block mode one tape block is written for each write call and the byte -count determines the size of the corresponding tape block. Note that +count determines the size of the corresponding tape block. +Note that the blocks on the tape don't contain any information about the writing mode: when reading, the only important thing is to use commands that accept the block sizes on the tape. .PP In variable-block mode the read byte count does not have to match -the tape block size exactly. If the byte count is larger than the +the tape block size exactly. +If the byte count is larger than the next block on tape, the driver returns the data and the function -returns the actual block size. If the block size is larger than the +returns the actual block size. +If the block size is larger than the byte count, the requested amount of data from the start of the block is returned and the rest of the block is discarded. .PP In fixed-block mode the read byte counts can be arbitrary if buffering is enabled, or a multiple of the tape block size if -buffering is disabled. Kernels before 2.1.121 allow writes with -arbitrary byte count if buffering is enabled. In all other cases +buffering is disabled. +Kernels before 2.1.121 allow writes with +arbitrary byte count if buffering is enabled. +In all other cases (kernel before 2.1.121 with buffering disabled or newer kernel) the write byte count must be a multiple of the tape block size. .PP In the 2.6 kernel, the driver tries to use direct transfers between the user -buffer and the device. If this is not possible, the driver's internal buffer -is used. The reasons for not using direct transfers include improper alignment +buffer and the device. +If this is not possible, the driver's internal buffer +is used. +The reasons for not using direct transfers include improper alignment of the user buffer (default is 512 bytes but this can be changed by the HBA driver), one of more pages of the user buffer not reachable by the SCSI adapter, etc. @@ -188,14 +213,19 @@ A filemark is automatically written to tape if the last tape operation before close was a write. .PP When a filemark is encountered while reading, the following -happens. If there are data remaining in the buffer when the filemark -is found, the buffered data is returned. The next read returns zero -bytes. The following read returns data from the next file. The end of +happens. +If there are data remaining in the buffer when the filemark +is found, the buffered data is returned. +The next read returns zero +bytes. +The following read returns data from the next file. +The end of recorded data is signaled by returning zero bytes for two consecutive -read calls. The third read returns an error. +read calls. +The third read returns an error. .SH IOCTLS -The driver supports three -.BR ioctl () +The driver supports three +.BR ioctl () requests. Requests not recognized by the .B st @@ -243,12 +273,15 @@ Enable compression of tape data within the drive if .B mt_count is non-zero and disable compression if .B mt_count -is zero. This command uses the MODE page 15 supported by most DATs. +is zero. +This command uses the MODE page 15 supported by most DATs. .IP MTEOM Go to the end of the recorded media (for appending files). .IP MTERASE -Erase tape. With 2.6 kernel, short erase (mark tape empty) is performed if the -argument is zero. Otherwise long erase (erase all) is done. +Erase tape. +With 2.6 kernel, short erase (mark tape empty) is performed if the +argument is zero. +Otherwise long erase (erase all) is done. .IP MTFSF Forward space over .B mt_count @@ -267,18 +300,22 @@ Forward space over .B mt_count setmarks. .IP MTLOAD -Execute the SCSI load command. A special case is available for some HP -autoloaders. If +Execute the SCSI load command. +A special case is available for some HP +autoloaders. +If .B mt_count is the constant MT_ST_HPLOADER_OFFSET plus a number, the number is sent to the drive to control the autoloader. .IP MTLOCK Lock the tape drive door. .IP MTMKPART -Format the tape into one or two partitions. If +Format the tape into one or two partitions. +If .B mt_count is non-zero, it gives the size of the first partition and the second -partition contains the rest of the tape. If +partition contains the rest of the tape. +If .B mt_count is zero, the tape is formatted into one partition. This command is not allowed for a drive unless the partition support @@ -315,7 +352,8 @@ documentation. .IP MTSETPART The active partition is switched to .BR mt_count . -The partitions are numbered from zero. This command is not allowed for +The partitions are numbered from zero. +This command is not allowed for a drive unless the partition support is enabled for the drive (see MT_ST_CAN_PARTITIONS below). .IP MTUNLOAD @@ -382,14 +420,17 @@ must include one of the constants \s-1MT_ST_BOOLEANS\s+1, \s-1MT_ST_DEFBOOLEANS\s+1 logically or'ed with whatever combination of the following options is desired. Using \s-1MT_ST_BOOLEANS\s+1 the options can be set to the values -defined in the corresponding bits. With \s-1MT_ST_SETBOOLEANS\s+1 the +defined in the corresponding bits. +With \s-1MT_ST_SETBOOLEANS\s+1 the options can be selectively set and with \s-1MT_ST_DEFBOOLEANS\s+1 selectively cleared. .IP "" The default options for a tape device are set with -\s-1MT_ST_DEFBOOLEANS\s+1. A non-active tape device (e.g., device with +\s-1MT_ST_DEFBOOLEANS\s+1. +A non-active tape device (e.g., device with minor 32 or 160) is activated when the default options for it are -defined the first time. An activated device inherits from the device +defined the first time. +An activated device inherits from the device activated at start-up the options not set explicitly. .IP "" The Boolean options are: @@ -426,7 +467,8 @@ Note: This option should not be set true for QIC tape drives since they are unable to overwrite a filemark. These drives detect the end of recorded data by testing for blank tape -rather than two consecutive filemarks. Most other current drives also +rather than two consecutive filemarks. +Most other current drives also detect the end of recorded data and using two filemarks is usually necessary only when interchanging tapes with some other systems. .PP @@ -449,46 +491,61 @@ opened and unlocked when it is closed. The tape options (block size, mode, compression, etc.) may change when changing from one device linked to a drive to another device linked to the same drive depending on how the devices are -defined. This option defines when the changes are enforced by the +defined. +This option defines when the changes are enforced by the driver using SCSI-commands and when the drives auto-detection -capabilities are relied upon. If this option is false, the driver -sends the SCSI-commands immediately when the device is changed. If the +capabilities are relied upon. +If this option is false, the driver +sends the SCSI-commands immediately when the device is changed. +If the option is true, the SCSI-commands are not sent until a write is -requested. In this case the drive firmware is allowed to detect the +requested. +In this case the drive firmware is allowed to detect the tape structure when reading and the SCSI-commands are used only to make sure that a tape is written according to the correct specification. .IP "\s-1MT_ST_CAN_BSR\s+1 (Default: false)" When read-ahead is used, the tape must sometimes be spaced backward to the correct position when the device is closed and the SCSI command to -space backwards over records is used for this purpose. Some older +space backwards over records is used for this purpose. +Some older drives can't process this command reliably and this option can be used -to instruct the driver not to use the command. The end result is that, +to instruct the driver not to use the command. +The end result is that, with read-ahead and fixed-block mode, the tape may not be correctly -positioned within a file when the device is closed. With 2.6 kernel, the +positioned within a file when the device is closed. +With 2.6 kernel, the default is true for drives supporting SCSI-3. .IP "\s-1MT_ST_NO_BLKLIMS\s+1 (Default: false)" -Some drives don't accept the READ BLOCK LIMITS SCSI command. If -this is used, the driver does not use the command. The drawback is +Some drives don't accept the READ BLOCK LIMITS SCSI command. +If +this is used, the driver does not use the command. +The drawback is that the driver can't check before sending commands if the selected block size is acceptable to the drive. .IP "\s-1MT_ST_CAN_PARTITIONS\s+1 (Default: false)" This option enables support for several partitions within a -tape. The option applies to all devices linked to a drive. +tape. +The option applies to all devices linked to a drive. .IP "\s-1MT_ST_SCSI2LOGICAL\s+1 (Default: false)" This option instructs the driver to use the logical block addresses defined in the SCSI-2 standard when performing the seek and tell operations (both with MTSEEK and MTIOCPOS commands and when changing tape -partition). Otherwise the device-specific addresses are used. +partition). +Otherwise the device-specific addresses are used. It is highly advisable to set this option if the drive supports the -logical addresses because they count also filemarks. There are some +logical addresses because they count also filemarks. +There are some drives that only support the logical block addresses. .IP "\s-1MT_ST_SYSV\s+1 (Default: false)" When this option is enabled, the tape devices use the SystemV -semantics. Otherwise the BSD semantics are used. The most important +semantics. +Otherwise the BSD semantics are used. +The most important difference between the semantics is what happens when a device used for reading is closed: in System V semantics the tape is spaced forward past the next filemark if this has not happened while using the -device. In BSD semantics the tape position is not changed. +device. +In BSD semantics the tape position is not changed. .IP "\s-1MT_NO_WAIT\s+1 (Default: false)" Enables immediate mode (i.e., don't wait for the command to finish) for some commands (e.g., rewind). @@ -507,32 +564,43 @@ commands (e.g., rewind). .IP "" The default block size for a device can be set with \s-1MT_ST_DEF_BLKSIZE\s+1 and the default density code can be set with -\s-1MT_ST_DEFDENSITY\s+1. The values for the parameters are or'ed +\s-1MT_ST_DEFDENSITY\s+1. +The values for the parameters are or'ed with the operation code. .IP "" With kernels 2.1.x and later, the timeout values can be set with the subcommand \s-1MT_ST_SET_TIMEOUT\s+1 ORed with the timeout in seconds. The long timeout (used for rewinds and other commands that may take a long time) can be set with -\s-1MT_ST_SET_LONG_TIMEOUT\s+1. The kernel defaults are very long to +\s-1MT_ST_SET_LONG_TIMEOUT\s+1. +The kernel defaults are very long to make sure that a successful command is not timed out with any -drive. Because of this the driver may seem stuck even if it is only -waiting for the timeout. These commands can be used to set more -practical values for a specific drive. The timeouts set for one device +drive. +Because of this the driver may seem stuck even if it is only +waiting for the timeout. +These commands can be used to set more +practical values for a specific drive. +The timeouts set for one device apply for all devices linked to the same drive. .IP "" Starting from kernels 2.4.19 and 2.5.43, the driver supports a status bit which indicates whether the drive requests cleaning. The method used by the drive to return cleaning information is set using the -\s-1MT_ST_SEL_CLN\s+1 subcommand. If the value is zero, the cleaning -bit is always zero. If the value is one, the TapeAlert data defined -in the SCSI-3 standard is used (not yet implemented). Values 2-17 are -reserved. If the lowest eight bits are >= 18, bits from the extended -sense data are used. The bits 9-16 specify a mask to select the bits +\s-1MT_ST_SEL_CLN\s+1 subcommand. +If the value is zero, the cleaning +bit is always zero. +If the value is one, the TapeAlert data defined +in the SCSI-3 standard is used (not yet implemented). +Values 2-17 are +reserved. +If the lowest eight bits are >= 18, bits from the extended +sense data are used. +The bits 9-16 specify a mask to select the bits to look at and the bits 17-23 specify the bit pattern to look for. If the bit pattern is zero, one or more bits under the mask indicate -the cleaning request. If the pattern is non-zero, the pattern must match +the cleaning request. +If the pattern is non-zero, the pattern must match the masked sense data byte. .SS "\s-1MTIOCGET\s+1 \(em Get status" .PP @@ -607,13 +675,16 @@ density setting for 9-track \(12" tape drives only. The drive does not have a tape in place. .HP \s-1GMT_IM_REP_EN(\s+1\fIx\fP\s-1)\s+1: -Immediate report mode. This bit is set if there are no guarantees that +Immediate report mode. +This bit is set if there are no guarantees that the data has been physically written to the tape when the write call -returns. It is set zero only when the driver does not buffer data and +returns. +It is set zero only when the driver does not buffer data and the drive is set not to buffer data. .HP \s-1GMT_CLN(\s+1\fIx\fP\s-1)\s+1: -The drive has requested cleaning. Implemented in kernels >= 2.4.19 and 2.5.43. +The drive has requested cleaning. +Implemented in kernels >= 2.4.19 and 2.5.43. .RE .IP \fBmt_erreg\fP The only field defined in @@ -660,10 +731,10 @@ The requested operation could not be completed. A write operation could not be completed because the tape reached end-of-medium. .IP ENOMEM -The byte count in +The byte count in .BR read () -is smaller than the next physical block on -the tape. (Before 2.2.18 and 2.4.0-test6 the extra bytes have been +is smaller than the next physical block on the tape. +(Before 2.2.18 and 2.4.0-test6 the extra bytes have been silently ignored.) .IP EACCES An attempt was made to write or erase a write-protected tape. @@ -696,7 +767,8 @@ write-protected. /dev/nst* : the non-rewind SCSI tape devices .SH AUTHOR The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi) -starting from a driver written by Dwayne Forsyth. Several other +starting from a driver written by Dwayne Forsyth. +Several other people have also contributed to the driver. .SH "SEE ALSO" .BR mt (1) @@ -706,37 +778,46 @@ the most recent information about the driver and its configuration possibilities. .SH NOTES 1. When exchanging data between systems, both systems have to agree on -the physical tape block size. The parameters of a drive after startup +the physical tape block size. +The parameters of a drive after startup are often not the ones most operating systems use with these -devices. Most systems use drives in variable-block mode if the drive -supports that mode. This applies to most modern drives, including -DATs, 8mm helical scan drives, DLTs, etc. It may be advisable to use +devices. +Most systems use drives in variable-block mode if the drive +supports that mode. +This applies to most modern drives, including +DATs, 8mm helical scan drives, DLTs, etc. +It may be advisable to use these drives in variable-block mode also in Linux (i.e., use MTSETBLK or MTSETDEFBLK at system startup to set the mode), at least when -exchanging data with a foreign system. The drawback of +exchanging data with a foreign system. +The drawback of this is that a fairly large tape block size has to be used to get acceptable data transfer rates on the SCSI bus. .PP 2. Many programs (e.g., tar) allow the user to specify the blocking -factor on the command line. Note that this determines the physical block +factor on the command line. +Note that this determines the physical block size on tape only in variable-block mode. .PP 3. In order to use SCSI tape drives, the basic SCSI driver, a SCSI-adapter driver and the SCSI tape driver must be either -configured into the kernel or loaded as modules. If the SCSI-tape +configured into the kernel or loaded as modules. +If the SCSI-tape driver is not present, the drive is recognized but the tape support described in this page is not available. .PP -4. The driver writes error messages to the console/log. The SENSE +4. The driver writes error messages to the console/log. +The SENSE codes written into some messages are automatically translated to text if verbose SCSI messages are enabled in kernel configuration. .PP 5. The driver's internal buffering allows good throughput in fixed-block -mode also with small -.BR read () -and -.BR write () -byte counts. With direct transfers +mode also with small +.BR read () +and +.BR write () +byte counts. +With direct transfers this is not possible and may cause a surprise when moving to the 2.6 kernel. The solution is to tell the software to use larger transfers (often diff --git a/man4/tty.4 b/man4/tty.4 index bcfa9e783..cd451a703 100644 --- a/man4/tty.4 +++ b/man4/tty.4 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2003-04-07 by Michael Kerrisk .\" @@ -28,8 +28,8 @@ tty \- controlling terminal .SH DESCRIPTION The file \fI/dev/tty\fP is a character file with major number 5 and -minor number 0, usually of mode 0666 and owner.group root.tty. It is a -synonym for the controlling terminal of a process, if any. +minor number 0, usually of mode 0666 and owner.group root.tty. +It is a synonym for the controlling terminal of a process, if any. .LP In addition to the \fBioctl\fP() requests supported by the device that \fBtty\fP refers to, the \fBioctl\fP() request \fBTIOCNOTTY\fP is supported. diff --git a/man4/tty_ioctl.4 b/man4/tty_ioctl.4 index 3c57dd6ce..d5668b38a 100644 --- a/man4/tty_ioctl.4 +++ b/man4/tty_ioctl.4 @@ -7,9 +7,9 @@ tty ioctl \- ioctls for terminals and serial lines .SH SYNOPSIS .sp -.BR "#include " +.BR "#include " .sp -.BI "int ioctl(int " fd ", int " cmd ", ...);" +.BI "int ioctl(int " fd ", int " cmd ", ...);" .SH DESCRIPTION The .BR ioctl () @@ -19,7 +19,8 @@ or \fIarg\fP. .LP Use of .I ioctl -makes for non-portable programs. Use the POSIX interface described in +makes for non-portable programs. +Use the POSIX interface described in .BR termios (3) whenever possible. .SS "Get and Set Terminal Attributes" @@ -64,17 +65,19 @@ instead of a .TP .BI "TCSETAF const struct termio *" argp .SS "Locking the termios structure" -The termios structure of a tty can be locked. The lock is itself +The termios structure of a tty can be locked. +The lock is itself a termios structure, with non-zero bits or fields indicating a locked value. .TP .BI "TIOCGLCKTRMIOS struct termios *" argp -Gets the locking status of the termios structure of +Gets the locking status of the termios structure of the terminal. .TP .BI "TIOCSLCKTRMIOS const struct termios *" argp -Sets the locking status of the termios structure of -the terminal. Only root can do this. +Sets the locking status of the termios structure of +the terminal. +Only root can do this. .SS "Get and Set Window Size" Window sizes are kept in the kernel, but not used by the kernel (except in the case of virtual consoles, where the kernel will @@ -109,7 +112,8 @@ Equivalent to If the terminal is using asynchronous serial data transmission, and .I arg is zero, then send a break (a stream of zero bits) for between -0.25 and 0.5 seconds. If the terminal is not using asynchronous +0.25 and 0.5 seconds. +If the terminal is not using asynchronous serial data transmission, then either a break is sent, or the function returns without doing anything. When @@ -135,7 +139,8 @@ HP-UX ignores .IR arg .) .TP .BI "TCSBRKP int " arg -So-called "POSIX version" of TCSBRK. It treats non-zero +So-called "POSIX version" of TCSBRK. +It treats non-zero .I arg as a timeinterval measured in deciseconds, and does nothing when the driver does not support breaks. @@ -183,7 +188,8 @@ Redirect output that would have gone to .I /dev/console or .I /dev/tty0 -to the given tty. If that was a pty master, send it to the slave. +to the given tty. +If that was a pty master, send it to the slave. Anybody can do this as long as the output was not redirected yet. If it was redirected already EBUSY is returned, but root may stop redirection by using this ioctl with @@ -197,7 +203,8 @@ or .BI "TIOCSCTTY int " arg Make the given tty the controlling tty of the current process. The current process must be a session leader and not have a -controlling tty already. If this tty is already the controlling tty +controlling tty already. +If this tty is already the controlling tty of a different session group then the ioctl fails with EPERM, unless the caller is root and .I arg @@ -206,7 +213,8 @@ it as controlling tty lose it. .TP .BI TIOCNOTTY void If the given tty was the controlling tty of the current process, -give up this controlling tty. If the process was session leader, +give up this controlling tty. +If the process was session leader, then send SIGHUP and SIGCONT to the foreground process group and all processes in the current session lose their controlling tty. .SS "Process group and session ID" @@ -224,8 +232,10 @@ Equivalent to Set the foreground process group ID of this tty. .TP .BI "TIOCGSID pid_t *" argp -Get the session ID of the given tty. This will fail with ENOTTY -in case the tty is not a master pty and not our controlling tty. Strange. +Get the session ID of the given tty. +This will fail with ENOTTY +in case the tty is not a master pty and not our controlling tty. +Strange. .SS "Exclusive mode" .TP .BI "TIOCEXCL void" @@ -251,11 +261,12 @@ Enable (when .RI * argp is non-zero) or disable packet mode. Can be applied to the master side of a pseudo-terminal only (and will return -ENOTTY otherwise). In packet mode, each subsequent +ENOTTY otherwise). +In packet mode, each subsequent .BR read (2) will return a packet that either contains a single non-zero control byte, -or has a single byte containing zero (''\0') followed by data -written on the slave side of the pty. +or has a single byte containing zero (''\0') followed by data +written on the slave side of the pty. If the first byte is not TIOCPKT_DATA (0), it is an OR of one or more of the following bits: @@ -342,7 +353,7 @@ For the TIOCLINUX ioctl, see .BI "TIOCTTYGSTRUCT struct tty_struct *" argp Get the tty_struct corresponding to .IR fd . -.\" +.\" .\" .SS "Serial info" .\" .sp .\" .BR "#include " @@ -356,7 +367,8 @@ Get the tty_struct corresponding to .SH "RETURN VALUE" The .BR ioctl () -system call returns 0 on success. On error it returns \-1 and sets +system call returns 0 on success. +On error it returns \-1 and sets .I errno appropriately. .SH ERRORS @@ -382,7 +394,7 @@ Check the condition of DTR on the serial port. #include int -main(void) +main(void) { int fd, serial; diff --git a/man4/vcs.4 b/man4/vcs.4 index f0e49aff7..422aa217b 100644 --- a/man4/vcs.4 +++ b/man4/vcs.4 @@ -28,8 +28,8 @@ vcs, vcsa \- virtual console memory .SH DESCRIPTION \fI/dev/vcs0\fP is a character device with major number 7 and minor number -0, usually of mode 0644 and owner root.tty. It refers to the memory -of the currently +0, usually of mode 0644 and owner root.tty. +It refers to the memory of the currently displayed virtual console terminal. .LP \fI/dev/vcs[1\-63]\fP are character devices for virtual console @@ -47,7 +47,7 @@ administrator can control access using file system permissions. The devices for the first eight virtual consoles may be created by: .nf - for x in 0 1 2 3 4 5 6 7 8; do + for x in 0 1 2 3 4 5 6 7 8; do mknod \-m 644 /dev/vcs$x c 7 $x; mknod \-m 644 /dev/vcsa$x c 7 $[$x+128]; done @@ -56,9 +56,9 @@ The devices for the first eight virtual consoles may be created by: No .BR ioctl () -requests are supported. +requests are supported. .SH EXAMPLE -You may do a screendump on vt3 by switching to vt1 and typing +You may do a screendump on vt3 by switching to vt1 and typing \fIcat /dev/vcs3 >foo\fP. Note that the output does not contain newline characters, so some processing may be required, like in \fIfold \-w 81 /dev/vcs3 | lpr\fP or (horrors) @@ -76,8 +76,8 @@ there: #include #include -int -main(void) +int +main(void) { int fd; char *device = "/dev/vcsa2"; diff --git a/man4/wavelan.4 b/man4/wavelan.4 index bc5d86aee..f5186d6a2 100644 --- a/man4/wavelan.4 +++ b/man4/wavelan.4 @@ -5,7 +5,7 @@ .\" wavelan.c.4 .\" .\" Provenance of this page is unclear. Licensed under the GPL, -.\" after inquiries with Jean Tourrilhes and Bruce Janson +.\" after inquiries with Jean Tourrilhes and Bruce Janson .\" (mtk, July 2006) .\" .TH WAVELAN 4 1996-10-22 "Univ. of Sydney (Basser Dep. of Comp. Sci.)" @@ -28,11 +28,14 @@ is the low-level device driver for the NCR / AT&T / Lucent .B WaveLAN ISA and Digital (DEC) .B RoamAbout DS -wireless ethernet adapter. This driver is available as a module or -might be compiled in the kernel. This driver supports multiple cards +wireless ethernet adapter. +This driver is available as a module or +might be compiled in the kernel. +This driver supports multiple cards in both forms (up to 4) and allocates the next available ethernet device (eth0..eth#) for each card found, unless a device name is -explicitly specified (see below). This device name will be reported +explicitly specified (see below). +This device name will be reported in the kernel log file with the MAC address, NWID and frequency used by the card. .\" @@ -41,13 +44,15 @@ by the card. .SH PARAMETERS This section apply to the module form (parameters passed on the .BR insmod (8) -command line). If the driver is included in the kernel, use the +command line). +If the driver is included in the kernel, use the .I ether=IRQ,IO,NAME syntax on the kernel command line. .TP .B io Specify the list of base address where to search for wavelan cards -(setting by dip switch on the card). If you don't specify any io +(setting by dip switch on the card). +If you don't specify any io address, the driver will scan 0x390 and 0x3E0 addresses, which might conflict with other hardware... .TP @@ -68,7 +73,7 @@ Use to manipulate wireless extensions. .\" NWID sub part .SS NWID (or domain) -Set the network ID +Set the network ID .RI [ 0 to .IR FFFF ] @@ -84,7 +89,8 @@ specifying one of the 10 defined channels .I 2.422, 2.425, 2.4305, 2.432, 2.442, 2.452, 2.460, 2.462 or .IR 2.484 ) -or directly by its value. The frequency is changed immediately and +or directly by its value. +The frequency is changed immediately and permanently. Frequency availability depends on the regulations... .\" Spy sub part @@ -123,7 +129,8 @@ modem (packet below that level are discarded). .SS Histogram This functionality allow to set a number of signal level intervals and to count the number of packets received in each of those defined -intervals. This distribution might be used to calculate the mean value +intervals. +This distribution might be used to calculate the mean value and standard deviation of the signal level. .\" .\" SPECIFIC part @@ -131,10 +138,12 @@ and standard deviation of the signal level. .SH "SPECIFIC NOTES" This driver will fail to detect some .B non NCR/ATT&T/Lucent -Wavelan cards. If it's your case, you must look in the source code on +Wavelan cards. +If it's your case, you must look in the source code on how to add your card to the detection routine. .PP -Some of the mentioned features are optional. You may enable to disable +Some of the mentioned features are optional. +You may enable to disable them by changing flags in the driver header and recompile. .\" .\" AUTHOR part diff --git a/man5/acct.5 b/man5/acct.5 index 726a69f21..38502dc12 100644 --- a/man5/acct.5 +++ b/man5/acct.5 @@ -33,7 +33,8 @@ the system call .RS acct("/somewhere/accountingfile"); .RE -will start the process accounting. Each time a process terminates +will start the process accounting. +Each time a process terminates a record for this process is appended to the accounting file. The accounting structure .I "struct acct" diff --git a/man5/charmap.5 b/man5/charmap.5 index 0a061593e..904c53bb5 100644 --- a/man5/charmap.5 +++ b/man5/charmap.5 @@ -1,6 +1,6 @@ .\" Hey emacs, this is -*- nroff -*- .\" -.\" This file is part of locale(1) which displays the settings of the +.\" This file is part of locale(1) which displays the settings of the .\" current locale. .\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) .\" @@ -23,8 +23,9 @@ charmap \- character symbols to define character encodings .SH DESCRIPTION A character set description (charmap) defines a character set of -available characters and their encodings. All supported character -sets should have the +available characters and their encodings. +All supported character +sets should have the .B portable character set as a proper subset. .\" Not true anymore: @@ -41,12 +42,14 @@ is followed by the name of the codeset. .TP .I is followed by the max number of bytes for a multibyte-character. -Multibyte characters are currently not supported. The default value +Multibyte characters are currently not supported. +The default value is 1. .TP .I -is followed by the min number of bytes for a character. This -value must be less or equal than +is followed by the min number of bytes for a character. +This +value must be less or equal than .BR mb_cur_max . If not specified, it defaults to .BR mb_cur_max . @@ -54,14 +57,16 @@ If not specified, it defaults to .I is followed by a character that should be used as the escape-character for the rest of the file to mark characters that -should be interpreted in a special way. It defaults to +should be interpreted in a special way. +It defaults to the backslash ( -.B \\\\ +.B \\\\ ). .TP .I is followed by a character that will be used as the -comment-character for the rest of the file. It defaults to the +comment-character for the rest of the file. +It defaults to the number sign ( .B # ). @@ -74,22 +79,23 @@ The following lines may have one of the two following forms to define the character-encodings: .TP .I -This form defines exactly one character and its encoding. +This form defines exactly one character and its encoding. .TP .I ... -This form defines a couple of characters. This is only useful for +This form defines a couple of characters. +This is only useful for mutlibyte-characters, which are currently not implemented. .PP The last line in a charmap-definition file must contain .B END CHARMAP. .SH "SYMBOLIC NAMES" -A +A .B symbolic name -for a character contains only characters of the +for a character contains only characters of the .B portable character set. The name itself is enclosed between angle brackets. Characters following an -.B +.B are interpreted as itself; for example, the sequence .B '<\\\\\\\\\\\\>>' represents the symbolic name @@ -103,7 +109,7 @@ encoding may be in each of the following three forms: with a decimal number .TP .I x -with a hexadecimal number +with a hexadecimal number .TP .I with an octal number. diff --git a/man5/core.5 b/man5/core.5 index 0230b9d22..66a78c3ce 100644 --- a/man5/core.5 +++ b/man5/core.5 @@ -21,58 +21,58 @@ .SH NAME core \- core dump file .SH DESCRIPTION -The default action of certain signals is to cause a process to terminate +The default action of certain signals is to cause a process to terminate and produce a .IR "core dump file" , -a disk file containing an image of the process's memory at +a disk file containing an image of the process's memory at the time of termination. A list of the signals which cause a process to dump core can be found in .BR signal (7). A process can set its soft .BR RLIMIT_CORE -resource limit to place an upper limit on the size of the core dump file +resource limit to place an upper limit on the size of the core dump file that will be produced if it receives a "core dump" signal; see .BR getrlimit (2) for details. -There are various circumstances in which a core dump file is +There are various circumstances in which a core dump file is not produced: .IP * The process does not have permission to write the core file. -(By default the core file is called +(By default the core file is called .IR core , -and is created in the current working directory. +and is created in the current working directory. See below for details on naming.) -Writing the core file will fail if the directory in which -it is to be created is non-writable, -or if a file with the same name exists and +Writing the core file will fail if the directory in which +it is to be created is non-writable, +or if a file with the same name exists and is not writable -or is not a regular file +or is not a regular file (e.g., it is a directory or a symbolic link). .IP * -A (writable, regular) file with the same name as would be used for the -core dump already exists, but there is more than one hard link to that +A (writable, regular) file with the same name as would be used for the +core dump already exists, but there is more than one hard link to that file. .IP * -The file system where the core dump file would be created is full; -or has run out of i-nodes; or is mounted read only; +The file system where the core dump file would be created is full; +or has run out of i-nodes; or is mounted read only; or the user has reached their quota for the file system. .IP * -The directory in which the core dump file is to be created does +The directory in which the core dump file is to be created does not exist. .IP * .B RLIMIT_CORE -or +or .B RLIMIT_FSIZE resource limits for a process are set to zero (see .BR getrlimit (2)). .IP * -The binary being executed by the process does not have read +The binary being executed by the process does not have read permission enabled. .IP * The process is executing a set-user-ID (set-group-ID) program -that is owned by a user (group) other than the real user (group) +that is owned by a user (group) other than the real user (group) ID of the process. (However, see the description of the .BR prctl (2) @@ -82,9 +82,9 @@ operation, and the description of the file in .BR proc (5).) .SS Naming of core dump files -By default, a core dump file is named +By default, a core dump file is named .IR core , -but the +but the .I /proc/sys/kernel/core_pattern file (since Linux 2.6 and 2.4.21) @@ -92,7 +92,7 @@ can be set to define a template that is used to name core dump files. The template can contain % specifiers which are substituted by the following values when a core file is created: .nf - + %% A single % character %p PID of dumped process %u real UID of dumped process @@ -101,10 +101,10 @@ by the following values when a core file is created: %t time of dump (seconds since 0:00h, 1 Jan 1970) %h hostname (same as 'nodename' returned by \fBuname\fP(2)) %e executable filename - + .fi -A single % at the end of the template is dropped from the -core filename, as is the combination of a % followed by any +A single % at the end of the template is dropped from the +core filename, as is the combination of a % followed by any character other than those listed above. All other characters in the template become a literal part of the core filename. @@ -130,7 +130,7 @@ If this file contains a non-zero value, then the core dump file includes the process ID in a name of the form .IR core.PID . .SH NOTES -The +The .BR gdb (1) .I gcore command can be used to obtain a core dump of a running process. @@ -140,7 +140,7 @@ shares its memory with another process by being created with the .B CLONE_VM flag of .BR clone (2)) -dumps core, then the process ID is always appended to the core filename, +dumps core, then the process ID is always appended to the core filename, unless the process ID was already included elsewhere in the filename via a %p specification in .IR /proc/sys/kernel/core_pattern . @@ -148,11 +148,11 @@ filename via a %p specification in .\" it might be worth incorporating it into the text: .\" Always including the PID in the name of the core file made .\" sense for LinuxThreads, where each thread had a unique PID, -.\" but doesn't seem to server any purpose with NPTL, where all the -.\" threads in a process share the same PID (as POSIX.1 requires). -.\" Probably the behaviour is maintained so that applications using -.\" LinuxThreads continue appending the PID (the kernel has no easy -.\" way of telling which threading implementation the userspace +.\" but doesn't seem to server any purpose with NPTL, where all the +.\" threads in a process share the same PID (as POSIX.1 requires). +.\" Probably the behaviour is maintained so that applications using +.\" LinuxThreads continue appending the PID (the kernel has no easy +.\" way of telling which threading implementation the userspace .\" application is using). -- mtk, April 2006 .SH SEE ALSO .BR gdb (1), diff --git a/man5/dir_colors.5 b/man5/dir_colors.5 index 1cf558d2c..b8be4bb5e 100644 --- a/man5/dir_colors.5 +++ b/man5/dir_colors.5 @@ -1,4 +1,4 @@ -.\" +.\" .\" manpage for /etc/dir_colors, config file for dircolors(1) .\" extracted from color-ls 3.12.0.3 dircolors(1) manpage .\" @@ -38,29 +38,33 @@ file in one's home directory. This configuration file consists of several statements, one per line. Anything right of a hash mark (#) is treated as a comment, if the hash mark is at the beginning of a line or is preceded by at least one -whitespace. Blank lines are ignored. +whitespace. +Blank lines are ignored. .PP The .I global section of the file consists of any statement before the first .B TERM -statement. Any statement in the global section of the file is -considered valid for all terminal types. Following the global section -is one or more +statement. +Any statement in the global section of the file is +considered valid for all terminal types. +Following the global section +is one or more .I terminal-specific sections, preceded by one or more .B TERM statements which specify the terminal types (as given by the .B TERM -environment variable) the following declarations apply to. It is -always possible to override a global declaration by a subsequent +environment variable) the following declarations apply to. +It is always possible to override a global declaration by a subsequent terminal-specific one. .PP The following statements are recognized; case is insignificant: .TP .B TERM \fIterminal-type\fR Starts a terminal-specific section and specifies which terminal it -applies to. Multiple +applies to. +Multiple .B TERM statements can be used to create a section which applies for several terminal types. @@ -70,21 +74,25 @@ terminal types. .BR dircolors (1).) Specifies that colorization should always be enabled (\fIyes\fR or \fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if -the output is a terminal (\fItty\fR). The default is \fIno\fR. +the output is a terminal (\fItty\fR). +The default is \fIno\fR. .TP .B EIGHTBIT yes|no (Slackware only; ignored by GNU .BR dircolors (1).) Specifies that eight-bit ISO 8859 characters should be enabled by -default. For compatibility reasons, this can also be specified as 1 for -\fIyes\fR or 0 for \fIno\fR. The default is \fIno\fR. +default. +For compatibility reasons, this can also be specified as 1 for +\fIyes\fR or 0 for \fIno\fR. +The default is \fIno\fR. .TP .B OPTIONS \fIoptions\fR (Slackware only; ignored by GNU .BR dircolors (1).) Adds command line options to the default .B ls -command line. The options can be any valid +command line. +The options can be any valid .B ls command line options, and should include the leading minus sign. Please note that @@ -105,7 +113,8 @@ Specifies the color used for a symbolic link. .TP .B ORPHAN \fIcolor-sequence\fR Specifies the color used for an orphaned symbolic link (one which -points to a nonexistent file). If this is unspecified, +points to a nonexistent file). +If this is unspecified, .B ls will use the .B LINK @@ -113,7 +122,8 @@ color instead. .TP .B MISSING \fIcolor-sequence\fR Specifies the color used for a missing file (a nonexistent file which -nevertheless has a symbolic link pointing to it). If this is unspecified, +nevertheless has a symbolic link pointing to it). +If this is unspecified, .B ls will use the .B FILE @@ -157,14 +167,17 @@ for non-ISO\ 6429 terminals (see below). Specifies the color used for any file that ends in \fIextension\fR. .TP \fB .\fIextension\fR \fIcolor-sequence\fR -Same as \fB*\fR.\fIextension\fR. Specifies the color used for any file that -ends in .\fIextension\fR. Note that the period is included in the +Same as \fB*\fR.\fIextension\fR. +Specifies the color used for any file that +ends in .\fIextension\fR. +Note that the period is included in the extension, which makes it impossible to specify an extension not starting with a period, such as .B ~ for .B emacs -backup files. This form should be considered obsolete. +backup files. +This form should be considered obsolete. .SH "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 @@ -175,13 +188,14 @@ codes and harmlessly eliminate them from the output or emulate them. uses ISO 6429 codes by default, assuming colorization is enabled. ISO 6429 color sequences are composed of sequences of numbers -separated by semicolons. The most common codes are: +separated by semicolons. +The most common codes are: .sp .RS +.2i .ta 1.0i .nf 0 to restore default color - 1 for brighter colors + 1 for brighter colors 4 for underlined text 5 for flashing text 30 for black foreground @@ -225,8 +239,9 @@ uses the following defaults: .fi .RE .sp -A few terminal programs do not recognize the default -properly. If all text gets colorized after you do a directory +A few terminal programs do not recognize the default +properly. +If all text gets colorized after you do a directory listing, change the .B NORMAL and @@ -236,7 +251,8 @@ colors. .SH "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. To do so, you will have to use the +a suitable setup. +To do so, you will have to use the .BR LEFTCODE , .BR RIGHTCODE , and @@ -253,13 +269,16 @@ generates the following output sequence: .BR ENDCODE , where the .I typecode -is the color sequence that depends on the type or name of file. If the +is the color sequence that depends on the type or name of file. +If the .B ENDCODE is undefined, the sequence .B "LEFTCODE NORMAL RIGHTCODE" -will be used instead. The purpose of the left- and rightcodes is +will be used instead. +The purpose of the left- and rightcodes is merely to reduce the amount of typing necessary (and to hide ugly -escape codes away from the user). If they are not appropriate for +escape codes away from the user). +If they are not appropriate for your terminal, you can eliminate them by specifying the respective keyword on a line by itself. .PP @@ -268,17 +287,19 @@ If the .B ENDCODE is defined in the global section of the setup file, it .I cannot -be undefined in a terminal-specific section of the file. This means -any +be undefined in a terminal-specific section of the file. +This means any .B NORMAL -definition will have no effect. A different +definition will have no effect. +A different .B ENDCODE can, however, be specified, which would have the same effect. .SH "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 -^-notation can be used. The C-style notation +^-notation can be used. +The C-style notation includes the following characters: .sp .RS +.2i diff --git a/man5/elf.5 b/man5/elf.5 index 500d4a04c..12709f652 100644 --- a/man5/elf.5 +++ b/man5/elf.5 @@ -98,7 +98,8 @@ ElfN_Xword uint64_t .\" Elf32_Size Unsigned object size .Ed .Pp -(Note: The *BSD terminology is a bit different. There Elf64_Half is +(Note: The *BSD terminology is a bit different. +There Elf64_Half is twice as large as Elf32_Half, and Elf64Quarter is used for uint16_t. In order to avoid confusion these types are replaced by explicit ones in the below.) @@ -1178,7 +1179,7 @@ typedef struct { } Elf64_Sym; .Ed .Pp -The 32-bit and 64-bit versions have the same members, just in a different +The 32-bit and 64-bit versions have the same members, just in a different order. .Bl -tag -width "st_value" -offset indent .It Dv st_name @@ -1345,8 +1346,9 @@ This member specifies a constant addend used to compute the value to be stored into the relocatable field. .El .Pp -The .dynamic section contains a series of structures that hold relevant -dynamic linking information. The d_tag member controls the interpretation +The .dynamic section contains a series of structures that hold relevant +dynamic linking information. +The d_tag member controls the interpretation of d_un. .Bd -literal -offset indent typedef struct { @@ -1421,7 +1423,7 @@ Absence of this indicates no relocs should apply to a non-writable segment .It Dv DT_JMPREL Address of reloc entries solely for the PLT .It Dv DT_BIND_NOW -Instruct dynamic linker to process all relocs before transferring control to +Instruct dynamic linker to process all relocs before transferring control to the executable .It Dv DT_RUNPATH String table offset to library search path @@ -1433,12 +1435,14 @@ End of processor-specific semantics .It Dv d_val This member represents integer values with various interpretations. .It Dv d_ptr -This member represents program virtual addresses. When interpreting -these addresses, the actual address should be computed based on the -original file value and memory base address. Files do not contain +This member represents program virtual addresses. +When interpreting +these addresses, the actual address should be computed based on the +original file value and memory base address. +Files do not contain relocation entries to fixup these addresses. .It Dv _DYNAMIC -Array containing all the dynamic structures in the .dynamic section. +Array containing all the dynamic structures in the .dynamic section. This is automatically populated by the linker. .El .Sh SEE ALSO diff --git a/man5/fs.5 b/man5/fs.5 index 385dc510a..331a36c12 100644 --- a/man5/fs.5 +++ b/man5/fs.5 @@ -46,14 +46,16 @@ Below a short description of a few of the available filesystems. .TP .B "minix" is the filesystem used in the Minix operating system, the first to run -under Linux. It has a number of shortcomings: a 64MB partition size +under Linux. +It has a number of shortcomings: a 64MB partition size limit, short filenames, a single time stamp, etc. It remains useful for floppies and RAM disks. .TP .B ext is an elaborate extension of the .B minix -filesystem. It has been completely superseded by the second version +filesystem. +It has been completely superseded by the second version of the extended filesystem .RB ( ext2 ) and has been removed from the kernel (in 2.1.21). @@ -69,12 +71,14 @@ offers the best performance (in terms of speed and CPU usage) of the filesystems supported under Linux. .TP .B ext3 -is a journaling version of the ext2 filesystem. It is easy to +is a journaling version of the ext2 filesystem. +It is easy to switch back and forth between ext2 and ext3. .TP .B xiafs was designed and implemented to be a stable, safe filesystem by -extending the Minix filesystem code. It provides the basic most +extending the Minix filesystem code. +It provides the basic most requested features without undue complexity. The .B xia @@ -88,7 +92,8 @@ filenames can be no longer than 8 characters, followed by an optional period and 3 character extension. .TP .B umsdos -is an extended DOS filesystem used by Linux. It adds capability for +is an extended DOS filesystem used by Linux. +It adds capability for long filenames, UID/GID, POSIX permissions, and special files (devices, named pipes, etc.) under the DOS filesystem, without sacrificing compatibility with DOS. @@ -101,7 +106,8 @@ VFAT adds the capability to use long filenames under the MSDOS filesystem. is a pseudo-filesystem which is used as an interface to kernel data structures rather than reading and interpreting .IR /dev/kmem . -In particular, its files do not take disk space. See +In particular, its files do not take disk space. +See .BR proc (5). .TP .B iso9660 @@ -110,29 +116,31 @@ is a CD-ROM filesystem type conforming to the ISO 9660 standard. .TP .B "High Sierra" Linux supports High Sierra, the precursor to the ISO 9660 standard for -CD-ROM filesystems. It is automatically recognized within the +CD-ROM filesystems. +It is automatically recognized within the .B iso9660 filesystem support under Linux. .TP .B "Rock Ridge" Linux also supports the System Use Sharing Protocol records specified -by the Rock Ridge Interchange Protocol. They are used to further -describe the files in the +by the Rock Ridge Interchange Protocol. +They are used to further describe the files in the .B iso9660 filesystem to a UNIX host, and provide information such as long -filenames, UID/GID, POSIX permissions, and devices. It is -automatically recognized within the +filenames, UID/GID, POSIX permissions, and devices. +It is automatically recognized within the .B iso9660 filesystem support under Linux. .RE .TP .B hpfs -is the High Performance Filesystem, used in OS/2. This filesystem is +is the High Performance Filesystem, used in OS/2. +This filesystem is read-only under Linux due to the lack of available documentation. .TP .B sysv -is an implementation of the SystemV/Coherent filesystem for Linux. It -implements all of Xenix FS, SystemV/386 FS, and Coherent FS. +is an implementation of the SystemV/Coherent filesystem for Linux. +It implements all of Xenix FS, SystemV/386 FS, and Coherent FS. .TP .B nfs is the network filesystem used to access disks located on remote computers. diff --git a/man5/ftpusers.5 b/man5/ftpusers.5 index 9b429c756..471dc453b 100644 --- a/man5/ftpusers.5 +++ b/man5/ftpusers.5 @@ -21,22 +21,26 @@ ftpusers \- list of users that may not log in via the FTP daemon The text file .B ftpusers contains a list of users that may not log in using the -File Transfer Protocol (FTP) server daemon. This file is used not merely for +File Transfer Protocol (FTP) server daemon. +This file is used not merely for system administration purposes but for improving security within a TCP/IP -networked environment. It will typically contain a list of the users that +networked environment. +It will typically contain a list of the users that either have no business using ftp or have too many privileges to be allowed to log in through the FTP server daemon. Such users usually include root, daemon, bin, uucp, and news. If your FTP server daemon doesn't use .B ftpusers then it is suggested that you read its documentation to find out how to -block access for certain users. Washington University FTP server Daemon +block access for certain users. +Washington University FTP server Daemon (wuftpd) and Professional FTP Daemon (proftpd) are known to make use of .BR ftpusers . .SH FORMAT The format of .B ftpusers -is very simple. There is one account name (or user name) per line. +is very simple. +There is one account name (or user name) per line. Lines starting with a # are ignored. .SH FILES .I /etc/ftpusers diff --git a/man5/group.5 b/man5/group.5 index bab7eb368..2a84165f1 100644 --- a/man5/group.5 +++ b/man5/group.5 @@ -19,14 +19,15 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:06:03 1993 by Rik Faith (faith@cs.unc.edu) .TH GROUP 5 1992-12-29 "Linux" "Linux Programmer's Manual" .SH NAME group \- user group file .SH DESCRIPTION \fI/etc/group\fP is an ASCII file which defines the groups to which users -belong. There is one entry per line, and each line has the format: +belong. +There is one entry per line, and each line has the format: .sp .RS group_name:passwd:GID:user_list @@ -36,8 +37,8 @@ The field descriptions are: .IP group_name the name of the group. .IP password -the (encrypted) group password. If this field is -empty, no password is needed. +the (encrypted) group password. +If this field is empty, no password is needed. .IP GID the numerical group ID. .IP user_list diff --git a/man5/host.conf.5 b/man5/host.conf.5 index 5c8fe3f6f..e6571c28d 100644 --- a/man5/host.conf.5 +++ b/man5/host.conf.5 @@ -31,24 +31,30 @@ The file .I /etc/host.conf contains configuration information specific to the resolver library. It should contain one configuration keyword per line, followed by -appropriate configuration information. The keywords recognized are +appropriate configuration information. +The keywords recognized are .IR order ", " trim ", " multi ", " nospoof ", " spoof ", and " reorder . These keywords are described below. .TP .I order -This keyword specifies how host lookups are to be performed. It -should be followed by one or more lookup methods, separated by commas. +This keyword specifies how host lookups are to be performed. +It should be followed by one or more lookup methods, separated by commas. Valid methods are .IR bind ", " hosts ", and " nis . .TP -.I trim -This keyword may be listed more than once. Each time it should be +.I trim +This keyword may be listed more than once. +Each time it should be followed by a list of domains, separated by colons (`:'), semicolons -(`;') or commas (`,'), with the leading dot. When set, the +(`;') or commas (`,'), with the leading dot. +When set, the resolv+ library will automatically trim the given domain name from the -end of any hostname resolved via DNS. This is intended for use with -local hosts and domains. (Related note: trim will not affect hostnames -gathered via NIS or the hosts file. Care should be taken to +end of any hostname resolved via DNS. +This is intended for use with +local hosts and domains. +(Related note: trim will not affect hostnames +gathered via NIS or the hosts file. +Care should be taken to ensure that the first hostname for each entry in the hosts file is fully qualified or non-qualified, as appropriate for the local installation.) @@ -62,7 +68,8 @@ the resolv+ library will return all valid addresses for a host that appears in the .I /etc/hosts file, -instead of only the first. This is +instead of only the first. +This is .I off by default, as it may cause a substantial performance loss at sites with large hosts files. @@ -76,7 +83,8 @@ the resolv+ library will attempt to prevent hostname spoofing to enhance the security of .BR rlogin " and " rsh . It works as follows: after performing a host address lookup, resolv+ -will perform a hostname lookup for that address. If the two hostnames +will perform a hostname lookup for that address. +If the two hostnames do not match, the query will fail. The default value is .IR off . @@ -89,7 +97,8 @@ If this option is set to and the .I nospoof option is also set, resolv+ will log a warning of the error via the -syslog facility. The default value is +syslog facility. +The default value is .IR off . .TP .I spoof @@ -119,12 +128,13 @@ If set to resolv+ will attempt to reorder host addresses so that local addresses (i.e., on the same subnet) are listed first when a .BR gethostbyname (3) -is performed. Reordering is done for all lookup methods. The default -value is +is performed. +Reordering is done for all lookup methods. +The default value is .IR off . .SH ENVIRONMENT There are six environment variables that can be used to allow users to -override the behavior which is configured in +override the behavior which is configured in .IR /etc/host.conf . .TP .B RESOLV_HOST_CONF @@ -141,7 +151,8 @@ Overrides the .IR nospoof ", " spoofalert " and " spoof commands in the same way as the .I spoof -command is parsed. Valid values are +command is parsed. +Valid values are .IR off ", " nowarn " and " warn . .TP .B RESOLV_MULTI @@ -162,7 +173,8 @@ domains that should be trimmed. .B RESOLV_OVERRIDE_TRIM_DOMAINS A list of domains, separated by colons (`:'), semicolons (`;') or commas (`,'), with the leading dot, which will replace the list of -domains that should be trimmed. Overrides the +domains that should be trimmed. +Overrides the .I trim command. .SH FILES diff --git a/man5/hosts.5 b/man5/hosts.5 index 62a7a52b6..522c0954a 100644 --- a/man5/hosts.5 +++ b/man5/hosts.5 @@ -30,10 +30,12 @@ hosts \- The static table lookup for host names .SH SYNOPSIS .B /etc/hosts .SH DESCRIPTION -This manual page describes the format of the +This manual page describes the format of the .I /etc/hosts -file. This file is a simple text file that associates IP addresses -with hostnames, one line per IP address. For each host a single +file. +This file is a simple text file that associates IP addresses +with hostnames, one line per IP address. +For each host a single line should be present with the following information: .RS .PP @@ -41,39 +43,46 @@ IP_address canonical_hostname [aliases...] .RE .PP Fields of the entry are separated by any number of blanks and/or -tab characters. Text from a "#" character until the end of the line is -a comment, and is ignored. Host names may contain only alphanumeric -characters, minus signs ("\-"), and periods ("."). They must begin with an +tab characters. +Text from a "#" character until the end of the line is +a comment, and is ignored. +Host names may contain only alphanumeric +characters, minus signs ("\-"), and periods ("."). +They must begin with an alphabetic character and end with an alphanumeric character. Optional aliases provide for name changes, alternate spellings, shorter hostnames, or generic hostnames (for example, .IR localhost ). .PP The Berkeley Internet Name Domain (BIND) Server implements the -Internet name server for UNIX systems. It augments or replaces the +Internet name server for UNIX systems. +It augments or replaces the .I /etc/hosts file or host name lookup, and frees a host from relying on .I /etc/hosts -being up to date and complete. +being up to date and complete. .PP In modern systems, even though the host table has been superseded by DNS, it is still widely used for: .TP .B bootstrapping Most systems have a small host table containing the name and address -information for important hosts on the local network. This is useful -when DNS is not running, for example during system bootup. +information for important hosts on the local network. +This is useful +when DNS is not running, for example during system bootup. .TP .B NIS Sites that use NIS use the host table as input to the NIS host -database. Even though NIS can be used with DNS, most NIS sites still -use the host table with an entry for all local hosts as a backup. -.TP +database. +Even though NIS can be used with DNS, most NIS sites still +use the host table with an entry for all local hosts as a backup. +.TP .B isolated nodes Very small sites that are isolated from the network use the host table -instead of DNS. If the local information rarely changes, and the +instead of DNS. +If the local information rarely changes, and the network is not connected to the Internet, DNS offers little -advantage. +advantage. .SH EXAMPLE .nf 127.0.0.1 localhost @@ -90,13 +99,16 @@ RFC\ 952 gave the original format for the host table, though it has since changed. Before the advent of DNS, the host table was the only way of resolving -hostnames on the fledgling Internet. Indeed, this file could be +hostnames on the fledgling Internet. +Indeed, this file could be created from the official host data base maintained at the Network Information Control Center (NIC), though local changes were often required to bring it up to date regarding unofficial aliases and/or -unknown hosts. The NIC no longer maintains the hosts.txt files, +unknown hosts. +The NIC no longer maintains the hosts.txt files, 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, +historical hosts.txt files on the WWW. +I just found three, from 92, 94, and 95. .SH FILES .I /etc/hosts diff --git a/man5/hosts.equiv.5 b/man5/hosts.equiv.5 index 046c13856..85b867ce4 100644 --- a/man5/hosts.equiv.5 +++ b/man5/hosts.equiv.5 @@ -14,33 +14,42 @@ The file uses the following format: \fI[ + | \- ]\fP \fI[hostname]\fP \fI[username]\fP .PP The \fIhostname\fP is the name of a host which is logically equivalent -to the local host. Users logged into that host are allowed to access +to the local host. +Users logged into that host are allowed to access like-named user accounts on the local host without supplying a password. The \fIhostname\fP may be (optionally) preceded by a plus (+) sign. If the plus sign is used alone it allows any host to access your system. You can explicitly deny access to a host by preceding the \fIhostname\fP -by a minus (\-) sign. Users from that host must always supply a password. +by a minus (\-) sign. +Users from that host must always supply a password. For security reasons you should always use the FQDN of the hostname and not the short hostname. .PP The \fIusername\fP entry grants a specific user access to all user -accounts (except root) without supplying a password. That means the -user is NOT restricted to like-named accounts. The \fIusername\fP may -be (optionally) preceded by a plus (+) sign. You can also explicitly +accounts (except root) without supplying a password. +That means the +user is NOT restricted to like-named accounts. +The \fIusername\fP may +be (optionally) preceded by a plus (+) sign. +You can also explicitly deny access to a specific user by preceding the \fIusername\fP with -a minus (\-) sign. This says that the user is not trusted no matter +a minus (\-) sign. +This says that the user is not trusted no matter what other entries for that host exist. .PP Netgroups can be specified by preceding the netgroup by an @ sign. .PP -Be extremely careful when using the plus (+) sign. A simple typographical -error could result in a standalone plus sign. A standalone plus sign is +Be extremely careful when using the plus (+) sign. +A simple typographical +error could result in a standalone plus sign. +A standalone plus sign is a wildcard character that means "any host"! .SH FILES .I /etc/hosts.equiv .SH NOTES Some systems will only honor the contents of this file when it has owner -root and no write permission for anybody else. Some exceptionally +root and no write permission for anybody else. +Some exceptionally paranoid systems even require that there be no other hard links to the file. .PP Modern systems use the Pluggable Authentication Modules library (PAM). diff --git a/man5/intro.5 b/man5/intro.5 index b9973ff37..0af3dab88 100644 --- a/man5/intro.5 +++ b/man5/intro.5 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:06:52 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Jan 14 00:34:09 1996 by Andries Brouwer (aeb@cwi.nl) .TH INTRO 5 1993-07-24 "Linux" "Linux Programmer's Manual" @@ -30,6 +30,7 @@ This chapter describes various file formats and protocols, and the used C structures, if any. .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! .SH "SEE ALSO" .BR standards (7) diff --git a/man5/issue.5 b/man5/issue.5 index 8c0ad0129..88537a5fc 100644 --- a/man5/issue.5 +++ b/man5/issue.5 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sun Jul 25 11:06:22 1993 by Rik Faith .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond .TH ISSUE 5 1993-07-24 "Linux" "Linux Programmer's Manual" @@ -27,9 +27,9 @@ issue \- pre-login message and identification file .SH DESCRIPTION The file \fI/etc/issue\fP is a text file which contains a message or -system identification to be printed before the login prompt. It may -contain various \fB@\fP\fIchar\fP and \fB\e\fP\fIchar\fP sequences, if -supported by the +system identification to be printed before the login prompt. +It may contain various \fB@\fP\fIchar\fP and \fB\e\fP\fIchar\fP +sequences, if supported by the .BR getty -type program employed on the system. .SH FILES diff --git a/man5/locale.5 b/man5/locale.5 index 0c7879133..6c9db6505 100644 --- a/man5/locale.5 +++ b/man5/locale.5 @@ -22,10 +22,10 @@ .SH NAME locale \- Describes a locale definition file .SH DESCRIPTION -The +The .B locale definition files contains all the information that the -.BR localedef (1) +.BR localedef (1) command needs to convert it into the binary locale database. The definition files consist of sections which each describe a @@ -37,19 +37,22 @@ of the following keywords: .I is followed by a character that should be used as the escape-character for the rest of the file to mark characters that -should be interpreted in a special way. It defaults to +should be interpreted in a special way. +It defaults to the backslash ( -.B \\\\ +.B \\\\ ). .TP .I is followed by a character that will be used as the -comment-character for the rest of the file. It defaults to the +comment-character for the rest of the file. +It defaults to the number sign (#). .PP The locale definition has one part for each locale category. Each part can be copied from another existing locale or -can be defined from scratch. If the category should be copied, +can be defined from scratch. +If the category should be copied, the only valid keyword in the definition is .B copy followed by the name of the locale which should be copied. @@ -57,20 +60,22 @@ followed by the name of the locale which should be copied. .\" LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_NAME, .\" LC_PAPER, LC_TELEPHONE. These need to be documented. .SS LC_CTYPE -The definition for the +The definition for the .B LC_CTYPE -category starts with the string -.I LC_CTYPE +category starts with the string +.I LC_CTYPE in the first column. There are the following keywords allowed: .TP .I upper -followed by a list of uppercase letters. The letters +followed by a list of uppercase letters. +The letters .B A trough .B Z -are included automatically. Characters also specified as +are included automatically. +Characters also specified as .BR cntrl , .BR digit , .BR punct , @@ -79,11 +84,13 @@ or are not allowed. .TP .I lower -followed by a list of lowercase letters. The letters +followed by a list of lowercase letters. +The letters .B a trough .B z -are included automatically. Characters also specified as +are included automatically. +Characters also specified as .BR cntrl , .BR digit , .BR punct , @@ -92,11 +99,13 @@ or are not allowed. .TP .I alpha -followed by a list of letters. All character specified as either +followed by a list of letters. +All character specified as either .B upper -or +or .B lower -are automatically included. Characters also specified as +are automatically included. +Characters also specified as .BR cntrl , .BR digit , .BR punct , @@ -105,16 +114,19 @@ or are not allowed. .TP .I digit -followed by the characters classified as numeric digits. Only the -digits -.B 0 +followed by the characters classified as numeric digits. +Only the +digits +.B 0 trough -.B 9 -are allowed. They are included by default in this class. +.B 9 +are allowed. +They are included by default in this class. .TP .I space followed by a list of characters defined as white-space -characters. Characters also specified as +characters. +Characters also specified as .BR upper , .BR lower , .BR alpha , @@ -122,7 +134,8 @@ characters. Characters also specified as .BR graph , or .B xdigit -are not allowed. The characters +are not allowed. +The characters .BR , .BR , .BR , @@ -147,7 +160,8 @@ or are not allowed. .TP .I punct -followed by a list of punctuation characters. Characters also +followed by a list of punctuation characters. +Characters also specified as .BR upper , .BR lower , @@ -162,14 +176,15 @@ character are not allowed. .I graph followed by a list of printable characters, not including the .B -character. The characters defined as +character. +The characters defined as .BR upper , .BR lower , .BR alpha , .BR digit , .BR xdigit , and -.B punct +.B punct are automatically included. Characters also specified as .B cntrl @@ -178,7 +193,8 @@ are not allowed. .I print followed by a list of printable characters, including the .B -character. The characters defined as +character. +The characters defined as .BR upper , .BR lower , .BR alpha , @@ -194,8 +210,10 @@ are not allowed. .TP .I xdigit followed by a list of characters classified as hexadecimal -digits. The decimal digits must be included followed by one or -more set of six characters in ascending order. The following +digits. +The decimal digits must be included followed by one or +more set of six characters in ascending order. +The following characters are included by default: .B 0 trough @@ -208,35 +226,39 @@ trough .BR F . .TP .I blank -followed by a list of characters classified as +followed by a list of characters classified as .BR blank . The characters .B -and +and .B are automatically included. .TP .I toupper followed by a list of mappings from lowercase to uppercase -letters. Each mapping is a pair of a lowercase and an uppercase letter -separated with a +letters. +Each mapping is a pair of a lowercase and an uppercase letter +separated with a .B , -and enclosed in parentheses. The members of the list are separated +and enclosed in parentheses. +The members of the list are separated with semicolons. .TP .I tolower followed by a list of mappings from uppercase to lowercase -letters. If the keyword tolower is not present, the reverse of the +letters. +If the keyword tolower is not present, the reverse of the toupper list is used. .PP -The +The .B LC_CTYPE -definition ends with the string +definition ends with the string .I END LC_CYTPE. .SS LC_COLLATE -The -.B LC_COLLATE -category defines the rules for collating characters. Due to +The +.B LC_COLLATE +category defines the rules for collating characters. +Due to limitations of libc not all POSIX-options are implemented. The definition starts with the string @@ -263,17 +285,17 @@ and is terminated with the keyword .TP .IR order_end . .PP -For more details see the sources in +For more details see the sources in .I /usr/lib/nls/src notably the examples .BR POSIX , .B Example -and +and .B Example2 .PP -The +The .B LC_COLLATE -definition ends with the string +definition ends with the string .IR END LC_COLLATE . .SS LC_MONETARY The definition starts with the string @@ -283,7 +305,8 @@ in the first column. There are the following keywords allowed: .TP .I int_curr_symbol -followed by the international currency symbol. This must be a +followed by the international currency symbol. +This must be a 4-character string containing the international currency symbol as defined by the ISO 4217 standard (three characters) followed by a separator. @@ -301,7 +324,7 @@ when formatting monetary quantities. .TP .I mon_grouping followed by a string that describes the formatting of numeric -quantities. +quantities. .TP .I positive_sign followed by a string that is used to indicate a positive sign for @@ -313,17 +336,17 @@ monetary quantities. .TP .I int_frac_digits followed by the number of fractional digits that should be used when -formatting with the +formatting with the .BR int_curr_symbol . .TP .I frac_digits followed by the number of fractional digits that should be used when -formatting with the +formatting with the .BR currency_symbol . .TP .I p_cs_precedes -followed by an integer set to -.B 1 +followed by an integer set to +.B 1 if the .I currency_symbol or @@ -342,9 +365,9 @@ value. .TP .B 1 means that a space should be printed between the symbol and the -value. +value. .TP -.B 2 +.B 2 means that a space should be printed between the symbol and the sign string, if adjacent. .RE @@ -352,7 +375,7 @@ sign string, if adjacent. .I n_cs_precedes .RS .TP -.B 0 +.B 0 - the symbol succeeds the value. .TP .B 1 @@ -360,11 +383,11 @@ sign string, if adjacent. .RE .TP .I n_sep_by_space -An integer set to +An integer set to .B 0 if no space separates the .I currency_symbol -or +or .I int_curr_symbol from the value for a negative monetary quantity, set to .B 1 @@ -376,7 +399,7 @@ if a space separates the symbol and the sign string, if adjacent. .RS .TP .B 0 -Parentheses enclose the quantity and the +Parentheses enclose the quantity and the .I currency_symbol or .IR int_curr_symbol . @@ -410,7 +433,7 @@ or the .RS .TP .B 0 -Parentheses enclose the quantity and the +Parentheses enclose the quantity and the .I currency_symbol or .IR int_curr_symbol . @@ -440,9 +463,9 @@ or the .IR int_curr_symbol . .RE .PP -The +The .B LC_MONETARY -definition ends with the string +definition ends with the string .I END LC_MONETARY. .SS LC_NUMERIC The definition starts with the string @@ -461,11 +484,11 @@ when formatting numeric quantities. .TP .I grouping followed by a string that describes the formatting of numeric -quantities. +quantities. .PP -The +The .B LC_NUMERIC -definition ends with the string +definition ends with the string .I END LC_NUMERIC. .SS LC_TIME The definition starts with the string @@ -475,11 +498,13 @@ in the first column. The following keywords are allowed: .TP .I abday -followed by a list of abbreviated weekday names. The list starts with +followed by a list of abbreviated weekday names. +The list starts with Sunday or its translation. .TP .I day -followed by a list of weekday names. The list starts with Sunday. +followed by a list of weekday names. +The list starts with Sunday. .TP .I abmon followed by a list of abbreviated month names. @@ -490,7 +515,7 @@ followed by a list of month names. .I am_pm The appropriate representation of the .B am -and +and .B pm strings. .TP @@ -506,9 +531,9 @@ The appropriate time format. .I t_fmt_ampm The appropriate time format when using 12h clock format. .PP -The +The .B LC_TIME -definition ends with the string +definition ends with the string .I END LC_TIME. .SS LC_MESSAGES The definition starts with the string @@ -519,15 +544,15 @@ The following keywords are allowed: .TP .I yesexpr followed by a regular expression that describes possible -yes-responses. +yes-responses. .TP .I noexpr followed by a regular expression that describes possible -no-responses. +no-responses. .PP -The +The .B LC_MESSAGES -definition ends with the string +definition ends with the string .I END LC_MESSAGES. See the POSIX.2 standard for details. diff --git a/man5/motd.5 b/man5/motd.5 index 31de11b89..157d7576d 100644 --- a/man5/motd.5 +++ b/man5/motd.5 @@ -19,14 +19,14 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:08:16 1993 by Rik Faith .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond .TH MOTD 5 1992-12-29 "Linux" "Linux Programmer's Manual" .SH NAME motd \- message of the day .SH DESCRIPTION -The contents of \fI/etc/motd\fP are displayed by +The contents of \fI/etc/motd\fP are displayed by .BR login (1) after a successful login but just before it executes the login shell. diff --git a/man5/nologin.5 b/man5/nologin.5 index 02490a41b..65c731bc8 100644 --- a/man5/nologin.5 +++ b/man5/nologin.5 @@ -26,9 +26,10 @@ .SH NAME nologin \- prevent non-root users from logging into the system .SH DESCRIPTION -If the file \fI/etc/nologin\fP exists, +If the file \fI/etc/nologin\fP exists, .BR login (1) -will allow access only to root. Other users will +will allow access only to root. +Other users will be shown the contents of this file and their logins will be refused. .SH FILES /etc/nologin diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5 index 009791805..265465137 100644 --- a/man5/nscd.conf.5 +++ b/man5/nscd.conf.5 @@ -25,9 +25,12 @@ The file .I /etc/nscd.conf is read from .BR nscd (8) -at startup. Each line specifies either an attribute and a value, or an -attribute, service, and a value. Fields are separated either by SPACE -or TAB characters. A `#' (number sign) indicates the beginning of a +at startup. +Each line specifies either an attribute and a value, or an +attribute, service, and a value. +Fields are separated either by SPACE +or TAB characters. +A `#' (number sign) indicates the beginning of a comment; following characters, up to the end of the line, are not interpreted by nscd. @@ -49,7 +52,8 @@ Sets the desired debug level. .I number .RS This is the number of threads that are started to wait for -requests. At least five threads will always be created. +requests. +At least five threads will always be created. .RE .B server-user @@ -77,7 +81,8 @@ Sets the TTL (time-to-live) for positive entries (successful queries) in the specified cache for .IR service . .I Value -is in seconds. Larger values increase cache hit rates and reduce mean +is in seconds. +Larger values increase cache hit rates and reduce mean response times, but increase problems with cache coherence. .RE @@ -89,7 +94,8 @@ Sets the TTL (time-to-live) for negative entries (unsuccessful queries) in the specified cache for .IR service . .I Value -is in seconds. Can result in significant performance improvements if there +is in seconds. +Can result in significant performance improvements if there are several files owned by UIDs (user IDs) not in system databases (for example untarring the linux kernel sources as root); should be kept small to reduce cache coherency problems. @@ -110,7 +116,8 @@ should remain a prime number for optimum efficiency. .RS Enables or disables checking the file belonging to the specified .I service -for changes. The files are +for changes. +The files are .IR /etc/passwd , .IR /etc/group , and @@ -134,7 +141,8 @@ unlimited | .I number .RS Limit on the number of times a cached entry gets reloaded without being used -before it gets removed. The default is 5. +before it gets removed. +The default is 5. .RE .B paranoia @@ -170,7 +178,7 @@ mode is set. .I .RS The memory mapping of the nscd databases for -.I service +.I service is shared with the clients so that they can directly search in them instead of having to ask the daemon over the socket each time a lookup is performed. diff --git a/man5/nsswitch.conf.5 b/man5/nsswitch.conf.5 index 719411824..47a159e9e 100644 --- a/man5/nsswitch.conf.5 +++ b/man5/nsswitch.conf.5 @@ -27,16 +27,20 @@ nsswitch.conf \- System Databases and Name Service Switch configuration file .SH DESCRIPTION Various functions in the C Library need to be configured to work -correctly in the local environment. Traditionally, this was done by +correctly in the local environment. +Traditionally, this was done by using files (e.g., `/etc/passwd'), but other nameservices (like the Network Information Service (NIS) and the Domain Name Service (DNS)) became popular, and were hacked into the C library, usually with a fixed search order. .LP The Linux libc5 with NYS support and the GNU C Library 2.x (libc.so.6) -contain a cleaner solution of this problem. It is designed after a method -used by Sun Microsystems in the C library of Solaris 2. We follow their -name and call this scheme "Name Service Switch" (NSS). The sources for +contain a cleaner solution of this problem. +It is designed after a method +used by Sun Microsystems in the C library of Solaris 2. +We follow their +name and call this scheme "Name Service Switch" (NSS). +The sources for the "databases" and their lookup order are specified in the .I /etc/nsswitch.conf file. @@ -148,22 +152,28 @@ different items: .PD .LP For libc5 with NYS, the allowed service specifications are `files', `nis', -and `nisplus'. For hosts, you could specify `dns' as extra service, for +and `nisplus'. +For hosts, you could specify `dns' as extra service, for passwd and group `compat', but not for shadow. .LP For glibc, you must have a file called .BI /lib/libnss_SERVICE.so. X -for every SERVICE you are using. On a standard installation, you could use -`files', `db', `nis', and `nisplus'. For hosts, you could specify `dns' as -extra service, for passwd, group, and shadow `compat'. These services will not +for every SERVICE you are using. +On a standard installation, you could use +`files', `db', `nis', and `nisplus'. +For hosts, you could specify `dns' as +extra service, for passwd, group, and shadow `compat'. +These services will not be used by libc5 with NYS. The version number .I X is 1 for glibc 2.0 and 2 for glibc 2.1. .LP The second item in the specification gives the user much finer -control on the lookup process. Action items are placed between two -service names and are written within brackets. The general form is +control on the lookup process. +Action items are placed between two +service names and are written within brackets. +The general form is .LP `[' ( `!'? STATUS `=' ACTION )+ `]' .LP @@ -176,12 +186,14 @@ STATUS => success | notfound | unavail | tryagain ACTION => return | continue .PD .LP -The case of the keywords is insignificant. The STATUS values are -the results of a call to a lookup function of a specific service. They -mean: +The case of the keywords is insignificant. +The STATUS values are +the results of a call to a lookup function of a specific service. +They mean: .TP .B success -No error occurred and the wanted entry is returned. The default +No error occurred and the wanted entry is returned. +The default action for this is `return'. .TP .B notfound @@ -189,24 +201,29 @@ The lookup process works ok but the needed value was not found. The default action is `continue'. .TP .B unavail -The service is permanently unavailable. This can either mean the +The service is permanently unavailable. +This can either mean the needed file is not available, or, for DNS, the server is not -available or does not allow queries. The default action is +available or does not allow queries. +The default action is `continue'. .TP .B tryagain -The service is temporarily unavailable. This could mean a file is -locked or a server currently cannot accept more connections. The -default action is `continue'. +The service is temporarily unavailable. +This could mean a file is +locked or a server currently cannot accept more connections. +The default action is `continue'. .SS Interaction with +/\- syntax (compat mode) Linux libc5 without NYS does not have the name service switch but does -allow the user some policy control. In +allow the user some policy control. +In .I /etc/passwd you could have entries of the form +user or +@netgroup (include the specified user from the NIS passwd map), \-user or \-@netgroup (exclude the specified user), and + (include every user, except the excluded ones, from the NIS -passwd map). Since most people only put a + at the end of +passwd map). +Since most people only put a + at the end of .I /etc/passwd to include everything from NIS, the switch provides a faster alternative for this case (`passwd: files nis') which doesn't @@ -216,7 +233,8 @@ require the single + entry in and .IR /etc/shadow . If this is not sufficient, the NSS `compat' service provides full -+/\- semantics. By default, the source is `nis', but this may be ++/\- semantics. +By default, the source is `nis', but this may be overridden by specifying `nisplus' as source for the pseudo-databases .BR passwd_compat , .B group_compat @@ -260,4 +278,5 @@ the entire file is read only once; if the file is later changed, the process will continue using the old configuration. .LP With Solaris, it isn't possible to link programs using the NSS Service -statically. With Linux, this is no problem. +statically. +With Linux, this is no problem. diff --git a/man5/passwd.5 b/man5/passwd.5 index eab7b8a31..48b2ca2dd 100644 --- a/man5/passwd.5 +++ b/man5/passwd.5 @@ -40,12 +40,13 @@ use it to map user IDs to user names), but write access only for the superuser. .PP In the good old days there was no great problem with this general -read permission. Everybody could read the encrypted passwords, but the +read permission. +Everybody could read the encrypted passwords, but the hardware was too slow to crack a well-chosen password, and moreover, the -basic assumption used to be that of a friendly user-community. These days -many people run some version of the shadow password suite, where +basic assumption used to be that of a friendly user-community. +These days many people run some version of the shadow password suite, where .I /etc/passwd -has asterisks (*) instead of encrypted passwords, +has asterisks (*) instead of encrypted passwords, and the encrypted passwords are in .I /etc/shadow which is readable by the superuser only. @@ -70,7 +71,8 @@ The field descriptions are: .RS .TP 1.0in .I account -the name of the user on the system. It should not contain capital letters. +the name of the user on the system. +It should not contain capital letters. .TP .I password the encrypted user password, an asterisk (*), or the letter 'x'. @@ -86,12 +88,15 @@ the numerical primary group ID for this user. .TP .I GECOS This field is optional and only used for informational purposes. -Usually, it contains the full user name. GECOS means General Electric +Usually, it contains the full user name. +GECOS means General Electric Comprehensive Operating System, which has been renamed to GCOS when -GE's large systems division was sold to Honeywell. Dennis Ritchie has -reported: "Sometimes we sent printer output or batch jobs to the GCOS -machine. The gcos field in the password file was a place to stash the -information for the $IDENTcard. Not elegant." +GE's large systems division was sold to Honeywell. +Dennis Ritchie has reported: "Sometimes we sent printer output or +batch jobs to the GCOS machine. +The gcos field in the password file was a place to stash the +information for the $IDENTcard. +Not elegant." .TP .I directory the user's $HOME directory. @@ -117,7 +122,8 @@ run existing processes and initiate new ones through .BR rsh (1), .BR cron (1), .BR at (1), -or mail filters, etc. Trying to lock an account by simply changing the +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 diff --git a/man5/proc.5 b/man5/proc.5 index fc8abd0ee..399886369 100644 --- a/man5/proc.5 +++ b/man5/proc.5 @@ -39,22 +39,22 @@ .\" 2005-07-13, mtk, added /proc/sys/fs/mqueue/* .\" 2005-09-16, mtk, Added /proc/sys/fs/suid_dumpable .\" 2005-09-19, mtk, added /proc/zoneinfo -.\" 2005-03-01, mtk, moved /proc/sys/fs/mqueue/* material to +.\" 2005-03-01, mtk, moved /proc/sys/fs/mqueue/* material to .\" mq_overview.7. .\" .\" FIXME 2.6.14 has /proc/PID/numa_maps (if CONFIG_NUMA is .\" enabled); this needs to be documented. -.\" Info on numa_maps can be found in the patch-2.6.14 +.\" Info on numa_maps can be found in the patch-2.6.14 .\" Changelog, but this is possibly not up to date. .\" .\" FIXME 2.6.13 seems to have /proc/vmcore implemented -.\" in the source code, but there is no option available under -.\" 'make xconfig'; eventually this should be fixed, and then info -.\" from the patch-2.6.13 and change log could be used to write an +.\" in the source code, but there is no option available under +.\" 'make xconfig'; eventually this should be fixed, and then info +.\" from the patch-2.6.13 and change log could be used to write an .\" entry in this man page. .\" -.\" FIXME cross check against Documentation/filesystems/proc.txt -.\" to see what information could be imported from that file +.\" FIXME cross check against Documentation/filesystems/proc.txt +.\" to see what information could be imported from that file .\" into this file. .\" .TH PROC 5 2005-05-12 "" "Linux Programmer's Manual" @@ -64,9 +64,10 @@ proc \- process information pseudo-filesystem The .I proc filesystem is a pseudo-filesystem which is used as an interface to -kernel data structures. It is commonly mounted at +kernel data structures. +It is commonly mounted at .IR /proc . -Most of it is read-only, but some files allow kernel variables to be +Most of it is read-only, but some files allow kernel variables to be changed. .LP The following outline gives a quick tour through the /proc hierarchy. @@ -80,21 +81,21 @@ pseudo-files and directories. .TP .IR /proc/[number]/auxv " (since 2.6.0-test7)" This contains the contents of the ELF interpreter information passed -to the process at exec time. +to the process at exec time. The format is one \fIunsigned long\fP ID -plus one \fIunsigned long\fP value for each entry. +plus one \fIunsigned long\fP value for each entry. The last entry contains two zeros. .TP .I /proc/[number]/cmdline This holds the complete command line for the process, unless the whole -process has been swapped out or the process is a zombie. In -either of these latter cases, there is nothing in this file: i.e. a +process has been swapped out or the process is a zombie. +In either of these latter cases, there is nothing in this file: i.e. a read on this file will return 0 characters. -The command line arguments appear in this file as a set of +The command line arguments appear in this file as a set of null-separated strings, with a further null byte after the last string. .TP .I /proc/[number]/cwd -This is a symbolic link to the current working directory of the process. +This is a symbolic link to the current working directory of the process. To find out the cwd of process 20, for instance, you can do this: .br @@ -104,14 +105,15 @@ cd /proc/20/cwd; /bin/pwd .fi .ft -Note that the -.I pwd +Note that the +.I pwd command is often a shell builtin, and might -not work properly. In bash, you may use pwd \-P. +not work properly. +In bash, you may use pwd \-P. .\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of this symbolic link -are not available if the main thread has already terminated +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated (typically by calling .BR pthread_exit (3). .TP @@ -134,21 +136,23 @@ Thus, to print out the environment of process 1, you would do: .I /proc/[number]/exe Under Linux 2.2 and later, this file is a symbolic link containing the actual pathname of the executed command. -This symbolic link can be dereferenced normally; attempting to open -it will open the executable. You can even type +This symbolic link can be dereferenced normally; attempting to open +it will open the executable. +You can even type .I /proc/[number]/exe -to run another copy of the same executable as is being run by +to run another copy of the same executable as is being run by process [number]. .\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of this symbolic link -are not available if the main thread has already terminated +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated (typically by calling .BR pthread_exit (3)). Under Linux 2.0 and earlier .I /proc/[number]/exe -is a pointer to the binary which was executed, -and appears as a symbolic link. A +is a pointer to the binary which was executed, +and appears as a symbolic link. +A .BR readlink (2) call on this file under Linux 2.0 returns a string in the format: @@ -163,12 +167,12 @@ with the \-inum option can be used to locate the file. .I /proc/[number]/fd This is a subdirectory containing one entry for each file which the process has open, named by its file descriptor, and which is a -symbolic link to the actual file. Thus, 0 is -standard input, 1 standard output, 2 standard error, etc. +symbolic link to the actual file. +Thus, 0 is standard input, 1 standard output, 2 standard error, etc. .\" The following was still true as at kernel 2.6.13 In a multithreaded process, the contents of this directory -are not available if the main thread has already terminated +are not available if the main thread has already terminated (typically by calling .BR pthread_exit (3)). @@ -191,7 +195,8 @@ and you have a working filter. .\" are not seekable. /proc/self/fd/N is approximately the same as /dev/fd/N in some UNIX -and UNIX-like systems. Most Linux MAKEDEV scripts symbolically link +and UNIX-like systems. +Most Linux MAKEDEV scripts symbolically link /dev/fd to /proc/self/fd, in fact. .\" FIXME Describe /proc/[number]/loginuid .\" Added in 2.6.11; updating requires CAP_AUDIT_CONTROL @@ -260,12 +265,13 @@ and Unix and Linux support the idea of a per-process root of the filesystem, set by the .BR chroot (2) -system call. This file is a symbolic link that points to the process's +system call. +This file is a symbolic link that points to the process's root directory, and behaves as exe, fd/*, etc. do. .\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of this symbolic link -are not available if the main thread has already terminated +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated (typically by calling .BR pthread_exit (3)). .\" FIXME Describe /proc/[number]/seccomp @@ -295,13 +301,14 @@ the amount of the mapping that is currently resident in RAM, the number clean and dirty shared pages in the mapping, and the number clean and dirty private pages in the mapping. -This file is only present if the CONFIG_MMU kernel configuration +This file is only present if the CONFIG_MMU kernel configuration option is enabled. .TP .I /proc/[number]/stat -Status information about the process. This is used by -.BR ps (1). -It is defined in +Status information about the process. +This is used by +.BR ps (1). +It is defined in .IR /usr/src/linux/fs/proc/array.c "." The fields, in order, with their proper @@ -313,8 +320,8 @@ format specifiers, are: The process ID. .TP \fIcomm\fP %s -The filename of the executable, in parentheses. This is visible -whether or not the executable is swapped out. +The filename of the executable, in parentheses. +This is visible whether or not the executable is swapped out. .TP \fIstate\fP %c One character from the string "RSDZTW" where R is running, S is @@ -341,7 +348,8 @@ The process group ID of the process which currently owns the tty that the process is connected to. .TP \fIflags\fP %lu -The kernel flags word of the process. For bit meanings, +The kernel flags word of the process. +For bit meanings, see the PF_* defines in .IR . Details depend on the kernel version. @@ -372,7 +380,8 @@ mode. .TP \fIcutime\fP %ld The number of jiffies that this process's -waited-for children have been scheduled in user mode. (See also +waited-for children have been scheduled in user mode. +(See also .BR times (2).) .TP \fIcstime\fP %ld @@ -380,8 +389,8 @@ The number of jiffies that this process's waited-for children have been scheduled in kernel mode. .TP \fIpriority\fP %ld -The standard nice value, plus fifteen. The value is never negative in -the kernel. +The standard nice value, plus fifteen. +The value is never negative in the kernel. .TP \fInice\fP %ld The nice value ranges from 19 (nicest) to \-19 (not nice to others). @@ -410,8 +419,10 @@ Virtual memory size in bytes. .TP \fIrss\fP %ld Resident Set Size: number of pages the process has in real memory, -minus 3 for administrative purposes. This is just the pages which -count towards text, data, or stack space. This does not include pages +minus 3 for administrative purposes. +This is just the pages which +count towards text, data, or stack space. +This does not include pages which have not been demand-loaded in, or which are swapped out. .TP \fIrlim\fP %lu @@ -447,9 +458,11 @@ The bitmap of ignored signals. The bitmap of caught signals. .TP \fIwchan\fP %lu -This is the "channel" in which the process is waiting. It is the +This is the "channel" in which the process is waiting. +It is the address of a system call, and can be looked up in a namelist if you -need a textual name. (If you have an up-to-date /etc/psdatabase, then +need a textual name. +(If you have an up-to-date /etc/psdatabase, then try \fIps \-l\fP to see the WCHAN field in action.) .TP \fInswap\fP %lu @@ -477,7 +490,8 @@ Aggregated block I/O delays (measured in clock ticks (centiseconds)). .RE .TP .I /proc/[number]/statm -Provides information about memory status in pages. The columns are: +Provides information about memory status in pages. +The columns are: size total program size resident resident set size share shared pages @@ -507,17 +521,17 @@ For attributes that are shared by all threads, the contents for each of the files under the .I task/[thread-ID] subdirectories will be the same as in the corresponding -file in the parent +file in the parent .I /proc/[number] directory -(e.g., in a multithreaded process, all of the +(e.g., in a multithreaded process, all of the .I task/[thread-ID]/cwd -files will have the same value as the +files will have the same value as the .I /proc/[number]/cwd -file in the parent directory, since all of the threads in a process +file in the parent directory, since all of the threads in a process share a working directory). For attributes that are distinct for each thread, -the corresponding files under +the corresponding files under .I task/[thread-ID] may have different values (e.g., various fields in each of the .I task/[thread-ID]/status @@ -526,7 +540,7 @@ files may be different for each thread). .\" The following was still true as at kernel 2.6.13 In a multithreaded process, the contents of the .I /proc/[number]/task -directory are not available if the main thread has already terminated +directory are not available if the main thread has already terminated (typically by calling .BR pthread_exit (3)). .TP @@ -544,19 +558,21 @@ at kernel compilation time. .I /proc/bus/pccard/drivers .TP .I /proc/bus/pci -Contains various bus subdirectories and pseudo-files containing -information about pci busses, installed devices, and device -drivers. Some of these files are not ASCII. +Contains various bus subdirectories and pseudo-files containing +information about pci busses, installed devices, and device +drivers. +Some of these files are not ASCII. .TP .I /proc/bus/pci/devices -Information about pci devices. They may be accessed through +Information about pci devices. +They may be accessed through .BR lspci (8) and .BR setpci (8). .TP .I /proc/cmdline -Arguments passed to the Linux kernel at boot time. Often done via -a boot manager such as +Arguments passed to the Linux kernel at boot time. +Often done via a boot manager such as .BR lilo (1). .\" FIXME Document /proc/config.gz (new in kernel 2.6) .TP @@ -564,13 +580,14 @@ a boot manager such as This is a collection of CPU and system architecture dependent items, for each supported architecture a different list. Two common entries are \fIprocessor\fP which gives CPU number and -\fIbogomips\fP; a system constant that is calculated -during kernel initialization. SMP machines have information for +\fIbogomips\fP; a system constant that is calculated +during kernel initialization. +SMP machines have information for each CPU. .TP .I /proc/devices -Text listing of major numbers and device groups. This can be used by -MAKEDEV scripts for consistency with the kernel. +Text listing of major numbers and device groups. +This can be used by MAKEDEV scripts for consistency with the kernel. .TP .IR /proc/diskstats " (since Linux 2.5.69)" This file contains disk I/O statistics for each disk device. @@ -579,7 +596,7 @@ See the kernel source file for further information. .TP .I /proc/dma -This is a list of the registered \fIISA\fP DMA (direct memory access) +This is a list of the registered \fIISA\fP DMA (direct memory access) channels in use. .TP .I /proc/driver @@ -589,7 +606,7 @@ Empty subdirectory. List of the execution domains (ABI personalities). .TP .I /proc/fb -Frame buffer information when CONFIG_FB is defined during kernel +Frame buffer information when CONFIG_FB is defined during kernel compilation. .TP .I /proc/filesystems @@ -603,8 +620,9 @@ Empty subdirectory. .TP .I /proc/ide This directory -exists on systems with the ide bus. There are directories for each -ide channel and attached device. Files include: +exists on systems with the ide bus. +There are directories for each ide channel and attached device. +Files include: .nf cache buffer size in KB @@ -619,20 +637,21 @@ smart_thresholds in hexadecimal smart_values in hexadecimal .fi -The +The .BR hdparm (8) utility provides access to this information in a friendly format. .TP .I /proc/interrupts This is used to record the number of interrupts per each IRQ on (at -least) the i386 architecture. Very easy to read formatting, done in +least) the i386 architecture. +Very easy to read formatting, done in ASCII. .TP .I /proc/iomem I/O memory map in Linux 2.4. .TP .I /proc/ioports -This is a list of currently registered Input-Output port regions that +This is a list of currently registered Input-Output port regions that are in use. .TP .IR /proc/kallsyms " (since Linux 2.5.71)" @@ -645,7 +664,8 @@ was named .TP .I /proc/kcore This file represents the physical memory of the system and is stored -in the ELF core file format. With this pseudo-file, and an unstripped +in the ELF core file format. +With this pseudo-file, and an unstripped kernel (/usr/src/linux/vmlinux) binary, GDB can be used to examine the current state of any kernel data structures. @@ -655,9 +675,11 @@ The total length of the file is the size of physical memory (RAM) plus .I /proc/kmsg This file can be used instead of the .BR syslog (2) -system call to read kernel messages. A process must have superuser +system call to read kernel messages. +A process must have superuser privileges to read this file, and only one process should read this -file. This file should not be read if a syslog process is running +file. +This file should not be read if a syslog process is running which uses the .BR syslog (2) system call facility to log kernel messages. @@ -679,7 +701,7 @@ They are the same as the load average numbers given by and other programs. The fourth field consists of two numbers separated by a slash (/). The first of these is the number of currently executing kernel -scheduling entities (processes, threads); +scheduling entities (processes, threads); this will be less than or equal to the number of CPUs. The value after the slash is the number of kernel scheduling entities that currently exist on the system. @@ -711,7 +733,7 @@ except in bytes rather than KB. This is a list of all the file systems currently mounted on the system. The format of this file is documented in .BR fstab (5). -Since kernel version 2.6.15, this file is pollable: +Since kernel version 2.6.15, this file is pollable: after opening the file for reading, a change in this file (i.e., a file system mount or unmount) causes .BR select (2) @@ -727,22 +749,26 @@ See also .BR lsmod (8). .TP .I /proc/mtrr -Memory Type Range Registers. -See +Memory Type Range Registers. +See .I /usr/src/linux/Documentation/mtrr.txt for details. .TP .I /proc/net various net pseudo-files, all of which give the status of some part of -the networking layer. These files contain ASCII structures and are, -therefore, readable with cat. However, the standard +the networking layer. +These files contain ASCII structures and are, +therefore, readable with cat. +However, the standard .BR netstat (8) suite provides much cleaner access to these files. .TP .I /proc/net/arp This holds an ASCII readable dump of the kernel ARP table used for -address resolutions. It will show both dynamically learned and -pre-programmed ARP entries. The format is: +address resolutions. +It will show both dynamically learned and +pre-programmed ARP entries. +The format is: .nf .ft CW @@ -755,19 +781,22 @@ IP address HW type Flags HW address Mask Device .in Here 'IP address' is the IPv4 address of the machine and the 'HW type' -is the hardware type of the address from RFC\ 826. -The flags are the internal +is the hardware type of the address from RFC\ 826. +The flags are the internal flags of the ARP structure (as defined in /usr/include/linux/if_arp.h) and the 'HW address' is the data link layer mapping for that IP address if it is known. .TP .I /proc/net/dev -The dev pseudo-file contains network device status information. This gives -the number of received and sent packets, the number of errors and +The dev pseudo-file contains network device status information. +This gives +the number of received and sent packets, the number of errors and collisions -and other basic statistics. These are used by the +and other basic statistics. +These are used by the .BR ifconfig (8) -program to report device status. The format is: +program to report device status. +The format is: .nf .ft CW @@ -801,7 +830,8 @@ indx interface_name dmi_u dmi_g dmi_address .fi .TP .I /proc/net/igmp -Internet Group Management Protocol. Defined in +Internet Group Management Protocol. +Defined in .IR /usr/src/linux/net/core/igmp.c . .TP .I /proc/net/rarp @@ -809,17 +839,21 @@ This file uses the same format as the .I arp file and contains the current reverse mapping database used to provide .BR rarp (8) -reverse address lookup services. If RARP is not configured into the +reverse address lookup services. +If RARP is not configured into the kernel, this file will not be present. .TP .I /proc/net/raw -Holds a dump of the RAW socket table. Much of the information is not of +Holds a dump of the RAW socket table. +Much of the information is not of use -apart from debugging. The 'sl' value is the kernel hash slot for the +apart from debugging. +The 'sl' value is the kernel hash slot for the socket, the 'local address' is the local address and protocol number pair."St" is -the internal status of the socket. The "tx_queue" and "rx_queue" are the +the internal status of the socket. +The "tx_queue" and "rx_queue" are the outgoing and incoming data queue in terms of kernel memory usage. The "tr", "tm->when", and "rexmits" fields are not used by RAW. The "uid" @@ -830,13 +864,15 @@ field holds the effective UID of the creator of the socket. .\" .BR route (8). .TP .I /proc/net/snmp -This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP +This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP management -information bases for an snmp agent. +information bases for an snmp agent. .TP .I /proc/net/tcp -Holds a dump of the TCP socket table. Much of the information is not -of use apart from debugging. The "sl" value is the kernel hash slot +Holds a dump of the TCP socket table. +Much of the information is not +of use apart from debugging. +The "sl" value is the kernel hash slot for the socket, the "local address" is the local address and port number pair. The "remote address" is the remote address and port number pair (if connected). 'St' is the internal status of the socket. @@ -848,14 +884,17 @@ The "uid" field holds the effective UID of the creator of the socket. .TP .I /proc/net/udp -Holds a dump of the UDP socket table. Much of the information is not of -use apart from debugging. The "sl" value is the kernel hash slot for the +Holds a dump of the UDP socket table. +Much of the information is not of +use apart from debugging. +The "sl" value is the kernel hash slot for the socket, the "local address" is the local address and port number pair. The "remote address" is the remote address and port number pair (if connected). "St" is the internal status of the socket. The "tx_queue" and "rx_queue" are the outgoing and incoming data queue -in terms of kernel memory usage. The "tr", "tm->when", and "rexmits" fields -are not used by UDP. +in terms of kernel memory usage. +The "tr", "tm->when", and "rexmits" fields +are not used by UDP. The "uid" field holds the effective UID of the creator of the socket. The format is: @@ -873,7 +912,8 @@ sl local_address rem_address st tx_queue rx_queue tr rexmits tm->when uid .TP .I /proc/net/unix Lists the UNIX domain sockets present within the system and their -status. The format is: +status. +The format is: .nf .sp .5 .ft CW @@ -887,7 +927,8 @@ Num RefCount Protocol Flags Type St Path Here 'Num' is the kernel table slot number, 'RefCount' is the number of users of the socket, 'Protocol' is currently always 0, 'Flags' represent the internal kernel flags holding the status of the -socket. Currently, type is always '1' (Unix domain datagram sockets are +socket. +Currently, type is always '1' (Unix domain datagram sockets are not yet supported in the kernel). 'St' is the internal state of the socket and Path is the bound path (if any) of the socket. .TP @@ -900,50 +941,55 @@ This is a listing of all PCI devices found during kernel initialization and their configuration. .TP .I /proc/scsi -A directory with the scsi mid-level pseudo-file and various SCSI lowlevel -driver -directories, which contain a file for each SCSI host in this system, all -of -which give the status of some part of the SCSI IO subsystem. -These files contain ASCII structures and are, therefore, readable with -cat. +A directory with the scsi mid-level pseudo-file and various SCSI lowlevel +driver +directories, which contain a file for each SCSI host in this system, all +of +which give the status of some part of the SCSI IO subsystem. +These files contain ASCII structures and are, therefore, readable with +cat. -You can also write to some of the files to reconfigure the subsystem or +You can also write to some of the files to reconfigure the subsystem or switch certain features on or off. .TP .I /proc/scsi/scsi -This is a listing of all SCSI devices known to the kernel. The listing is +This is a listing of all SCSI devices known to the kernel. +The listing is similar to the one seen during bootup. -scsi currently supports only the \fIadd-single-device\fP command which +scsi currently supports only the \fIadd-single-device\fP command which allows root to add a hotplugged device to the list of known devices. -An -.B echo 'scsi add-single-device 1 0 5 0' > /proc/scsi/scsi -will cause -host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. If there +An +.B echo 'scsi add-single-device 1 0 5 0' > /proc/scsi/scsi +will cause +host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. +If there is already a device known on this address or the address is invalid, an error will be returned. .TP .I /proc/scsi/[drivername] -\fI[drivername]\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, -aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, -scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000. -These directories show up for all drivers that registered at least one -SCSI -HBA. Every directory contains one file per registered host. Every +\fI[drivername]\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, +aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, +scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000. +These directories show up for all drivers that registered at least one +SCSI +HBA. +Every directory contains one file per registered host. +Every host-file is named after the number the host was assigned during -initialization. +initialization. -Reading these files will usually show driver and host configuration, +Reading these files will usually show driver and host configuration, statistics etc. Writing to these files allows different things on different hosts. For example, with the \fIlatency\fP and \fInolatency\fP commands, root can switch on and off command latency measurement code in the -eata_dma driver. With the \fIlockup\fP and \fIunlock\fP commands, -root can control bus lockups simulated by the scsi_debug driver. +eata_dma driver. +With the \fIlockup\fP and \fIunlock\fP commands, +root can control bus lockups simulated by the scsi_debug driver. .TP .I /proc/self This directory refers to the process accessing the /proc filesystem, @@ -951,7 +997,8 @@ and is identical to the /proc directory named by the process ID of the same process. .TP .I /proc/slabinfo -Information about kernel caches. The columns are: +Information about kernel caches. +The columns are: .nf cache-name num-active-objs @@ -961,12 +1008,14 @@ num-active-slabs total-slabs num-pages-per-slab .fi -See +See .BR slabinfo (5) for details. .TP .I /proc/stat -kernel/system statistics. Varies with architecture. Common +kernel/system statistics. +Varies with architecture. +Common entries include: .RS .TP @@ -976,7 +1025,7 @@ USER_HZ (1/100ths of a second on most architectures), that the system spent in user mode, user mode with low priority (nice), system mode, and the idle task, respectively. -.\" FIXME Actually, the following info abut the /proc/stat 'cpu' field +.\" FIXME Actually, the following info abut the /proc/stat 'cpu' field .\" does not seem to be quite right (at least in 2.6.12) The last value should be USER_HZ times the second entry in the uptime pseudo-file. @@ -988,7 +1037,7 @@ In Linux 2.6 this line includes three additional columns: \- time servicing interrupts (since 2.6.0-test4); .I softirq \- time servicing softirqs (since 2.6.0-test4). -.\" FIXME 2.6.11 adds a further column "steal" (see +.\" FIXME 2.6.11 adds a further column "steal" (see .\" fs/proc/proc_misc.c); this is not yet described... .TP \fIpage 5741 1808\fP @@ -998,7 +1047,7 @@ out (from disk). \fIswap 1 0\fP The number of swap pages that have been brought in and out. .TP -.\" FIXME The following is not the full picture for the 'intr' of +.\" FIXME The following is not the full picture for the 'intr' of .\" /proc/stat on 2.6: \fIintr 1462898\fP This line shows counts of interrupts serviced since boot time, @@ -1030,7 +1079,8 @@ Number of processes blocked waiting for I/O to complete. .RE .TP .I /proc/swaps -Swap areas in use. See also +Swap areas in use. +See also .BR swapon (8). .TP .I /proc/sys @@ -1039,7 +1089,8 @@ and subdirectories corresponding to kernel variables. These variables can be read and sometimes modified using the \fIproc\fP file system, and the .BR sysctl (2) -system call. Presently, there are subdirectories +system call. +Presently, there are subdirectories .IR abi ", " debug ", " dev ", " fs ", " kernel ", " net ", " proc ", " .IR rxrpc ", " sunrpc " and " vm that each contain more files and subdirectories. @@ -1060,21 +1111,21 @@ some systems, it may be empty. This contains the subdirectories .IR binfmt_misc ", " inotify ", and " mqueue , and files -.IR dentry-state ", " dir-notify-enable ", " dquot-nr ", " file-max ", " -.IR file-nr ", " inode-max ", " inode-nr ", " inode-state ", " -.IR lease-break-time ", " leases-enable ", " +.IR dentry-state ", " dir-notify-enable ", " dquot-nr ", " file-max ", " +.IR file-nr ", " inode-max ", " inode-nr ", " inode-state ", " +.IR lease-break-time ", " leases-enable ", " .IR overflowgid ", " overflowuid ", " .IR suid_dumpable ", " .IR super-max ", and " super-nr . .TP .I /proc/sys/fs/binfmt_misc -Documentation for files in this directory can be found +Documentation for files in this directory can be found in the kernel sources in .IR Documentation/binfmt_misc.txt . .TP .I /proc/sys/fs/dentry-state -This file contains six numbers, -.IR nr_dentry ", " nr_unused ", " age_limit " (age in seconds), " +This file contains six numbers, +.IR nr_dentry ", " nr_unused ", " age_limit " (age in seconds), " want_pages (pages requested by system) and two dummy values. nr_dentry seems to be 0 all the time. @@ -1129,12 +1180,12 @@ The kernel constant imposes an upper limit on the value that may be placed in .IR file-max . -If you increase +If you increase .IR /proc/sys/fs/file-max "," be sure to increase .I /proc/sys/fs/inode-max to 3-4 times the new -value of +value of .IR /proc/sys/fs/file-max "," or you will run out of inodes. .TP @@ -1143,21 +1194,24 @@ This (read-only) file gives the number of files presently opened. It contains three numbers: The number of allocated file handles, the number of free file handles and the maximum -number of file handles. The kernel allocates file handles dynamically, -but it -doesn't free them again. If the number of allocated files is close to the +number of file handles. +The kernel allocates file handles dynamically, but it +doesn't free them again. +If the number of allocated files is close to the maximum, you should consider increasing the maximum. When the number of free file handles is large, you've encountered a peak in your usage of file handles and you probably don't need to increase the maximum. .TP -.I /proc/sys/fs/inode-max +.I /proc/sys/fs/inode-max This file contains the maximum number of in-memory inodes. On some (2.4) systems, it may not be -present. This value should be 3-4 times larger +present. +This value should be 3-4 times larger than the value in file-max, since stdin, stdout and network sockets also -need an inode to handle them. When you regularly run +need an inode to handle them. +When you regularly run out of inodes, you need to increase this value. .TP .I /proc/sys/fs/inode-nr @@ -1165,11 +1219,10 @@ This file contains the first two values from inode-state. .TP .I /proc/sys/fs/inode-state This file -contains seven numbers: nr_inodes, nr_free_inodes, preshrink and four -dummy -values. -nr_inodes is the number of inodes the system has -allocated. This can be slightly more than inode-max because +contains seven numbers: nr_inodes, nr_free_inodes, preshrink and four +dummy values. +nr_inodes is the number of inodes the system has allocated. +This can be slightly more than inode-max because Linux allocates them one page full at a time. nr_free_inodes represents the number of free inodes. preshrink is non-zero when the nr_inodes > inode-max and the @@ -1177,12 +1230,12 @@ system needs to prune the inode list instead of allocating more. .TP .IR /proc/sys/fs/inotify " (since Linux 2.6.13)" -This directory contains files +This directory contains files .IR max_queued_events ", " max_user_instances ", and " max_user_watches , that can be used to limit the amount of kernel memory consumed by the .I inotify interface. -For further details, see +For further details, see .BR inotify (7). .TP .I /proc/sys/fs/lease-break-time @@ -1203,11 +1256,11 @@ If this file contains the value 0, leases are disabled. A non-zero value enables leases. .TP .IR /proc/sys/fs/mqueue " (since Linux 2.6.6)" -This directory contains files +This directory contains files .IR msg_max ", " msgsize_max ", and " queues_max , controlling the resources used by POSIX message queues. See -.BR mq_overview (7) +.BR mq_overview (7) for details. .TP .IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid @@ -1215,51 +1268,53 @@ These files allow you to change the value of the fixed UID and GID. The default is 65534. Some filesystems only support 16-bit UIDs and GIDs, although in Linux -UIDs and GIDs are 32 bits. When one of these filesystems is mounted +UIDs and GIDs are 32 bits. +When one of these filesystems is mounted with writes enabled, any UID or GID that would exceed 65535 is translated to the overflow value before being written to disk. .TP .IR /proc/sys/fs/suid_dumpable " (since Linux 2.6.13)" .\" The following is based on text from Documentation/sysctl/kernel.txt -The value in this file determines whether core dump files are +The value in this file determines whether core dump files are produced for set-user-ID or otherwise protected/tainted binaries. Three different integer values can be specified: .sp \fI0\ (default)\fP This provides the traditional (pre-Linux 2.6.13) behaviour. -A core dump will not be produced for a process which has +A core dump will not be produced for a process which has changed credentials (by calling -.BR seteuid (2), -.BR setgid (2), -or similar, or by executing a set-user-ID or set-group-ID program) +.BR seteuid (2), +.BR setgid (2), +or similar, or by executing a set-user-ID or set-group-ID program) or whose binary does not have read permission enabled. .sp \fI1\ ("debug")\fP All processes dump core when possible. -The core dump is owned by the file system user ID of the dumping process +The core dump is owned by the file system user ID of the dumping process and no security is applied. This is intended for system debugging situations only. Ptrace is unchecked. .sp \fI2\ ("suidsafe")\fP -Any binary which normally would not be dumped (see "0" above) -is dumped readable by root only. +Any binary which normally would not be dumped (see "0" above) +is dumped readable by root only. This allows the user to remove the core dump file but not to read it. -For security reasons core dumps in this mode will not overwrite one +For security reasons core dumps in this mode will not overwrite one another or other files. This mode is appropriate when administrators are attempting to debug problems in a normal environment. .TP -.I /proc/sys/fs/super-max -This file +.I /proc/sys/fs/super-max +This file controls the maximum number of superblocks, and thus the maximum number of mounted filesystems the kernel -can have. You only need to increase super-max if you need to +can have. +You only need to increase super-max if you need to mount more filesystems than the current value in super-max allows you to. .TP .I /proc/sys/fs/super-nr -This file +This file contains the number of filesystems currently mounted. .TP .I /proc/sys/kernel @@ -1267,28 +1322,32 @@ This directory contains files .IR acct ", " cad_pid ", " cap-bound ", " .IR core_pattern ", " core_uses_pid ", " .IR ctrl-alt-del ", " dentry-state ", " domainname ", " -.IR hotplug ", " hostname ", " +.IR hotplug ", " hostname ", " .IR htab-reclaim " (PowerPC only), " .IR java-appletviewer " (binfmt_java, obsolete), " .IR java-interpreter " (binfmt_java, obsolete), " l2cr " (PowerPC only), " -.IR modprobe ", " msgmax ", " msgmnb ", " +.IR modprobe ", " msgmax ", " msgmnb ", " .IR msgmni ", " osrelease ", " ostype ", " overflowgid ", " overflowuid , .IR panic ", " panic_on_oops ", " pid_max ", " .IR powersave-nap " (PowerPC only), " printk ", " pty ", " random ", " -.IR real-root-dev ", " reboot-cmd " (SPARC only), " rtsig-max ", " +.IR real-root-dev ", " reboot-cmd " (SPARC only), " rtsig-max ", " .IR rtsig-nr ", " sem ", " sg-big-buff ", " .IR shmall ", " shmmax ", " shmmni ", " sysrq ", " tainted ", " threads-max , .IR version ", and " zero-paged " (PowerPC only)." .TP .I /proc/sys/kernel/acct -This file +This file contains three numbers: highwater, lowwater and frequency. If BSD-style process accounting is enabled these values control -its behaviour. If free space on filesystem where the log lives -goes below lowwater percent accounting suspends. If free space gets -above highwater percent accounting resumes. Frequency determines +its behaviour. +If free space on filesystem where the log lives +goes below lowwater percent accounting suspends. +If free space gets +above highwater percent accounting resumes. +Frequency determines how often the kernel checks the amount of free space (value is in -seconds). Default values are 4, 2 and 30. +seconds). +Default values are 4, 2 and 30. That is, suspend accounting if <= 2% of space is free; resume it if >= 4% of space is free; consider information about amount of free space valid for 30 seconds. @@ -1298,7 +1357,7 @@ This file holds the value of the kernel .IR "capability bounding set" (expressed as a signed decimal number). This set is ANDed against the capabilities permitted to a process -during +during .BR exec (). .TP .I /proc/sys/kernel/core_pattern @@ -1354,8 +1413,10 @@ has the same effect as Note, however, that the classic darkstar.frop.org has the hostname "darkstar" and DNS (Internet Domain Name Server) domainname "frop.org", not to be confused with the NIS (Network -Information Service) or YP (Yellow Pages) domainname. These two -domain names are in general different. For a detailed discussion +Information Service) or YP (Yellow Pages) domainname. +These two +domain names are in general different. +For a detailed discussion see the .BR hostname (1) man page. @@ -1369,7 +1430,9 @@ each time the system hits the idle loop. .I /proc/sys/kernel/l2cr (PowerPC only) This file contains a flag that controls the L2 cache of G3 processor -boards. If 0, the cache is disabled. Enabled if non-zero. +boards. +If 0, the cache is disabled. +Enabled if non-zero. .TP .I /proc/sys/kernel/modprobe This file @@ -1410,40 +1473,42 @@ gives read/write access to the kernel variable .IR panic_timeout . If this is zero, the kernel will loop on a panic; if non-zero it indicates that the kernel should autoreboot after this number -of seconds. When you use the +of seconds. +When you use the software watchdog device driver, the recommended setting is 60. .TP .I /proc/sys/kernel/panic_on_oops -This file (new in Linux 2.5) controls the kernel's behaviour when an oops -or -BUG is encountered. If this file contains 0, then the system -tries to continue operation. If it contains 1, then the system +This file (new in Linux 2.5) controls the kernel's behaviour when an oops +or BUG is encountered. +If this file contains 0, then the system +tries to continue operation. +If it contains 1, then the system delays a few seconds (to give klogd time to record the oops output) -and then panics. +and then panics. If the .I /proc/sys/kernel/panic file is also non-zero then the machine will be rebooted. .TP .I /proc/sys/kernel/pid_max -This file +This file (new in Linux 2.5) specifies the value at which PIDs wrap around (i.e., the value in this file is one greater than the maximum PID). The default value for this file, 32768, results in the same range of PIDs as on earlier kernels. -On 32-bit platforms, 32768 is the maximum value for +On 32-bit platforms, 32768 is the maximum value for .IR pid_max . -On 64-bit systems, +On 64-bit systems, .I pid_max can be set to any value up to 2^22 (PID_MAX_LIMIT, approximately 4 million). -.\" Prior to 2.6.10, pid_max could also be raised above 32768 on 32-bit +.\" Prior to 2.6.10, pid_max could also be raised above 32768 on 32-bit .\" platforms, but this broke /proc/PID .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2 .TP .IR /proc/sys/kernel/powersave-nap " (PowerPC only)" -This file -contains a flag. If set, Linux-PPC will use the 'nap' mode of +This file contains a flag. +If set, Linux-PPC will use the 'nap' mode of powersaving, otherwise the 'doze' mode will be used. .TP @@ -1452,7 +1517,8 @@ The four values in this file are console_loglevel, default_message_loglevel, minimum_console_level and default_console_loglevel. These values influence printk() behavior when printing or -logging error messages. See +logging error messages. +See .BR syslog (2) for more info on the different loglevels. Messages with a higher priority than @@ -1464,7 +1530,7 @@ console_loglevel can be set. default_console_loglevel is the default value for console_loglevel. .TP .IR /proc/sys/kernel/pty " (since Linux 2.6.4)" -This directory +This directory contains two files relating to the number of Unix 98 pseudo-terminals (see .BR pts (4)) @@ -1481,7 +1547,7 @@ indicates how many pseudo-terminals are currently in use. This directory contains various parameters controlling the operation of the file .IR /dev/random . -See +See .BR random (4) for further information. .TP @@ -1491,11 +1557,12 @@ is documented in the kernel source file Documentation/initrd.txt. .TP .IR /proc/sys/kernel/reboot-cmd " (Sparc only) " This file seems to be a way to give an argument to the SPARC -ROM/Flash boot loader. Maybe to tell it what to do after +ROM/Flash boot loader. +Maybe to tell it what to do after rebooting? .TP .I /proc/sys/kernel/rtsig-max -(Only in kernels up to and including 2.6.7; see +(Only in kernels up to and including 2.6.7; see .BR setrlimit (2)) This file can be used to tune the maximum number of POSIX realtime (queued) signals that can be outstanding @@ -1507,7 +1574,7 @@ This file shows the number POSIX realtime signals currently queued. .TP .IR /proc/sys/kernel/sem " (since Linux 2.4)" This file contains 4 numbers defining limits for System V IPC semaphores. -These fields are, in order: +These fields are, in order: .RS .IP SEMMSL 8 The maximum semaphores per semaphore set. @@ -1522,13 +1589,12 @@ A system-wide limit on the maximum number of semaphore identifiers. .RE .TP .I /proc/sys/kernel/sg-big-buff -This file +This file shows the size of the generic SCSI device (sg) buffer. You can't tune it just yet, but you could change it on compile time by editing include/scsi/sg.h and changing -the value of SG_BIG_BUFF. However, there shouldn't be any reason to -change -this value. +the value of SG_BIG_BUFF. +However, there shouldn't be any reason to change this value. .TP .I /proc/sys/kernel/shmall This file @@ -1538,10 +1604,11 @@ System V shared memory. .I /proc/sys/kernel/shmmax This file can be used to query and set the run time limit -on the maximum (System V IPC) shared memory segment size that can be +on the maximum (System V IPC) shared memory segment size that can be created. -Shared memory segments up to 1Gb are now supported in the -kernel. This value defaults to SHMMAX. +Shared memory segments up to 1Gb are now supported in the +kernel. +This value defaults to SHMMAX. .TP .I /proc/sys/kernel/shmmni (available in Linux 2.4 and onwards) @@ -1564,7 +1631,8 @@ date behind it indicates the time the kernel was built. .TP .IR /proc/sys/kernel/zero-paged " (PowerPC only) " This file -contains a flag. When enabled (non-zero), Linux-PPC will pre-zero pages in +contains a flag. +When enabled (non-zero), Linux-PPC will pre-zero pages in the idle loop, possibly speeding up get_free_pages. .TP .I /proc/sys/net @@ -1579,10 +1647,11 @@ This directory may be empty. .TP .I /proc/sys/sunrpc This directory supports Sun remote procedure call for network file system -(NFS). On some systems, it is not present. +(NFS). +On some systems, it is not present. .TP .I /proc/sys/vm -This directory contains files for memory management tuning, buffer and +This directory contains files for memory management tuning, buffer and cache management. .TP @@ -1590,16 +1659,16 @@ management. Writing to this file causes the kernel to drop clean caches, dentries and inodes from memory, causing that memory to become free. -To free pagecache, use +To free pagecache, use .IR "echo 1 > /proc/sys/vm/drop_caches" ; to free dentries and inodes, use .IR "echo 2 > /proc/sys/vm/drop_caches" ; to free pagecache, dentries and inodes, use .IR "echo 3 > /proc/sys/vm/drop_caches" . -Because this is a non-destructive operation and dirty objects +Because this is a non-destructive operation and dirty objects are not freeable, the -user should run +user should run .BR sync (8) first. .TP @@ -1609,7 +1678,8 @@ If non-zero, this disable the new 32-bit memory-mapping layout; the kernel will use the legacy (2.4) layout for all processes. .TP .I /proc/sys/vm/overcommit_memory -This file contains the kernel virtual memory accounting mode. Values are: +This file contains the kernel virtual memory accounting mode. +Values are: .br 0: heuristic overcommit (this is the default) .br @@ -1629,13 +1699,13 @@ is the size of the physical memory, and r is the contents of the file .IR /proc/sys/vm/overcommit_ratio . .TP .I /proc/sys/vm/overcommit_ratio -See the description of +See the description of .IR /proc/sys/vm/overcommit_memory . .TP .I /proc/sysvipc -Subdirectory containing the pseudo-files +Subdirectory containing the pseudo-files .IR msg ", " sem " and " shm "." -These files list the System V Interprocess Communication (IPC) objects +These files list the System V Interprocess Communication (IPC) objects (respectively: message queues, semaphores, and shared memory) that currently exist on the system, providing similar information to that available via @@ -1646,7 +1716,7 @@ for easy understanding. provides further background on the information shown by these files. .TP .I /proc/tty -Subdirectory containing the pseudo-files and subdirectories for +Subdirectory containing the pseudo-files and subdirectories for tty drivers and line disciplines. .TP .I /proc/uptime @@ -1655,8 +1725,9 @@ and the amount of time spent in idle process (seconds). .TP .I /proc/version This string identifies the kernel version that is currently running. -It includes the contents of /proc/sys/ostype, /proc/sys/osrelease and -/proc/sys/version. For example: +It includes the contents of /proc/sys/ostype, /proc/sys/osrelease and +/proc/sys/version. +For example: .nf .in -2 .ft CW @@ -1702,7 +1773,7 @@ This is useful for analysing virtual memory behaviour. .I /usr/src/linux/Documentation/filesystems/proc.txt .SH CAVEATS Note that many strings (i.e., the environment and command line) are in -the internal format, with sub-fields terminated by null bytes ('\\0'), +the internal format, with sub-fields terminated by null bytes ('\\0'), so you may find that things are more readable if you use \fIod \-c\fP or \fItr "\\000" "\\n"\fP to read them. diff --git a/man5/protocols.5 b/man5/protocols.5 index 59bac1efb..6211ef0ac 100644 --- a/man5/protocols.5 +++ b/man5/protocols.5 @@ -30,13 +30,16 @@ protocols \- the protocols definition file .SH DESCRIPTION This file is a plain ASCII file, describing the various DARPA internet -protocols that are available from the TCP/IP subsystem. It should be +protocols that are available from the TCP/IP subsystem. +It should be consulted instead of using the numbers in the ARPA include files, or, -even worse, just guessing them. These numbers will occur in the +even worse, just guessing them. +These numbers will occur in the protocol field of any ip header. Keep this file untouched since changes would result in incorrect ip -packages. Protocol numbers and names are specified by the IANA +packages. +Protocol numbers and names are specified by the IANA (Internet Assigned Numbers Authority). .\" .. by the DDN Network Information Center. @@ -54,7 +57,8 @@ of the line following it are ignored. The field descriptions are: .TP .I protocol -the native name for the protocol. For example ip, tcp, or udp. +the native name for the protocol. +For example ip, tcp, or udp. .TP .I number the official number for this protocol as it will appear within the ip diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5 index 84f612ab3..4f7d4fca2 100644 --- a/man5/resolv.conf.5 +++ b/man5/resolv.conf.5 @@ -100,10 +100,14 @@ with a total of 256 characters. .TP \fBsortlist\fP Sortlist allows addresses returned by gethostbyname to be sorted. -A sortlist is specified by IP address netmask pairs. The netmask is -optional and defaults to the natural netmask of the net. The IP address -and optional network pairs are separated by slashes. Up to 10 pairs may -be specified. E.g., +A sortlist is specified by IP address netmask pairs. +The netmask is +optional and defaults to the natural netmask of the net. +The IP address +and optional network pairs are separated by slashes. +Up to 10 pairs may +be specified. +E.g., .br .in +2 sortlist 130.155.160.0/255.255.240.0 130.155.0.0 @@ -127,7 +131,8 @@ sets RES_DEBUG in sets a threshold for the number of dots which must appear in a name given to \fBres_query\fP() (see .BR resolver (3)) -before an \fIinitial absolute query\fP will be made. The default for +before an \fIinitial absolute query\fP will be made. +The default for \fIn\fP is ``1'', meaning that if there are any dots in a name, the name will be tried first as an absolute name before any \fIsearch list\fP elements are appended to it. @@ -135,14 +140,15 @@ elements are appended to it. .BI timeout: n sets the amount of time the resolver will wait for a response from a remote name server before retrying the -query via a different name server. Measured in seconds, +query via a different name server. +Measured in seconds, the default is RES_TIMEOUT (currently 5, see ). .TP .BI attempts: n sets the number of times the resolver will send a query to its name servers before giving up and returning -an error to the calling application. The default -is RES_DFLRETRY (currently 2, see ). +an error to the calling application. +The default is RES_DFLRETRY (currently 2, see ). .TP .B rotate sets RES_ROTATE in @@ -181,8 +187,8 @@ amended on a per-process basis by setting the environment variable as explained above under \fBoptions\fP. .LP The keyword and value must appear on a single line, and the keyword -(e.g. \fBnameserver\fP) must start the line. The value follows -the keyword, separated by white space. +(e.g. \fBnameserver\fP) must start the line. +The value follows the keyword, separated by white space. .SH FILES .IR /etc/resolv.conf , .I diff --git a/man5/rpc.5 b/man5/rpc.5 index bbdc442a3..c5b3c9075 100644 --- a/man5/rpc.5 +++ b/man5/rpc.5 @@ -1,7 +1,7 @@ .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) .\" .\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI; -.TH RPC 5 1985-09-26 +.TH RPC 5 1985-09-26 .SH NAME rpc \- rpc program number data base .SH SYNOPSIS @@ -63,7 +63,7 @@ status 100024 bootparam 100026 ypupdated 100028 ypupdate keyserv 100029 keyserver -tfsd 100037 +tfsd 100037 nsed 100038 nsemntd 100039 .fi diff --git a/man5/securetty.5 b/man5/securetty.5 index 7c710303f..844e616e8 100644 --- a/man5/securetty.5 +++ b/man5/securetty.5 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sun Jul 25 11:06:27 1993 by Rik Faith (faith@cs.unc.edu) .TH SECURETTY 5 1992-12-29 "Linux" "Linux Programmer's Manual" .SH NAME diff --git a/man5/services.5 b/man5/services.5 index f97f225f6..cb44035ce 100644 --- a/man5/services.5 +++ b/man5/services.5 @@ -11,7 +11,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -19,7 +19,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -37,40 +37,44 @@ services \- Internet network services list .B services is a plain ASCII file providing a mapping between friendly textual names for internet services, and their underlying assigned port -numbers and protocol types. Every networking program should look into +numbers and protocol types. +Every networking program should look into this file to get the port number (and protocol) for its service. The C library routines .BR getservent (3), .BR getservbyname (3), .BR getservbyport (3), .BR setservent (3), -and +and .BR endservent (3) support querying this file from programs. Port numbers are assigned by the IANA (Internet Assigned Numbers Authority), and their current policy is to assign both TCP and UDP -protocols when assigning a port number. Therefore, most entries will +protocols when assigning a port number. +Therefore, most entries will have two entries, even for TCP only services. Port numbers below 1024 (so-called 'low numbered' ports) can only be bound to by root (see .BR bind (2), .BR tcp (7), -and +and .BR udp (7)). This is so clients connecting to low numbered ports can trust that the service running on the port is the standard implementation, -and not a rogue service run by a user of the machine. Well-known port -numbers specified by the IANA are normally located in this root-only -space. +and not a rogue service run by a user of the machine. +Well-known port numbers specified by the IANA are normally +located in this root-only space. -The presence of an entry for a service in the +The presence of an entry for a service in the .B services file does not necessarily mean that the service is currently running -on the machine. See +on the machine. +See .BR inetd.conf (5) -for the configuration of Internet services offered. Note that not all +for the configuration of Internet services offered. +Note that not all networking services are started by .BR inetd (8), and so won't appear in @@ -94,44 +98,51 @@ Each line describes one service, and is of the form: where: .TP 10 .I service-name -is the friendly name the service is known by and looked up under. It -is case sensitive. Often, the client program is named after the +is the friendly name the service is known by and looked up under. +It is case sensitive. +Often, the client program is named after the .IR service-name "." .TP .I port is the port number (in decimal) to use for this service. .TP .I protocol -is the type of protocol to be used. This field should match an entry +is the type of protocol to be used. +This field should match an entry in the .BR protocols (5) -file. Typical values include +file. +Typical values include .B tcp and .BR udp . .TP .I aliases is an optional space or tab separated list of other names for this -service (but see the BUGS section below). Again, the names are case +service (but see the BUGS section below). +Again, the names are case sensitive. .PP Either spaces or tabs may be used to separate the fields. Comments are started by the hash sign (#) and continue until the end -of the line. Blank lines are skipped. +of the line. +Blank lines are skipped. The .I service-name should begin in the first column of the file, since leading spaces are not stripped. .I service-names -can be any printable characters excluding space and tab. However, -a conservative choice of characters should be used to minimize -inter-operability problems. E.g., a\-z, 0\-9, and hyphen (\-) would seem a +can be any printable characters excluding space and tab. +However, a conservative choice of characters should be used to minimize +inter-operability problems. +E.g., a\-z, 0\-9, and hyphen (\-) would seem a sensible choice. Lines not matching this format should not be present in the -file. (Currently, they are silently skipped by +file. +(Currently, they are silently skipped by .BR getservent (3), .BR getservbyname (3), and @@ -142,7 +153,8 @@ As a backwards compatibility feature, the slash (/) between the .I port number and .I protocol -name can in fact be either a slash or a comma (,). Use of the comma in +name can in fact be either a slash or a comma (,). +Use of the comma in modern installations is depreciated. This file might be distributed over a network using a network-wide diff --git a/man5/shells.5 b/man5/shells.5 index 99b453d89..fb81f05d2 100644 --- a/man5/shells.5 +++ b/man5/shells.5 @@ -34,7 +34,8 @@ This file is consulted by and available to be queried by other programs. .PP 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 +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 EXAMPLE .I /etc/shells diff --git a/man5/slabinfo.5 b/man5/slabinfo.5 index 356605967..bf8201869 100644 --- a/man5/slabinfo.5 +++ b/man5/slabinfo.5 @@ -28,9 +28,11 @@ .SH DESCRIPTION Frequently used objects in the Linux kernel (buffer heads, inodes, dentries, etc.) -have their own cache. The file +have their own cache. +The file .I /proc/slabinfo -gives statistics. For example: +gives statistics. +For example: .LP .RS .nf @@ -58,7 +60,8 @@ least one active object, the total number of allocated pages, and the number of pages per slab are given. Note that because of object alignment and slab cache overhead, -objects are not normally packed tightly into pages. Pages with +objects are not normally packed tightly into pages. +Pages with even one in-use object are considered in-use and cannot be freed. @@ -70,16 +73,18 @@ the number of times the cache has grown (new pages added to this cache); the number of times the cache has been reaped (unused pages removed from this cache); and the number of times there was an error allocating new pages -to this cache. If slab cache statistics are not enabled +to this cache. +If slab cache statistics are not enabled for this kernel, these columns will not be shown. SMP systems will also have "(SMP)" in the first line of output, and will have two additional columns for each slab, reporting the slab allocation policy for the CPU-local cache (to reduce the need for inter-CPU synchronization -when allocating objects from the cache). The first column -is the per-CPU limit: the maximum number of objects that -will be cached for each CPU. The second column is the +when allocating objects from the cache). +The first column is the per-CPU limit: the maximum number of objects that +will be cached for each CPU. +The second column is the batchcount: the maximum number of free objects in the global cache that will be transferred to the per-CPU cache if it is empty, or the number of objects to be returned @@ -87,10 +92,12 @@ to the global cache if the per-CPU cache is full. If both slab cache statistics and SMP are defined, there will be four additional columns, reporting the per-CPU -cache statistics. The first two are the per-CPU cache +cache statistics. +The first two are the per-CPU cache allocation hit and miss counts: the number of times an object was or was not available in the per-CPU cache -for allocation. The next two are the per-CPU cache free +for allocation. +The next two are the per-CPU cache free hit and miss counts: the number of times a freed object could or could not fit within the per-CPU cache limit, before flushing objects to the global cache. diff --git a/man5/termcap.5 b/man5/termcap.5 index 302287eba..2453f7b1b 100644 --- a/man5/termcap.5 +++ b/man5/termcap.5 @@ -30,38 +30,45 @@ termcap \- terminal capability database .SH DESCRIPTION The termcap database is an obsolete facility for describing the -capabilities of character-cell terminals and printers. It is retained -only for capability with old programs; new ones should use the +capabilities of character-cell terminals and printers. +It is retained only for capability with old programs; +new ones should use the .BR terminfo (5) database and associated libraries. .LP .I /etc/termcap is an ASCII file (the database master) that lists the capabilities of -many different types of terminals. Programs can read termcap to find +many different types of terminals. +Programs can read termcap to find the particular escape codes needed to control the visual attributes of -the terminal actually in use. (Other aspects of the terminal are -handled by +the terminal actually in use. +(Other aspects of the terminal are +handled by .BR stty (1).) The termcap database is indexed on the TERM environment variable. .LP Termcap entries must be defined on a single logical line, with `\\' -used to suppress the newline. Fields are separated by `:'. The first -field of each entry starts at the left-hand margin, and contains a list -of names for the terminal, separated by '|'. +used to suppress the newline. +Fields are separated by `:'. +The first field of each entry starts at the left-hand margin, +and contains a list of names for the terminal, separated by '|'. .LP The first subfield may (in BSD termcap entries from versions 4.3 and -prior) contain a short name consisting of two characters. This short -name may consist of capital or small letters. In 4.4BSD termcap -entries this field is omitted. +prior) contain a short name consisting of two characters. +This short name may consist of capital or small letters. +In 4.4BSD termcap entries this field is omitted. .LP The second subfield (first, in the newer 4.4BSD format) contains the -name used by the environment variable TERM. It should be spelled in -lowercase letters. Selectable hardware capabilities should be marked -by appending a hyphen and a suffix to this name. See below for an -example. Usual suffixes are w (more than 80 characters wide), am +name used by the environment variable TERM. +It should be spelled in lowercase letters. +Selectable hardware capabilities should be marked +by appending a hyphen and a suffix to this name. +See below for an example. +Usual suffixes are w (more than 80 characters wide), am (automatic margins), nam (no automatic margins), and rv (reverse video -display). The third subfield contains a long and descriptive name for +display). +The third subfield contains a long and descriptive name for this termcap entry. .LP Subsequent fields contain the terminal capabilities; any continued @@ -69,8 +76,8 @@ capability lines must be indented one tab from the left margin. .LP Although there is no defined order, it is suggested to write first boolean, then numeric, and then string capabilities, each sorted -alphabetically without looking at lower or upper spelling. Capabilities -of similar functions can be written in one line. +alphabetically without looking at lower or upper spelling. +Capabilities of similar functions can be written in one line. .LP .nf Example for: @@ -368,9 +375,11 @@ There are several ways of defining the control codes for string capabilities: .LP Every normal character represents itself, except '^','\e' and '%'. .LP -A '^x' means Control-x. Control-A equals 1 decimal. +A '^x' means Control-x. +Control-A equals 1 decimal. .LP -\ex means a special code. x can be one of the following characters: +\ex means a special code. +x can be one of the following characters: .RS E Escape (27) .br @@ -384,7 +393,8 @@ b Backspace (8) .br f Form feed (12) .br -0 Null character. A \exxx specifies the octal character xxx. +0 Null character. +A \exxx specifies the octal character xxx. .RE .IP i Increments parameters by one. @@ -400,7 +410,8 @@ Do ASCII output of this parameter with a field with of 3 Print a '%' .LP If you use binary output, then you should avoid the null character -because it terminates the string. You should reset tabulator expansion +because it terminates the string. +You should reset tabulator expansion if a tabulator can be the binary output of a parameter. .IP Warning: The above metacharacters for parameters may be wrong, they document Minix @@ -412,7 +423,8 @@ start the alternative charset .IP ae end it .IP ac -pairs of characters. The first character is the name of the block graphic +pairs of characters. +The first character is the name of the block graphic symbol and the second characters is its definition. .LP The following names are available: diff --git a/man5/ttytype.5 b/man5/ttytype.5 index b8b1d4d73..6cdaaba49 100644 --- a/man5/ttytype.5 +++ b/man5/ttytype.5 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:17:50 1993 by Rik Faith .\" Modified Thu Oct 19 21:25:21 MET 1995 by Martin Schulze .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond @@ -28,14 +28,15 @@ .SH NAME ttytype \- terminal device to default terminal type mapping .SH DESCRIPTION -The +The .I /etc/ttytype file associates termcap/terminfo terminal type names -with tty lines. Each line consists of a terminal type, followed by +with tty lines. +Each line consists of a terminal type, followed by whitespace, followed by a tty name (a device name without the .IR /dev/ ") prefix." -This association is used by the program +This association is used by the program .BR tset (1) to set the environment variable TERM to the default terminal name for the user's current tty. diff --git a/man5/utmp.5 b/man5/utmp.5 index 807fa2844..e9db6ea27 100644 --- a/man5/utmp.5 +++ b/man5/utmp.5 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) .\" Modified 1995-02-26 by Michael Haardt .\" Modified 1996-07-20 by Michael Haardt @@ -34,13 +34,15 @@ utmp, wtmp \- login records The .I utmp file allows one to discover information about who is currently using the -system. There may be more users currently using the system, because not +system. +There may be more users currently using the system, because not all programs use utmp logging. .PP .B Warning: .I utmp must not be writable, because many system programs (foolishly) -depend on its integrity. You risk faked system logfiles and +depend on its integrity. +You risk faked system logfiles and modifications of system files if you leave .I utmp writable to any user. @@ -81,9 +83,9 @@ struct utmp { char ut_host[UT_HOSTSIZE]; /* hostname for remote login */ struct exit_status ut_exit; /* The exit status of a process marked as DEAD_PROCESS */ - - /* The ut_session and ut_tv fields must be the same size when - compiled 32- and 64-bit. This allows data files and shared + + /* The ut_session and ut_tv fields must be the same size when + compiled 32- and 64-bit. This allows data files and shared memory to be shared between 32- and 64-bit applications */ #if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32 int32_t ut_session; /* Session ID, used for windowing */ @@ -126,9 +128,10 @@ Before an entry is processed, though, cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing \fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP -and where no process with PID \fIut_pid\fP exists. If no empty record -with the needed \fIut_id\fP can be found, init creates a new one. It -sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the +and where no process with PID \fIut_pid\fP exists. +If no empty record +with the needed \fIut_id\fP can be found, init creates a new one. +It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the current values, and \fIut_type\fP to \fBINIT_PROCESS\fP. .PP .BR getty (8) @@ -138,7 +141,8 @@ for connection to be established. .BR login (8), after a user has been authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes -\fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP. Depending on +\fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP. +Depending on .BR getty (8) and .BR login (8), @@ -155,29 +159,35 @@ clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes. and other terminal emulators directly create a \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the last two letters of \fI/dev/ttyp\fP\fI%c\fP or by using \fIp\fP\fI%d\fP for -\fI/dev/pts/\fP\fI%d\fP. If they find a \fBDEAD_PROCESS\fP for this ID, -they recycle it, otherwise they create a new entry. If they can, they +\fI/dev/pts/\fP\fI%d\fP. +If they find a \fBDEAD_PROCESS\fP for this ID, +they recycle it, otherwise they create a new entry. +If they can, they will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP as well. .PP \fIxdm\fP(8) should not create a utmp record, because there is no -assigned terminal. Letting it create one will result in errors, such -as 'finger: cannot stat /dev/machine.dom'. It should create wtmp entries, -though, just like +assigned terminal. +Letting it create one will result in errors, such +as 'finger: cannot stat /dev/machine.dom'. +It should create wtmp entries, though, just like .BR ftpd (8) does. .PP .BR telnetd (8) sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to .BR login (8) -as usual. After the telnet session ends, +as usual. +After the telnet session ends, .BR telnetd (8) cleans up utmp in the described way. .PP -The \fIwtmp\fP file records all logins and logouts. Its format is -exactly like \fIutmp\fP except that a null user name indicates a logout -on the associated terminal. Furthermore, the terminal name \fB~\fP +The \fIwtmp\fP file records all logins and logouts. +Its format is exactly like \fIutmp\fP except that a null user name +indicates a logout +on the associated terminal. +Furthermore, the terminal name \fB~\fP with user name \fBshutdown\fP or \fBreboot\fP indicates a system shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP logs the old/new system time when @@ -195,7 +205,7 @@ Note that on \fIbiarch\fP platforms, i.e. systems which can run both \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode. The same goes for \fIut_session\fP and \fIut_time\fP if they are present. This allows data files and shared memory to be shared between -32-bit and 64-bit applications. +32-bit and 64-bit applications. Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP, then instead of the call: .RS @@ -227,13 +237,17 @@ ut.ut_tv.tv_usec = tv.tv_usec; Linux utmp entries conform neither to v7/BSD nor to System V; they are a mix of the two. v7/BSD has fewer fields; most importantly it lacks \fIut_type\fP, which causes native v7/BSD-like programs to display (for -example) dead or login entries. Further, there is no configuration file -which allocates slots to sessions. BSD does so because it lacks -\fIut_id\fP fields. In Linux (as in System V), the \fIut_id\fP field of a +example) dead or login entries. +Further, there is no configuration file +which allocates slots to sessions. +BSD does so because it lacks \fIut_id\fP fields. +In Linux (as in System V), the \fIut_id\fP field of a record will never change once it has been set, which reserves that slot -without needing a configuration file. Clearing \fIut_id\fP may result +without needing a configuration file. +Clearing \fIut_id\fP may result in race conditions leading to corrupted utmp entries and potential -security holes. Clearing the above mentioned fields by filling them +security holes. +Clearing the above mentioned fields by filling them with null bytes is not required by System V semantics, but it allows to run many programs which assume BSD semantics and which do not modify utmp. Linux uses the BSD conventions for line contents, as documented above. @@ -245,7 +259,8 @@ System V has no \fIut_host\fP or \fIut_addr_v6\fP fields. .PP Unlike various other systems, where utmp logging can be disabled by removing the file, utmp -must always exist on Linux. If you want to disable \fIwho\fP(1) then +must always exist on Linux. +If you want to disable \fIwho\fP(1) then do not make utmp world readable. .PP Note that the utmp struct from libc5 has changed in libc6. Because of this, diff --git a/man6/intro.6 b/man6/intro.6 index 74e6a4b69..493614269 100644 --- a/man6/intro.6 +++ b/man6/intro.6 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith (faith@cs.unc.edu) .TH INTRO 6 1993-07-24 "Linux" "Linux Programmer's Manual" .SH NAME @@ -29,4 +29,5 @@ This chapter describes all the games and funny little programs available on the system. .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! diff --git a/man7/LDP.7 b/man7/LDP.7 index 5376f7314..b54b98215 100644 --- a/man7/LDP.7 +++ b/man7/LDP.7 @@ -25,7 +25,7 @@ free documentation resources including guides, FAQs, HOWTOs, and man-pages to the Linux community. .SH AUTHORS The various documents in the LDP archives are maintained by individual -authors, and are listed in the beginning of each HOWTO. +authors, and are listed in the beginning of each HOWTO. If you have any questions or inputs to a document we encourage you to contact the authors directly. @@ -62,7 +62,8 @@ For subscription information, see the website. .PP If you are interested in DocBook beyond the simple markup of your LDP document, you may want to consider joining one of the OASIS DocBook -mailing lists. Please see +mailing lists. +Please see \fBhttp://docbook\&.org/mailinglist/index\&.html\fP for more information. .SH FILES diff --git a/man7/arp.7 b/man7/arp.7 index 84146f23e..4a0515f99 100644 --- a/man7/arp.7 +++ b/man7/arp.7 @@ -6,60 +6,68 @@ .\" of the modification is added to the header. .\" Modified June 1999 Andi Kleen .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ -.TH ARP 7 1999-06-03 "Linux Man Page" "Linux Programmer's Manual" +.TH ARP 7 1999-06-03 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -arp \- Linux ARP kernel module. +arp \- Linux ARP kernel module. .SH DESCRIPTION This kernel protocol module implements the Address Resolution Protocol defined in RFC\ 826. It is used to convert between Layer2 hardware addresses -and IPv4 protocol addresses on directly connected networks. -The user normally doesn't interact directly with this module except to -configure it; +and IPv4 protocol addresses on directly connected networks. +The user normally doesn't interact directly with this module except to +configure it; instead it provides a service for other protocols in the kernel. A user process can receive ARP packets by using .BR packet (7) -sockets. There is also a mechanism for managing the ARP cache +sockets. +There is also a mechanism for managing the ARP cache in user-space by using .BR netlink (7) -sockets. The ARP table can also be controlled via -.BR ioctl (2) -on any -.B PF_INET +sockets. +The ARP table can also be controlled via +.BR ioctl (2) +on any +.B PF_INET socket. The ARP module maintains a cache of mappings between hardware addresses -and protocol addresses. The cache has a limited size so old and less -frequently used entries are garbage-collected. Entries which are marked -as permanent are never deleted by the garbage-collector. The cache can +and protocol addresses. +The cache has a limited size so old and less +frequently used entries are garbage-collected. +Entries which are marked +as permanent are never deleted by the garbage-collector. +The cache can be directly manipulated by the use of ioctls and its behaviour can be -tuned by the sysctls defined below. +tuned by the sysctls defined below. When there is no positive feedback for an existing mapping after some time (see the sysctls below) a neighbour cache entry is considered stale. Positive feedback can be gotten from a higher layer; for example from -a successful TCP ACK. Other protocols can signal forward progress +a successful TCP ACK. +Other protocols can signal forward progress using the .B MSG_CONFIRM flag to .BR sendmsg (2). When there is no forward progress ARP tries to reprobe. It first tries to ask a local arp daemon -.B app_solicit +.B app_solicit times for an updated MAC address. If that fails and an old MAC address is known an unicast probe is send .B ucast_solicit -times. If that fails too it will broadcast a new ARP -request to the network. Requests are only send when there is data queued -for sending. +times. +If that fails too it will broadcast a new ARP +request to the network. +Requests are only send when there is data queued +for sending. -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. +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 -Three ioctls are available on all +Three ioctls are available on all .B PF_INET sockets. They take a pointer to a @@ -113,23 +121,24 @@ If the .B ATF_NETMASK flag is set, then .I arp_netmask -should be valid. +should be valid. 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. +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 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 +The sysctls can be accessed by reading or writing the .I /proc/sys/net/ipv4/neigh/*/* -files or with the +files or with the .BR sysctl (2) -interface. Each interface in the system has its own directory in +interface. +Each interface in the system has its own directory in /proc/sys/net/ipv4/neigh/. -The setting in the `default' directory is used for all newly created +The setting in the `default' directory is used for all newly created devices. -Unless otherwise specified time related sysctls are specified +Unless otherwise specified time related sysctls are specified in seconds. .TP .B anycast_delay @@ -154,18 +163,18 @@ Defaults to 30 seconds. .TP .B delay_first_probe_time Delay before first probe after it has been decided that a neighbour -is stale. +is stale. Defaults to 5 seconds. .TP .B gc_interval -How frequently the garbage collector for neighbour entries +How frequently the garbage collector for neighbour entries should attempt to run. Defaults to 30 seconds. .TP .B gc_stale_time -Determines how often to check for stale neighbour entries. When -a neighbour entry is considered stale it is resolved again before -sending data to it. +Determines how often to check for stale neighbour entries. +When a neighbour entry is considered stale it is resolved again before +sending data to it. Defaults to 60 seconds. .TP .B gc_thresh1 @@ -193,7 +202,7 @@ mapping (generally due to network misconfiguration). Defaults to 1 second. .TP .B mcast_solicit -The maximum number of attempts to resolve an address by +The maximum number of attempts to resolve an address by multicast/broadcast before marking the entry as unreachable. Defaults to 3. .TP @@ -223,18 +232,18 @@ 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 +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 +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 +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 +This man page mashes IPv4 specific and shared between IPv4 and IPv6 functionality together. .SH VERSIONS The @@ -244,9 +253,10 @@ changed in Linux 2.0 to include the member and the ioctl numbers changed at the same time. Support for the old ioctls was dropped in Linux 2.2. -Support for proxy arp entries for networks (netmask not equal 0xffffffff) -was dropped in Linux 2.2. It is replaced by automatic proxy arp setup by -the kernel for all reachable hosts on other interfaces (when +Support for proxy arp entries for networks (netmask not equal 0xffffffff) +was dropped in Linux 2.2. +It is replaced by automatic proxy arp setup by +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. diff --git a/man7/ascii.7 b/man7/ascii.7 index c898a8c58..f0747d51c 100644 --- a/man7/ascii.7 +++ b/man7/ascii.7 @@ -36,7 +36,8 @@ ascii \- the ASCII character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION ASCII is the American Standard Code for Information Interchange. -It is a 7-bit code. Many 8-bit codes (such as ISO 8859-1, the +It is a 7-bit code. +Many 8-bit codes (such as ISO 8859-1, the Linux default character set) contain ASCII as their lower half. The international counterpart of ASCII is known as ISO 646. .LP diff --git a/man7/boot.7 b/man7/boot.7 index 0c3160b8e..516d5bc2a 100644 --- a/man7/boot.7 +++ b/man7/boot.7 @@ -14,7 +14,7 @@ .LP boot\-scripts \- General description of boot sequence .SH "DESCRIPTION" -.LP +.LP The boot sequence varies in details among systems but can be roughly divided to the following steps: (i) hardware boot, (ii) OS loader, @@ -24,12 +24,13 @@ We will describe each of these in more detail below. .SS "Hardware\-boot" After power\-on or hard reset, control is given to a program stored on read only memory (normally -PROM). In PC we usually call this program the -\fBBIOS\fR. +PROM). +In PC we usually call this program the \fBBIOS\fR. This program normally makes a basic self\-test of the machine and accesses non\-volatile memory to read -further parameters. This memory in the PC is +further parameters. +This memory in the PC is battery\-backed CMOS memory, so most people refer to it as the \fBCMOS\fR, although outside of the PC world, it is usually called \fBnvram\fR @@ -43,9 +44,10 @@ to probe as possible boot devices. Then the hardware boot stage accesses the boot device, loads the OS Loader, which is located on a fixed position on the boot device, and transfers control to it. -.TP +.TP Note: -We do not cover here booting from network. Those who want +We do not cover here booting from network. +Those who want to investigate this subject may want to research: DHCP, TFTP, PXE, Etherboot. .SS "OS Loader" @@ -54,7 +56,8 @@ of the boot device \- this is the \fBMBR\fR (Master Boot Record). In most systems, this primary loader is very -limited due to various constraints. Even on non\-PC systems +limited due to various constraints. +Even on non\-PC systems there are some limitations to the size and complexity of this loader, but the size limitation of the PC MBR (512 bytes including the partition table) makes it @@ -75,7 +78,8 @@ containing the bootstrap code to load the second part of the loader from the root partition. The main job of the OS Loader is to locate the kernel -on the disk, load it and run it. Most OS loaders allow +on the disk, load it and run it. +Most OS loaders allow interactive use, to enable specification of alternative kernel (maybe a backup in case the last compiled one isn't functioning) and to pass optional parameters @@ -88,12 +92,14 @@ file system (/). Some of the parameters that may be passed to the kernel relate to these activities (e.g: You can override the -default root file system). For further information +default root file system). +For further information on Linux kernel parameters read .BR bootparam (7). Only then the kernel creates the first (user land) -process which is numbered 1. This process executes the +process which is numbered 1. +This process executes the program .IR /sbin/init , passing any parameters that weren't handled by the kernel already. @@ -106,7 +112,8 @@ This file defines what should be run in different \fIrun-levels\fR. This gives the system administrator an easy management scheme, where each run-level is associated with a set of services (e.g: \fBS\fR is \fIsingle\-user\fR, on \fB2\fR most network -services start, etc.). The administrator may change the current +services start, etc.). +The administrator may change the current run-level via .BR init (8) and query the current run-level via @@ -117,12 +124,13 @@ by editing this file, inittab only bootstraps a set of scripts that actually start/stop the individual services. .SS "Boot Scripts" -.TP +.TP Note: The following description applies to System V release 4 based system, which currently covers most commercial Unix systems (Solaris, HP-UX, Irix, Tru64) as well as the major Linux distributions (RedHat, Debian, Mandrake, -Suse, Caldera). Some systems (Slackware Linux, FreeBSD, OpenBSD) +Suse, Caldera). +Some systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat different scheme of boot scripts. .LP For each managed service (mail, nfs server, cron, etc.) there is @@ -131,31 +139,38 @@ a single startup script located in a specific directory in most versions of Linux). Each of these scripts accepts as a single argument the word 'start' \-\- causing it to start the service, or the word -\&'stop' \-\- causing it to stop the service. The script may optionally +\&'stop' \-\- causing it to stop the service. +The script may optionally accept other "convenience" parameters (e.g: 'restart', to stop and then -start, 'status' do display the service status). Running the script +start, 'status' do display the service status). +Running the script without parameters displays the possible arguments. .SS "Sequencing Directories" To make specific scripts start/stop at specific run-levels and in -specific order, there are \fIsequencing directories\fR. These -are normally in \fI/etc/rc[0\-6S].d\fR. In each of these directories +specific order, there are \fIsequencing directories\fR. +These +are normally in \fI/etc/rc[0\-6S].d\fR. +In each of these directories there are links (usually symbolic) to the scripts in the \fIinit.d\fR directory. -A primary script (usually \fI/etc/rc\fR) is called from +A primary script (usually \fI/etc/rc\fR) is called from .BR inittab (5) and calls the services scripts via the links in the sequencing directories. All links with names that begin with 'S' are being called with -the argument 'start' (thereby starting the service). All links with +the argument 'start' (thereby starting the service). +All links with names that begin with 'K' are being called with the argument 'stop' (thereby stopping the service). To define the starting or stopping order within the same run-level, the names of the links contain order-numbers. Also, to make the names clearer, they usually -end with the name of the service they refer to. Example: +end with the name of the service they refer to. +Example: the link \fI/etc/rc2.d/S80sendmail\fR starts the sendmail service on -runlevel 2. This happens after \fI/etc/rc2.d/S12syslog\fR is run +runlevel 2. +This happens after \fI/etc/rc2.d/S12syslog\fR is run but before \fI/etc/rc2.d/S90xfs\fR is run. To manage the boot order and run-levels, we have to manage these links. @@ -164,19 +179,21 @@ However, on many versions of Linux, there are tools to help with this task .BR chkconfig (8)). .SS "Boot Configuration" Usually the daemons started may optionally receive command line options -and parameters. To allow system administrators to change these -parameters without editing the boot scripts themselves, -configuration files are used. These are located in a specific +and parameters. +To allow system administrators to change these +parameters without editing the boot scripts themselves, +configuration files are used. +These are located in a specific directory (\fI/etc/sysconfig\fR on RedHat systems) and are used by the boot scripts. In older Unix systems, these files contained the actual command line options for the daemons, but in modern Linux systems (and also -in HP-UX), these files just contain shell variables. The boot -scripts in \fI/etc/init.d\fR \fBsource\fR the configuration +in HP-UX), these files just contain shell variables. +The boot scripts in \fI/etc/init.d\fR \fBsource\fR the configuration files, and then use the variable values. .SH "FILES" -.LP +.LP .IR /etc/init.d/ , .IR /etc/rc[S0\-6].d/ . .I /etc/sysconfig/ diff --git a/man7/bootparam.7 b/man7/bootparam.7 index 5a08df228..0a4d442ba 100644 --- a/man7/bootparam.7 +++ b/man7/bootparam.7 @@ -29,7 +29,8 @@ bootparam \- Introduction to boot time parameters of the Linux kernel .SH DESCRIPTION The Linux kernel accepts certain `command line options' or `boot time -parameters' at the moment it is started. In general this is used to +parameters' at the moment it is started. +In general this is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on its own, or to avoid/override the values that the kernel would otherwise detect. @@ -45,8 +46,10 @@ using rdev, see for further details. The LILO program (LInux LOader) written by Werner Almesberger is the -most commonly used. It has the ability to boot various kernels, and -stores the configuration information in a plain text file. (See +most commonly used. +It has the ability to boot various kernels, and +stores the configuration information in a plain text file. +(See .BR lilo (8) and .BR lilo.conf (5).) @@ -58,51 +61,59 @@ prompt (with boot-args) assuming that certain resources are available. This is good for people that want to launch Linux from DOS. It is also very useful if you have certain hardware which relies on -the supplied DOS driver to put the hardware into a known state. A -common example is `SoundBlaster Compatible' sound cards that require +the supplied DOS driver to put the hardware into a known state. +A common example is `SoundBlaster Compatible' sound cards that require the DOS driver to twiddle a few mystical registers to put the card -into a SB compatible mode. Booting DOS with the supplied driver, and +into a SB compatible mode. +Booting DOS with the supplied driver, and then loading Linux from the DOS prompt with loadlin avoids the reset of the card that happens if one rebooted instead. .SH "THE ARGUMENT LIST" The kernel command line is parsed into a list of strings -(boot arguments) separated by spaces. Most of the boot args -take the form of: +(boot arguments) separated by spaces. +Most of the boot args take the form of: .IP name[=value_1][,value_2]...[,value_10] .LP where `name' is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. Note the limit of 10 is real, as the present code only handles 10 comma -separated parameters per keyword. (However, you can re-use the same +separated parameters per keyword. +(However, you can re-use the same keyword with up to an additional 10 parameters in unusually complicated situations, assuming the setup function supports it.) -Most of the sorting goes on in linux/init/main.c. First, the kernel +Most of the sorting goes on in linux/init/main.c. +First, the kernel checks to see if the argument is any of the special arguments `root=', -`nfsroot=', `nfsaddrs=', `ro', `rw', `debug' or `init'. The meaning -of these special arguments is described below. +`nfsroot=', `nfsaddrs=', `ro', `rw', `debug' or `init'. +The meaning of these special arguments is described below. Then it walks a list of setup functions (contained in the bootsetups array) to see if the specified argument string (such as `foo') has been associated with a setup function (`foo_setup()') for a particular -device or part of the kernel. If you passed the kernel the line +device or part of the kernel. +If you passed the kernel the line foo=3,4,5,6 then the kernel would search the bootsetups array to see -if `foo' was registered. If it was, then it would call the setup +if `foo' was registered. +If it was, then it would call the setup function associated with `foo' (foo_setup()) and hand it the arguments 3, 4, 5 and 6 as given on the kernel command line. Anything of the form `foo=bar' that is not accepted as a setup function as described above is then interpreted as an environment variable to -be set. A (useless?) example would be to use `TERM=vt100' as a boot +be set. +A (useless?) example would be to use `TERM=vt100' as a boot argument. Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then passed onto process -one, which is usually the init program. The most common argument that +one, which is usually the init program. +The most common argument that is passed to the init process is the word `single' which instructs init to boot the computer in single user mode, and not launch all the usual -daemons. Check the manual page for the version of init installed on +daemons. +Check the manual page for the version of init installed on your system to see what arguments it accepts. .SH "GENERAL NON-DEVICE SPECIFIC BOOT ARGS" .SS "`init=...'" @@ -120,30 +131,38 @@ and panic if all of this fails. This sets the nfs boot address to the given string. This boot address is used in case of a net boot. .SS "`nfsroot=...'" -This sets the nfs root name to the given string. If this string +This sets the nfs root name to the given string. +If this string does not begin with '/' or ',' or a digit, then it is prefixed by -`/tftpboot/'. This root name is used in case of a net boot. +`/tftpboot/'. +This root name is used in case of a net boot. .SS "`no387'" (Only when CONFIG_BUGi386 is defined.) Some i387 coprocessor chips have bugs that show up when used in 32 bit -protected mode. For example, some of the early ULSI-387 chips would +protected mode. +For example, some of the early ULSI-387 chips would cause solid lockups while performing floating point calculations. Using the `no387' boot arg causes Linux to ignore the maths -coprocessor even if you have one. Of course you must then have your +coprocessor even if you have one. +Of course you must then have your kernel compiled with math emulation support! .SS "`no-hlt'" (Only when CONFIG_BUGi386 is defined.) Some of the early i486DX-100 chips have a problem with the `hlt' instruction, in that they can't reliably return to operating mode -after this instruction is used. Using the `no-hlt' instruction tells +after this instruction is used. +Using the `no-hlt' instruction tells Linux to just run an infinite loop when there is nothing else to do, -and to not halt the CPU. This allows people with these broken chips +and to not halt the CPU. +This allows people with these broken chips to use Linux. .SS "`root=...'" This argument tells the kernel what device is to be used as the root -filesystem while booting. The default of this setting is determined +filesystem while booting. +The default of this setting is determined at compile time, and usually is the value of the root device of the -system that the kernel was built on. To override this value, and +system that the kernel was built on. +To override this value, and select the second floppy drive as the root device, one would use `root=/dev/fd1'. (The root device can also be set using .BR rdev (8).) @@ -158,22 +177,25 @@ the device type (`hd' for ST-506 compatible hard disk, with Y in floppy disk, with Y the floppy drive number \(em fd0 would be the DOS `A:' drive, and fd1 would be `B:'), Y the driver letter or number, and N the number (in decimal) of the partition on this device -(absent in the case of floppies). Recent kernels allow many other +(absent in the case of floppies). +Recent kernels allow many other types, mostly for CD-ROMs: nfs, ram, scd, mcd, cdu535, aztcd, cm206cd, gscd, sbpcd, sonycd, bpcd. (The type nfs specifies a net boot; ram refers to a ram disk.) Note that this has nothing to do with the designation of these -devices on your file system. The `/dev/' part is purely conventional. +devices on your file system. +The `/dev/' part is purely conventional. The more awkward and less portable numeric specification of the above -possible root devices in major/minor format is also accepted. (E.g., -/dev/sda3 is major 8, minor 3, so you could use `root=0x803' as an +possible root devices in major/minor format is also accepted. +(E.g., /dev/sda3 is major 8, minor 3, so you could use `root=0x803' as an alternative.) .SS "`ro' and `rw'" The `ro' option tells the kernel to mount the root filesystem as `readonly' so that filesystem consistency check programs (fsck) -can do their work on a quiescent file system. No processes can +can do their work on a quiescent file system. +No processes can write to files on the filesystem in question until it is `remounted' as read/write capable, e.g., by `mount \-w \-n \-o remount /'. (See also @@ -185,19 +207,21 @@ This is the default. The choice between read-only and read/write can also be set using .BR rdev (8). .SS "`reserve=...'" -This is used to protect I/O port regions from probes. The form of the -command is: +This is used to protect I/O port regions from probes. +The form of the command is: .IP .BI reserve= iobase,extent[,iobase,extent]... .LP In some machines it may be necessary to prevent device drivers from -checking for devices (auto-probing) in a specific region. This may be +checking for devices (auto-probing) in a specific region. +This may be because of hardware that reacts badly to the probing, or hardware that would be mistakenly identified, or merely hardware you don't want the kernel to initialize. The reserve boot-time argument specifies an I/O port region that -shouldn't be probed. A device driver will not probe a reserved region, +shouldn't be probed. +A device driver will not probe a reserved region, unless another boot argument explicitly specifies that it do so. For example, the boot line @@ -209,25 +233,30 @@ keeps all device drivers except the driver for `blah' from probing .SS "`mem=...'" The BIOS call defined in the PC specification that returns the amount of installed memory was only designed to be able -to report up to 64MB. Linux uses this BIOS call at boot to -determine how much memory is installed. If you have more than 64MB of +to report up to 64MB. +Linux uses this BIOS call at boot to +determine how much memory is installed. +If you have more than 64MB of RAM installed, you can use this boot arg to tell Linux how much memory -you have. The value is in decimal or hexadecimal (prefix 0x), +you have. +The value is in decimal or hexadecimal (prefix 0x), and the suffixes `k' (times 1024) or `M' (times 1048576) can be used. Here is a quote from Linus on usage of the `mem=' parameter. \&``The kernel will accept any `mem=xx' parameter you give it, and if it turns out that you lied to it, it will crash horribly sooner or later. The parameter indicates the highest addressable RAM address, so -\&`mem=0x1000000' means you have 16MB of memory, for example. For a -96MB machine this would be `mem=0x6000000'. +\&`mem=0x1000000' means you have 16MB of memory, for example. +For a 96MB machine this would be `mem=0x6000000'. NOTE NOTE NOTE: some machines might use the top of memory for BIOS cacheing or whatever, so you might not actually have up to the full -96MB addressable. The reverse is also true: some chipsets will map +96MB addressable. +The reverse is also true: some chipsets will map the physical memory that is covered by the BIOS area into the area just past the top of memory, so the top-of-mem might actually be 96MB -+ 384kB for example. If you tell linux that it has more memory than ++ 384kB for example. +If you tell linux that it has more memory than it actually does have, bad things will happen: maybe not at once, but surely eventually.'' @@ -247,7 +276,8 @@ but might destroy not yet written data in a disk cache. A warm reboot may be faster.) By default a reboot is hard, by asking the keyboard controller to pulse the reset line low, but there is at least one type -of motherboard where that doesn't work. The option `reboot=bios' will +of motherboard where that doesn't work. +The option `reboot=bios' will instead jump through the BIOS. .SS "`nosmp'" and "`maxcpus=N'" (Only when __SMP__ is defined.) @@ -257,26 +287,32 @@ of CPUs activated in SMP mode to N. .SH "BOOT ARGUMENTS FOR USE BY KERNEL DEVELOPERS" .SS "`debug'" Kernel messages are handed off to the kernel log daemon klogd so that they -may be logged to disk. Messages with a priority above +may be logged to disk. +Messages with a priority above .I console_loglevel -are also printed on the console. (For these levels, see .) +are also printed on the console. +(For these levels, see .) By default this variable is set to log anything more important than -debug messages. This boot argument will cause the kernel to also +debug messages. +This boot argument will cause the kernel to also print the messages of DEBUG priority. The console loglevel can also be set at run time via an option -to klogd. See +to klogd. +See .BR klogd (8). .SS "`profile=N'" It is possible to enable a kernel profiling function, if one wishes to find out where the kernel is spending its CPU cycles. Profiling is enabled by setting the variable .I prof_shift -to a non-zero value. This is done either by specifying CONFIG_PROFILE at +to a non-zero value. +This is done either by specifying CONFIG_PROFILE at compile time, or by giving the `profile=' option. Now the value that .I prof_shift gets will be N, when given, or CONFIG_PROFILE_SHIFT, when that is given, -or 2, the default. The significance of this variable is that it +or 2, the default. +The significance of this variable is that it gives the granularity of the profiling: each clock tick, if the system was executing kernel code, a counter is incremented: .IP @@ -296,20 +332,23 @@ For kernel tuners only. .SS "`buff=N1,N2,N3,N4,N5,N6'" Set the six parameters max_buff_age, buff_advance, buff_decline, buff_initial_age, bufferout_weight, buffermem_grace that control -kernel buffer memory management. For kernel tuners only. +kernel buffer memory management. +For kernel tuners only. .SH "BOOT ARGUMENTS FOR RAMDISK USE" (Only if the kernel was compiled with CONFIG_BLK_DEV_RAM.) In general it is a bad idea to use a ramdisk under Linux \(em the system will use available memory more efficiently itself. But while booting (or while constructing boot floppies) it is often useful to load the floppy contents into a -ramdisk. One might also have a system in which first +ramdisk. +One might also have a system in which first some modules (for filesystem or hardware) must be loaded before the main disk can be accessed. In Linux 1.3.48, ramdisk handling was changed drastically. Earlier, the memory was allocated statically, and there was -a `ramdisk=N' parameter to tell its size. (This could also +a `ramdisk=N' parameter to tell its size. +(This could also be set in the kernel image at compile time, or by use of .BR rdev (8).) These days ram disks use the buffer cache, and grow dynamically. @@ -320,13 +359,17 @@ in conjunction with the new ramdisk setup), see There are four parameters, two boolean and two integral. .SS "`load_ramdisk=N'" -If N=1, do load a ramdisk. If N=0, do not load a ramdisk. +If N=1, do load a ramdisk. +If N=0, do not load a ramdisk. (This is the default.) .SS "`prompt_ramdisk=N'" -If N=1, do prompt for insertion of the floppy. (This is the default.) -If N=0, do not prompt. (Thus, this parameter is never needed.) +If N=1, do prompt for insertion of the floppy. +(This is the default.) +If N=0, do not prompt. +(Thus, this parameter is never needed.) .SS "`ramdisk_size=N' or (obsolete) `ramdisk=N'" -Set the maximal size of the ramdisk(s) to N kB. The default is 4096 (4 MB). +Set the maximal size of the ramdisk(s) to N kB. +The default is 4096 (4 MB). .SS "`ramdisk_start=N'" Sets the starting block number (the offset on the floppy where the ramdisk starts) to N. @@ -356,45 +399,54 @@ the last process that used it has closed General notation for this section: .I iobase --- the first I/O port that the SCSI host occupies. These are -specified in hexadecimal notation, and usually lie in the range from -0x200 to 0x3ff. +-- the first I/O port that the SCSI host occupies. +These are specified in hexadecimal notation, +and usually lie in the range from 0x200 to 0x3ff. .I irq -- the hardware interrupt that the card is configured to use. Valid values will be dependent on the card in question, but will -usually be 5, 7, 9, 10, 11, 12, and 15. The other values are usually +usually be 5, 7, 9, 10, 11, 12, and 15. +The other values are usually used for common peripherals like IDE hard disks, floppies, serial ports, etc. .I scsi-id -- the ID that the host adapter uses to identify itself on the -SCSI bus. Only some host adapters allow you to change this value, as -most have it permanently specified internally. The usual default value +SCSI bus. +Only some host adapters allow you to change this value, as +most have it permanently specified internally. +The usual default value is 7, but the Seagate and Future Domain TMC-950 boards use 6. .I parity -- whether the SCSI host adapter expects the attached devices -to supply a parity value with all information exchanges. Specifying a -one indicates parity checking is enabled, and a zero disables parity -checking. Again, not all adapters will support selection of parity +to supply a parity value with all information exchanges. +Specifying a one indicates parity checking is enabled, +and a zero disables parity checking. +Again, not all adapters will support selection of parity behaviour as a boot argument. .SS "`max_scsi_luns=...'" A SCSI device can have a number of `sub-devices' contained within -itself. The most common example is one of the new SCSI CD-ROMs that -handle more than one disk at a time. Each CD is addressed as a -`Logical Unit Number' (LUN) of that particular device. But most +itself. +The most common example is one of the new SCSI CD-ROMs that +handle more than one disk at a time. +Each CD is addressed as a +`Logical Unit Number' (LUN) of that particular device. +But most devices, such as hard disks, tape drives and such are only one device, and will be assigned to LUN zero. Some poorly designed SCSI devices cannot handle being probed for -LUNs not equal to zero. Therefore, if the compile time flag +LUNs not equal to zero. +Therefore, if the compile time flag CONFIG_SCSI_MULTI_LUN is not set, newer kernels will by default only probe LUN zero. To specify the number of probed LUNs at boot, one enters `max_scsi_luns=n' as a boot arg, where n is a number between one and -eight. To avoid problems as described above, one would use n=1 to +eight. +To avoid problems as described above, one would use n=1 to avoid upsetting such broken devices. .SS "SCSI tape configuration" Some boot time configuration of the SCSI tape driver can be achieved @@ -402,13 +454,16 @@ by using the following: .IP .BI st= buf_size[,write_threshold[,max_bufs]] .LP -The first two numbers are specified in units of kB. The default +The first two numbers are specified in units of kB. +The default .I buf_size is 32kB, and the maximum size that can be specified is a -ridiculous 16384kB. The +ridiculous 16384kB. +The .I write_threshold is the value at which the buffer is committed to tape, with a -default value of 30kB. The maximum number of buffers varies +default value of 30kB. +The maximum number of buffers varies with the number of drives detected, and has a default of two. An example usage would be: .IP @@ -421,7 +476,8 @@ The aha numbers refer to cards and the aic numbers refer to the actual SCSI chip on these type of cards, including the Soundblaster-16 SCSI. The probe code for these SCSI hosts looks for an installed BIOS, and -if none is present, the probe will not find your card. Then you will +if none is present, the probe will not find your card. +Then you will have to use a boot arg of the form: .IP .BI aha152x= iobase[,irq[,scsi-id[,reconnect[,parity]]]] @@ -432,7 +488,8 @@ value can be specified to set the debug level. All the parameters are as described at the top of this section, and the .I reconnect value will allow device disconnect/reconnect if a non-zero value -is used. An example usage is as follows: +is used. +An example usage is as follows: .IP aha152x=0x340,11,7,1 .LP @@ -441,28 +498,34 @@ you want to specify a parity setting, then you will have to specify an iobase, irq, scsi-id and reconnect value as well. .SS "Adaptec aha154x configuration" The aha1542 series cards have an i82077 floppy controller onboard, -while the aha1540 series cards do not. These are busmastering cards, +while the aha1540 series cards do not. +These are busmastering cards, and have parameters to set the ``fairness'' that is used to share -the bus with other devices. The boot arg looks like the following. +the bus with other devices. +The boot arg looks like the following. .IP .BI aha1542= iobase[,buson,busoff[,dmaspeed]] .LP Valid iobase values are usually one of: 0x130, 0x134, 0x230, 0x234, -0x330, 0x334. Clone cards may permit other values. +0x330, 0x334. +Clone cards may permit other values. The .IR buson ", " busoff values refer to the number of microseconds that the -card dominates the ISA bus. The defaults are 11us on, and 4us off, so +card dominates the ISA bus. +The defaults are 11us on, and 4us off, so that other cards (such as an ISA LANCE Ethernet card) have a chance to get access to the ISA bus. The .I dmaspeed value refers to the rate (in MB/s) at which the DMA -(Direct Memory Access) transfers proceed. The default is 5MB/s. +(Direct Memory Access) transfers proceed. +The default is 5MB/s. Newer revision cards allow you to select this value as part of the -soft-configuration, older cards use jumpers. You can use values up to +soft-configuration, older cards use jumpers. +You can use values up to 10MB/s assuming that your motherboard is capable of handling it. Experiment with caution if using values over 5MB/s. .SS "Adaptec aha274x, aha284x, aic7xxx configuration" @@ -473,17 +536,22 @@ These boards can accept an argument of the form: The .I extended value, if non-zero, indicates that extended translation for large -disks is enabled. The +disks is enabled. +The .I no_reset value, if non-zero, tells the driver not to reset the SCSI bus when setting up the host adaptor at boot. .SS "AdvanSys SCSI Hosts configuration (`advansys=')" The AdvanSys driver can accept up to four i/o addresses that will be -probed for an AdvanSys SCSI card. Note that these values (if used) do -not effect EISA or PCI probing in any way. They are only used for -probing ISA and VLB cards. In addition, if the driver has been +probed for an AdvanSys SCSI card. +Note that these values (if used) do +not effect EISA or PCI probing in any way. +They are only used for +probing ISA and VLB cards. +In addition, if the driver has been compiled with debugging enabled, the level of debugging output can be -set by adding an 0xdeb[0-f] parameter. The 0-f allows setting the +set by adding an 0xdeb[0-f] parameter. +The 0-f allows setting the level of the debugging messages to any of 16 levels of verbosity. .SS "AM53C974" .IP @@ -495,14 +563,17 @@ level of the debugging messages to any of 16 levels of verbosity. For an extensive discussion of the BusLogic command line parameters, see .IR /usr/src/linux/drivers/scsi/BusLogic.c -(lines 3149-3270 in the kernel version I am looking at). The text +(lines 3149-3270 in the kernel version I am looking at). +The text below is a very much abbreviated extract. -The parameters N1-N5 are integers. The parameters S1,... are strings. +The parameters N1-N5 are integers. +The parameters S1,... are strings. N1 is the I/O Address at which the Host Adapter is located. N2 is the Tagged Queue Depth to use for Target Devices that support Tagged Queuing. -N3 is the Bus Settle Time in seconds. This is the amount of time +N3 is the Bus Settle Time in seconds. +This is the amount of time to wait between a Host Adapter Hard Reset which initiates a SCSI Bus Reset and issuing any SCSI Commands. N4 is the Local Options (for one Host Adapter). @@ -530,7 +601,8 @@ The default list of i/o ports to be probed can be changed by The .I mem_base value is the value of the memory mapped I/O region that -the card uses. This will usually be one of the following values: +the card uses. +This will usually be one of the following values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000. .SS "IN2000 configuration" .IP @@ -539,7 +611,8 @@ the card uses. This will usually be one of the following values: where S is a comma-separated string of items keyword[:value]. Recognized keywords (possibly with value) are: ioport:addr, noreset, nosync:x, period:ns, disconnect:x, -debug:x, proc:x. For the function of these parameters, see +debug:x, proc:x. +For the function of these parameters, see .IR /usr/src/linux/drivers/scsi/in2000.c . .SS "NCR5380 and NCR53C400 configuration" The boot arg is of the form @@ -551,7 +624,9 @@ or .BI ncr53c400= iobase,irq .LP If the card doesn't use interrupts, then an IRQ value of 255 (0xff) will -disable interrupts. An IRQ value of 254 means to autoprobe. More +disable interrupts. +An IRQ value of 254 means to autoprobe. +More details can be found in the file .IR /usr/src/linux/drivers/scsi/README.g_NCR5380 . .SS "NCR53C8xx configuration" @@ -573,13 +648,15 @@ Specify irq = 0 for non-interrupt driven mode. Set fastpio = 1 for fast pio mode, 0 for slow mode. .SS "Pro Audio Spectrum configuration" The PAS16 uses a NC5380 SCSI chip, and newer models support -jumperless configuration. The boot arg is of the form: +jumperless configuration. +The boot arg is of the form: .IP .BI pas16= iobase,irq .LP The only difference is that you can specify an IRQ value of 255, which will tell the driver to work without using interrupts, albeit at a -performance loss. The iobase is usually 0x388. +performance loss. +The iobase is usually 0x388. .SS "Seagate ST-0x configuration" If your card is not detected at boot time, you will then have to use a boot arg of the form: @@ -589,7 +666,8 @@ you will then have to use a boot arg of the form: The .I mem_base value is the value of the memory mapped I/O region that -the card uses. This will usually be one of the following values: +the card uses. +This will usually be one of the following values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, 0xde000. .SS "Trantor T128 configuration" These cards are also based on the NCR5380 chip, and accept the @@ -611,35 +689,43 @@ The default list of i/o ports to be probed can be changed by .IP .BI wd33c93= S .LP -where S is a comma-separated string of options. Recognized options are +where S is a comma-separated string of options. +Recognized options are nosync:bitmask, nodma:x, period:ns, disconnect:x, debug:x, -clock:x, next. For details, see +clock:x, next. +For details, see .IR /usr/src/linux/drivers/scsi/wd33c93.c . .SH "HARD DISKS" .SS "IDE Disk/CD-ROM Driver Parameters" The IDE driver accepts a number of parameters, which range from disk -geometry specifications, to support for broken controller chips. Drive -specific options are specified by using `hdX=' with X in `a'-`h'. +geometry specifications, to support for broken controller chips. +Drive specific options are specified by using `hdX=' with X in `a'-`h'. -Non-drive specific options are specified with the prefix `hd='. Note -that using a drive specific prefix for a non-drive specific option +Non-drive specific options are specified with the prefix `hd='. +Note that using a drive specific prefix for a non-drive specific option will still work, and the option will just be applied as expected. Also note that `hd=' can be used to refer to the next unspecified -drive in the (a, ..., h) sequence. For the following discussions, -the `hd=' option will be cited for brevity. See the file +drive in the (a, ..., h) sequence. +For the following discussions, +the `hd=' option will be cited for brevity. +See the file README.ide in linux/drivers/block for more details. .SS "The `hd=cyls,heads,sects[,wpcom[,irq]]' options" These options are used to specify the physical geometry of the disk. -Only the first three values are required. The cylinder/head/sectors -values will be those used by fdisk. The write precompensation value -is ignored for IDE disks. The IRQ value specified will be the IRQ +Only the first three values are required. +The cylinder/head/sectors +values will be those used by fdisk. +The write precompensation value +is ignored for IDE disks. +The IRQ value specified will be the IRQ used for the interface that the drive resides on, and is not really a drive specific parameter. .SS "The `hd=serialize' option" The dual IDE interface CMD-640 chip is broken as designed such that when drives on the secondary interface are used at the same time as -drives on the primary interface, it will corrupt your data. Using this +drives on the primary interface, it will corrupt your data. +Using this option tells the driver to make sure that both interfaces are never used at the same time. .SS "The `hd=dtc2278' option" @@ -647,7 +733,8 @@ This option tells the driver that you have a DTC-2278D IDE interface. The driver then tries to do DTC specific operations to enable the second interface and to enable faster transfer modes. .SS "The `hd=noprobe' option" -Do not probe for this drive. For example, +Do not probe for this drive. +For example, .IP hdb=noprobe hdb=1166,7,17 .LP @@ -659,14 +746,17 @@ Some drives apparently have the WRERR_STAT bit stuck on permanently. This enables a work-around for these broken devices. .SS "The `hd=cdrom' option" This tells the IDE driver that there is an ATAPI compatible CD-ROM -attached in place of a normal IDE hard disk. In most cases the CD-ROM +attached in place of a normal IDE hard disk. +In most cases the CD-ROM is identified automatically, but if it isn't then this may help. .SS "Standard ST-506 Disk Driver Options (`hd=')" The standard disk driver can accept geometry arguments for the disks -similar to the IDE driver. Note however that it only expects three -values (C/H/S); any more or any less and it will silently ignore -you. Also, it only accepts `hd=' as an argument, i.e. `hda=' -and so on are not valid here. The format is as follows: +similar to the IDE driver. +Note however that it only expects three +values (C/H/S); any more or any less and it will silently ignore you. +Also, it only accepts `hd=' as an argument, i.e. `hda=' +and so on are not valid here. +The format is as follows: .IP hd=cyls,heads,sects .LP @@ -680,20 +770,25 @@ If the card is not recognised, you will have to use a boot arg of the form: xd=type,irq,iobase,dma_chan .LP The type value specifies the particular manufacturer of the card, -overriding autodetection. For the types to use, consult the +overriding autodetection. +For the types to use, consult the .I drivers/block/xd.c -source file of the kernel you are using. The type is an index in the list +source file of the kernel you are using. +The type is an index in the list .I xd_sigs and in the course of time .\" 1.1.50, 1.3.81, 1.3.99, 2.0.34, 2.1.67, 2.1.78, 2.1.127 types have been added to or deleted from the middle of the list, -changing all type numbers. Today (Linux 2.5.0) the types are +changing all type numbers. +Today (Linux 2.5.0) the types are 0=generic; 1=DTC 5150cx; 2,3=DTC 5150x; 4,5=Western Digital; 6,7,8=Seagate; 9=Omti; 10=XEBEC, and where here several types are given with the same designation, they are equivalent. The xd_setup() function does no checking on the values, and assumes -that you entered all four values. Don't disappoint it. Here is an +that you entered all four values. +Don't disappoint it. +Here is an example usage for a WD1002 controller with the BIOS disabled/removed, using the `default' XT controller parameters: .IP @@ -723,7 +818,8 @@ The syntax for this type of card is: aztcd=iobase[,magic_number] .LP If you set the magic_number to 0x79 then the driver will try and run -anyway in the event of an unknown firmware version. All other values +anyway in the event of an unknown firmware version. +All other values are ignored. .SS "Parallel port CD-ROM drives" Syntax: @@ -735,18 +831,19 @@ pcd.nice=nice where `port' is the base address, `pro' is the protocol number, `uni' is the unit selector (for chained devices), `mod' is the mode (or \-1 to choose the best automatically), `slv' is 1 if it should be a slave, -and `dly' is a small integer for slowing down port accesses. The -`nice' parameter controls the driver's use of idle CPU time, at the +and `dly' is a small integer for slowing down port accesses. +The `nice' parameter controls the driver's use of idle CPU time, at the expense of some speed. .SS "The CDU-31A and CDU-33A Sony Interface" This CD-ROM interface is found on some of the Pro Audio Spectrum sound -cards, and other Sony supplied interface cards. The syntax is as -follows: +cards, and other Sony supplied interface cards. +The syntax is as follows: .IP cdu31a=iobase,[irq[,is_pas_card]] .LP Specifying an IRQ value of zero tells the driver that hardware -interrupts aren't supported (as on some PAS cards). If your card +interrupts aren't supported (as on some PAS cards). +If your card supports interrupts, you should use them as it cuts down on the CPU usage of the driver. @@ -770,8 +867,10 @@ Syntax: .IP isp16=[iobase[,irq[,dma[,type]]]] .LP -(three integers and a string). If the type is given as `noisp16', -the interface will not be configured. Other recognized types +(three integers and a string). +If the type is given as `noisp16', +the interface will not be configured. +Other recognized types are: `Sanyo", `Sony', `Panasonic' and `Mitsumi'. .SS "The Mitsumi Standard Interface" The syntax for this CD-ROM interface is: @@ -801,7 +900,8 @@ cm206=[iobase][,irq] .LP The driver assumes numbers between 3 and 11 are IRQ values, and numbers between 0x300 and 0x370 are I/O ports, so you can specify one, -or both numbers, in any order. It also accepts `cm206=auto' to enable +or both numbers, in any order. +It also accepts `cm206=auto' to enable autoprobing. .SS "The Sanyo Interface" The syntax for this type of card is: @@ -813,24 +913,26 @@ The syntax for this type of card is: sbpcd=iobase,type .LP where type is one of the following (case sensitive) strings: -`SoundBlaster', `LaserMate', or `SPEA'. The I/O base is that of the +`SoundBlaster', `LaserMate', or `SPEA'. +The I/O base is that of the CD-ROM interface, and not that of the sound portion of the card. .SH "ETHERNET DEVICES" Different drivers make use of different parameters, but they all at -least share having an IRQ, an I/O port base value, and a name. In its -most generic form, it looks something like this: +least share having an IRQ, an I/O port base value, and a name. +In its most generic form, it looks something like this: .IP ether=irq,iobase[,param_1[,...param_8]],name .LP -The first non-numeric argument is taken as the name. The param_n -values (if applicable) usually have different meanings for each -different card/driver. Typical param_n values are used to specify +The first non-numeric argument is taken as the name. +The param_n values (if applicable) usually have different meanings for each +different card/driver. +Typical param_n values are used to specify things like shared memory address, interface selection, DMA channel and the like. The most common use of this parameter is to force probing for a second -ethercard, as the default is to only probe for one. This can be -accomplished with a simple: +ethercard, as the default is to only probe for one. +This can be accomplished with a simple: .IP ether=0,0,eth1 .LP @@ -839,60 +941,77 @@ example tell the driver(s) to autoprobe. The Ethernet-HowTo has extensive documentation on using multiple cards and on the card/driver specific implementation -of the param_n values where used. Interested readers should refer to +of the param_n values where used. +Interested readers should refer to the section in that document on their particular card. .SH "THE FLOPPY DISK DRIVER" There are many floppy driver options, and they are all listed in -README.fd in linux/drivers/block. This information is taken directly +README.fd in linux/drivers/block. +This information is taken directly from that file. .SS "floppy=mask,allowed_drive_mask" -Sets the bitmask of allowed drives to mask. By default, only units 0 -and 1 of each floppy controller are allowed. This is done because +Sets the bitmask of allowed drives to mask. +By default, only units 0 +and 1 of each floppy controller are allowed. +This is done because certain non-standard hardware (ASUS PCI motherboards) mess up the -keyboard when accessing units 2 or 3. This option is somewhat +keyboard when accessing units 2 or 3. +This option is somewhat obsoleted by the cmos option. .SS "floppy=all_drives" -Sets the bitmask of allowed drives to all drives. Use this if you have +Sets the bitmask of allowed drives to all drives. +Use this if you have more than two drives connected to a floppy controller. .SS "floppy=asus_pci" Sets the bitmask to allow only units 0 and 1. (The default) .SS "floppy=daring" Tells the floppy driver that you have a well behaved floppy -controller. This allows more efficient and smoother operation, but -may fail on certain controllers. This may speed up certain operations. +controller. +This allows more efficient and smoother operation, but +may fail on certain controllers. +This may speed up certain operations. .SS "floppy=0,daring" Tells the floppy driver that your floppy controller should be used with caution. .SS "floppy=one_fdc" Tells the floppy driver that you have only floppy controller (default) .SS "floppy=two_fdc or floppy=address,two_fdc" -Tells the floppy driver that you have two floppy controllers. The -second floppy controller is assumed to be at address. If address is +Tells the floppy driver that you have two floppy controllers. +The second floppy controller is assumed to be at address. +If address is not given, 0x370 is assumed. .SS "floppy=thinkpad" -Tells the floppy driver that you have a Thinkpad. Thinkpads use an +Tells the floppy driver that you have a Thinkpad. +Thinkpads use an inverted convention for the disk change line. .SS "floppy=0,thinkpad" Tells the floppy driver that you don't have a Thinkpad. .SS "floppy=drive,type,cmos" -Sets the cmos type of drive to type. Additionally, this drive is -allowed in the bitmask. This is useful if you have more than two +Sets the cmos type of drive to type. +Additionally, this drive is +allowed in the bitmask. +This is useful if you have more than two floppy drives (only two can be described in the physical cmos), or if -your BIOS uses non-standard CMOS types. Setting the CMOS to 0 for the +your BIOS uses non-standard CMOS types. +Setting the CMOS to 0 for the first two drives (default) makes the floppy driver read the physical cmos for those drives. .SS "floppy=unexpected_interrupts" Print a warning message when an unexpected interrupt is received (default behaviour) .SS "floppy=no_unexpected_interrupts or floppy=L40SX" -Don't print a message when an unexpected interrupt is received. This -is needed on IBM L40SX laptops in certain video modes. (There seems to -be an interaction between video and floppy. The unexpected interrupts +Don't print a message when an unexpected interrupt is received. +This is needed on IBM L40SX laptops in certain video modes. +(There seems to +be an interaction between video and floppy. +The unexpected interrupts only affect performance, and can safely be ignored.) .SH "THE SOUND DRIVER" The sound driver can also accept boot args to override the compiled in -values. This is not recommended, as it is rather complex. It is -described in the Readme.Linux file, in linux/drivers/sound. It accepts +values. +This is not recommended, as it is rather complex. +It is described in the Readme.Linux file, in linux/drivers/sound. +It accepts a boot arg of the form: .IP sound=device1[,device2[,device3...[,device10]]] @@ -910,7 +1029,8 @@ I \- interrupt line in hex (i.e 10=a, 11=b, ...) d \- DMA channel. As you can see it gets pretty messy, and you are better off to compile -in your own personal values as recommended. Using a boot arg of +in your own personal values as recommended. +Using a boot arg of `sound=0' will disable the sound driver entirely. .SH "ISDN DRIVERS" .SS "The ICN ISDN driver" @@ -926,7 +1046,8 @@ Syntax: pcbit=membase1,irq1[,membase2,irq2] .LP where membaseN is the shared memory base of the N'th card, and irqN is -the interrupt setting of the N'th card. The default is IRQ 5 and +the interrupt setting of the N'th card. +The default is IRQ 5 and membase 0xD0000. .SS "The Teles ISDN driver" Syntax: @@ -974,7 +1095,8 @@ Syntax: baycom=iobase,irq,modem .LP There are precisely 3 parameters; for several cards, give -several `baycom=' commands. The modem parameter is a string +several `baycom=' commands. +The modem parameter is a string that can take one of the values ser12, ser12*, par96, par96*. Here the * denotes that software DCD is to be used, and ser12/par96 chooses between the supported modem types. @@ -1003,13 +1125,16 @@ lp=reset lp=port[,port...] .LP You can tell the printer driver what ports to use and what ports not -to use. The latter comes in handy if you don't want the printer driver +to use. +The latter comes in handy if you don't want the printer driver to claim all available parallel ports, so that other drivers (e.g. PLIP, PPA) can use them instead. -The format of the argument is multiple port names. For example, +The format of the argument is multiple port names. +For example, lp=none,parport0 would use the first parallel port for lp1, and -disable lp0. To disable the printer driver entirely, one can use +disable lp0. +To disable the printer driver entirely, one can use lp=0. .SS "WDT500/501 driver" Syntax: @@ -1026,14 +1151,16 @@ And precisely the same is true for the msmouse driver. atamouse=threshold[,y-threshold] .IP If only one argument is given, it is used for both -x-threshold and y-threshold. Otherwise, the first argument +x-threshold and y-threshold. +Otherwise, the first argument is the x-threshold, and the second the y-threshold. These values must lie between 1 and 20 (inclusive); the default is 2. .SH "VIDEO HARDWARE" .SS "`no-scroll'" This option tells the console driver not to use hardware scroll (where a scroll is effected by moving the screen origin in video -memory, instead of moving the data). It is required by certain +memory, instead of moving the data). +It is required by certain Braille machines. .SH AUTHORS Linus Torvalds (and many others) diff --git a/man7/capabilities.7 b/man7/capabilities.7 index c82d8e1a0..c6c599648 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -39,8 +39,8 @@ while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list). -Starting with kernel 2.2, Linux divides the privileges traditionally -associated with superuser into distinct units, known as +Starting with kernel 2.2, Linux divides the privileges traditionally +associated with superuser into distinct units, known as .IR capabilities , which can be independently enabled and disabled. Capabilities are a per-thread attribute. @@ -111,7 +111,7 @@ This includes use of the KDSIGACCEPT ioctl. .\" FIXME CAP_KILL also has an effect for threads + setting child .\" termination signal to other than SIGCHLD: without this .\" capability, the termination signal reverts to SIGCHLD -.\" if the child does an exec(). What is the rationale +.\" if the child does an exec(). What is the rationale .\" for this? .TP .B CAP_LEASE @@ -195,11 +195,11 @@ to assign and .B IOPRIO_CLASS_IDLE I/O scheduling classes; -perform +perform .BR keyctl (2) .B KEYCTL_CHOWN and -.B KEYCTL_SETPERM +.B KEYCTL_SETPERM operations. allow forged UID when passing socket credentials; exceed @@ -209,17 +209,17 @@ in system calls that open files (e.g., .BR accept (2), .BR execve (2), .BR open (2), -.BR pipe (2); -without this capability these system calls will fail with the error -.B ENFILE +.BR pipe (2); +without this capability these system calls will fail with the error +.B ENFILE if this limit is encountered); -employ -.BR CLONE_NEWNS +employ +.BR CLONE_NEWNS flag with .BR clone (2) and .BR unshare (2); -perform +perform .B KEYCTL_CHOWN and .B KEYCTL_SETPERM @@ -253,14 +253,14 @@ and setting scheduling policies and priorities for arbitrary processes .RB ( sched_setscheduler (2), .BR sched_setparam (2)); set CPU affinity for arbitrary processes -.RB ( sched_setaffinity (2)); +.RB ( sched_setaffinity (2)); set I/O scheduling class and priority for arbitrary processes -.RB ( ioprio_set (2)); +.RB ( ioprio_set (2)); allow .BR migrate_pages (2) to be applied to arbitrary processes and allow processes to be migrated to arbitrary nodes; -.\" FIXME CAP_SYS_NICE also has the following effect for +.\" FIXME CAP_SYS_NICE also has the following effect for .\" migrate_pages(2): .\" do_migrate_pages(mm, &old, &new, .\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); @@ -269,9 +269,9 @@ allow to be applied to arbitrary processes; use the .B MPOL_MF_MOVE_ALL -flag with +flag with .BR mbind (2) -and +and .BR move_pages (2). .TP .B CAP_SYS_PACCT @@ -330,8 +330,8 @@ perform permission checks for the thread. the capabilities that the thread may assume (i.e., a limiting superset for the effective and inheritable sets). If a thread drops a capability from its permitted set, -it can never re-acquire that capability (unless it -.BR exec ()s +it can never re-acquire that capability (unless it +.BR exec ()s a set-user-ID-root program). .TP .IR inheritable : @@ -384,7 +384,7 @@ that for all privileged operations, the kernel check whether the thread has the required capability in its effective set. .IP 2. 4 -that the kernel provide +that the kernel provide system calls allowing a thread's capability sets to be changed and retrieved. .IP 3. 4 @@ -393,7 +393,7 @@ so that a process gains those capabilities when the file is execed. .PP As at Linux 2.6.14, only the first two of these requirements are met. -Eventually, it should be possible to associate three +Eventually, it should be possible to associate three capability sets with an executable file, which, in conjunction with the capability sets of the thread, will determine the capabilities of a thread after an @@ -401,7 +401,7 @@ will determine the capabilities of a thread after an .TP .IR Inheritable " (formerly known as " allowed ): this set is ANDed with the thread's inheritable set to determine which -inheritable capabilities are permitted to the thread after the +inheritable capabilities are permitted to the thread after the .BR exec (). .TP .IR Permitted " (formerly known as " forced ): @@ -414,7 +414,7 @@ also to be set in the new effective set. (F(effective) would normally be either all zeroes or all ones.) .PP In the meantime, since the current implementation does not -support file capability sets, during an +support file capability sets, during an .BR exec (): .IP 1. 4 All three file capability sets are initially assumed to be cleared. @@ -428,14 +428,14 @@ If a set-user-ID-root program is being executed, then the file effective set is defined to be all ones. .SS Transformation of Capabilities During exec() .PP -During an -.BR exec (), +During an +.BR exec (), the kernel calculates the new capabilities of the process using the following algorithm: .in +4 .nf -P'(permitted) = (P(inheritable) & F(inheritable)) | +P'(permitted) = (P(inheritable) & F(inheritable)) | (F(permitted) & cap_bset) P'(effective) = P'(permitted) & F(effective) @@ -446,10 +446,10 @@ P'(inheritable) = P(inheritable) [i.e., unchanged] .in -4 where: .IP P 10 -denotes the value of a thread capability set before the +denotes the value of a thread capability set before the .BR exec () .IP P' 10 -denotes the value of a capability set after the +denotes the value of a capability set after the .BR exec () .IP F 10 denotes a file capability set @@ -457,40 +457,40 @@ denotes a file capability set is the value of the capability bounding set. .PP In the current implementation, the upshot of this algorithm is that -when a process +when a process .BR exec ()s a set-user-ID-root program, or when a process with an effective UID of 0 .BR exec ()s a program, -it gains all capabilities in its permitted and effective capability sets, -except those masked out by the capability bounding set (i.e., +it gains all capabilities in its permitted and effective capability sets, +except those masked out by the capability bounding set (i.e., .BR CAP_SETPCAP ). -.\" If a process with real UID 0, and non-zero effective UID does an -.\" exec(), then it gets all capabilities (less CAP_SETPCAP) in its +.\" If a process with real UID 0, and non-zero effective UID does an +.\" exec(), then it gets all capabilities (less CAP_SETPCAP) in its .\" permitted set, and no effective capabilities This provides semantics that are the same as those provided by traditional Unix systems. .SS Effect of User ID Changes on Capabilities -To preserve the traditional semantics for transitions between -0 and non-zero user IDs, -the kernel makes the following changes to a thread's capability -sets on changes to the thread's real, effective, saved set, +To preserve the traditional semantics for transitions between +0 and non-zero user IDs, +the kernel makes the following changes to a thread's capability +sets on changes to the thread's real, effective, saved set, and file system user IDs (using .BR setuid (2), .BR setresuid (2), or similar): .IP 1. 4 -If one or more of the real, effective or saved set user IDs -was previously 0, and as a result of the UID changes all of these IDs -have a non-zero value, -then all capabilities are cleared from the permitted and effective +If one or more of the real, effective or saved set user IDs +was previously 0, and as a result of the UID changes all of these IDs +have a non-zero value, +then all capabilities are cleared from the permitted and effective capability sets. .IP 2. 4 -If the effective user ID is changed from 0 to non-zero, +If the effective user ID is changed from 0 to non-zero, then all capabilities are cleared from the effective set. .IP 3. 4 If the effective user ID is changed from non-zero to 0, -then the permitted set is copied to the effective set. +then the permitted set is copied to the effective set. .IP 4. 4 If the file system user ID is changed from 0 to non-zero (see .BR setfsuid (2)) @@ -502,7 +502,7 @@ then the following capabilities are cleared from the effective set: and .BR CAP_FSETID . If the file system UID is changed from non-zero to 0, -then any of these capabilities that are enabled in the permitted set +then any of these capabilities that are enabled in the permitted set are enabled in the effective set. .PP If a thread that has a 0 value for one or more of its user IDs wants diff --git a/man7/charsets.7 b/man7/charsets.7 index 9b1cb7ecd..209b8e3f3 100644 --- a/man7/charsets.7 +++ b/man7/charsets.7 @@ -14,31 +14,36 @@ .SH NAME charsets \- programmer's view of character sets and internationalization .SH DESCRIPTION -Linux is an international operating system. Various of its utilities +Linux is an international operating system. +Various of its utilities and device drivers (including the console driver) support multilingual character sets including Latin-alphabet letters with diacritical marks, accents, ligatures, and entire non-Latin alphabets including Greek, Cyrillic, Arabic, and Hebrew. .LP This manual page presents a programmer's-eye view of different -character-set standards and how they fit together on Linux. Standards +character-set standards and how they fit together on Linux. +Standards discussed include ASCII, ISO 8859, KOI8-R, Unicode, ISO 2022 and -ISO 4873. The primary emphasis is on character sets actually used as +ISO 4873. +The primary emphasis is on character sets actually used as locale character sets, not the myriad others that can be found in data from other systems. .LP A complete list of charsets used in a officially supported locale in glibc 2.2.3 is: ISO-8859-{1,2,3,5,6,7,8,9,13,15}, CP1251, UTF-8, EUC-{KR,JP,TW}, KOI8-{R,U}, GB2312, GB18030, GBK, BIG5, BIG5-HKSCS and TIS-620 (in no -particular order.) (Romanian may be switching to ISO-8859-16.) +particular order.) +(Romanian may be switching to ISO-8859-16.) .SH ASCII ASCII (American Standard Code For Information Interchange) is the original -7-bit character set, originally designed for American English. It is -currently described by the ECMA-6 standard. +7-bit character set, originally designed for American English. +It is currently described by the ECMA-6 standard. .LP Various ASCII variants replacing the dollar sign with other currency symbols and replacing punctuation with non-English alphabetic characters -to cover German, French, Spanish and others in 7 bits exist. All are +to cover German, French, Spanish and others in 7 bits exist. +All are deprecated; GNU libc doesn't support locales whose character sets aren't true supersets of ASCII. (These sets are also known as ISO-646, a close relative of ASCII that permitted replacing these characters.) @@ -50,7 +55,8 @@ ISO 8859 is a series of 15 8-bit character sets all of which have US ASCII in their low (7-bit) half, invisible control characters in positions 128 to 159, and 96 fixed-width graphics in positions 160-255. .LP -Of these, the most important is ISO 8859-1 (Latin-1). It is natively +Of these, the most important is ISO 8859-1 (Latin-1). +It is natively supported in the Linux console driver, fairly well supported in X11R6, and is the base character set of HTML. .LP @@ -68,7 +74,8 @@ Here are brief descriptions of each set: Latin-1 covers most Western European languages such as Albanian, Catalan, Danish, Dutch, English, Faroese, Finnish, French, German, Galician, Irish, Icelandic, Italian, Norwegian, Portuguese, Spanish, and -Swedish. The lack of the ligatures Dutch ij, French oe and old-style +Swedish. +The lack of the ligatures Dutch ij, French oe and old-style ,,German`` quotation marks is considered tolerable. .TP 8859-2 (Latin-2) @@ -81,17 +88,20 @@ Latin-3 is popular with authors of Esperanto, Galician, and Maltese. (Turkish is now written with 8859-9 instead.) .TP 8859-4 (Latin-4) -Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. It -is essentially obsolete; see 8859-10 (Latin-6) and 8859-13 (Latin-7). +Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. +It is essentially obsolete; see 8859-10 (Latin-6) and 8859-13 (Latin-7). .TP 8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, -Russian, Serbian and Ukrainian. Ukrainians read the letter `ghe' +Russian, Serbian and Ukrainian. +Ukrainians read the letter `ghe' with downstroke as `heh' and would need a ghe with upstroke to write a -correct ghe. See the discussion of KOI8-R below. +correct ghe. +See the discussion of KOI8-R below. .TP 8859-6 -Supports Arabic. The 8859-6 glyph table is a fixed font of separate +Supports Arabic. +The 8859-6 glyph table is a fixed font of separate letter forms, but a proper display engine should combine these using the proper initial, medial, and final forms. .TP @@ -99,8 +109,8 @@ using the proper initial, medial, and final forms. Supports Modern Greek. .TP 8859-8 -Supports modern Hebrew without niqud (punctuation signs). Niqud -and full-fledged Biblical Hebrew are outside the scope of this +Supports modern Hebrew without niqud (punctuation signs). +Niqud and full-fledged Biblical Hebrew are outside the scope of this character set; under Linux, UTF-8 is the preferred encoding for these. .TP @@ -110,18 +120,22 @@ Turkish ones. .TP 8859-10 (Latin-6) Latin 6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters -that were missing in Latin 4 to cover the entire Nordic area. RFC -1345 listed a preliminary and different `latin6'. Skolt Sami still +that were missing in Latin 4 to cover the entire Nordic area. +RFC 1345 listed a preliminary and different `latin6'. +Skolt Sami still needs a few more accents than these. .TP 8859-11 -This only exists as a rejected draft standard. The draft standard +This only exists as a rejected draft standard. +The draft standard was identical to TIS-620, which is used under Linux for Thai. .TP 8859-12 -This set does not exist. While Vietnamese has been suggested for this +This set does not exist. +While Vietnamese has been suggested for this space, it does not fit within the 96 (non-combining) characters ISO -8859 offers. UTF-8 is the preferred character set for Vietnamese use +8859 offers. +UTF-8 is the preferred character set for Vietnamese use under Linux. .TP 8859-13 (Latin-7) @@ -140,114 +154,148 @@ Latin-1. This set covers many of the languages covered by 8859-2, and supports Romanian more completely then that set does. .SH KOI8-R -KOI8-R is a non-ISO character set popular in Russia. The lower half +KOI8-R is a non-ISO character set popular in Russia. +The lower half is US ASCII; the upper is a Cyrillic character set somewhat better -designed than ISO 8859-5. KOI8-U is a common character set, based off -KOI8-R, that has better support for Ukrainian. Neither of these sets +designed than ISO 8859-5. +KOI8-U is a common character set, based off +KOI8-R, that has better support for Ukrainian. +Neither of these sets are ISO-2022 compatible, unlike the ISO-8859 series. .LP Console support for KOI8-R is available under Linux through user-mode utilities that modify keyboard bindings and the EGA graphics table, and employ the "user mapping" font table in the console driver. -.\" Thanks to Tomohiro KUBOTA for the following sections about +.\" Thanks to Tomohiro KUBOTA for the following sections about .\" national standards. .SH JIS X 0208 -JIS X 0208 is a Japanese national standard character set. Though -there are some more Japanese national standard character sets (like -JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important -one. Characters are mapped into a 94x94 two-byte matrix, -whose each byte is in the range 0x21-0x7e. Note that JIS X 0208 -is a character set, not an encoding. This means that JIS X 0208 -itself is not used for expressing text data. JIS X 0208 is used +JIS X 0208 is a Japanese national standard character set. +Though there are some more Japanese national standard character sets (like +JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important one. +Characters are mapped into a 94x94 two-byte matrix, +whose each byte is in the range 0x21-0x7e. +Note that JIS X 0208 is a character set, not an encoding. +This means that JIS X 0208 +itself is not used for expressing text data. +JIS X 0208 is used as a component to construct encodings such as EUC-JP, Shift_JIS, -and ISO-2022-JP. EUC-JP is the most important encoding for Linux -and includes US ASCII and JIS X 0208. In EUC-JP, JIS X 0208 +and ISO-2022-JP. +EUC-JP is the most important encoding for Linux +and includes US ASCII and JIS X 0208. +In EUC-JP, JIS X 0208 characters are expressed in two bytes, each of which is the JIS X 0208 code plus 0x80. .SH KS X 1001 -KS X 1001 is a Korean national standard character set. Just as +KS X 1001 is a Korean national standard character set. +Just as JIS X 0208, characters are mapped into a 94x94 two-byte matrix. KS X 1001 is used like JIS X 0208, as a component to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. EUC-KR is the most important encoding for Linux and includes -US ASCII and KS X 1001. KS C 5601 is an older name for KS X 1001. +US ASCII and KS X 1001. +KS C 5601 is an older name for KS X 1001. .SH GB 2312 GB 2312 is a mainland Chinese national standard character set used -to express simplified Chinese. Just like JIS X 0208, characters are -mapped into a 94x94 two-byte matrix used to construct EUC-CN. EUC-CN +to express simplified Chinese. +Just like JIS X 0208, characters are +mapped into a 94x94 two-byte matrix used to construct EUC-CN. +EUC-CN is the most important encoding for Linux and includes US ASCII and -GB 2312. Note that EUC-CN is often called as GB, GB 2312, or CN-GB. +GB 2312. +Note that EUC-CN is often called as GB, GB 2312, or CN-GB. .SH Big5 Big5 is a popular character set in Taiwan to express traditional -Chinese. (Big5 is both a character set and an encoding.) It is a -superset of US ASCII. Non-ASCII characters are expressed in two -bytes. Bytes 0xa1-0xfe are used as leading bytes for two-byte -characters. Big5 and its extension is widely used in Taiwan and Hong -Kong. It is not ISO 2022-compliant. +Chinese. +(Big5 is both a character set and an encoding.) +It is a superset of US ASCII. +Non-ASCII characters are expressed in two bytes. +Bytes 0xa1-0xfe are used as leading bytes for two-byte characters. +Big5 and its extension is widely used in Taiwan and Hong Kong. +It is not ISO 2022-compliant. .SH TIS 620 TIS 620 is a Thai national standard character set and a superset -of US ASCII. Like ISO 8859 series, Thai characters are mapped into -0xa1-0xfe. TIS 620 is the only commonly used character set under +of US ASCII. +Like ISO 8859 series, Thai characters are mapped into +0xa1-0xfe. +TIS 620 is the only commonly used character set under Linux besides UTF-8 to have combining characters. .SH UNICODE Unicode (ISO 10646) is a standard which aims to unambiguously represent every -character in every human language. Unicode's structure permits 20.1 bits -to encode every character. Since most computers don't include 20.1-bit +character in every human language. +Unicode's structure permits 20.1 bits to encode every character. +Since most computers don't include 20.1-bit integers, Unicode is usually encoded as 32-bit integers internally and either a series of 16-bit integers (UTF-16) (needing two 16-bit integers only when encoding certain rare characters) or a series of 8-bit bytes -(UTF-8). Information on Unicode is available at . +(UTF-8). +Information on Unicode is available at . .LP Linux represents Unicode using the 8-bit Unicode Transformation Format -(UTF-8). UTF-8 is a variable length encoding of Unicode. It uses 1 +(UTF-8). +UTF-8 is a variable length encoding of Unicode. +It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. .LP -Let 0,1,x stand for a zero, one, or arbitrary bit. A byte 0xxxxxxx +Let 0,1,x stand for a zero, one, or arbitrary bit. +A byte 0xxxxxxx stands for the Unicode 00000000 0xxxxxxx which codes the same symbol -as the ASCII 0xxxxxxx. Thus, ASCII goes unchanged into UTF-8, and +as the ASCII 0xxxxxxx. +Thus, ASCII goes unchanged into UTF-8, and people using only ASCII do not notice any change: not in code, and not in file size. .LP A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy -is assembled into 00000xxx xxyyyyyy. A byte 1110xxxx is the start +is assembled into 00000xxx xxyyyyyy. +A byte 1110xxxx is the start of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz. (When UTF-8 is used to code the 31-bit ISO 10646 then this progression continues up to 6-byte codes.) .LP For most people who use ISO-8859 character sets, this means that the -characters outside of ASCII are now coded with two bytes. This tends -to expand ordinary text files by only one or two percent. For Russian +characters outside of ASCII are now coded with two bytes. +This tends +to expand ordinary text files by only one or two percent. +For Russian or Greek users, this expands ordinary text files by 100%, since text in -those languages is mostly outside of ASCII. For Japanese users this means -that the 16-bit codes now in common use will take three bytes. While there +those languages is mostly outside of ASCII. +For Japanese users this means +that the 16-bit codes now in common use will take three bytes. +While there are algorithmic conversions from some character sets (esp. ISO-8859-1) to Unicode, general conversion requires carrying around conversion tables, which can be quite large for 16-bit codes. .LP Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other -byte is the head of a code. Note that the only way ASCII bytes occur -in a UTF-8 stream, is as themselves. In particular, there are no +byte is the head of a code. +Note that the only way ASCII bytes occur +in a UTF-8 stream, is as themselves. +In particular, there are no embedded NULs ('\\0') or '/'s that form part of some larger code. .LP Since ASCII, and, in particular, NUL and '/', are unchanged, the -kernel does not notice that UTF-8 is being used. It does not care at +kernel does not notice that UTF-8 is being used. +It does not care at all what the bytes it is handling stand for. .LP Rendering of Unicode data streams is typically handled through -`subfont' tables which map a subset of Unicode to glyphs. Internally +`subfont' tables which map a subset of Unicode to glyphs. +Internally the kernel uses Unicode to describe the subfont loaded in video RAM. This means that in UTF-8 mode one can use a character set with 512 -different symbols. This is not enough for Japanese, Chinese and +different symbols. +This is not enough for Japanese, Chinese and Korean, but it is enough for most other purposes. .LP At the current time, the console driver does not handle combining -characters. So Thai, Sioux and any other script needing combining +characters. +So Thai, Sioux and any other script needing combining characters can't be handled on the console. .SH "ISO 2022 AND ISO 4873" The ISO 2022 and 4873 standards describe a font-control model -based on VT100 practice. This model is (partially) supported +based on VT100 practice. +This model is (partially) supported by the Linux kernel and by .BR xterm (1). It is popular in Japan and Korea. @@ -257,7 +305,8 @@ and one of them is the current character set for codes with high bit zero (initially G0), and one of them is the current character set for codes with high bit one (initially G1). Each graphic character set has 94 or 96 characters, and is -essentially a 7-bit character set. It uses codes either +essentially a 7-bit character set. +It uses codes either 040-0177 (041-0176) or 0240-0377 (0241-0376). G0 always has size 94 and uses codes 041-0176. .LP diff --git a/man7/complex.7 b/man7/complex.7 index 7fb5f9b80..55343f141 100644 --- a/man7/complex.7 +++ b/man7/complex.7 @@ -10,11 +10,14 @@ complex \- basics of complex mathematics Complex numbers are numbers of the form z = a+b*i, where a and b are real numbers and i = sqrt(\-1), so that i*i = \-1. .br -There are other ways to represent that number. The pair (a,b) of real +There are other ways to represent that number. +The pair (a,b) of real numbers may be viewed as a point in the plane, given by X- and -Y-coordinates. This same point may also be described by giving +Y-coordinates. +This same point may also be described by giving the pair of real numbers (r,phi), where r is the distance to the origin O, -and phi the angle between the X-axis and the line Oz. Now +and phi the angle between the X-axis and the line Oz. +Now z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). .PP The basic operations are defined on z = a+b*i and w = c+d*i as: @@ -29,7 +32,8 @@ Nearly all math function have a complex counterpart but there are some complex only functions. .SH EXAMPLE Your C-compiler can work with complex numbers if it supports the C99 standard. -Link with \-lm. The imaginary unit is represented by I. +Link with \-lm. +The imaginary unit is represented by I. .sp .nf /* check that exp(i * pi) == \-1 */ @@ -37,7 +41,7 @@ Link with \-lm. The imaginary unit is represented by I. #include int -main(void) +main(void) { double pi = 4 * atan(1); complex z = cexp(I * pi); diff --git a/man7/ddp.7 b/man7/ddp.7 index 4d2e1342a..9800f77d3 100644 --- a/man7/ddp.7 +++ b/man7/ddp.7 @@ -4,57 +4,62 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ -.TH DDP 7 1999-05-01 "Linux Man Page" "Linux Programmer's Manual" +.TH DDP 7 1999-05-01 "Linux Man Page" "Linux Programmer's Manual" .SH NAME ddp \- Linux AppleTalk protocol implementation .SH SYNOPSIS .B #include .br -.B #include +.B #include .sp .IB ddp_socket " = socket(PF_APPLETALK, SOCK_DGRAM, 0);" -.br +.br .IB raw_socket " = socket(PF_APPLETALK, SOCK_RAW, " protocol ");" .SH DESCRIPTION -Linux implements the Appletalk protocols described in +Linux implements the Appletalk protocols described in .IR "Inside Appletalk" . Only the DDP layer and AARP are present in -the kernel. They are designed to be used via the -.B netatalk +the kernel. +They are designed to be used via the +.B netatalk protocol -libraries. This page documents the interface for those who wish or need to +libraries. +This page documents the interface for those who wish or need to use the DDP layer directly. .PP The communication between Appletalk and the user program works using a -BSD-compatible socket interface. For more information on sockets, see -.BR socket (7). +BSD-compatible socket interface. +For more information on sockets, see +.BR socket (7). .PP -An AppleTalk socket is created by calling the -.BR socket (2) -function with a +An AppleTalk socket is created by calling the +.BR socket (2) +function with a .B PF_APPLETALK -socket family argument. Valid socket types are +socket family argument. +Valid socket types are .B SOCK_DGRAM -to open a -.B ddp +to open a +.B ddp socket or .B SOCK_RAW -to open a -.B raw -socket. -.I protocol -is the Appletalk protocol to be received or sent. For -.B SOCK_RAW +to open a +.B raw +socket. +.I protocol +is the Appletalk protocol to be received or sent. +For +.B SOCK_RAW you must specify .BR ATPROTO_DDP . .PP -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. +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" An Appletalk socket address is defined as a combination of a network number, -a node number, and a port number. +a node number, and a port number. .PP .RS .nf @@ -70,49 +75,52 @@ struct sockaddr_atalk { }; .ta .fi -.RE +.RE .PP .I sat_family -is always set to -.BR AF_APPLETALK . +is always set to +.BR AF_APPLETALK . .I sat_port -contains the port. The port numbers below 129 are known as +contains the port. +The port numbers below 129 are known as .I reserved ports. -Only processes with the effective user ID 0 or the -.B CAP_NET_BIND_SERVICE -capability may -.BR bind (2) -to these sockets. -.I sat_addr +Only processes with the effective user ID 0 or the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these sockets. +.I sat_addr is the host address. -The +The .I net -member of +member of .I struct at_addr -contains the host network in network byte order. The value of -.B AT_ANYNET -is a +contains the host network in network byte order. +The value of +.B AT_ANYNET +is a wildcard and also implies \(lqthis network.\(rq -The +The .I node -member of +member of .I struct at_addr -contains the host node number. The value of -.B AT_ANYNODE -is a -wildcard and also implies \(lqthis node.\(rq The value of -.B ATADDR_BCAST +contains the host node number. +The value of +.B AT_ANYNODE +is a +wildcard and also implies \(lqthis node.\(rq The value of +.B ATADDR_BCAST is a link local broadcast address. .\" FIXME this doesn't make sense [johnl] .SH "SOCKET OPTIONS" No protocol-specific socket options are supported. .SH SYSCTLS -IP supports a sysctl interface to configure some global AppleTalk -parameters. -The sysctls can be accessed by reading or writing the -.I /proc/sys/net/atalk/* -files or with the +IP supports a sysctl interface to configure some global AppleTalk +parameters. +The sysctls can be accessed by reading or writing the +.I /proc/sys/net/atalk/* +files or with the .BR sysctl (2) interface. .TP @@ -120,11 +128,11 @@ interface. The time interval (in seconds) before an AARP cache entry expires. .TP .B aarp-resolve-time -The time interval (in seconds) before an AARP cache entry is resolved. +The time interval (in seconds) before an AARP cache entry is resolved. .TP .B aarp-retransmit-limit The number of retransmissions of an AARP query before the node is declared -dead. +dead. .TP .B aarp-tick-time The timer rate (in seconds) for the timer driving AARP. @@ -133,22 +141,24 @@ The default values match the specification and should never need to be changed. .SH IOCTLS All ioctls described in -.BR socket (7) +.BR socket (7) apply to ddp. .\" FIXME Add a section about multicasting .SH NOTES -Be very careful with the +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. +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 +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 +.\" give more uniform error returns (ENOMEM vs ENOBUFS, EPERM vs .\" EACCES etc.) .TP .B ENOTCONN @@ -156,29 +166,29 @@ The operation is only defined on a connected socket, but the socket wasn't connected. .TP .B EINVAL -Invalid argument passed. +Invalid argument passed. .TP -.B EMSGSIZE +.B EMSGSIZE Datagram is bigger than the DDP MTU. .TP .B EACCES -The user tried to execute an operation without the necessary permissions. -These include sending to a broadcast address without +The user tried to execute an operation without the necessary permissions. +These include sending to a broadcast address without having the broadcast flag set, -and trying to bind to a reserved port without effective user ID 0 or -.BR CAP_NET_BIND_SERVICE . +and trying to bind to a reserved port without effective user ID 0 or +.BR CAP_NET_BIND_SERVICE . .TP .B EADDRINUSE Tried to bind to an address already in use. .TP .BR ENOMEM " and " ENOBUFS -Not enough memory available. +Not enough memory available. .TP .BR ENOPROTOOPT " and " EOPNOTSUPP Invalid socket option passed. .TP .B EPERM -User doesn't have permission to set high priority, +User doesn't have permission to set high priority, make a configuration change, or send signals to the requested process or group, .TP @@ -193,46 +203,47 @@ Operation on a nonblocking socket would block. The socket was unconfigured, or an unknown socket type was requested. .TP .B EISCONN -.BR connect (2) +.BR connect (2) was called on an already connected socket. .TP .B EALREADY A connection operation on a non-blocking socket is already in progress. .TP .B ECONNABORTED -A connection was closed during an -.BR accept (2). +A connection was closed during an +.BR accept (2). .TP .B EPIPE The connection was unexpectedly closed or shut down by the other end. .TP .B ENOENT -.B SIOCGSTAMP +.B SIOCGSTAMP was called on a socket where no packet arrived. .TP .B EHOSTUNREACH -No routing table entry matches the destination address. +No routing table entry matches the destination address. .TP -.B ENODEV +.B ENODEV Network device not available or not capable of sending IP. .TP -.B ENOPKG +.B ENOPKG A kernel subsystem was not configured. .SH COMPATIBILITY -The basic AppleTalk socket interface is compatible with -.B netatalk -on BSD-derived systems. Many BSD systems fail to check +The basic AppleTalk socket interface is compatible with +.B netatalk +on BSD-derived systems. +Many BSD systems fail to check .B SO_BROADCAST when sending broadcast frames; this can lead to compatibility problems. .PP -The +The raw socket mode is unique to Linux and exists to support the alternative CAP package and AppleTalk monitoring tools more easily. .SH BUGS -There are too many inconsistent error values. +There are too many inconsistent error values. .PP -The ioctls used to configure routing tables, devices, +The ioctls used to configure routing tables, devices, AARP tables and other devices are not yet described. .SH "SEE ALSO" .BR recvmsg (2), diff --git a/man7/environ.7 b/man7/environ.7 index 7066c0a28..ac9044457 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -21,7 +21,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sun Jul 25 10:45:30 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer (aeb@cwi.nl) .\" Modified Mon Oct 21 17:47:19 1996 by Eric S. Raymond (esr@thyrsus.com) @@ -53,8 +53,10 @@ in case they came from glibc and was defined.) This array of strings is made available to the process by the .BR exec (3) -call that started the process. By convention these strings -have the form `\fIname\fP\fB=\fP\fIvalue\fP'. Common examples are: +call that started the process. +By convention these strings +have the form `\fIname\fP\fB=\fP\fIvalue\fP'. +Common examples are: .TP .B USER The name of the logged-in user (used by some BSD-derived programs). @@ -84,7 +86,8 @@ of a change directory command, \fBMANPATH\fP used by \fBman\fP(1) to find manual pages, etc.) .TP .B PWD -The current working directory. Set by some shells. +The current working directory. +Set by some shells. .TP .B SHELL The pathname of the user's login shell. @@ -122,7 +125,7 @@ influenced by the presence or value of certain environment variables. A random collection: .LP The variables -.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ", " +.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ", " .BR LC_ALL ", " LC_MESSAGES ", " etc. influence locale handling, cf. .BR locale (5). @@ -166,12 +169,14 @@ gives information on how to address a given terminal tell applications about the window size, possibly overriding the actual size. .LP .BR PRINTER " or " LPDEST -may specify the desired printer to use. See +may specify the desired printer to use. +See .BR lpr (1). .LP Etc. .SH BUGS -Clearly there is a security risk here. Many a system command has been +Clearly there is a security risk here. +Many a system command has been tricked into mischief by a user who specified unusual values for .BR IFS " or " LD_LIBRARY_PATH . @@ -202,7 +207,8 @@ Thus, one has and .BR GZIP . Such usage is considered mistaken, and to be avoided in new -programs. The authors of +programs. +The authors of .I gzip should consider renaming their option to .BR GZIP_OPT . diff --git a/man7/epoll.7 b/man7/epoll.7 index 02f288370..e37bc24f9 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -26,13 +26,14 @@ epoll \- I/O event notification facility .B #include .SH DESCRIPTION .B epoll -is a variant of +is a variant of .BR poll (2) that can be used either as Edge or Level Triggered interface and scales -well to large numbers of watched fds. Three system calls are provided to +well to large numbers of watched fds. +Three system calls are provided to set up and control an .B epoll -set: +set: .BR epoll_create (2), .BR epoll_ctl (2), .BR epoll_wait (2). @@ -41,16 +42,18 @@ An .B epoll set is connected to a file descriptor created by .BR epoll_create (2). -Interest for certain file descriptors is then registered via +Interest for certain file descriptors is then registered via .BR epoll_ctl (2). -Finally, the actual wait is started by +Finally, the actual wait is started by .BR epoll_wait (2). .SH NOTES The .B epoll event distribution interface is able to behave both as Edge Triggered -( ET ) and Level Triggered ( LT ). The difference between ET and LT -event distribution mechanism can be described as follows. Suppose that +( ET ) and Level Triggered ( LT ). +The difference between ET and LT +event distribution mechanism can be described as follows. +Suppose that this scenario happens : .TP .B 1 @@ -91,12 +94,14 @@ done in step .B 5 will probably hang because of the available data still present in the file input buffers and the remote peer might be expecting a response based on the -data it already sent. The reason for this is that Edge Triggered event +data it already sent. +The reason for this is that Edge Triggered event distribution delivers events only when events happens on the monitored file. So, in step .B 5 the caller might end up waiting for some data that is already present inside -the input buffer. In the above example, an event on +the input buffer. +In the above example, an event on .B RFD will be generated because of the write done in .BR 2 @@ -108,7 +113,8 @@ does not consume the whole buffer data, the call to .BR epoll_wait (2) done in step .B 5 -might lock indefinitely. The +might lock indefinitely. +The .B epoll interface, when used with the .B EPOLLET @@ -117,18 +123,18 @@ should use non-blocking file descriptors to avoid having a blocking read or write starve the task that is handling multiple file descriptors. The suggested way to use .B epoll -as an Edge Triggered +as an Edge Triggered .RB ( EPOLLET ) interface is below, and possible pitfalls to avoid follow. .RS -.TP +.TP .B i with non-blocking file descriptors -.TP +.TP .B ii by going to wait for an event only after .BR read (2) -or +or .BR write (2) return EAGAIN .RE @@ -138,7 +144,8 @@ On the contrary, when used as a Level Triggered interface, is by all means a faster .BR poll (2), and can be used wherever the latter is used since it shares the -same semantics. Since even with the Edge Triggered +same semantics. +Since even with the Edge Triggered .B epoll multiple events can be generated up on receipt of multiple chunks of data, the caller has the option to specify the @@ -149,7 +156,8 @@ to disable the associated file descriptor after the receipt of an event with .BR epoll_wait (2). When the .B EPOLLONESHOT -flag is specified, it is caller responsibility to rearm the file descriptor using +flag is specified, +it is caller responsibility to rearm the file descriptor using .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . @@ -160,10 +168,12 @@ when employed like a Level Triggered interface does have the same semantics of .BR poll (2), an Edge Triggered usage requires more clarification to avoid stalls -in the application event loop. In this example, listener is a +in the application event loop. +In this example, listener is a non-blocking socket on which .BR listen (2) -has been called. The function do_use_fd() uses the new ready +has been called. +The function do_use_fd() uses the new ready file descriptor until EAGAIN is returned by either .BR read (2) or @@ -174,7 +184,7 @@ it will continue to .BR read (2) or .BR write (2) -from where it stopped before. +from where it stopped before. .nf struct epoll_event ev, *events; @@ -210,7 +220,8 @@ possible to add the file descriptor inside the epoll interface ( .B EPOLL_CTL_ADD ) once by specifying ( .BR EPOLLIN | EPOLLOUT -). This allows you to avoid +). +This allows you to avoid continuously switching between .B EPOLLIN and @@ -219,16 +230,18 @@ calling .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.SH QUESTIONS AND ANSWERS -.TP -.B Q1 +.SH QUESTIONS AND ANSWERS +.TP +.B Q1 What happens if you add the same fd to an epoll_set twice? .TP -.B A1 -You will probably get EEXIST. However, it is possible that two -threads may add the same fd twice. This is a harmless condition. +.B A1 +You will probably get EEXIST. +However, it is possible that two +threads may add the same fd twice. +This is a harmless condition. .TP -.B Q2 +.B Q2 Can two .B epoll sets wait for the same fd? If so, are events reported @@ -237,7 +250,9 @@ to both sets fds? .TP .B A2 -Yes. However, it is not recommended. Yes it would be reported to both. +Yes. +However, it is not recommended. +Yes it would be reported to both. .TP .B Q3 Is the @@ -247,15 +262,16 @@ fd itself poll/epoll/selectable? .B A3 Yes. .TP -.B Q4 +.B Q4 What happens if the .B epoll fd is put into its own fd set? .TP .B A4 -It will fail. However, you can add an +It will fail. +However, you can add an .B epoll -fd inside another epoll fd set. +fd inside another epoll fd set. .TP .B Q5 Can I send the @@ -273,7 +289,7 @@ sets automatically? .B A6 Yes. .TP -.B Q7 +.B Q7 If more than one event comes in between .BR epoll_wait (2) calls, are they combined or reported separately? @@ -286,8 +302,10 @@ Does an operation on an fd affect the already collected but not yet reported events? .TP .B A8 -You can do two operations on an existing fd. Remove would be meaningless for -this case. Modify will re-read available I/O. +You can do two operations on an existing fd. +Remove would be meaningless for +this case. +Modify will re-read available I/O. .TP .B Q9 Do I need to continuously read/write an fd until EAGAIN when using the @@ -295,64 +313,76 @@ Do I need to continuously read/write an fd until EAGAIN when using the flag ( Edge Triggered behaviour ) ? .TP .B A9 -No you don't. Receiving an event from +No you don't. +Receiving an event from .BR epoll_wait (2) -should suggest to you that such file descriptor is ready for the requested I/O -operation. You have simply to consider it ready until you will receive the -next EAGAIN. When and how you will use such file descriptor is entirely up -to you. Also, the condition that the read/write I/O space is exhausted can +should suggest to you that such file descriptor is ready +for the requested I/O operation. +You have simply to consider it ready until you will receive the +next EAGAIN. +When and how you will use such file descriptor is entirely up +to you. +Also, the condition that the read/write I/O space is exhausted can be detected by checking the amount of data read/write from/to the target -file descriptor. For example, if you call +file descriptor. +For example, if you call .BR read (2) by asking to read a certain amount of data and .BR read (2) returns a lower number of bytes, you can be sure to have exhausted the read -I/O space for such file descriptor. Same is valid when writing using the +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 .TP .B o Starvation ( Edge Triggered ) .PP -If there is a large amount of I/O space, it is possible that by trying to drain -it the other files will not get processed causing starvation. This -is not specific to +If there is a large amount of I/O space, +it is possible that by trying to drain +it the other files will not get processed causing starvation. +This is not specific to .BR epoll . .PP -The solution is to maintain a ready list and mark the file descriptor as ready +The solution is to maintain a ready list +and mark the file descriptor as ready in its associated data structure, thereby allowing the application to remember which files need to be processed but still round robin amongst -all the ready files. This also supports ignoring subsequent events you +all the ready files. +This also supports ignoring subsequent events you receive for fd's that are already ready. .TP -.B o If using an event cache... +.B o If using an event cache... .PP If you use an event cache or store all the fd's returned from .BR epoll_wait (2), -then make sure to provide a way to mark its closure dynamically (ie- caused by -a previous event's processing). Suppose you receive 100 events from +then make sure to provide a way to mark +its closure dynamically (ie- caused by +a previous event's processing). +Suppose you receive 100 events from .BR epoll_wait (2), -and in event #47 a condition causes event #13 to be closed. -If you remove the structure and +and in event #47 a condition causes event #13 to be closed. +If you remove the structure and .BR close () -the fd for event #13, then your -event cache might still say there are events waiting for that fd causing +the fd for event #13, then your +event cache might still say there are events waiting for that fd causing confusion. -.PP +.PP One solution for this is to call, during the processing of event 47, .BR epoll_ctl ( EPOLL_CTL_DEL ) -to delete fd 13 and -.BR close (), +to delete fd 13 and +.BR close (), then mark its associated -data structure as removed and link it to a cleanup list. If you find another +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 CONFORMING TO -The epoll API is Linux specific. +The epoll API is Linux specific. Some other systems provide similar -mechanisms, e.g., FreeBSD has -.IR kqueue , -and Solaris has +mechanisms, e.g., FreeBSD has +.IR kqueue , +and Solaris has .IR /dev/poll . .SH VERSIONS .BR epoll (7) diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 2f9f799ba..85efdcb5d 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -32,11 +32,11 @@ feature_test_macros \- feature test macros .SH DESCRIPTION Feature test macros allow the programmer to control the definitions that are exposed by system header files when a program is compiled. -This can be useful for creating portable applications, +This can be useful for creating portable applications, by preventing non-standard definitions from being exposed. Other macros can be used to expose non-standard definitions that are not exposed by default. -The precise effects of each of the feature test macros described below +The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I header file. @@ -45,21 +45,21 @@ In order to be effective, a feature test macro .IR "must be defined before including any header files" . This can either be done in the compilation command .RI ( "cc -DMACRO=value" ) -or by defining the macro within the source code before +or by defining the macro within the source code before including any headers. Linux/glibc understands the following feature test macros: .TP .B _POSIX_C_SOURCE -Defining this macro with the value 1 causes header files to expose +Defining this macro with the value 1 causes header files to expose definitions conforming to POSIX.1-1990 and ISO C (1990). -Defining with the value 199309 or greater additionally exposes +Defining with the value 199309 or greater additionally exposes definitions for POSIX.1b (real-time extensions). -Defining with the value 199506 or greater additionally exposes +Defining with the value 199506 or greater additionally exposes definitions for POSIX.1c (threads). -Defining with the value 200112 exposes definitions corresponding +Defining with the value 200112 exposes definitions corresponding to the POSIX.1-2001 base specification (excluding the XSI extension). -.TP +.TP .B _POSIX_SOURCE Defining this obsolete macro with any value is equivalent to defining .B _POSIX_C_SOURCE @@ -71,7 +71,7 @@ definitions conforming to POSIX.1, POSIX.2, and XPG4. Defining with the value 500 or greater additionally exposes definitions for SUSv2 (UNIX 98). Defining with the value 600 or greater additionally exposes -definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification +definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification plus the XSI extension) and C 99 definitions. .TP .B _XOPEN_SOURCE_EXTENDED @@ -84,28 +84,28 @@ UNIX extensions. Exposes C 99 extensions to ISO C (1990). .TP .B _LARGEFILE64_SOURCE -Expose definitions for the alternative API specified by the -LFS (Large File Summit) as a "transitional extension" to the -Single UNIX Specification. +Expose definitions for the alternative API specified by the +LFS (Large File Summit) as a "transitional extension" to the +Single UNIX Specification. (See http://opengroup.org/platform/lfs.html.) .TP .B _FILE_OFFSET_BITS -Defining this macro with the value 64 -automatically converts references to 32-bit functions and data types -related to file I/O and file system operations into references to +Defining this macro with the value 64 +automatically converts references to 32-bit functions and data types +related to file I/O and file system operations into references to their 64-bit counterparts. This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. .TP .B _BSD_SOURCE -Defining this macro with any value cause header files to expose +Defining this macro with any value cause header files to expose BSD-derived definitions. Defining this macro also causes BSD definitions to be preferred in some situations where standards conflict. .TP .B _SVID_SOURCE -Defining this macro with any value cause header files to expose -System V-derived definitions. +Defining this macro with any value cause header files to expose +System V-derived definitions. (SVID == System V Interface Definition; see .BR standards (7).) .TP @@ -129,7 +129,7 @@ For multithreaded programs, use instead. .TP .B _THREAD_SAFE -Synonym for +Synonym for .BR _REENTRANT , provided for compatibility with some other implementations. .TP @@ -145,7 +145,7 @@ to detect some buffer overflow errors when employing various string and memory manipulation functions. Not all buffer overflows are detected, just some common cases. In the current implementation checks are added for -calls to +calls to .BR memcpy (3), .BR mempcpy (3), .BR memmove (3), @@ -159,21 +159,21 @@ calls to .BR snprintf (3), .BR vsprintf (3), .BR vsnprintf (3), -and +and .BR gets (3). -If -.B _FORTIFY_SOURCE -is set to 1, with compiler optimization level 1 +If +.B _FORTIFY_SOURCE +is set to 1, with compiler optimization level 1 .RI ( "gcc -O1" ) -and above, checks that shouldn't change the behaviour of +and above, checks that shouldn't change the behaviour of conforming programs are performed. -With -.B _FORTIFY_SOURCE +With +.B _FORTIFY_SOURCE set to 2 some more checking is added, but some conforming programs might fail. -Some of the checks can be performed at compile time, -and result in compiler warnings; -other checks take place at run time, +Some of the checks can be performed at compile time, +and result in compiler warnings; +other checks take place at run time, and result in a run-time error if the check fails. Use of this macro requires compiler support, available with .BR gcc (1) @@ -188,10 +188,10 @@ is invoked, the following macros are defined by default: and .BR _POSIX_C_SOURCE =199506. If individual macros are defined, then other macros are disabled -unless they are also explicitly defined. (Exception: -if +unless they are also explicitly defined. +(Exception: if .BR _POSIX_C_SOURCE -is not otherwise defined, +is not otherwise defined, then it is always defined with the value 200112 (199506 in glibc versions before 2.4), unless the compiler is invoked in one of its standard modes, e.g., the @@ -206,8 +206,8 @@ and .BR _XOPEN_SOURCE . .BR _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1). -.BR _FILE_OFFSET_BITS -is not specified by any standard, +.BR _FILE_OFFSET_BITS +is not specified by any standard, but is employed on some other implementations. .BR _BSD_SOURCE , .BR _SVID_SOURCE , @@ -221,15 +221,15 @@ are Linux (glibc) specific. .I is a Linux/glibc specific header file. Other systems have an analogous file, but typically with a different name. -This header file is automatically included by other header files as -required: it is not necessary to explicitly include it in order to +This header file is automatically included by other header files as +required: it is not necessary to explicitly include it in order to employ feature test macros. According to which of the above feature test macros are defined, .I -internally defines various other macros that are checked by -other glibc header files. +internally defines various other macros that are checked by +other glibc header files. These macros have names prefixed by two underscores (e.g., __USE_MISC). Programs should \fInever\fP define these macros directly: -instead, the appropriate feature test macro(s) from the +instead, the appropriate feature test macro(s) from the list above should be employed. diff --git a/man7/fifo.7 b/man7/fifo.7 index 4733b82ef..d33b85fa4 100644 --- a/man7/fifo.7 +++ b/man7/fifo.7 @@ -3,19 +3,21 @@ .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. -.\" +.\" .\" 990620 - page created - aeb@cwi.nl .\" -.TH FIFO 7 1999-06-20 "Linux" "Linux Programmer's Manual" +.TH FIFO 7 1999-06-20 "Linux" "Linux Programmer's Manual" .SH NAME fifo \- first-in first-out special file, named pipe .SH DESCRIPTION A FIFO special file (a named pipe) is similar to a pipe, except that it is accessed as part of the file system. It can be opened by multiple processes for reading or -writing. When processes are exchanging data via the FIFO, +writing. +When processes are exchanging data via the FIFO, the kernel passes all data internally without writing it -to the file system. Thus, the FIFO special file has no +to the file system. +Thus, the FIFO special file has no contents on the file system, the file system entry merely serves as a reference point so that processes can access the pipe using a name in the file system. @@ -23,19 +25,24 @@ the pipe using a name in the file system. The kernel maintains exactly one pipe object for each FIFO special file that is opened by at least one process. The FIFO must be opened on both ends (reading and writing) -before data can be passed. Normally, opening the FIFO blocks +before data can be passed. +Normally, opening the FIFO blocks until the other end is opened also. .PP -A process can open a FIFO in non-blocking mode. In this +A process can open a FIFO in non-blocking mode. +In this case, opening for read only will succeed even if no-one has opened on the write side yet; opening for write only will fail with ENXIO (no such device or address) unless the other end has already been opened. .PP Under Linux, opening a FIFO for read and write will succeed -both in blocking and non-blocking mode. POSIX leaves this -behaviour undefined. This can be used to open a FIFO for -writing while there are no readers available. A process +both in blocking and non-blocking mode. +POSIX leaves this +behaviour undefined. +This can be used to open a FIFO for +writing while there are no readers available. +A process that uses both ends of the connection in order to communicate with itself should be very careful to avoid deadlocks. .SH NOTES diff --git a/man7/futex.7 b/man7/futex.7 index b1ddc3ebf..645de63b0 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -1,9 +1,9 @@ .\" This page is made available under the MIT license. .\" -.\" This manpage has been automatically generated by docbook2man +.\" This manpage has been automatically generated by docbook2man .\" from a DocBook document. This tool can be found at: -.\" -.\" Please send any bug reports, improvements, comments, patches, +.\" +.\" Please send any bug reports, improvements, comments, patches, .\" etc. to Steve Cheng . .TH FUTEX 7 2002-12-31 "" "Linux Programmer's Manual" .SH NAME @@ -14,96 +14,97 @@ futex \- Fast Userspace Locking .fi .SH DESCRIPTION .PP -The Linux kernel provides futexes ('Fast Userspace muTexes') -as a building block for fast userspace -locking and semaphores. -Futexes are very basic and lend themselves well for building higher level +The Linux kernel provides futexes ('Fast Userspace muTexes') +as a building block for fast userspace +locking and semaphores. +Futexes are very basic and lend themselves well for building higher level locking abstractions such as POSIX mutexes. .PP -This page does not set out to document all design decisions -but restricts itself to issues relevant for -application and library development. -Most programmers will in fact not be using futexes directly but -instead rely on system libraries built on them, +This page does not set out to document all design decisions +but restricts itself to issues relevant for +application and library development. +Most programmers will in fact not be using futexes directly but +instead rely on system libraries built on them, such as the NPTL pthreads implementation. .PP -A futex is identified by a piece of memory which can be -shared between different processes. -In these different processes, it need not have identical addresses. -In its bare form, a futex has semaphore semantics; -it is a counter that can be incremented and decremented atomically; +A futex is identified by a piece of memory which can be +shared between different processes. +In these different processes, it need not have identical addresses. +In its bare form, a futex has semaphore semantics; +it is a counter that can be incremented and decremented atomically; processes can wait for the value to become positive. .PP -Futex operation is entirely userspace for the non-contended case. -The kernel is only involved to arbitrate the contended case. -As any sane design will strive for non-contention, +Futex operation is entirely userspace for the non-contended case. +The kernel is only involved to arbitrate the contended case. +As any sane design will strive for non-contention, futexes are also optimised for this situation. .PP -In its bare form, a futex is an aligned integer which is -only touched by atomic assembler instructions. -Processes can share this integer using -.BR mmap (), -via shared memory segments or because they share memory space, +In its bare form, a futex is an aligned integer which is +only touched by atomic assembler instructions. +Processes can share this integer using +.BR mmap (), +via shared memory segments or because they share memory space, in which case the application is commonly called multithreaded. .SH "SEMANTICS" .PP -Any futex operation starts in userspace, +Any futex operation starts in userspace, but it may necessary to communicate with the kernel using the \fBfutex\fR(2) system call. .PP -To 'up' a futex, execute the proper assembler instructions that -will cause the host CPU to atomically increment the integer. -Afterwards, check if it has in fact changed from 0 to 1, in which case -there were no waiters and the operation is done. +To 'up' a futex, execute the proper assembler instructions that +will cause the host CPU to atomically increment the integer. +Afterwards, check if it has in fact changed from 0 to 1, in which case +there were no waiters and the operation is done. This is the non-contended case which is fast and should be common. .PP -In the contended case, the atomic increment changed the counter -from \-1 (or some other negative number). -If this is detected, there are waiters. -Userspace should now set the counter to 1 and instruct the +In the contended case, the atomic increment changed the counter +from \-1 (or some other negative number). +If this is detected, there are waiters. +Userspace should now set the counter to 1 and instruct the kernel to wake up any waiters using the FUTEX_WAKE operation. .PP -Waiting on a futex, to 'down' it, is the reverse operation. -Atomically decrement the counter and check if it changed to 0, -in which case the operation is done and the futex was uncontended. -In all other circumstances, the process should set the counter to \-1 -and request that the kernel wait for another process to up the futex. +Waiting on a futex, to 'down' it, is the reverse operation. +Atomically decrement the counter and check if it changed to 0, +in which case the operation is done and the futex was uncontended. +In all other circumstances, the process should set the counter to \-1 +and request that the kernel wait for another process to up the futex. This is done using the FUTEX_WAIT operation. .PP -The -.BR futex () -system call can optionally be passed a timeout specifying how long +The +.BR futex () +system call can optionally be passed a timeout specifying how long the kernel should -wait for the futex to be upped. +wait for the futex to be upped. In this case, semantics are more complex and the programmer is referred to \fBfutex\fR(2) for -more details. The same holds for asynchronous futex waiting. +more details. +The same holds for asynchronous futex waiting. .SH "NOTES" .PP -To reiterate, bare futexes are not intended as an easy to use -abstraction for end-users. -Implementors are expected to be assembly literate and to have read +To reiterate, bare futexes are not intended as an easy to use +abstraction for end-users. +Implementors are expected to be assembly literate and to have read the sources of the futex userspace library referenced below. .PP -This man page illustrates the most common use of the \fBfutex\fR(2) +This man page illustrates the most common use of the \fBfutex\fR(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). +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 +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 "SEE ALSO" .PP \fBfutex\fR(2), -`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' -(proceedings of the Ottawa Linux Symposium 2002), -futex example library, futex-*.tar.bz2 +`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 . diff --git a/man7/glob.7 b/man7/glob.7 index c27eda945..81a073c0f 100644 --- a/man7/glob.7 +++ b/man7/glob.7 @@ -38,9 +38,11 @@ that will perform this function for a user program. The rules are as follows (POSIX.2, 3.13). .SH "WILDCARD MATCHING" A string is a wildcard pattern if it contains one of the -characters `?', `*' or `['. Globbing is the operation +characters `?', `*' or `['. +Globbing is the operation that expands a wildcard pattern into the list of pathnames -matching the pattern. Matching is defined by: +matching the pattern. +Matching is defined by: A `?' (not between brackets) matches any single character. @@ -52,8 +54,8 @@ leading `[' is not an `!' matches a single character, namely any of the characters enclosed by the brackets. The string enclosed by the brackets cannot be empty; therefore `]' can be allowed between the brackets, provided -that it is the first character. (Thus, `[][!]' matches the -three characters `[', `]' and `!'.) +that it is the first character. +(Thus, `[][!]' matches the three characters `[', `]' and `!'.) .SS Ranges There is one special convention: two characters separated by `\-' denote a range. @@ -76,8 +78,10 @@ Between brackets these characters stand for themselves. Thus, `[[?*\e]' matches the four characters `[', `?', `*' and `\e'. .SH PATHNAMES Globbing is applied on each of the components of a pathname -separately. A `/' in a pathname cannot be matched by a `?' or `*' -wildcard, or by a range like `[.\-0]'. A range cannot contain an +separately. +A `/' in a pathname cannot be matched by a `?' or `*' +wildcard, or by a range like `[.\-0]'. +A range cannot contain an explicit `/' character; this would lead to a syntax error. If a filename starts with a `.', this character must be matched explicitly. @@ -86,7 +90,8 @@ archive all your files; `tar c .' is better.) .SH "EMPTY LISTS" The nice and simple rule given above: `expand a wildcard pattern into the list of matching pathnames' was the original Unix -definition. It allowed one to have patterns that expand into +definition. +It allowed one to have patterns that expand into an empty list, as in .br .nf @@ -102,7 +107,8 @@ With one can force the classical behaviour by setting .IR allow_null_glob_expansion=true . -(Similar problems occur elsewhere. E.g., where old scripts have +(Similar problems occur elsewhere. +E.g., where old scripts have .br .nf rm `find . \-name "*~"` @@ -118,7 +124,8 @@ called with an empty argument list.) .SH NOTES .SS Regular expressions Note that wildcard patterns are not regular expressions, -although they are a bit similar. First of all, they match +although they are a bit similar. +First of all, they match filenames, rather than text, and secondly, the conventions are not the same: e.g., in a regular expression `*' means zero or more copies of the preceding thing. @@ -132,7 +139,8 @@ so that `[\ \-%]' stands for `[\ !"#$%]' and `[a\-z]' stands for "any lowercase letter". Some Unix implementations generalized this so that a range X\-Y stands for the set of characters with code between the codes for -X and for Y. However, this requires the user to know the +X and for Y. +However, this requires the user to know the character coding in use on the local system, and moreover, is not convenient if the collating sequence for the local alphabet differs from the ordering of the character codes. @@ -140,7 +148,8 @@ Therefore, POSIX extended the bracket notation greatly, both for wildcard patterns and for regular expressions. In the above we saw three types of items that can occur in a bracket expression: namely (i) the negation, (ii) explicit single characters, -and (iii) ranges. POSIX specifies ranges in an internationally +and (iii) ranges. +POSIX specifies ranges in an internationally more useful way and adds three more types: (iii) Ranges X\-Y comprise all characters that fall between X @@ -163,13 +172,15 @@ in the current locale. (v) Collating symbols, like `[.ch.]' or `[.a-acute.]', where the string between `[.' and `.]' is a collating -element defined for the current locale. Note that this may +element defined for the current locale. +Note that this may be a multi-character element. (vi) Equivalence class expressions, like `[=a=]', where the string between `[=' and `=]' is any collating element from its equivalence class, as defined for the -current locale. For example, `[[=a=]]' might be equivalent +current locale. +For example, `[[=a=]]' might be equivalent to `[aáàäâ]' (warning: Latin-1 here), that is, to `[a[.a-acute.][.a-grave.][.a-umlaut.][.a-circumflex.]]'. .SH "SEE ALSO" diff --git a/man7/hier.7 b/man7/hier.7 index 7bb0323f2..0ffe0428f 100644 --- a/man7/hier.7 +++ b/man7/hier.7 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -33,22 +33,26 @@ hier \- Description of the file system hierarchy A typical Linux system has, among others, the following directories: .TP .I / -This is the root directory. This is where the whole tree starts. +This is the root directory. +This is where the whole tree starts. .TP .I /bin This directory contains executable programs which are needed in single user mode and to bring the system up or repair it. .TP .I /boot -Contains static files for the boot loader. This directory only holds -the files which are needed during the boot process. The map installer +Contains static files for the boot loader. +This directory only holds +the files which are needed during the boot process. +The map installer and configuration files should go to .I /sbin and .IR /etc . .TP .I /dev -Special or device files, which refer to physical devices. See +Special or device files, which refer to physical devices. +See .BR mknod (1). .TP .I /dos @@ -56,7 +60,8 @@ If both MS\-DOS and Linux are run on one computer, this is a typical place to mount a DOS file system. .TP .I /etc -Contains configuration files which are local to the machine. Some +Contains configuration files which are local to the machine. +Some larger software packages, like X11, can have their own subdirectories below .IR /etc . @@ -69,7 +74,7 @@ and you may have links for these files to .TP .I /etc/opt Host-specific configuration files for add-on applications installed -in +in .IR /opt . .TP .I /etc/sgml @@ -84,7 +89,8 @@ Configuration files for the X11 window system (optional). .TP .I /home On machines with home directories for users, these are usually beneath -this directory, directly or not. The structure of this directory +this directory, directly or not. +The structure of this directory depends on local administration decisions. .TP .I /lib @@ -101,7 +107,8 @@ This directory should contain add-on packages that contain static files. This is a mount point for the .I proc filesystem, which provides information about running processes and -the kernel. This pseudo-file system is described in more detail in +the kernel. +This pseudo-file system is described in more detail in .BR proc (5). .TP .I /root @@ -118,8 +125,8 @@ This directory contains temporary files which may be deleted with no notice, such as by a regular job or at system boot up. .TP .I /usr -This directory is usually mounted from a separate partition. It -should hold only sharable, read-only data, so that it can be mounted +This directory is usually mounted from a separate partition. +It should hold only sharable, read-only data, so that it can be mounted by various machines running Linux. .TP .I /usr/X11R6 @@ -136,18 +143,20 @@ Data files associated with the X\-Windows system. .TP .I /usr/X11R6/lib/X11 These contain miscellaneous files needed to run X; Often, there is a -symbolic link from +symbolic link from .I /usr/lib/X11 to this directory. .TP .I /usr/X11R6/include/X11 Contains include files needed for compiling programs using the X11 -window system. Often, there is a symbolic link from +window system. +Often, there is a symbolic link from .I /usr/include/X11 to this directory. .TP .I /usr/bin -This is the primary directory for executable programs. Most programs +This is the primary directory for executable programs. +Most programs executed by normal users which are not needed for booting or for repairing the system and which are not installed locally should be placed in this directory. @@ -167,10 +176,12 @@ Replaced by .TP .I /usr/etc Site-wide configuration files to be shared between several machines -may be stored in this directory. However, commands should always +may be stored in this directory. +However, commands should always reference those files using the .I /etc -directory. Links from files in +directory. +Links from files in .I /etc should point to the appropriate files in .IR /usr/etc . @@ -182,12 +193,14 @@ Binaries for games and educational programs (optional). Include files for the C compiler. .TP .I /usr/include/X11 -Include files for the C compiler and the X\-Windows system. This is +Include files for the C compiler and the X\-Windows system. +This is usually a symbolic link to .IR /usr/X11R6/include/X11 . .TP .I /usr/include/asm -Include files which declare some assembler functions. This used to be a +Include files which declare some assembler functions. +This used to be a symbolic link to .IR /usr/src/linux/include/asm . .TP @@ -198,14 +211,17 @@ system release and used to be a symbolic link to to get at operating system specific information. (Note that one should have include files there that work correctly with -the current libc and in user space. However, Linux kernel source is not +the current libc and in user space. +However, Linux kernel source is not designed to be used with user programs and does not know anything -about the libc you are using. It is very likely that things will break +about the libc you are using. +It is very likely that things will break if you let .I /usr/include/asm and .I /usr/include/linux -point at a random kernel tree. Debian systems don't do this +point at a random kernel tree. +Debian systems don't do this and use headers from a known good kernel version, provided in the libc*-dev package.) .TP @@ -214,12 +230,14 @@ Include files to use with the GNU C++ compiler. .TP .I /usr/lib Object libraries, including dynamic libraries, plus some executables -which usually are not invoked directly. More complicated programs may +which usually are not invoked directly. +More complicated programs may have whole subdirectories there. .TP .I /usr/lib/X11 The usual place for data files associated with X programs, and -configuration files for the X system itself. On Linux, it usually is +configuration files for the X system itself. +On Linux, it usually is a symbolic link to .IR /usr/X11R6/lib/X11 . .TP @@ -231,7 +249,7 @@ contains executables and include files for the GNU C compiler, Files for the GNU groff document formatting system. .TP .I /usr/lib/uucp -Files for +Files for .BR uucp (1). .TP .I /usr/local @@ -272,7 +290,7 @@ of the same OS. Source code for locally installed software. .TP .I /usr/man -Replaced by +Replaced by .IR /usr/share/man . .TP .I /usr/sbin @@ -293,7 +311,7 @@ or .TP .I /usr/share/dict Contains the word lists used by spell checkers. -.TP +.TP .I /usr/share/doc Documentation about installed programs. .TP @@ -311,8 +329,9 @@ Locale information goes here. Manual pages go here in subdirectories according to the man page sections. .TP .I /usr/share/man//man[1\-9] -These directories contain manual pages for the specific locale in source code -form. Systems which use a unique language and code set for all manual pages +These directories contain manual pages for the +specific locale in source code form. +Systems which use a unique language and code set for all manual pages may omit the substring. .TP .I /usr/share/misc @@ -336,7 +355,8 @@ Files for timezone information. .TP .I /usr/src Source files for different parts of the system, included with some packages -for reference purposes. Don't work here with your own projects, as files +for reference purposes. +Don't work here with your own projects, as files below /usr should be read-only except when installing software. .TP .I /usr/src/linux @@ -345,7 +365,8 @@ Some distributions put here the source for the default kernel they ship. You should probably use another directory when building your own kernel. .TP .I /usr/tmp -Obsolete. This should be a link +Obsolete. +This should be a link to .IR /var/tmp . This link is present only for compatibility reasons and shouldn't be used. @@ -368,7 +389,8 @@ Data cached for programs. .TP .IR /var/catman/cat[1\-9] " or " /var/cache/man/cat[1\-9] These directories contain preformatted manual pages according to their -man page section. (The use of preformatted manual pages is deprecated.) +man page section. +(The use of preformatted manual pages is deprecated.) .TP .I /var/cron Reserved for historical reasons. @@ -381,7 +403,8 @@ Variable data for .IR /usr/local . .TP .I /var/lock -Lock files are placed in this directory. The naming convention for +Lock files are placed in this directory. +The naming convention for device lock files is .I LCK.. where @@ -395,11 +418,12 @@ character. Miscellaneous log files. .TP .I /var/opt -Variable data for +Variable data for .IR /opt . .TP .I /var/mail -Users' mailboxes. Replaces +Users' mailboxes. +Replaces .IR /var/spool/mail . .TP .I /var/msgs @@ -429,7 +453,7 @@ Spooled jobs for Spooled files for printing. .TP .I /var/spool/mail -Replaced by +Replaced by .IR /var/mail . .TP .I /var/spool/mqueue @@ -439,7 +463,7 @@ Queued outgoing mail. Spool directory for news. .TP .I /var/spool/rwho -Spooled files for +Spooled files for .BR rwhod (8). .TP .I /var/spool/smail diff --git a/man7/icmp.7 b/man7/icmp.7 index 738dc2c73..b98d5dda0 100644 --- a/man7/icmp.7 +++ b/man7/icmp.7 @@ -4,27 +4,28 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ -.TH ICMP 7 1999-04-27 "Linux Man Page" "Linux Programmer's Manual" +.TH ICMP 7 1999-04-27 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -icmp, IPPROTO_ICMP \- Linux IPv4 ICMP kernel module. +icmp, IPPROTO_ICMP \- Linux IPv4 ICMP kernel module. .SH DESCRIPTION -This kernel protocol module implements the Internet Control -Message Protocol defined in RFC\ 792. +This kernel protocol module implements the Internet Control +Message Protocol defined in RFC\ 792. It is used to signal error conditions and for diagnosis. -The user doesn't interact directly with this module; -instead it communicates with the other protocols in the kernel -and these pass the ICMP errors to the application layers. +The user doesn't interact directly with this module; +instead it communicates with the other protocols in the kernel +and these pass the ICMP errors to the application layers. The kernel ICMP module also answers ICMP requests. .PP A user protocol may receive ICMP packets for all local sockets by opening -a raw socket with the protocol +a raw socket with the protocol .BR IPPROTO_ICMP . See .BR raw (7) for more information. The types of ICMP packets passed to the socket can be filtered using the -.B ICMP_FILTER -socket option. ICMP packets are always processed by the kernel too, even +.B ICMP_FILTER +socket option. +ICMP packets are always processed by the kernel too, even when passed to a user socket. .LP Linux limits the rate of ICMP error packets to each destination. @@ -34,22 +35,22 @@ and are also limited by the destination route of the incoming packets. .SH SYSCTLS ICMP supports a sysctl interface to configure some global IP parameters. -The sysctls can be accessed by reading or writing the -.I /proc/sys/net/ipv4/* -files or with the +The sysctls can be accessed by reading or writing the +.I /proc/sys/net/ipv4/* +files or with the .BR sysctl (2) -interface. +interface. Most of these sysctls are rate limitations for specific ICMP types. -Linux 2.2 uses a token bucket filter to limit ICMPs. +Linux 2.2 uses a token bucket filter to limit ICMPs. .\" FIXME better description needed -The value is the timeout in jiffies until the token bucket filter is -cleared after a burst. +The value is the timeout in jiffies until the token bucket filter is +cleared after a burst. A jiffy is a system dependent unit, usually 10ms on x86 and about 1ms on alpha and IA64. .TP .B icmp_destunreach_rate -Maximum rate to send ICMP Destination Unreachable packets. -This limits the rate at which packets are sent to any individual +Maximum rate to send ICMP Destination Unreachable packets. +This limits the rate at which packets are sent to any individual route or destination. The limit does not affect sending of .B ICMP_FRAG_NEEDED @@ -58,17 +59,17 @@ packets needed for path MTU discovery. .B icmp_echo_ignore_all If this value is non-zero, Linux will ignore all .B ICMP_ECHO -requests. +requests. .TP .B icmp_echo_ignore_broadcasts If this value is non-zero, Linux will ignore all .B ICMP_ECHO -packets sent to broadcast addresses. +packets sent to broadcast addresses. .TP .B icmp_echoreply_rate Maximum rate for sending .B ICMP_ECHOREPLY -packets in response to +packets in response to .B ICMP_ECHOREQUEST packets. .TP @@ -81,11 +82,12 @@ These packets are sent when a packet arrives with an invalid IP header. .B icmp_timeexceed_rate Maximum rate for sending .B ICMP_TIME_EXCEEDED -packets. These packets are -sent to prevent loops when a packet has crossed too many hops. +packets. +These packets are +sent to prevent loops when a packet has crossed too many hops. .SH NOTES -As many other implementations don't support -.B IPPROTO_ICMP +As many other implementations don't support +.B IPPROTO_ICMP raw sockets, this feature should not be relied on in portable programs. .\" not really true ATM @@ -94,14 +96,14 @@ should not be relied on in portable programs. .PP .B ICMP_REDIRECT packets are not sent when Linux is not acting as a router. -They are also only accepted from the old gateway defined in the +They are also only accepted from the old gateway defined in the routing table and the redirect routes are expired after some time. .PP The 64-bit timestamp returned by .B ICMP_TIMESTAMP is in milliseconds since January 1, 1970. .PP -Linux ICMP internally uses a raw socket to send ICMPs. +Linux ICMP internally uses a raw socket to send ICMPs. This raw socket may appear in .BR netstat (8) output with a zero inode. diff --git a/man7/inotify.7 b/man7/inotify.7 index 8e09ff7b3..61a1099d3 100644 --- a/man7/inotify.7 +++ b/man7/inotify.7 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -25,29 +25,29 @@ inotify \- monitoring file system events .SH DESCRIPTION The -.I inotify +.I inotify API provides a mechanism for monitoring file system events. Inotify can be used to monitor individual files, or to monitor directories. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. -The following system calls are used with this API: +The following system calls are used with this API: .BR inotify_init (), .BR inotify_add_watch (), .BR inotify_rm_watch (), .BR read (), -and +and .BR close (). .BR inotify_init (2) -creates an inotify instance and returns a file descriptor +creates an inotify instance and returns a file descriptor referring to the inotify instance. .BR inotify_add_watch (2) manipulates the "watch list" associated with an inotify instance. Each item ("watch") in the watch list specifies the pathname of -a file or directory, +a file or directory, along with some set of events that the kernel should monitor for the file referred to by that pathname. .BR inotify_add_watch () @@ -60,16 +60,16 @@ when the watch is created. .BR inotify_rm_watch (2) removes an item from an inotify watch list. -When all file descriptors referring to an inotify +When all file descriptors referring to an inotify instance have been closed, -the underlying object and its resources are +the underlying object and its resources are freed for re-use by the kernel; all associated watches are automatically freed. To determine what events have occurred, an application .BR read (2)s from the inotify file descriptor. -If no events have so far occurred, then, +If no events have so far occurred, then, assuming a blocking file descriptor, .BR read () will block until at least one event occurs. @@ -83,7 +83,7 @@ returns a buffer containing one or more of the following structures: struct inotify_event { int wd; /* Watch descriptor */ uint32_t mask; /* Mask of events */ - uint32_t cookie; /* Unique cookie associating related + uint32_t cookie; /* Unique cookie associating related events (for rename(2)) */ uint32_t len; /* Size of 'name' field */ char name[]; /* Optional null-terminated name */ @@ -93,7 +93,7 @@ struct inotify_event { .I wd identifies the watch for which this event occurs. -It is one of the watch descriptors returned by a previous call to +It is one of the watch descriptors returned by a previous call to .BR inotify_add_watch (). .I mask @@ -104,33 +104,33 @@ is a unique integer that connects related events. Currently this is only used for rename events, and allows the resulting pair of .B IN_MOVE_FROM -and +and .B IN_MOVE_TO events to be connected by the application. -The +The .I name field is only present when an event is returned -for a file inside a watched directory; +for a file inside a watched directory; it identifies the file pathname relative to the watched directory. -This pathname is null-terminated, +This pathname is null-terminated, and may include further null bytes to align subsequent reads to a suitable address boundary. The .I len -field counts all of the bytes in +field counts all of the bytes in .IR name , -including the null bytes; +including the null bytes; the length of each .I inotify_event structure is thus .IR "sizeof(inotify_event)+len" . .SS inotify events -The +The .BR inotify_add_watch (2) .I mask -argument and the +argument and the .I mask field of the .I inotify_event @@ -142,7 +142,7 @@ The following bits can be specified in .I mask when calling .BR inotify_add_watch () -and may be returned in the +and may be returned in the .I mask field returned by .BR read (): @@ -152,7 +152,7 @@ lB lB lB l. Bit Description IN_ACCESS File was accessed (read) (*) -IN_ATTRIB Metadata changed (permissions, timestamps, +IN_ATTRIB Metadata changed (permissions, timestamps, extended attributes, etc.) (*) IN_CLOSE_WRITE File opened for writing was closed (*) IN_CLOSE_NOWRITE File not opened for writing was closed (*) @@ -167,8 +167,8 @@ IN_OPEN File was opened (*) .TE .in -0.25i .PP -When monitoring a directory, -the events marked with an asterisk (*) above can occur for +When monitoring a directory, +the events marked with an asterisk (*) above can occur for files in the directory, in which case the .I name field in the returned @@ -192,7 +192,7 @@ and which equates to IN_CLOSE_WRITE|IN_CLOSE_NOWRITE. .PP -The following further bits can be specified in +The following further bits can be specified in .I mask when calling .BR inotify_add_watch (): @@ -201,10 +201,10 @@ when calling lB lB lB l. Bit Description -IN_DONT_FOLLOW Don't dereference \fIpathname\fP if it is a symbolic link +IN_DONT_FOLLOW Don't dereference \fIpathname\fP if it is a symbolic link IN_MASK_ADD Add (OR) events to watch mask for this pathname if it already exists (instead of replacing mask) -IN_ONESHOT Monitor \fIpathname\fP for one event, then remove from +IN_ONESHOT Monitor \fIpathname\fP for one event, then remove from watch list IN_ONLYDIR Only watch \fIpathname\fP if it is a directory .TE @@ -219,7 +219,7 @@ field returned by lB lB lB l. Bit Description -IN_IGNORED Watch was removed explicitly (\fBinotify_rm_watch\fP()) +IN_IGNORED Watch was removed explicitly (\fBinotify_rm_watch\fP()) or automatically (file was deleted, or file system was unmounted) IN_ISDIR Subject of this event is a directory @@ -228,51 +228,51 @@ IN_UNMOUNT File system containing watched object was unmounted .TE .in -0.25i .SS /proc interfaces -The following interfaces can be used to limit the amount of +The following interfaces can be used to limit the amount of kernel memory consumed by inotify: .TP .IR /proc/sys/fs/inotify/max_queued_events The value in this file is used when an application calls .BR inotify_init (2) -to set an upper limit on the number of events that can be +to set an upper limit on the number of events that can be queued to the corresponding inotify instance. Events in excess of this limit are dropped, but an .B IN_Q_OVERFLOW event is always generated. .TP .IR /proc/sys/fs/inotify/max_user_instances -This specifies an upper limit on the number of inotify instances +This specifies an upper limit on the number of inotify instances that can be created per real user ID. .TP .IR /proc/sys/fs/inotify/max_user_watches -This specifies a limit on the number of watches that can be associated +This specifies a limit on the number of watches that can be associated with each inotify instance. .SH "NOTES" Inotify file descriptors can be monitored using .BR select (2), .BR poll (2), -and +and .BR epoll (7). -If successive output inotify events produced on the -inotify file descriptor are identical (same -.IR wd , -.IR mask , +If successive output inotify events produced on the +inotify file descriptor are identical (same +.IR wd , +.IR mask , .IR cookie , and .IR name ) then they are coalesced into a single event. -The events returned by reading from an inotify file descriptor -form an ordered queue. -Thus, for example, it is guaranteed that when renaming from -one directory to another, events will be produced in the +The events returned by reading from an inotify file descriptor +form an ordered queue. +Thus, for example, it is guaranteed that when renaming from +one directory to another, events will be produced in the correct order on the inotify file descriptor. The .B FIONREAD .BR ioctl () -returns the number of bytes available to read from an +returns the number of bytes available to read from an inotify file descriptor. Inotify monitoring of directories is not recursive: @@ -284,17 +284,17 @@ The required library interfaces were added to glibc in version 2.4. .SH "BUGS" In kernels before 2.6.16, the .B IN_ONESHOT -.I mask +.I mask flag does not work. -As at glibc 2.4, the definitions for -.BR IN_DONT_FOLLOW , +As at glibc 2.4, the definitions for +.BR IN_DONT_FOLLOW , .BR IN_MASK_ADD , -and -.B IN_ONLYDIR -are missing from +and +.B IN_ONLYDIR +are missing from .IR . -.\" FIXME . but these definitions were added to the glibc on 17 May 06: +.\" FIXME . but these definitions were added to the glibc on 17 May 06: .\" check later to see in which glibc version these changes are actually .\" released. .SH "CONFORMING TO" diff --git a/man7/intro.7 b/man7/intro.7 index 242323155..1522026ce 100644 --- a/man7/intro.7 +++ b/man7/intro.7 @@ -21,19 +21,20 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 .\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) .TH INTRO 7 1993-04-23 "Linux" "Linux Programmer's Manual" .SH NAME intro \- Introduction to overview, conventions, and miscellany section .SH DESCRIPTION -This chapter provides overviews on various topics, and -describes conventions and protocols, +This chapter provides overviews on various topics, and +describes conventions and protocols, character set standards, the standard file system layout, and miscellaneous other things. .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! .SH "SEE ALSO" .BR standards (7) diff --git a/man7/ip.7 b/man7/ip.7 index f8c5132e2..7c04c7a0e 100644 --- a/man7/ip.7 +++ b/man7/ip.7 @@ -6,7 +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 $ -.TH IP 7 2001-06-19 "Linux Man Page" "Linux Programmer's Manual" +.TH IP 7 2001-06-19 "Linux Man Page" "Linux Programmer's Manual" .SH NAME ip \- Linux IPv4 protocol implementation .SH SYNOPSIS @@ -21,40 +21,40 @@ ip \- Linux IPv4 protocol implementation .IB tcp_socket " = socket(PF_INET, SOCK_STREAM, 0);" .br .IB udp_socket " = socket(PF_INET, SOCK_DGRAM, 0);" -.br +.br .IB raw_socket " = socket(PF_INET, SOCK_RAW, " protocol ");" .SH DESCRIPTION -Linux implements the Internet Protocol, version 4, -described in RFC\ 791 and RFC\ 1122. -.B ip -contains a level 2 -multicasting implementation conforming to RFC\ 1112. +Linux implements the Internet Protocol, version 4, +described in RFC\ 791 and RFC\ 1122. +.B ip +contains a level 2 +multicasting implementation conforming to RFC\ 1112. It also contains an IP router including a packet filter. .\" FIXME has someone verified that 2.1 is really 1812 compliant? .PP The programming interface is BSD sockets compatible. -For more information on sockets, see -.BR socket (7). +For more information on sockets, see +.BR socket (7). .PP An IP socket is created by calling the -.BR socket (2) -function as +.BR socket (2) +function as .BR "socket(PF_INET, socket_type, protocol)" . -Valid socket types are -.B SOCK_STREAM -to open a -.BR tcp (7) -socket, +Valid socket types are +.B SOCK_STREAM +to open a +.BR tcp (7) +socket, .B SOCK_DGRAM to open a .BR udp (7) socket, or .B SOCK_RAW -to open a +to open a .BR raw (7) -socket to access the IP protocol directly. -.I protocol -is the IP protocol in the IP header to be received or sent. +socket to access the IP protocol directly. +.I protocol +is the IP protocol in the IP header to be received or sent. The only valid values for .I protocol are @@ -64,25 +64,27 @@ and for TCP sockets and .B 0 and -.B IPPROTO_UDP -for UDP sockets. For -.B SOCK_RAW +.B IPPROTO_UDP +for UDP sockets. +For +.B SOCK_RAW you may specify -a valid IANA IP protocol defined in +a valid IANA IP protocol defined in RFC\ 1700 assigned numbers. .PP -.\" FIXME ip current does an autobind in listen, but I'm not sure +.\" FIXME ip current does an autobind in listen, but I'm not sure .\" if that should be documented. -When a process wants to receive new incoming packets or connections, it +When a process wants to receive new incoming packets or connections, it should bind a socket to a local interface address using .BR bind (2). Only one IP socket may be bound to any given local (address, port) pair. -When -.B INADDR_ANY +When +.B INADDR_ANY is specified in the bind call the socket will be bound to .I all -local interfaces. When +local interfaces. +When .BR listen (2) or .BR connect (2) @@ -90,17 +92,18 @@ are called on an unbound socket, it is automatically bound to a random free port with the local address set to .BR INADDR_ANY . -A TCP local socket address that has been bound is unavailable for +A TCP local socket address that has been bound is unavailable for some time after closing, -unless the +unless the .B SO_REUSEADDR -flag has been set. Care should be taken when using this flag as it -makes TCP less reliable. +flag has been set. +Care should be taken when using this flag as it +makes TCP less reliable. .SH "ADDRESS FORMAT" -An IP socket address is defined as a combination of an IP interface +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 -are implemented by higher level protocols like +are implemented by higher level protocols like .BR udp (7) and .BR tcp (7). @@ -123,35 +126,35 @@ struct in_addr { .fi .in -0.25i .PP -.I sin_family -is always set to -.BR AF_INET . -This is required; in Linux 2.2 most networking functions return +.I sin_family +is always set to +.BR AF_INET . +This is required; in Linux 2.2 most networking functions return .B EINVAL when this setting is missing. .I sin_port -contains the port in network byte order. +contains the port in network byte order. The port numbers below 1024 are called .IR "reserved ports" . Only privileged processes (i.e., those having the -.B CAP_NET_BIND_SERVICE -capability) may -.BR bind (2) -to these sockets. -Note that the raw IPv4 protocol as such has no concept of a +.B CAP_NET_BIND_SERVICE +capability) may +.BR bind (2) +to these sockets. +Note that the raw IPv4 protocol as such has no concept of a port, they are only implemented by higher protocols like .BR tcp (7) and .BR udp (7). .PP -.I sin_addr +.I sin_addr is the IP host address. -The +The .I s_addr -member of +member of .I struct in_addr -contains the host interface address in network byte order. -.I in_addr +contains the host interface address in network byte order. +.I in_addr should be assigned one of the INADDR_* values (e.g., INADDR_ANY) or set using the .BR inet_aton (3), @@ -159,35 +162,36 @@ or set using the .BR inet_makeaddr (3) library functions or directly with the name resolver (see .BR gethostbyname (3)). -IPv4 addresses are divided into unicast, broadcast -and multicast addresses. +IPv4 addresses are divided into unicast, broadcast +and multicast addresses. Unicast addresses specify a single interface of a host, -broadcast addresses specify all hosts on a network and multicast -addresses address all hosts in a multicast group. -Datagrams to broadcast addresses can be only sent or received when the +broadcast addresses specify all hosts on a network and multicast +addresses address all hosts in a multicast group. +Datagrams to broadcast addresses can be only sent or received when the .B SO_BROADCAST socket flag is set. -In the current implementation connection oriented sockets are only allowed +In the current implementation connection oriented sockets are only allowed to use unicast addresses. .\" Leave a loophole for XTP @) -Note that the address and the port are always stored in +Note that the address and the port are always stored in network byte order. In particular, this means that you need to call -.BR htons (3) -on the number that is assigned to a port. All address/port manipulation +.BR htons (3) +on the number that is assigned to a port. +All address/port manipulation functions in the standard library work in network byte order. -There are several special addresses: +There are several special addresses: .B INADDR_LOOPBACK (127.0.0.1) always refers to the local host via the loopback device; -.B INADDR_ANY +.B INADDR_ANY (0.0.0.0) means any address for binding; .B INADDR_BROADCAST (255.255.255.255) -means any host and has the same effect on bind as +means any host and has the same effect on bind as .B INADDR_ANY for historical reasons. .SH "SOCKET OPTIONS" @@ -195,24 +199,26 @@ IP supports some protocol specific socket options that can be set with .BR setsockopt (2) and read with .BR getsockopt (2). -The socket option level for IP is +The socket option level for IP is .BR IPPROTO_IP . .\" or SOL_IP on Linux A boolean integer flag is zero when it is false, otherwise true. -.\" +.\" .\" FIXME Document IP_FREEBIND .\" .TP .B IP_OPTIONS Sets or get the IP options to be sent with every packet from this -socket. -The arguments are a pointer to a memory buffer containing the options +socket. +The arguments are a pointer to a memory buffer containing the options and the option length. The .BR setsockopt (2) call sets the IP options associated with a socket. -The maximum option size for IPv4 is 40 bytes. See RFC\ 791 for the allowed -options. When the initial connection request packet for a +The maximum option size for IPv4 is 40 bytes. +See RFC\ 791 for the allowed +options. +When the initial connection request packet for a .B SOCK_STREAM socket contains IP options, the IP options will be set automatically to the options from the initial packet with routing headers reversed. @@ -221,7 +227,8 @@ is established. The processing of all incoming source routing options is disabled by default and can be enabled by using the .B accept_source_route -sysctl. Other options like timestamps are still handled. +sysctl. +Other options like timestamps are still handled. For datagram sockets, IP options can be only set by the local user. Calling .BR getsockopt (2) @@ -232,12 +239,12 @@ puts the current IP options used for sending into the supplied buffer. .B IP_PKTINFO Pass an .I IP_PKTINFO -ancillary message that contains a -.I pktinfo +ancillary message that contains a +.I pktinfo structure that supplies some information about the incoming packet. This only works for datagram oriented sockets. -The argument is a flag that tells the socket whether the IP_PKTINFO -message should be passed or not. +The argument is a flag that tells the socket whether the IP_PKTINFO +message should be passed or not. The message itself can only be sent/retrieved as control message with a packet using .BR recvmsg (2) @@ -249,7 +256,7 @@ or struct in_pktinfo { unsigned int ipi_ifindex; /* Interface index */ struct in_addr ipi_spec_dst; /* Local address */ - struct in_addr ipi_addr; /* Header Destination + struct in_addr ipi_addr; /* Header Destination address */ }; .fi @@ -263,7 +270,7 @@ is the local address of the packet and .I ipi_addr is the destination address in the packet header. If -.I IP_PKTINFO +.I IP_PKTINFO is passed to .BR sendmsg (2) and @@ -279,43 +286,46 @@ index overwrites for the routing table lookup. .TP .B IP_RECVTOS -If enabled the -.I IP_TOS -ancillary message is passed with incoming packets. -It contains a byte which specifies the Type of Service/Precedence +If enabled the +.I IP_TOS +ancillary message is passed with incoming packets. +It contains a byte which specifies the Type of Service/Precedence field of the packet header. -Expects a boolean integer flag. +Expects a boolean integer flag. .TP .B IP_RECVTTL When this flag is set -pass a -.I IP_TTL -control message with the time to live -field of the received packet as a byte. Not supported for +pass a +.I IP_TTL +control message with the time to live +field of the received packet as a byte. +Not supported for .B SOCK_STREAM sockets. .TP .B IP_RECVOPTS Pass all incoming IP options to the user in a -.I IP_OPTIONS -control message. +.I IP_OPTIONS +control message. The routing header and other options are already filled in -for the local host. Not supported for -.I SOCK_STREAM +for the local host. +Not supported for +.I SOCK_STREAM sockets. .TP .B IP_RETOPTS -Identical to +Identical to .I IP_RECVOPTS but returns raw unprocessed options with timestamp and route record options not filled in for this hop. .TP .B IP_TOS -Set or receive the Type-Of-Service (TOS) field that is sent -with every IP packet originating from this socket. +Set or receive the Type-Of-Service (TOS) field that is sent +with every IP packet originating from this socket. It is used to prioritize packets on the network. -TOS is a byte. There are some standard TOS flags defined: -.B IPTOS_LOWDELAY +TOS is a byte. +There are some standard TOS flags defined: +.B IPTOS_LOWDELAY to minimize delays for interactive traffic, .B IPTOS_THROUGHPUT to optimize throughput, @@ -323,33 +333,35 @@ to optimize throughput, to optimize for reliability, .B IPTOS_MINCOST should be used for "filler data" where slow transmission doesn't matter. -At most one of these TOS values can be specified. +At most one of these TOS values can be specified. Other bits are invalid and shall be cleared. -Linux sends -.B IPTOS_LOWDELAY +Linux sends +.B IPTOS_LOWDELAY datagrams first by default, -but the exact behaviour depends on the configured queueing discipline. -.\" FIXME elaborate on this +but the exact behaviour depends on the configured queueing discipline. +.\" FIXME elaborate on this Some high priority levels may require superuser privileges (the .B CAP_NET_ADMIN capability). The priority can also be set in a protocol independent way by the .RB ( SOL_SOCKET ", " SO_PRIORITY ) socket option (see -.BR socket (7)). -.TP +.BR socket (7)). +.TP .B IP_TTL Set or retrieve the current time to live field that is used in every packet sent from this socket. .TP .B IP_HDRINCL -If enabled -the user supplies an IP header in front of the user data. -Only valid for -.B SOCK_RAW -sockets. See +If enabled +the user supplies an IP header in front of the user data. +Only valid for +.B SOCK_RAW +sockets. +See .BR raw (7) -for more information. When this flag is enabled the values set by +for more information. +When this flag is enabled the values set by .IR IP_OPTIONS , .I IP_TTL and @@ -357,29 +369,31 @@ and are ignored. .TP .BR IP_RECVERR " (defined in )" -Enable extended reliable error message passing. +Enable extended reliable error message passing. When enabled on a datagram socket all -generated errors will be queued in a per-socket error queue. When the user +generated errors will be queued in a per-socket error queue. +When the user receives an error from a socket operation the errors can -be received by calling -.BR recvmsg (2) -with the -.B MSG_ERRQUEUE -flag set. The -.I sock_extended_err -structure describing the error will be passed in a ancillary message with -the type -.I IP_RECVERR -and the level -.BR IPPROTO_IP . +be received by calling +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +The +.I sock_extended_err +structure describing the error will be passed in a ancillary message with +the type +.I IP_RECVERR +and the level +.BR IPPROTO_IP . .\" or SOL_IP on Linux This is useful for reliable error handling on unconnected sockets. The received data portion of the error queue contains the error packet. .IP -The -.I IP_RECVERR -control message contains a +The +.I IP_RECVERR +control message contains a .I sock_extended_err structure: .IP @@ -393,118 +407,126 @@ structure: struct sock_extended_err { u_int32_t ee_errno; /* error number */ - u_int8_t ee_origin; /* where the error originated */ + u_int8_t ee_origin; /* where the error originated */ u_int8_t ee_type; /* type */ u_int8_t ee_code; /* code */ u_int8_t ee_pad; u_int32_t ee_info; /* additional information */ - u_int32_t ee_data; /* other data */ - /* More data may follow */ + u_int32_t ee_data; /* other data */ + /* More data may follow */ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); .fi .in -0.25i .IP -.I ee_errno -contains the errno number of the queued error. +.I ee_errno +contains the errno number of the queued error. .I ee_origin -is the origin code of where the error originated. -The other fields are protocol specific. The macro -.B SO_EE_OFFENDER +is the origin code of where the error originated. +The other fields are protocol specific. +The macro +.B SO_EE_OFFENDER returns a pointer to the address of the network object where the error originated from given a pointer to the ancillary message. If this address is not known, the -.I sa_family -member of the -.I sockaddr -contains +.I sa_family +member of the +.I sockaddr +contains .B AF_UNSPEC -and the other fields of the -.I sockaddr -are undefined. +and the other fields of the +.I sockaddr +are undefined. .IP -IP uses the +IP uses the .I sock_extended_err structure as follows: -.I ee_origin -is set to -.B SO_EE_ORIGIN_ICMP +.I ee_origin +is set to +.B SO_EE_ORIGIN_ICMP for errors received as an ICMP packet, or -.B SO_EE_ORIGIN_LOCAL -for locally generated errors. Unknown values should be ignored. -.I ee_type -and -.I ee_code +.B SO_EE_ORIGIN_LOCAL +for locally generated errors. +Unknown values should be ignored. +.I ee_type +and +.I ee_code are set from the type and code fields of the ICMP header. .I ee_info -contains the discovered MTU for -.B EMSGSIZE -errors. The message also contains the +contains the discovered MTU for +.B EMSGSIZE +errors. +The message also contains the .I sockaddr_in of the node -caused the error, which can be accessed with the +caused the error, which can be accessed with the .B SO_EE_OFFENDER -macro. The +macro. +The .I sin_family -field of the SO_EE_OFFENDER address is +field of the SO_EE_OFFENDER address is .I AF_UNSPEC when the source was unknown. -When the error originated from the network, all IP options +When the error originated from the network, all IP options .RI ( IP_OPTIONS ", " IP_TTL ", " -etc.) enabled on the socket and contained in the -error packet are passed as control messages. The payload of the packet +etc.) enabled on the socket and contained in the +error packet are passed as control messages. +The payload of the packet causing the error is returned as normal payload. .\" FIXME . Is it a good idea to document that? It is a dubious feature. -.\" On -.\" .B SOCK_STREAM +.\" On +.\" .B SOCK_STREAM .\" sockets, -.\" .I IP_RECVERR +.\" .I IP_RECVERR .\" has slightly different semantics. Instead of .\" saving the errors for the next timeout, it passes all incoming -.\" errors immediately to the user. +.\" errors immediately to the user. .\" This might be useful for very short-lived TCP connections which -.\" need fast error handling. Use this option with care: +.\" need fast error handling. Use this option with care: .\" it makes TCP unreliable -.\" by not allowing it to recover properly from routing +.\" by not allowing it to recover properly from routing .\" shifts and other normal -.\" conditions and breaks the protocol specification. -Note that TCP has no error queue; -.B MSG_ERRQUEUE +.\" conditions and breaks the protocol specification. +Note that TCP has no error queue; +.B MSG_ERRQUEUE is illegal on -.B SOCK_STREAM -sockets. -.B IP_RECVERR +.B SOCK_STREAM +sockets. +.B IP_RECVERR is valid for TCP, but all errors are -returned by socket function return or -.B SO_ERROR +returned by socket function return or +.B SO_ERROR only. .IP For raw sockets, -.I IP_RECVERR +.I IP_RECVERR enables passing of all received ICMP errors to the application, otherwise errors are only reported on connected sockets .IP -It sets or retrieves an integer boolean flag. +It sets or retrieves an integer boolean flag. .I IP_RECVERR -defaults to off. +defaults to off. .TP .B IP_MTU_DISCOVER Sets or receives the Path MTU Discovery setting -for a socket. When enabled, Linux will perform Path MTU Discovery +for a socket. +When enabled, Linux will perform Path MTU Discovery as defined in RFC\ 1191 -on this socket. The don't fragment flag is set on all outgoing datagrams. -The system-wide default is controlled by the -.B ip_no_pmtu_disc -sysctl for -.B SOCK_STREAM -sockets, and disabled on all others. For non -.B SOCK_STREAM -sockets it is the user's responsibility to packetize the data -in MTU sized chunks and to do the retransmits if necessary. +on this socket. +The don't fragment flag is set on all outgoing datagrams. +The system-wide default is controlled by the +.B ip_no_pmtu_disc +sysctl for +.B SOCK_STREAM +sockets, and disabled on all others. +For non +.B SOCK_STREAM +sockets it is the user's responsibility to packetize the data +in MTU sized chunks and to do the retransmits if necessary. The kernel will reject packets that are bigger than the known path MTU if this flag is set (with .B EMSGSIZE -). +). .TS tab(:); c l @@ -512,32 +534,34 @@ l l. Path MTU discovery flags:Meaning IP_PMTUDISC_WANT:Use per-route settings. IP_PMTUDISC_DONT:Never do Path MTU Discovery. -IP_PMTUDISC_DO:Always do Path MTU Discovery. +IP_PMTUDISC_DO:Always do Path MTU Discovery. IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. -.TE +.TE When PMTU discovery is enabled the kernel automatically keeps track of -the path MTU per destination host. +the path MTU per destination host. When it is connected to a specific peer with .BR connect (2) -the currently known path MTU can be retrieved conveniently using the -.B IP_MTU -socket option (e.g. after a -.B EMSGSIZE -error occurred). It may change over time. -For connectionless sockets with many destinations -the new also MTU for a given destination can also be accessed using the -error queue (see +the currently known path MTU can be retrieved conveniently using the +.B IP_MTU +socket option (e.g. after a +.B EMSGSIZE +error occurred). +It may change over time. +For connectionless sockets with many destinations +the new also MTU for a given destination can also be accessed using the +error queue (see .BR IP_RECVERR ). A new error will be queued for every incoming MTU update. While MTU discovery is in progress initial packets from datagram sockets -may be dropped. Applications using UDP should be aware of this and not +may be dropped. +Applications using UDP should be aware of this and not take it into account for their packet retransmit strategy. To bootstrap the path MTU discovery process on unconnected sockets it is possible to start with a big datagram size -(up to 64K-headers bytes long) and let it shrink by updates of the +(up to 64K-headers bytes long) and let it shrink by updates of the path MTU. .\" FIXME this is an ugly hack @@ -548,65 +572,69 @@ and retrieve the MTU by calling .BR getsockopt (2) with the .B IP_MTU -option. +option. It is possible to implement RFC 4821 MTU probing with .B SOCK_DGRAM of .B SOCK_RAW -sockets by setting a value of +sockets by setting a value of .BR IP_PMTUDISC_PROBE . This is also particularly useful for diagnostic tools such as .BR tracepath (8) -that wish to deliberately send probe packets larger than +that wish to deliberately send probe packets larger than the observed Path MTU. .TP .B IP_MTU -Retrieve the current known path MTU of the current socket. -Only valid when the socket has been connected. Returns an integer. -Only valid as a -.BR getsockopt (2). +Retrieve the current known path MTU of the current socket. +Only valid when the socket has been connected. +Returns an integer. +Only valid as a +.BR getsockopt (2). .\" .TP .B IP_ROUTER_ALERT -Pass all to-be forwarded packets with the -IP Router Alert -option -set to this socket. Only valid for raw sockets. +Pass all to-be forwarded packets with the +IP Router Alert +option +set to this socket. +Only valid for raw sockets. This is useful, for instance, for user -space RSVP daemons. -The tapped packets are not forwarded by the kernel, it is -the users responsibility to send them out again. +space RSVP daemons. +The tapped packets are not forwarded by the kernel, it is +the users responsibility to send them out again. Socket binding is ignored, such packets are only filtered by protocol. -Expects an integer flag. +Expects an integer flag. .\" .TP .B IP_MULTICAST_TTL Set or reads the time-to-live value of outgoing multicast packets for this -socket. It is -very important for multicast packets to set the smallest TTL possible. +socket. +It is very important for multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don't leave the local -network unless the user program explicitly requests it. Argument is an +network unless the user program explicitly requests it. +Argument is an integer. .\" .TP .B IP_MULTICAST_LOOP -Sets or reads a boolean integer argument whether sent multicast +Sets or reads a boolean integer argument whether sent multicast packets should be looped back to the local sockets. .\" .TP .B IP_ADD_MEMBERSHIP -Join a multicast group. Argument is an +Join a multicast group. +Argument is an .I ip_mreqn -structure. +structure. .sp .in +0.25i .nf struct ip_mreqn { - struct in_addr imr_multiaddr; /* IP multicast group + struct in_addr imr_multiaddr; /* IP multicast group address */ - struct in_addr imr_address; /* IP address of local + struct in_addr imr_address; /* IP address of local interface */ int imr_ifindex; /* interface index */ }; @@ -614,60 +642,64 @@ struct ip_mreqn { .in -0.25i .sp .I imr_multiaddr -contains the address of the multicast group the application +contains the address of the multicast group the application wants to join or leave. -It must be a valid multicast address. +It must be a valid multicast address. .I imr_address -is the address of the local interface with which the system +is the address of the local interface with which the system should join the multicast -group; if it is equal to +group; if it is equal to .B INADDR_ANY an appropriate interface is chosen by the system. .I imr_ifindex is the interface index of the interface that should join/leave the -.I imr_multiaddr -group, or 0 to indicate any interface. +.I imr_multiaddr +group, or 0 to indicate any interface. .IP -For compatibility, the old -.I ip_mreq -structure is still supported. It differs from -.I ip_mreqn +For compatibility, the old +.I ip_mreq +structure is still supported. +It differs from +.I ip_mreqn only by not including -the -.I imr_ifindex -field. Only valid as a +the +.I imr_ifindex +field. +Only valid as a .BR setsockopt (2). .\" .TP .B IP_DROP_MEMBERSHIP -Leave a multicast group. Argument is an -.I ip_mreqn -or -.I ip_mreq +Leave a multicast group. +Argument is an +.I ip_mreqn +or +.I ip_mreq structure similar to -.IR IP_ADD_MEMBERSHIP . +.IR IP_ADD_MEMBERSHIP . .\" .TP .B IP_MULTICAST_IF -Set the local device for a multicast socket. Argument is an -.I ip_mreqn -or -.I ip_mreq -structure similar to +Set the local device for a multicast socket. +Argument is an +.I ip_mreqn +or +.I ip_mreq +structure similar to .IR IP_ADD_MEMBERSHIP . .IP When an invalid socket option is passed, .B ENOPROTOOPT -is returned. +is returned. .SH SYSCTLS The IP protocol -supports the sysctl interface to configure some global options. -The sysctls can be accessed by reading or writing the -.I /proc/sys/net/ipv4/* +supports the sysctl interface to configure some global options. +The sysctls can be accessed by reading or writing the +.I /proc/sys/net/ipv4/* files or using the .\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented: .\" ip_queue_maxlen -.\" ip_conntrack_max +.\" ip_conntrack_max .BR sysctl (2) interface. Variables described as @@ -678,12 +710,12 @@ meaning that the option is disabled. .\" .TP .BR ip_always_defrag " (Boolean)" -[New with kernel 2.2.13; in earlier kernel version the feature +[New with kernel 2.2.13; in earlier kernel version the feature was controlled at compile time by the -.B CONFIG_IP_ALWAYS_DEFRAG +.B CONFIG_IP_ALWAYS_DEFRAG option; this file is not present in 2.4.x and later] -When this boolean frag is enabled (not equal 0) incoming fragments +When this boolean frag is enabled (not equal 0) incoming fragments (parts of IP packets that arose when some host between origin and destination decided that the packets were too large and cut them into pieces) will be @@ -692,8 +724,10 @@ about to be forwarded. Only enable if running either a firewall that is the sole link to your network or a transparent proxy; never ever turn on here for a -normal router or host. Otherwise fragmented communication may me disturbed -when the fragments would travel over different links. Defragmentation +normal router or host. +Otherwise fragmented communication may me disturbed +when the fragments would travel over different links. +Defragmentation also has a large memory and CPU time cost. This is automagically turned on when masquerading or transparent @@ -706,50 +740,50 @@ Not documented. .\" .TP .BR ip_default_ttl " (integer; default: 64)" -Set the default time-to-live value of outgoing packets. -This can be changed per socket with the -.I IP_TTL +Set the default time-to-live value of outgoing packets. +This can be changed per socket with the +.I IP_TTL option. .\" .TP .BR ip_dynaddr " (Boolean; default: disabled)" -Enable dynamic socket address and masquerading entry rewriting on interface -address change. +Enable dynamic socket address and masquerading entry rewriting on interface +address change. This is useful for dialup interface with changing IP addresses. 0 means no rewriting, 1 turns it on and 2 enables verbose mode. .\" .TP .BR ip_forward " (Boolean; default: disabled)" -Enable IP forwarding with a boolean flag. -IP forwarding can be also set on a per interface basis. +Enable IP forwarding with a boolean flag. +IP forwarding can be also set on a per interface basis. .\" .TP .BR ip_local_port_range -Contains two integers that define the default local port range -allocated to sockets. +Contains two integers that define the default local port range +allocated to sockets. Allocation starts with the first number and ends with the second number. -Note that these should not conflict with the ports used by masquerading -(although the case is handled). -Also arbitrary choices may cause problems with some firewall packet +Note that these should not conflict with the ports used by masquerading +(although the case is handled). +Also arbitrary choices may cause problems with some firewall packet filters that make assumptions about the local ports in use. -First number should be at least >1024, better >4096 to avoid clashes -with well known ports and to minimize firewall problems. +First number should be at least >1024, better >4096 to avoid clashes +with well known ports and to minimize firewall problems. .\" .TP .BR ip_no_pmtu_disc " (Boolean; default: disabled)" -If enabled, don't do Path MTU Discovery for TCP sockets by default. -Path MTU discovery may fail if misconfigured firewalls (that drop -all ICMP packets) or misconfigured interfaces (e.g., a point-to-point -link where the both ends don't agree on the MTU) are on the path. -It is better to fix the broken routers on the path than to turn off -Path MTU Discovery globally, because not doing it incurs a high cost +If enabled, don't do Path MTU Discovery for TCP sockets by default. +Path MTU discovery may fail if misconfigured firewalls (that drop +all ICMP packets) or misconfigured interfaces (e.g., a point-to-point +link where the both ends don't agree on the MTU) are on the path. +It is better to fix the broken routers on the path than to turn off +Path MTU Discovery globally, because not doing it incurs a high cost to the network. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR ip_nonlocal_bind " (Boolean; default: disabled)" -If set, allows processes to -.BR bind () +If set, allows processes to +.BR bind () to non-local IP addresses, which can be quite useful, but may break some applications. .\" @@ -765,53 +799,55 @@ Regeneration interval (in seconds) of the hash secret (or lifetime for the hash secret) for IPv6 fragments. .TP .BR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)" -If the amount of queued IP fragments reaches +If the amount of queued IP fragments reaches .BR ipfrag_high_thresh , -the queue -is pruned down to -.BR ipfrag_low_thresh . -Contains an integer with the number of +the queue +is pruned down to +.BR ipfrag_low_thresh . +Contains an integer with the number of bytes. .TP .B neigh/* -See -.BR arp (7). -.\" FIXME Document the conf/*/* sysctls +See +.BR arp (7). +.\" FIXME Document the conf/*/* sysctls .\" FIXME Document the route/* sysctls .\" FIXME document them all .SH IOCTLS All ioctls described in -.BR socket (7) +.BR socket (7) apply to ip. .\" 2006-04-02, mtk .\" commented out the following because ipchains is obsolete -.\" .PP +.\" .PP .\" The ioctls to configure firewalling are documented in .\" .BR ipfw (4) -.\" from the -.\" .B ipchains -.\" package. +.\" from the +.\" .B ipchains +.\" package. .PP -Ioctls to configure generic device parameters are described in -.BR netdevice (7). +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 +Be very careful with the .B SO_BROADCAST -option \- it is not privileged in Linux. +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. +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 +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. +for the same task. .PP Some BSD sockets implementations also provide an .I IP_RECVTTL @@ -828,30 +864,30 @@ socket options level isn't portable, BSD-based stacks use .I IPPROTO_IP level. .SH ERRORS -.\" FIXME document all errors. +.\" FIXME document all errors. .\" We should really fix the kernels to give more uniform -.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) +.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) .TP .B ENOTCONN The operation is only defined on a connected socket, but the socket wasn't connected. .TP .B EINVAL -Invalid argument passed. -For send operations this can be caused by sending to a +Invalid argument passed. +For send operations this can be caused by sending to a .I blackhole route. .TP -.B EMSGSIZE +.B EMSGSIZE Datagram is bigger than an MTU on the path and it cannot be fragmented. .TP .B EACCES -The user tried to execute an operation without the necessary permissions. +The user tried to execute an operation without the necessary permissions. These include: -sending a packet to a broadcast address without having the +sending a packet to a broadcast address without having the .B SO_BROADCAST flag set; -sending a packet via a +sending a packet via a .I prohibit route; modifying firewall settings without superuser privileges (the @@ -872,7 +908,7 @@ User doesn't have permission to set high priority, change configuration, or send signals to the requested process or group. .TP .B EADDRNOTAVAIL -A non-existent interface was requested or the requested source +A non-existent interface was requested or the requested source address was not local. .TP @@ -891,30 +927,30 @@ An connection operation on a non-blocking socket is already in progress. .TP .B ECONNABORTED A connection was closed during an -.BR accept (2). +.BR accept (2). .TP .B EPIPE The connection was unexpectedly closed or shut down by the other end. .TP .B ENOENT -.B SIOCGSTAMP +.B SIOCGSTAMP was called on a socket where no packet arrived. .TP .B EHOSTUNREACH -No valid routing table entry matches the destination address. -This error can be caused by a ICMP message from a remote router or +No valid routing table entry matches the destination address. +This error can be caused by a ICMP message from a remote router or for the local routing table. .TP -.B ENODEV +.B ENODEV Network device not available or not capable of sending IP. .TP -.B ENOPKG +.B ENOPKG A kernel subsystem was not configured. .TP .BR ENOBUFS ", " ENOMEM -Not enough free memory. -This often means that the memory allocation is limited by the socket -buffer limits, not by the system memory, but this is not +Not enough free memory. +This often means that the memory allocation is limited by the socket +buffer limits, not by the system memory, but this is not 100% consistent. .PP Other errors may be generated by the overlaying protocols; see @@ -924,9 +960,9 @@ Other errors may be generated by the overlaying protocols; see and .BR socket (7). .SH VERSIONS -.IR IP_MTU , -.IR IP_MTU_DISCOVER , -.IR IP_PKTINFO , +.IR IP_MTU , +.IR IP_MTU_DISCOVER , +.IR IP_PKTINFO , .I IP_RECVERR and .I IP_ROUTER_ALERT @@ -939,25 +975,27 @@ programs intended to be portable. .I IP_PMTUDISC_PROBE is new in Linux 2.6.22. .PP -.I struct ip_mreqn -is new in Linux 2.2. Linux 2.0 only supported +.I struct ip_mreqn +is new in Linux 2.2. +Linux 2.0 only supported .BR ip_mreq . .PP -The sysctls were introduced with Linux 2.2. +The sysctls were introduced with Linux 2.2. .SH COMPATIBILITY -For compatibility with Linux 2.0, the obsolete +For compatibility with Linux 2.0, the obsolete .BI "socket(PF_INET, SOCK_PACKET, " protocol ) -syntax is still supported to open a -.BR packet (7) -socket. This is deprecated and should be replaced by +syntax is still supported to open a +.BR packet (7) +socket. +This is deprecated and should be replaced by .BI "socket(PF_PACKET, SOCK_RAW, " protocol ) -instead. The main difference is the -new -.I sockaddr_ll -address structure for generic link layer information instead of the old +instead. +The main difference is the new +.I sockaddr_ll +address structure for generic link layer information instead of the old .BR sockaddr_pkt . .SH BUGS -There are too many inconsistent error values. +There are too many inconsistent error values. .PP The ioctls to configure IP-specific interface options and ARP tables are not described. @@ -974,7 +1012,7 @@ by .BR recvmsg (2) does not work in some 2.2 kernels. .\" .SH AUTHORS -.\" This man page was written by Andi Kleen. +.\" This man page was written by Andi Kleen. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), diff --git a/man7/ipv6.7 b/man7/ipv6.7 index 8e2fd6542..a9b9395be 100644 --- a/man7/ipv6.7 +++ b/man7/ipv6.7 @@ -10,52 +10,55 @@ ipv6, PF_INET6 \- Linux IPv6 protocol implementation .SH SYNOPSIS .B #include .br -.B #include +.B #include .sp .IB tcp6_socket " = socket(PF_INET6, SOCK_STREAM, 0);" -.br +.br .IB raw6_socket " = socket(PF_INET6, SOCK_RAW, " protocol ");" .br .IB udp6_socket " = socket(PF_INET6, SOCK_DGRAM, " protocol ");" .SH DESCRIPTION -Linux 2.2 optionally implements the Internet Protocol, version 6. -This man page contains a description of the IPv6 basic API as -implemented by the Linux kernel and glibc 2.1. The interface +Linux 2.2 optionally implements the Internet Protocol, version 6. +This man page contains a description of the IPv6 basic API as +implemented by the Linux kernel and glibc 2.1. +The interface is based on the BSD sockets interface; see -.BR socket (7). +.BR socket (7). .PP -The IPv6 API aims to be mostly compatible with the -.BR ip (7) -v4 API. Only differences are described in this man page. +The IPv6 API aims to be mostly compatible with the +.BR ip (7) +v4 API. +Only differences are described in this man page. .PP -To bind an +To bind an .I AF_INET6 -socket to any process the local address should be copied from the +socket to any process the local address should be copied from the .B in6addr_any -variable which has -.I in6_addr +variable which has +.I in6_addr type. -In static initializations +In static initializations .B IN6ADDR_ANY_INIT may also be used, which expands to a constant expression. Both of them are in network order. .PP The IPv6 loopback address (::1) is available in the global .B in6addr_loopback -variable. For initializations +variable. +For initializations .B IN6ADDR_LOOPBACK_INIT should be used. .PP -IPv4 connections can be handled with the v6 API by using the -v4-mapped-on-v6 address type; +IPv4 connections can be handled with the v6 API by using the +v4-mapped-on-v6 address type; thus a program only needs only to support this API type to -support both protocols. +support both protocols. This is handled transparently by the address -handling functions in libc. +handling functions in libc. .PP -IPv4 and IPv6 share the local port space. +IPv4 and IPv6 share the local port space. When you get an IPv4 connection -or packet to a IPv6 socket its source address will be mapped +or packet to a IPv6 socket its source address will be mapped to v6 and it'll be mapped to v6. .SH "ADDRESS FORMAT" .sp @@ -66,7 +69,7 @@ struct sockaddr_in6 { u_int16_t sin6_port; /* port number */ u_int32_t sin6_flowinfo; /* IPv6 flow information */ struct in6_addr sin6_addr; /* IPv6 address */ - u_int32_t sin6_scope_id; /* Scope ID (new in 2.4) */ + u_int32_t sin6_scope_id; /* Scope ID (new in 2.4) */ }; struct in6_addr { @@ -75,20 +78,20 @@ struct in6_addr { .fi .RE .sp -.B sin6_family -is always set to -.BR AF_INET6 ; -.B sin6_port +.B sin6_family +is always set to +.BR AF_INET6 ; +.B sin6_port is the protocol port (see .B sin_port -in +in .BR ip (7)); .B sin6_flowinfo is the IPv6 flow identifier; .B sin6_addr is the 128bit IPv6 address. -.B sin6_scope_id -is an ID of depending of on the scope of the address. +.B sin6_scope_id +is an ID of depending of on the scope of the address. It is new in Linux 2.4. Linux only supports it for link scope addresses, in that case .I sin6_scope_id @@ -96,14 +99,14 @@ contains the interface index (see .BR netdevice (7)) .PP IPv6 supports several address types: unicast to address a single -host, multicast to address a group of hosts, -anycast to address the nearest member of a group of hosts +host, multicast to address a group of hosts, +anycast to address the nearest member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to address a IPv4 host, and other reserved address types. .PP -The address notation for IPv6 is a group of 16 2 digit hexadecimal -numbers, separated with a ':'. '::' stands for a string of 0 bits. -Special addresses are ::1 for loopback and ::FFFF: +The address notation for IPv6 is a group of 16 2 digit hexadecimal +numbers, separated with a ':'. '::' stands for a string of 0 bits. +Special addresses are ::1 for loopback and ::FFFF: for IPv4-mapped-on-IPv6. .PP The port space of IPv6 is shared with IPv4. @@ -112,24 +115,27 @@ IPv6 supports some protocol specific socket options that can be set with .BR setsockopt (2) and read with .BR getsockopt (2). -The socket option level for IPv6 is +The socket option level for IPv6 is .BR IPPROTO_IPV6 . A boolean integer flag is zero when it is false, otherwise true. .TP .B IPV6_ADDRFORM -Turn an +Turn an .I AF_INET6 -socket into a socket of a different address family. Only +socket into a socket of a different address family. +Only .I AF_INET -is currently supported for that. It is only allowed for IPv6 sockets -that are connected and bound to a v4-mapped-on-v6 address. The argument -is a pointer to a integer containing -.BR AF_INET . -This is useful to pass v4-mapped sockets as file descriptors to +is currently supported for that. +It is only allowed for IPv6 sockets +that are connected and bound to a v4-mapped-on-v6 address. +The argument is a pointer to a integer containing +.BR AF_INET . +This is useful to pass v4-mapped sockets as file descriptors to programs that don't know how to deal with the IPv6 API. .TP .B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP -Control membership in multicast groups. Argument is a pointer to a +Control membership in multicast groups. +Argument is a pointer to a .I struct ipv6_mreq structure. .\" FIXME IPV6_CHECKSUM is not documented, and probably should be @@ -138,33 +144,36 @@ structure. .\" FIXME IPV6_V6ONLY is not documented, and probably should be .\" FIXME IPV6_RECVPKTINFO is not documented, and probably should be .\" FIXME IPV6_2292PKTINFO is not documented, and probably should be -.\" FIXME there are probably many other IPV6_* socket options that +.\" FIXME there are probably many other IPV6_* socket options that .\" should be documented .TP .B IPV6_MTU -Set the MTU to be used for the socket. The MTU is limited by the device +Set the MTU to be used for the socket. +The MTU is limited by the device MTU or the path mtu when path mtu discovery is enabled. Argument is a pointer to integer. .TP .B IPV6_MTU_DISCOVER -Control path mtu discovery on the socket. See +Control path mtu discovery on the socket. +See .I IP_MTU_DISCOVER -in +in .BR ip (7) for details. .TP .B IPV6_MULTICAST_HOPS -Set the multicast hop limit for the socket. Argument is a pointer to an -integer. -\-1 in the value means use the route default, otherwise it should be +Set the multicast hop limit for the socket. +Argument is a pointer to an +integer. +\-1 in the value means use the route default, otherwise it should be between 0 and 255. -.TP +.TP .B IPV6_MULTICAST_IF Set the device for outgoing multicast packets on the socket. This is only allowed -for +for .I SOCK_DGRAM -and +and .I SOCK_RAW socket. The argument is an pointer to an interface index (see @@ -174,21 +183,23 @@ in an integer. .B IPV6_MULTICAST_LOOP Control whether the socket sees multicast packets that it has send itself. Argument is a pointer to boolean. -.TP +.TP .B IPV6_PKTINFO -Set delivery of the -.B IPV6_PKTINFO -control message on incoming datagrams. Only allowed for +Set delivery of the +.B IPV6_PKTINFO +control message on incoming datagrams. +Only allowed for .B SOCK_DGRAM or .B SOCK_RAW -sockets. Argument is a pointer to a boolean value in an integer. +sockets. +Argument is a pointer to a boolean value in an integer. .TP .nh .B IPV6_RTHDR, IPV6_AUTHHDR, IPV6_DSTOPS, IPV6_HOPOPTS, IPV6_FLOWINFO, IPV6_HOPLIMIT .hy -Set delivery of control messages for incoming datagrams containing -extension headers from the received packet. +Set delivery of control messages for incoming datagrams containing +extension headers from the received packet. .I IPV6_RTHDR delivers the routing header, .I IPV6_AUTHHDR @@ -196,23 +207,25 @@ delivers the authentication header, .I IPV6_DSTOPTS delivers the destination options, .I IPV6_HOPOPTS -delivers the hop options, +delivers the hop options, .I IPV6_FLOWINFO delivers an integer containing the flow ID, .I IPV6_HOPLIMIT -delivers an integer containing the hop count of the packet. -The control messages have the same type as the socket option. All these -header options can also be set for outgoing packets -by putting the appropriate control message into the control buffer of +delivers an integer containing the hop count of the packet. +The control messages have the same type as the socket option. +All these header options can also be set for outgoing packets +by putting the appropriate control message into the control buffer of .BR sendmsg (2). Only allowed for .B SOCK_DGRAM or .B SOCK_RAW -sockets. Argument is a pointer to a boolean value. +sockets. +Argument is a pointer to a boolean value. .TP .B IPV6_RECVERR -Control receiving of asynchronous error options. See +Control receiving of asynchronous error options. +See .I IP_RECVERR in .BR ip (7) @@ -220,52 +233,56 @@ for details. Argument is a pointer to boolean. .TP .B IPV6_ROUTER_ALERT -Pass all forwarded packets containing an router alert option to +Pass all forwarded packets containing an router alert option to this socket. -Only allowed for datagram sockets and for root. +Only allowed for datagram sockets and for root. Argument is a pointer to boolean. .TP .B IPV6_UNICAST_HOPS -Set the unicast hop limit for the socket. Argument is an pointer to an -integer. \-1 in the value means use the route default, +Set the unicast hop limit for the socket. +Argument is an pointer to an integer. +\-1 in the value means use the route default, otherwise it should be between 0 and 255. .\" FLOWLABEL_MGR, FLOWINFO_SEND .SH VERSIONS -The older +The older .I libinet6 libc5 based IPv6 API implementation for Linux is not described here -and may vary in details. +and may vary in details. .PP -Linux 2.4 will break binary compatibility for the sockaddr_in6 for 64bit +Linux 2.4 will break binary compatibility for the sockaddr_in6 for 64bit hosts by changing the alignment of -.I in6_addr -and adding an additional +.I in6_addr +and adding an additional .I sin6_scope_id -field. The kernel interfaces stay compatible, but a program including -sockaddr_in6 or in6_addr into other structures may not be. This is not +field. +The kernel interfaces stay compatible, but a program including +sockaddr_in6 or in6_addr into other structures may not be. +This is not a problem for 32bit hosts like i386. .PP The .B sin6_flowinfo -field is new in Linux 2.4. It is transparently passed/read by the kernel -when the passed address length contains it. -Some programs that pass a longer address buffer and then +field is new in Linux 2.4. +It is transparently passed/read by the kernel +when the passed address length contains it. +Some programs that pass a longer address buffer and then check the outgoing address length may break. .SH "PORTING NOTES" The .I sockaddr_in6 structure is bigger than the generic -.BR sockaddr . -Programs that assume that all address types can be stored safely in a +.BR sockaddr . +Programs that assume that all address types can be stored safely in a .I struct sockaddr -need to be changed to use +need to be changed to use .I struct sockaddr_storage for that instead. .SH BUGS -The IPv6 extended API as in RFC\ 2292 is currently only partly +The IPv6 extended API as in RFC\ 2292 is currently only partly implemented; although the 2.2 kernel has near complete support for receiving options, -the macros for generating IPv6 options are missing in glibc 2.1. +the macros for generating IPv6 options are missing in glibc 2.1. .PP IPSec support for EH and AH headers is missing. .PP @@ -276,6 +293,7 @@ This man page is not complete. .BR cmsg (3), .BR ip (7) .PP -RFC\ 2553: IPv6 BASIC API. Linux tries to be compliant to this. +RFC\ 2553: IPv6 BASIC API. +Linux tries to be compliant to this. .PP -RFC\ 2460: IPv6 specification. +RFC\ 2460: IPv6 specification. diff --git a/man7/iso_8859-1.7 b/man7/iso_8859-1.7 index c0f574edd..b2180f03c 100644 --- a/man7/iso_8859-1.7 +++ b/man7/iso_8859-1.7 @@ -30,7 +30,8 @@ iso_8859-1 \- the ISO 8859-1 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). Especially important is +character set (also known as ISO 646-IRV). +Especially important is ISO 8859-1, the "Latin Alphabet No. 1", which has become widely implemented and may already be seen as the de-facto standard ASCII replacement. @@ -66,7 +67,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-1 (Latin-1), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-1. .TS l l l c lp-1. diff --git a/man7/iso_8859-15.7 b/man7/iso_8859-15.7 index 9946d305a..110788fcc 100644 --- a/man7/iso_8859-15.7 +++ b/man7/iso_8859-15.7 @@ -28,11 +28,14 @@ iso_8859-15 \- the ISO 8859-15 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). Especially important is +character set (also known as ISO 646-IRV). +Especially important is ISO 8859-1, the "Latin Alphabet No. 1", which has become widely implemented and may already be seen as the de-facto standard ASCII -replacement. However, it lacks the EURO symbol and does not fully -cover Finnish and French. ISO 8859-15 is a modification of ISO 8859-1 +replacement. +However, it lacks the EURO symbol and does not fully +cover Finnish and French. +ISO 8859-15 is a modification of ISO 8859-1 that covers these needs. .P ISO 8859-15 supports the following languages: Albanian, Basque, Breton, @@ -64,7 +67,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-15 (Latin-9), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-15. .TS l l l c lp-1. diff --git a/man7/iso_8859-16.7 b/man7/iso_8859-16.7 index 303f9cad8..f665e4c91 100644 --- a/man7/iso_8859-16.7 +++ b/man7/iso_8859-16.7 @@ -28,13 +28,14 @@ iso_8859-16 \- the ISO 8859-16 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-16, the "Latin +character set (also known as ISO 646-IRV). +ISO 8859-16, the "Latin Alphabet No. 10" is used to encode Central and Eastern European Latin characters and is not implemented yet by any program vendors. .P ISO 8859-16 supports the following languages: Albanian, Bosnian, Croatian, English, Finnish, German, Hungarian, Irish, Polish, -Romanian, Slovenian and Serbian. +Romanian, Slovenian and Serbian. .P Also note that the following Cyrillic-based languages have one-to-one transliterations to Latin 10: Macedonian and Serbian. @@ -62,7 +63,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-16 (Latin-10), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-16. .TS l l l c lp-1. diff --git a/man7/iso_8859-2.7 b/man7/iso_8859-2.7 index 4a859395d..1e2efdf6e 100644 --- a/man7/iso_8859-2.7 +++ b/man7/iso_8859-2.7 @@ -31,7 +31,8 @@ iso_8859-2 \- the ISO 8859-2 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-2, the "Latin +character set (also known as ISO 646-IRV). +ISO 8859-2, the "Latin Alphabet No. 2" is used to encode Central and Eastern European Latin characters and is implemented by several program vendors. .P @@ -65,7 +66,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-2 (Latin-2), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-2. .TS l l l c lp-1. diff --git a/man7/iso_8859-7.7 b/man7/iso_8859-7.7 index 225100480..c9d8f2611 100644 --- a/man7/iso_8859-7.7 +++ b/man7/iso_8859-7.7 @@ -27,7 +27,8 @@ iso_8859-7 \- the ISO 8859-7 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-7 encodes the +character set (also known as ISO 646-IRV). +ISO 8859-7 encodes the characters used in modern monotonic Greek. .SS "ISO 8859 Alphabets" The full set of ISO 8859 alphabets includes: @@ -53,7 +54,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-7, which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-7. .TS l l l c lp-1. diff --git a/man7/iso_8859-9.7 b/man7/iso_8859-9.7 index 9ab429d7b..25be15310 100644 --- a/man7/iso_8859-9.7 +++ b/man7/iso_8859-9.7 @@ -27,7 +27,8 @@ iso_8859-9 \- the ISO 8859-9 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). ISO 8859-9, also known as +character set (also known as ISO 646-IRV). +ISO 8859-9, also known as the "Latin Alphabet No. 5", encodes the characters used in Turkish. .SS "ISO 8859 Alphabets" The full set of ISO 8859 alphabets includes: @@ -53,7 +54,8 @@ ISO 8859-16 Romanian (Latin-10) The following table displays the characters in ISO 8859-9 (Latin-5), which are printable and unlisted in the .BR ascii (7) -manual page. The fourth column will only show the proper glyphs +manual page. +The fourth column will only show the proper glyphs in an environment configured for ISO 8859-9. .TS l l l c lp-1. diff --git a/man7/koi8-r.7 b/man7/koi8-r.7 index 9d1529ef6..ff00ba605 100644 --- a/man7/koi8-r.7 +++ b/man7/koi8-r.7 @@ -29,7 +29,8 @@ koi8-r \- Russian Net Character Set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION KOI8-R is the character set of choice for encoding Russian texts for -many Unix-like operation systems. KOI8-R is a successor for KOI-8, a +many Unix-like operation systems. +KOI8-R is a successor for KOI-8, a de-facto standard for Internet Mail, News, WWW and other interactive services at least all over the ex-SU territory. .PP @@ -38,7 +39,8 @@ Set). .SH NOTE KOI8-R was designed for mixed Russian/English texts and covers only Russian Cyrillic characters, so if you're looking for Ukrainian, -Byelorussian, etc. Cyrillic characters, try ISO-IR-111, or KOI8-U +Byelorussian, etc. +Cyrillic characters, try ISO-IR-111, or KOI8-U (Ukrainian Character Set), or KOI8-C (for ancient Russian texts) instead, which are identical to KOI8-R in the Russian Cyrillic letters area. diff --git a/man7/locale.7 b/man7/locale.7 index a4ff35ae4..29b61155d 100644 --- a/man7/locale.7 +++ b/man7/locale.7 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,7 +16,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -33,9 +33,11 @@ locale \- Description of multi-language support .B #include .fi .SH DESCRIPTION -A locale is a set of language and cultural rules. These cover aspects +A locale is a set of language and cultural rules. +These cover aspects such as language for messages, different character sets, lexicographic -conventions, etc. A program needs to be able to determine its locale +conventions, etc. +A program needs to be able to determine its locale and act accordingly to be portable to different cultures. .PP The header @@ -50,7 +52,8 @@ to set the current locale, and to get information about number formatting. .PP There are different categories for local information a program might -need; they are declared as macros. Using them as the first argument +need; they are declared as macros. +Using them as the first argument to the .BR setlocale () function, it is possible to set one of these to the desired locale: @@ -60,7 +63,8 @@ This is used to change the behaviour of the functions .BR strcoll () and .BR strxfrm (), -which are used to compare strings in the local alphabet. For example, +which are used to compare strings in the local alphabet. +For example, the German sharp s is sorted as "ss". .TP .B LC_CTYPE @@ -78,18 +82,21 @@ or changes the information returned by .BR localeconv () which describes the way numbers are usually printed, with details such -as decimal point versus decimal comma. This information is internally +as decimal point versus decimal comma. +This information is internally used by the function .BR strfmon (). .TP .B LC_MESSAGES changes the language messages are displayed in and how an affirmative or -negative answer looks like. The GNU C-library contains the +negative answer looks like. +The GNU C-library contains the .BR gettext (), .BR ngettext (), and .BR rpmatch () -functions to ease the use of these information. The GNU gettext family of +functions to ease the use of these information. +The GNU gettext family of functions also obey the environment variable .BR LANGUAGE . .TP @@ -98,8 +105,8 @@ changes the information used by the .BR printf () and .BR scanf () -family of functions, when they are advised to use the -locale-settings. This information can also be read with the +family of functions, when they are advised to use the locale-settings. +This information can also be read with the .BR localeconv () function. .TP @@ -107,7 +114,7 @@ function. changes the behaviour of the .BR strftime () function to display the current time in a locally acceptable form; for -example, most of Europe uses a 24\-hour clock versus the +example, most of Europe uses a 24\-hour clock versus the 12\-hour clock used in the United States. .TP .B LC_ALL @@ -150,19 +157,19 @@ struct lconv { /* Numeric (non-monetary) information */ char *decimal_point; /* Radix character */ - char *thousands_sep; /* Separator for digit groups to left + char *thousands_sep; /* Separator for digit groups to left of radix character */ - char *grouping; /* Each element is the number of digits in a - group; elements with higher indices are - further left. An element with value CHAR_MAX - means that no further grouping is done. An - element with value 0 means that the previous + char *grouping; /* Each element is the number of digits in a + group; elements with higher indices are + further left. An element with value CHAR_MAX + means that no further grouping is done. An + element with value 0 means that the previous element is used for all groups further left. */ /* Remaining fields are for monetary information */ - char *int_curr_symbol; /* First three chars are a currency symbol - from ISO 4217. Fourth char is the + char *int_curr_symbol; /* First three chars are a currency symbol + from ISO 4217. Fourth char is the separator. Fifth char is '\0'. */ char *currency_symbol; /* Local currency symbol */ char *mon_decimal_point; /* Radix character */ @@ -172,11 +179,11 @@ struct lconv { char *negative_sign; /* Sign for negative values */ char int_frac_digits; /* Int'l fractional digits */ char frac_digits; /* Local fractional digits */ - char p_cs_precedes; /* 1 if currency_symbol precedes a + char p_cs_precedes; /* 1 if currency_symbol precedes a positive value, 0 if succeeds */ - char p_sep_by_space; /* 1 if a space separates currency_symbol + char p_sep_by_space; /* 1 if a space separates currency_symbol from a positive value */ - char n_cs_precedes; /* 1 if currency_symbol precedes a + char n_cs_precedes; /* 1 if currency_symbol precedes a negative value, 0 if succeeds */ char n_sep_by_space; /* 1 if a space separates currency_symbol from a negative value */ diff --git a/man7/mailaddr.7 b/man7/mailaddr.7 index 1c05ff6cc..5d0570e4b 100644 --- a/man7/mailaddr.7 +++ b/man7/mailaddr.7 @@ -23,14 +23,15 @@ .\" account for changes since 1995. Route-addrs are now even less .\" common, etc. Some minor wording improvements. Same copyright. .\" -.TH MAILADDR 7 2004-09-15 Linux "Linux User's Manual" +.TH MAILADDR 7 2004-09-15 Linux "Linux User's Manual" .UC 5 .SH NAME mailaddr \- mail addressing description .SH DESCRIPTION .nh This manual page gives a brief introduction to SMTP mail addresses, as -used on the Internet. These addresses are in the general format +used on the Internet. +These addresses are in the general format .PP user@domain .PP @@ -43,13 +44,15 @@ These examples are valid forms of the same address: .br eric@monet.berkeley.edu (Eric Allman) .PP -The domain part ("monet.berkeley.edu") is a mail-accepting domain. It -can be a host and in the past it usually was, but it doesn't have to -be. The domain part is not case sensitive. +The domain part ("monet.berkeley.edu") is a mail-accepting domain. +It can be a host and in the past it usually was, but it doesn't have to be. +The domain part is not case sensitive. .PP The local part ("eric") is often a user name, but its meaning is -defined by the local software. Sometimes it is case sensitive, -although that is unusual. If you see a local-part that looks like +defined by the local software. +Sometimes it is case sensitive, +although that is unusual. +If you see a local-part that looks like garbage, it is usually because of a gateway between an internal e-mail system and the net, here are some examples: .PP @@ -66,14 +69,16 @@ internal mail system that lacks proper internet support, an UUCP gateway, and the last one is just boring username policy.) .PP The real-name part ("Eric Allman") can either be placed before -<>, or in () at the end. (Strictly speaking the two aren't the same, -but the difference is beyond the scope of this page.) The name may -have to be quoted using "", e.g. if it contains ".": +<>, or in () at the end. +(Strictly speaking the two aren't the same, +but the difference is beyond the scope of this page.) +The name may have to be quoted using "", e.g. if it contains ".": .PP "Eric P. Allman" .SS Abbreviation. .PP -Many mail systems let users abbreviate the domain name. For instance, +Many mail systems let users abbreviate the domain name. +For instance, users at berkeley.edu may get away with "eric@monet" to send mail to Eric Allman. .I "This behavior is deprecated." @@ -81,23 +86,29 @@ Sometimes it works, but you should not depend on it. .SS Route-addrs. .PP In the past, sometimes one had to route a message through -several hosts to get it to its final destination. Addresses which -show these relays are termed "route-addrs". These use the syntax: +several hosts to get it to its final destination. +Addresses which +show these relays are termed "route-addrs". +These use the syntax: .PP <@hosta,@hostb:user@hostc> .PP This specifies that the message should be sent to hosta, from there -to hostb, and finally to hostc. Many hosts disregard route-addrs +to hostb, and finally to hostc. +Many hosts disregard route-addrs and send directly to hostc. .PP -Route-addrs are very unusual now. They occur sometimes in old mail -archives. It is generally possible to ignore all but the "user@hostc" +Route-addrs are very unusual now. +They occur sometimes in old mail +archives. +It is generally possible to ignore all but the "user@hostc" part of the address to determine the actual address. .SS Postmaster. .PP Every site is required to have a user or user alias designated "postmaster" to which problems with the mail system may be -addressed. The "postmaster" address is not case sensitive. +addressed. +The "postmaster" address is not case sensitive. .SH FILES .I /etc/aliases .br diff --git a/man7/man.7 b/man7/man.7 index e567e0fc6..e660fd3c0 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -52,7 +52,8 @@ macro package (often called the .B man macro package) and related conventions for creating manual (man) pages. This macro package should be used by developers when -writing or porting man pages for Linux. It is fairly compatible with other +writing or porting man pages for Linux. +It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package called mdoc; see @@ -64,7 +65,8 @@ simply by specifying the .B \-mdoc option instead of the .B \-man -option. Using the +option. +Using the .B \-mandoc option is, however, recommended, since this will automatically detect which macro package is in use. @@ -156,16 +158,19 @@ many of which only root can execute. This is an obsolete manual section. Once it was thought a good idea to document the Linux kernel here, but in fact very little has been documented, and the documentation -that exists is outdated already. There are better sources of -information for kernel developers. +that exists is outdated already. +There are better sources of +information for kernel developers. .RE .SH SECTIONS Sections are started with .B \&.SH -followed by the heading name. If the name contains spaces and appears +followed by the heading name. +If the name contains spaces and appears on the same line as .BR \&.SH , -then place the heading in double quotes. Traditional or suggested +then place the heading in double quotes. +Traditional or suggested headings include: NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR HANDLING, ERRORS, @@ -185,8 +190,8 @@ chess \\- the game of chess .sp .RE It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the command name. This -syntax is used by the +backslash before the single dash which follows the command name. +This syntax is used by the .BR makewhatis (8) program to create a database of short command descriptions for the .BR whatis (1) @@ -201,7 +206,8 @@ briefly describes the command or function's interface. For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable -arguments. Brackets ([]) surround optional arguments, vertical bars (|) +arguments. +Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (\&...) can be repeated. For functions, it shows any required data declarations or .B #include @@ -261,7 +267,8 @@ and how they affect it. .TP .B DIAGNOSTICS gives an overview of the most common error messages and how to -cope with them. You don't need to explain system error messages +cope with them. +You don't need to explain system error messages or fatal signals that can appear during execution of any program unless they're special in some way to your program. .TP @@ -323,7 +330,8 @@ usually uses the macro). .IP Any reference to another man page (or to the subject of the current man -page) is in bold. If the manual section number is given, it is given in +page) is in bold. +If the manual section number is given, it is given in Roman (normal) font, without any spaces (e.g., .BR man (7)). .LP @@ -365,9 +373,9 @@ Small (useful for acronyms) Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability's sake). -Arguments are delimited by -spaces. Double quotes can be used to specify an argument which contains -spaces. All of the arguments will be printed next to each other without +Arguments are delimited by spaces. +Double quotes can be used to specify an argument which contains spaces. +All of the arguments will be printed next to each other without intervening spaces, so that the .B \&.BR command can be used to specify a word in bold followed by a mark of @@ -390,7 +398,7 @@ As a result, successive indented paragraphs can use the same indent without re-specifying the indent value. A normal (non-indented) paragraph resets the prevailing indent value to its default value (0.5 inches). -By default a given indent is measured in ens; +By default a given indent is measured in ens; try to use ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are: @@ -453,7 +461,8 @@ a period as the tag; this simplifies translation to other formats. .TP .BI \&.TP " i" -Begin paragraph with hanging tag. The tag is given on the next line, but +Begin paragraph with hanging tag. +The tag is given on the next line, but its results are like those of the .B \&.IP command. @@ -529,7 +538,8 @@ is being used, the macro package's definition of the URL macro will supersede the locally defined one. .PP -A number of other link macros are available. See +A number of other link macros are available. +See .BR groff_www (7) for more details. .SS "Miscellaneous Macros" @@ -575,7 +585,7 @@ Avoid using the various troff preprocessors .BR tbl (1), but try to use the .B IP -and +and .B TP commands instead for two-column tables). Avoid using computations; most other tools can't process them. @@ -653,7 +663,7 @@ macros instead). The condition test .RB ( if,ie ) should only have 't' or 'n' as the condition. -Only translations +Only translations .RB ( tr ) that can be ignored should be used. Font changes @@ -682,10 +692,12 @@ If you include URLs, use the full URL can automatically find the URLs. .PP Tools processing these files should open the file and examine the first -non-whitespace character. A period (.) or single quote (') +non-whitespace character. +A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based -file (such as HTML or Docbook). Anything else suggests simple ASCII +file (such as HTML or Docbook). +Anything else suggests simple ASCII text (e.g., a "catman" result). .PP Many man pages begin with '\e" followed by a space and a list of characters, diff --git a/man7/mdoc.7 b/man7/mdoc.7 index 0c58e806a..4a5f4d8b6 100644 --- a/man7/mdoc.7 +++ b/man7/mdoc.7 @@ -197,7 +197,8 @@ is used. End-display (matches \&.Bd). .It Li \&.Bl Begin-list. -Create lists or columns. Options: +Create lists or columns. +Options: .Bl -tag -width flag -compact .It Ar List-types .Bl -column xbullet -compact diff --git a/man7/mdoc.samples.7 b/man7/mdoc.samples.7 index 9520b84aa..d3e120532 100644 --- a/man7/mdoc.samples.7 +++ b/man7/mdoc.samples.7 @@ -307,7 +307,7 @@ manual .Xr mdoc 7 . This is a technical .Em faux pas -as almost all of the macros in +as almost all of the macros in .Nm \-mdoc are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, @@ -442,7 +442,7 @@ The body of a man page is easily constructed from a basic template found in the file .Pa /usr/share/misc/mdoc.template . Several example man pages can also be found -in +in .Pa /usr/share/examples/mdoc . .Pp .Ss A manual page template @@ -831,7 +831,7 @@ The .Ql \&.An macro is used to specify the name of the author of the item being documented, or the name of the author of the actual manual page. -Any remaining arguments after the name information are assumed +Any remaining arguments after the name information are assumed to be punctuation. .Pp .Dl Usage: .An author_name \*(Pu @@ -1856,7 +1856,7 @@ name macro .Ql \&.Nm is required for sections 1, 5, 6, 7, 8. Section 4 manuals require a -.Ql ".Nm" , +.Ql ".Nm" , .Ql ".Fd" or a .Ql ".Cd" @@ -2371,7 +2371,7 @@ The font-mode must be one of the following three types: .Pp .Bl -tag -width "file file_name " -compact .It Sy \&Em | Fl emphasis -Same as if the +Same as if the .Ql \&.Em macro was used for the entire block of text. .It Sy \&Li | Fl literal diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 index ba59c70b5..fd48c3088 100644 --- a/man7/mq_overview.7 +++ b/man7/mq_overview.7 @@ -11,20 +11,20 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .TH MQ_OVERVIEW 7 2006-02-25 "Linux 2.6.16" "Linux Programmer's Manual" .SH NAME -mq_overview \- Overview of POSIX message queues +mq_overview \- Overview of POSIX message queues .SH DESCRIPTION -POSIX message queues allow processes to exchange data in +POSIX message queues allow processes to exchange data in the form of messages. This API is distinct from that provided by System V message queues .RB ( msgget (2), @@ -38,7 +38,7 @@ this function returns a .I message queue descriptor .RI ( mqd_t ), which is used to refer to the open message queue in later calls. -Each message queue is identified by a name of the form +Each message queue is identified by a name of the form .IR /somename . Two processes can operate on the same queue by passing the same name to .BR mq_open (). @@ -48,39 +48,39 @@ Messages are transferred to and from a queue using and .BR mq_receive (3). When a process has finished using the queue, it closes it using -.BR mq_close (3), +.BR mq_close (3), and when the queue is no longer required, it can be deleted using .BR mq_unlink (3). Queue attributes can be retrieved and (in some cases) modified using .BR mq_getattr (3) and .BR mq_setattr (3). -A process can request asynchronous notification +A process can request asynchronous notification of the arrival of a message on a previously empty queue using .BR mq_notify (3). A message queue descriptor is a reference to an -.IR "open message queue description" -(cf. +.IR "open message queue description" +(cf. .BR open (2)). -After a +After a .BR fork (2), a child inherits copies of its parent's message queue descriptors, -and these descriptors refer to the same open message queue descriptions +and these descriptors refer to the same open message queue descriptions as the corresponding descriptors in the parent. -Corresponding descriptors in the two processes share the flags +Corresponding descriptors in the two processes share the flags .RI ( mq_flags ) that are associated with the open message queue description. -Each message has an associated -.IR priority , -and messages are always delivered to the receiving process +Each message has an associated +.IR priority , +and messages are always delivered to the receiving process highest priority first. -Message priorities range from 0 (low) to +Message priorities range from 0 (low) to .I sysconf(_SC_MQ_PRIO_MAX)\ -\ 1 (high). On Linux, -.I sysconf(_SC_MQ_PRIO_MAX) +.I sysconf(_SC_MQ_PRIO_MAX) returns 32768, but POSIX.1-2001 only requires an implementation to support priorities in the range 0 to 31; some implementations only provide this range. @@ -113,7 +113,7 @@ Glibc support has been provided since version 2.3.4. .SS Kernel configuration Support for POSIX message queues is configurable via the .B CONFIG_POSIX_MQUEUE -kernel configuration option. +kernel configuration option. This option is enabled by default. .SS Persistence POSIX message queues have kernel persistence: @@ -126,11 +126,11 @@ Programs using the POSIX message queue API must be compiled with to link against the real-time library, .IR librt . .SS /proc interfaces -The following interfaces can be used to limit the amount of +The following interfaces can be used to limit the amount of kernel memory consumed by POSIX message queues: .TP .I /proc/sys/fs/mqueue/msg_max -This file can be used to view and change the ceiling value for the +This file can be used to view and change the ceiling value for the maximum number of messages in a queue. This value acts as a ceiling on the .I attr->mq_maxmsg @@ -139,14 +139,14 @@ argument given to The default and minimum value for .I msg_max is 10; the upper limit is HARD_MAX: -.IR "(131072\ /\ sizeof(void\ *))" +.IR "(131072\ /\ sizeof(void\ *))" (32768 on Linux/86). This limit is ignored for privileged processes .RB ( CAP_SYS_RESOURCE ), but the HARD_MAX ceiling is nevertheless imposed. .TP .I /proc/sys/fs/mqueue/msgsize_max -This file can be used to view and change the ceiling on the +This file can be used to view and change the ceiling on the maximum message size. This value acts as a ceiling on the .I attr->mq_msgsize @@ -160,9 +160,9 @@ This limit is ignored for privileged processes .RB ( CAP_SYS_RESOURCE ). .TP .I /proc/sys/fs/mqueue/queues_max -This file can be used to view and change the system-wide limit on the +This file can be used to view and change the system-wide limit on the number of message queues that can be created. -Only privileged processes +Only privileged processes .RB ( CAP_SYS_RESOURCE ) can create new message queues once this limit has been reached. The default value for @@ -171,13 +171,13 @@ is 256; it can be changed to any value in the range 0 to INT_MAX. .SS Resource limit The .BR RLIMIT_MSGQUEUE -resource limit, which places a limit on the amount of space -that can be consumed by all of the message queues -belonging to a process's real user ID, is described in +resource limit, which places a limit on the amount of space +that can be consumed by all of the message queues +belonging to a process's real user ID, is described in .BR getrlimit (2). .SS Mounting the message queue file system On Linux, message queues are created in a virtual file system. -(Other implementations may also provide such a feature, +(Other implementations may also provide such a feature, but the details are likely to differ.) This file system can be mounted using the following commands: .in +0.25i @@ -190,14 +190,14 @@ $ mount -t mqueue none /dev/mqueue .in -0.25i The sticky bit is automatically enabled on the mount directory. -After the file system has been mounted, the message queues on the system +After the file system has been mounted, the message queues on the system can be viewed and manipulated using the commands usually used for files (e.g., .BR ls (1) and .BR rm (1)). -The contents of each file in the directory consist of a single line +The contents of each file in the directory consist of a single line containing information about the queue: .in +0.25i .nf @@ -217,16 +217,16 @@ Number of bytes of data in all messages in the queue. .B NOTIFY_PID If this is non-zero, then the process with this PID has used .BR mq_notify (3) -to register for asynchronous message notification, +to register for asynchronous message notification, and the remaining fields describe how notification occurs. .TP .B NOTIFY Notification method: -0 is +0 is .BR SIGEV_SIGNAL ; 1 is -.BR SIGEV_NONE; -and +.BR SIGEV_NONE; +and 2 is .BR SIGEV_THREAD . .TP @@ -250,8 +250,8 @@ System V message queues .BR msgrcv (2), etc.) are an older API for exchanging messages between processes. POSIX message queues provide a better designed interface than -System V message queues; -on the other hand POSIX message queues are less widely available +System V message queues; +on the other hand POSIX message queues are less widely available (especially on older systems) than System V message queues. .SH EXAMPLE An example of the use of various message queue functions is shown in diff --git a/man7/netdevice.7 b/man7/netdevice.7 index b3ab1d9dc..2b6885174 100644 --- a/man7/netdevice.7 +++ b/man7/netdevice.7 @@ -9,7 +9,7 @@ .\" .\" Modified, 2004-11-25, mtk, formatting and a few wording fixes .\" -.TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" +.TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME netdevice \- Low level access to Linux network devices .SH SYNOPSIS @@ -20,11 +20,11 @@ netdevice \- Low level access to Linux network devices This man page describes the sockets interface which is used to configure network devices. -Linux supports some standard ioctls to configure network devices. -They can be used on any socket's file descriptor regardless of the -family or type. -They pass an -.B ifreq +Linux supports some standard ioctls to configure network devices. +They can be used on any socket's file descriptor regardless of the +family or type. +They pass an +.B ifreq structure: .nf @@ -47,24 +47,26 @@ struct ifreq { }; }; -struct ifconf { +struct ifconf { int ifc_len; /* size of buffer */ - union { - char * ifc_buf; /* buffer address */ + union { + char * ifc_buf; /* buffer address */ struct ifreq * ifc_req; /* array of structures */ - }; -}; + }; +}; .fi Normally, the user specifies which device to affect by setting .B ifr_name -to the name of the interface. All other members of the structure may -share memory. +to the name of the interface. +All other members of the structure may +share memory. .SH IOCTLS If an ioctl is marked as privileged then using it requires an effective user ID of 0 or the .B CAP_NET_ADMIN -capability. If this is not the case +capability. +If this is not the case .B EPERM will be returned. .TP @@ -107,7 +109,7 @@ IFF_AUTOMEDIA:Auto media selection active. IFF_DYNAMIC:T{ The addresses are lost when the interface goes down. T} -.TE +.TE Setting the active flag word is a privileged operation, but any process may read it. .TP @@ -123,7 +125,8 @@ if you attempt to set it. .BR SIOCGIFMTU ", " SIOCSIFMTU Get or set the MTU (Maximum Transfer Unit) of a device using .BR ifr_mtu . -Setting the MTU is a privileged operation. Setting the MTU to +Setting the MTU is a privileged operation. +Setting the MTU to too small values may cause kernel crashes. .TP .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR @@ -131,10 +134,10 @@ Get or set the hardware address of a device using .BR ifr_hwaddr . The hardware address is specified in a struct .IR sockaddr . -.I sa_family -contains the ARPHRD_* device type, +.I sa_family +contains the ARPHRD_* device type, .I sa_data -the L2 hardware address starting from byte 0. +the L2 hardware address starting from byte 0. Setting the hardware address is a privileged operation. .TP .B SIOCSIFHWBROADCAST @@ -151,10 +154,10 @@ Setting the parameters is a privileged operation. struct ifmap { unsigned long mem_start; unsigned long mem_end; - unsigned short base_addr; - unsigned char irq; - unsigned char dma; - unsigned char port; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; }; .fi @@ -176,38 +179,42 @@ Get or set the transmit queue length of a device using Setting the transmit queue length is a privileged operation. .TP .B SIOCSIFNAME -Changes the name of the interface specified in +Changes the name of the interface specified in .BR ifr_name to .BR ifr_newname . -This is a privileged operation. It is only allowed when the interface +This is a privileged operation. +It is only allowed when the interface is not up. .TP .B SIOCGIFCONF -Return a list of interface (transport layer) addresses. This currently -means only addresses of the AF_INET (IPv4) family for compatibility. -The user passes a +Return a list of interface (transport layer) addresses. +This currently +means only addresses of the AF_INET (IPv4) family for compatibility. +The user passes a .B ifconf -structure as argument to the ioctl. It contains a pointer to an array of +structure as argument to the ioctl. +It contains a pointer to an array of .I ifreq -structures in +structures in .B ifc_req -and its length in bytes in +and its length in bytes in .BR ifc_len . The kernel fills the ifreqs with all current L3 interface addresses that -are running: -.I ifr_name -contains the interface name (eth0:1 etc.), +are running: +.I ifr_name +contains the interface name (eth0:1 etc.), .I ifr_addr the address. -The kernel returns with the actual length in +The kernel returns with the actual length in .IR ifc_len . -If +If .I ifc_len is equal to the original length the buffer probably has overflowed and you should retry with a bigger buffer to get all addresses. When no error occurs the ioctl returns 0; -otherwise \-1. Overflow is not an error. +otherwise \-1. +Overflow is not an error. .\" FIXME Slaving isn't supported in 2.2 .\" . .\" .TP @@ -218,30 +225,32 @@ otherwise \-1. Overflow is not an error. .\" .PP .\" FIXME add amateur radio stuff. .PP -Most protocols support their own ioctls to configure protocol specific -interface options. See the protocol man pages for a description. -For configuring IP addresses see +Most protocols support their own ioctls to configure protocol specific +interface options. +See the protocol man pages for a description. +For configuring IP addresses see .BR ip (7). .PP -In addition some devices support private ioctls. +In addition some devices support private ioctls. These are not described here. .SH NOTES Strictly speaking, -.B SIOCGIFCONF -is IP specific and belongs in +.B SIOCGIFCONF +is IP specific and belongs in .BR ip (7). .LP The names of interfaces with no addresses or that don't have the -.B IFF_RUNNING +.B IFF_RUNNING flag set can be found via .IR /proc/net/dev . .LP -Local IPv6 IP addresses can be found via /proc/net or via +Local IPv6 IP addresses can be found via /proc/net or via .BR rtnetlink (7). .SH BUGS -glibc 2.1 is missing the -.I ifr_newname -macro in net/if.h. Add the following to your program as a workaround: +glibc 2.1 is missing the +.I ifr_newname +macro in net/if.h. +Add the following to your program as a workaround: .sp .RS .nf diff --git a/man7/netlink.7 b/man7/netlink.7 index 39aca26e2..a135a0ac5 100644 --- a/man7/netlink.7 +++ b/man7/netlink.7 @@ -27,7 +27,8 @@ There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is only provided for backwards compatibility. -Netlink is a datagram-oriented service. Both +Netlink is a datagram-oriented service. +Both .B SOCK_RAW and .B SOCK_DGRAM @@ -54,7 +55,8 @@ Messages from 1-wire subsystem. Reserved for user-mode socket protocols. .TP .B NETLINK_FIREWALL -Transport IPv4 packets from netfilter to userspace. Used by +Transport IPv4 packets from netfilter to userspace. +Used by .I ip_queue kernel module. .TP @@ -85,7 +87,8 @@ Auditing. Access to FIB lookup from userspace. .TP .B NETLINK_CONNECTOR -Kernel connector. See +Kernel connector. +See .I Documentation/connector/* in the kernel source for further information. .TP @@ -94,7 +97,8 @@ in the kernel source for further information. Netfilter subsystem. .TP .B NETLINK_IP6_FW -Transport IPv6 packets from netfilter to userspace. Used by +Transport IPv6 packets from netfilter to userspace. +Used by .I ip6_queue kernel module. .TP @@ -113,7 +117,8 @@ Netlink messages consist of a byte stream with one or multiple headers and associated payload. The byte stream should only be accessed with the standard .B NLMSG_* -macros. See +macros. +See .BR netlink (3) for further information. @@ -241,14 +246,17 @@ are opaque to netlink core. Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or -other error occurs. For reliable transfer the sender can request an +other error occurs. +For reliable transfer the sender can request an acknowledgement from the receiver by setting the .B NLM_F_ACK -flag. An acknowledgment is an +flag. +An acknowledgment is an .B NLMSG_ERROR packet with the error field set to 0. The application must generate acknowledgements for -received messages itself. The kernel tries to send an +received messages itself. +The kernel tries to send an .B NLMSG_ERROR message for every failed packet. A user process should follow this convention too. diff --git a/man7/packet.7 b/man7/packet.7 index 6ee298553..865782263 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -4,9 +4,9 @@ .\" 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 $ -.TH PACKET 7 1999-04-29 "Linux Man Page" "Linux Programmer's Manual" +.TH PACKET 7 1999-04-29 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -packet, PF_PACKET \- packet interface on device level. +packet, PF_PACKET \- packet interface on device level. .SH SYNOPSIS .nf .B #include @@ -15,70 +15,77 @@ packet, PF_PACKET \- packet interface on device level. .br .B #include /* the L2 protocols */ .sp -.BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol ); +.BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol ); .fi .SH DESCRIPTION Packet sockets are used to receive or send raw packets at the device driver -(OSI Layer 2) -level. They allow the user to implement protocol modules in user space +(OSI Layer 2) level. +They allow the user to implement protocol modules in user space on top of the physical layer. The .I socket_type -is either -.B SOCK_RAW -for raw packets including the link level header or +is either +.B SOCK_RAW +for raw packets including the link level header or .B SOCK_DGRAM -for cooked packets with the link level header removed. The link level -header information is available in a common format in a -.BR sockaddr_ll . -.I protocol -is the IEEE 802.3 protocol number in network order. See the -.I -include file for a list of allowed protocols. When protocol +for cooked packets with the link level header removed. +The link level +header information is available in a common format in a +.BR sockaddr_ll . +.I protocol +is the IEEE 802.3 protocol number in network order. +See the +.I +include file for a list of allowed protocols. +When protocol is set to -.B htons(ETH_P_ALL) +.B htons(ETH_P_ALL) then all protocols are received. All incoming packets of that protocol type will be passed to the packet socket before they are passed to the protocols implemented in the kernel. - + Only processes with effective UID 0 or the .B CAP_NET_RAW -capability may open packet sockets. +capability may open packet sockets. .B SOCK_RAW packets are passed to and from the device driver without any changes in -the packet data. +the packet data. When receiving a packet, the address is still parsed and passed in a standard .B sockaddr_ll -address structure. When transmitting a packet, the user supplied buffer -should contain the physical layer header. That packet is then +address structure. +When transmitting a packet, the user supplied buffer +should contain the physical layer header. +That packet is then queued unmodified to the network driver of the interface defined by the -destination address. Some device drivers always add other headers. +destination address. +Some device drivers always add other headers. .B SOCK_RAW -is similar to but not compatible with the obsolete +is similar to but not compatible with the obsolete .B PF_INET/SOCK_PACKET of Linux 2.0. -.B SOCK_DGRAM -operates on a slightly higher level. -The physical header is removed before the packet is passed to the user. +.B SOCK_DGRAM +operates on a slightly higher level. +The physical header is removed before the packet is passed to the user. Packets sent through a .B SOCK_DGRAM -packet socket get a suitable physical layer header based on the -information in the -.B sockaddr_ll +packet socket get a suitable physical layer header based on the +information in the +.B sockaddr_ll destination address before they are queued. By default all packets of the specified protocol type -are passed to a packet socket. +are passed to a packet socket. To only get packets from a specific interface use .BR bind (2) specifying an address in a .I struct sockaddr_ll -to bind the packet socket to an interface. Only the -.B sll_protocol +to bind the packet socket to an interface. +Only the +.B sll_protocol and the .B sll_ifindex address fields are used for purposes of binding. @@ -93,7 +100,7 @@ flag is passed to .BR recvmsg (2), .BR recv (2), .BR recvfrom (2) -the real length of the packet on the wire is always returned, +the real length of the packet on the wire is always returned, even when it is longer than the buffer. .SH "ADDRESS TYPES" The sockaddr_ll is a device independent physical layer address. @@ -104,30 +111,32 @@ struct sockaddr_ll { unsigned short sll_family; /* Always AF_PACKET */ unsigned short sll_protocol; /* Physical layer protocol */ int sll_ifindex; /* Interface number */ - unsigned short sll_hatype; /* Header type */ + unsigned short sll_hatype; /* Header type */ unsigned char sll_pkttype; /* Packet type */ - unsigned char sll_halen; /* Length of address */ + unsigned char sll_halen; /* Length of address */ unsigned char sll_addr[8]; /* Physical layer address */ }; .fi .in -0.25i -.B sll_protocol +.B sll_protocol is the standard ethernet protocol type in network order as defined in the .I -include file. It defaults to the socket's protocol. -.B sll_ifindex +include file. +It defaults to the socket's protocol. +.B sll_ifindex is the interface index of the interface (see .BR netdevice (7)); -0 matches any interface (only legal for binding). -.B sll_hatype -is a ARP type as defined in the +0 matches any interface (only legal for binding). +.B sll_hatype +is a ARP type as defined in the .I include file. -.B sll_pkttype -contains the packet type. Valid types are +.B sll_pkttype +contains the packet type. +Valid types are .B PACKET_HOST for a packet addressed to the local host, .B PACKET_BROADCAST @@ -139,12 +148,13 @@ for a packet to some other host that has been caught by a device driver in promiscuous mode, and .B PACKET_OUTGOING for a packet originated from the local host that is looped back to a packet -socket. These types make only sense for receiving. +socket. +These types make only sense for receiving. .B sll_addr and .B sll_halen -contain the physical layer (e.g. IEEE 802.3) address and its length. The -exact interpretation depends on the device. +contain the physical layer (e.g. IEEE 802.3) address and its length. +The exact interpretation depends on the device. When you send packets it is enough to specify .BR sll_family , @@ -162,15 +172,16 @@ and .B sll_ifindex are used. .SH "SOCKET OPTIONS" -Packet sockets can be used to configure physical layer multicasting -and promiscuous mode. It works by calling -.BR setsockopt (2) -on a packet socket for SOL_PACKET and one of the options -.B PACKET_ADD_MEMBERSHIP -to add a binding or +Packet sockets can be used to configure physical layer multicasting +and promiscuous mode. +It works by calling +.BR setsockopt (2) +on a packet socket for SOL_PACKET and one of the options +.B PACKET_ADD_MEMBERSHIP +to add a binding or .B PACKET_DROP_MEMBERSHIP to drop it. -They both expect a +They both expect a .B packet_mreq structure as argument: @@ -180,7 +191,7 @@ struct packet_mreq { int mr_ifindex; /* interface index */ unsigned short mr_type; /* action */ unsigned short mr_alen; /* address length */ - unsigned char mr_address[8]; /* physical layer address */ + unsigned char mr_address[8]; /* physical layer address */ }; .fi .in -0.25i @@ -194,35 +205,35 @@ parameter specifies which action to perform. .B PACKET_MR_PROMISC enables receiving all packets on a shared medium (often known as ``promiscuous mode''), -.B PACKET_MR_MULTICAST -binds the socket to the physical layer multicast group specified in +.B PACKET_MR_MULTICAST +binds the socket to the physical layer multicast group specified in .B mr_address and .BR mr_alen , and .B PACKET_MR_ALLMULTI -sets the socket up to receive all multicast packets arriving at -the interface. +sets the socket up to receive all multicast packets arriving at +the interface. -In addition the traditional ioctls +In addition the traditional ioctls .BR SIOCSIFFLAGS , -.BR SIOCADDMULTI , +.BR SIOCADDMULTI , .B SIOCDELMULTI can be used for the same purpose. .SH IOCTLS .B SIOCGSTAMP -can be used to receive the time stamp of the last received packet. -Argument is a +can be used to receive the time stamp of the last received packet. +Argument is a .I struct timeval. In addition all standard ioctls defined in .BR netdevice (7) -and +and .BR socket (7) are valid on packet sockets. .SH "ERROR HANDLING" -Packet sockets do no error handling other than errors occurred -while passing the packet to the device driver. +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 @@ -232,7 +243,7 @@ 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 +to specify an interface, which doesn't provide physical layer independence. .in +0.25i @@ -245,21 +256,21 @@ struct sockaddr_pkt { .fi .in -0.25i -.B spkt_family -contains +.B spkt_family +contains the device type, -.B spkt_protocol +.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. +.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 +For portable programs it is suggested to use .B PF_PACKET -via +via .BR pcap (3); although this only covers a subset of the .B PF_PACKET @@ -267,29 +278,30 @@ 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 +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 +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 +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. +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 -Interface is not up. +Interface is not up. .TP .B ENOTCONN No interface address passed. @@ -298,7 +310,7 @@ No interface address passed. Unknown device name or interface index specified in interface address. .TP .B EMSGSIZE -Packet is bigger than interface MTU. +Packet is bigger than interface MTU. .TP .B ENOBUFS Not enough memory to allocate the packet. @@ -323,11 +335,12 @@ No packet received. In addition other errors may be generated by the low-level driver. .SH VERSIONS -.B PF_PACKET -is a new feature in Linux 2.2. Earlier Linux versions supported only +.B PF_PACKET +is a new feature in Linux 2.2. +Earlier Linux versions supported only .BR SOCK_PACKET . .SH BUGS -glibc 2.1 does not have a define for +glibc 2.1 does not have a define for .BR SOL_PACKET . The suggested workaround is to use: .in +0.5i @@ -339,10 +352,10 @@ The suggested workaround is to use: .fi .in -0.5i -This is fixed in later glibc versions and also does not occur on +This is fixed in later glibc versions and also does not occur on libc5 systems. -The IEEE 802.2/803.3 LLC handling could be considered as a bug. +The IEEE 802.2/803.3 LLC handling could be considered as a bug. Socket filters are not documented. @@ -355,7 +368,8 @@ packets via SOCK_DGRAM. .SH HISTORICAL NOTE The include file .I -is present since glibc2.1. Older systems need +is present since glibc2.1. +Older systems need .sp .nf .B #include @@ -381,6 +395,6 @@ RFC\ 894 for the standard IP Ethernet encapsulation. RFC\ 1700 for the IEEE 802.3 IP encapsulation. -The +The .I include file for physical layer protocols. diff --git a/man7/pipe.7 b/man7/pipe.7 index f2babfafd..0dbba4cbb 100644 --- a/man7/pipe.7 +++ b/man7/pipe.7 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -23,22 +23,22 @@ .SH NAME pipe \- overview of pipes and FIFOs .SH DESCRIPTION -Pipes and FIFOs (also known as named pipes) +Pipes and FIFOs (also known as named pipes) provide a unidirectional interprocess communication channel. -A pipe has a -.I read end -and a +A pipe has a +.I read end +and a .IR "write end" . Data written to the write end of a pipe can be read from the read end of the pipe. -A pipe is created using +A pipe is created using .BR pipe (2), which creates a new pipe and returns two file descriptors, -one referring to the read end of the pipe, +one referring to the read end of the pipe, the other referring to the write end. -Pipes can be used to create a communication channel between related -processes; see +Pipes can be used to create a communication channel between related +processes; see .BR pipe (2) for an example. @@ -46,9 +46,9 @@ A FIFO (short for First In First Out) has a name within the file system (created using .BR mkfifo (3)), and is opened using -.BR open (2). +.BR open (2). Any process may open a FIFO, assuming the file permissions allow it. -The read end is opened using the +The read end is opened using the .B O_RDONLY flag; the write end is opened using the .B O_WRONLY @@ -56,41 +56,41 @@ flag. See .BR fifo (7) for further details. -.IR Note : +.IR Note : although FIFOs have a pathname in the file system, -I/O on FIFOs does not involve operations on the underlying device +I/O on FIFOs does not involve operations on the underlying device (if there is one). .SS "I/O on Pipes and FIFOs" The only difference between pipes and FIFOs is the manner in which -they are created and opened. -Once these tasks have been accomplished, +they are created and opened. +Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same semantics. If a process attempts to read from an empty pipe, then -.BR read (2) +.BR read (2) will block until data is available. If a process attempts to write to a full pipe (see below), then .BR write (2) blocks until sufficient data has been read from the pipe to allow the write to complete. -Non-blocking I/O is possible by using the +Non-blocking I/O is possible by using the .BR fcntl (2) -.B F_SETFL +.B F_SETFL operation to enable the .B O_NONBLOCK open file status flag. The communication channel provided by a pipe is a -.IR "byte stream" : +.IR "byte stream" : there is no concept of message boundaries. -If all file descriptors referring to the write end of a pipe -have been closed, then an attempt to +If all file descriptors referring to the write end of a pipe +have been closed, then an attempt to .BR read (2) from the pipe will see end-of-file .RB ( read (2) will return 0). -If all file descriptors referring to the read end of a pipe +If all file descriptors referring to the read end of a pipe have been closed, then a .BR write (2) will cause a @@ -100,15 +100,15 @@ If the calling process is ignoring this signal, then .BR write (2) fails with the error .BR EPIPE . -An application that uses +An application that uses .BR pipe (2) and .BR fork (2) -should use suitable +should use suitable .BR close (2) calls to close unnecessary duplicate file descriptors; -this ensures that end-of-file and -.BR SIGPIPE / EPIPE +this ensures that end-of-file and +.BR SIGPIPE / EPIPE are delivered when appropriate. It is not possible to apply @@ -119,36 +119,37 @@ A pipe has a limited capacity. If the pipe is full, then a .BR write (2) will block or fail, depending on whether the -.B O_NONBLOCK +.B O_NONBLOCK flag is set (see below). Different implementations have different limits for the pipe capacity. -Applications should not rely on a particular capacity: -an application should be designed so that a reading process consumes data -as soon as it is available, +Applications should not rely on a particular capacity: +an application should be designed so that a reading process consumes data +as soon as it is available, so that a writing process does not remain blocked. -In Linux versions before 2.6.11, the capacity of a pipe was the same as +In Linux versions before 2.6.11, the capacity of a pipe was the same as the system page size (e.g., 4096 bytes on x86). Since Linux 2.6.11, the pipe capacity is 65536 bytes. .SS PIPE_BUF POSIX.1-2001 says that .BR write (2)s -of less than -.B PIPE_BUF -bytes must be atomic: the output data is written to the pipe as a +of less than +.B PIPE_BUF +bytes must be atomic: the output data is written to the pipe as a contiguous sequence. Writes of more than .B PIPE_BUF -bytes may be non-atomic: the kernel may interleave the data +bytes may be non-atomic: the kernel may interleave the data with data written by other processes. -POSIX.1-2001 requires -.B PIPE_BUF -to be at least 512 bytes. (On Linux, -.B PIPE_BUF +POSIX.1-2001 requires +.B PIPE_BUF +to be at least 512 bytes. +(On Linux, +.B PIPE_BUF is 4096 bytes.) The precise semantics depend on whether the file descriptor is non-blocking .RB ( O_NONBLOCK ), -whether there are multiple writers to the pipe, and on +whether there are multiple writers to the pipe, and on .IR n , the number of bytes to be written: .TP @@ -168,7 +169,7 @@ bytes to the pipe, then .BR write (2) succeeds immediately, writing all .I n -bytes; otherwise +bytes; otherwise .BR write (2) fails, with .I errno @@ -176,54 +177,54 @@ set to .BR EAGAIN . .TP \fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP -The write is non-atomic: the data given to -.BR write (2) -may be interleaved with -.BR write (2)s -by other process; +The write is non-atomic: the data given to +.BR write (2) +may be interleaved with +.BR write (2)s +by other process; the .BR write (2) -blocks until +blocks until .I n bytes have been written. .TP \fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP -If the pipe is full, then +If the pipe is full, then .BR write (2) fails, with .I errno set to .BR EAGAIN . Otherwise, from 1 to -.I n +.I n bytes may be written (i.e., a "partial write" may occur; -the caller should check the return value from +the caller should check the return value from .BR write (2) to see how many bytes were actually written), and these bytes may be interleaved with writes by other processes. .SS "Open File Status Flags" -The only open file status flags that can be meaningfully applied to +The only open file status flags that can be meaningfully applied to a pipe or FIFO are .B O_NONBLOCK -and +and .BR O_ASYNC . Setting the .B O_ASYNC -flag for the read end of a pipe causes a signal +flag for the read end of a pipe causes a signal .RB ( SIGIO by default) to be generated when new input becomes available on the pipe (see .BR fcntl (2) for details). On Linux, -.B O_ASYNC +.B O_ASYNC is supported for pipes and FIFOs only since kernel 2.6. .SS "Portability notes" -On some systems (but not Linux), pipes are bidirectional: +On some systems (but not Linux), pipes are bidirectional: data can be transmitted in both directions between the pipe ends. According to POSIX.1-2001, pipes only need to be unidirectional. -Portable applications should avoid reliance on +Portable applications should avoid reliance on bidirectional pipe semantics. .SH "SEE ALSO" .BR dup (2), diff --git a/man7/posixoptions.7 b/man7/posixoptions.7 index e403faa57..3c5000626 100644 --- a/man7/posixoptions.7 +++ b/man7/posixoptions.7 @@ -32,7 +32,8 @@ to test the availability of interfaces at compile time, and functions .BR fpathconf (3), .BR pathconf (3), .BR confstr (3) -to do this at run time. From shell scripts one can use +to do this at run time. +From shell scripts one can use .BR getconf (1). For more detail, see .BR sysconf (3). @@ -132,7 +133,8 @@ is present. .\" .SS "FR" .\" Fortran runtime .SS "--- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING" -This option has been deleted. Not in final XPG6. +This option has been deleted. +Not in final XPG6. .SS "FSC - _POSIX_FSYNC - _SC_FSYNC " The function .IR fsync () @@ -156,20 +158,24 @@ then the system implements POSIX-style job control, and the functions are present. .fi .SS "MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES" -Shared memory is supported. The include file +Shared memory is supported. +The include file .I -is present. The functions +is present. +The functions .IR mmap (), .IR msync (), .IR munmap () are present. .SS "ML - _POSIX_MEMLOCK - _SC_MEMLOCK" -Shared memory can be locked into core. The functions +Shared memory can be locked into core. +The functions .IR mlockall (), .IR munlockall () are present. .SS "MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE" -More precisely, ranges can be locked into core. The functions +More precisely, ranges can be locked into core. +The functions .IR mlock (), .IR munlock () are present. @@ -180,7 +186,8 @@ is present. .SS "MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING" The include file .IR -is present. The functions +is present. +The functions .br .nf .in +4 @@ -210,7 +217,8 @@ Affected functions are .in -4 .fi .SS "--- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS" -This option has been deleted. Not in final XPG6. +This option has been deleted. +Not in final XPG6. .\" .SS "MX" .\" IEC 60559 Floating-Point Option. .SS "--- - _POSIX_NO_TRUNC" @@ -231,7 +239,8 @@ This affects the functions .SS "PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING" The include file .I -is present. The functions +is present. +The functions .br .nf .in +4 @@ -259,11 +268,13 @@ If also _POSIX_SPAWN is in effect, then the functions are present. .fi .SS "RS - _POSIX_RAW_SOCKETS" -Raw sockets are supported. Affected functions are +Raw sockets are supported. +Affected functions are .IR getsockopt (), .IR setsockopt (). .SS "--- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS" -This option implies the _POSIX_THREADS option. Conversely, +This option implies the _POSIX_THREADS option. +Conversely, under POSIX.1-2001 the _POSIX_THREADS option implies this option. .nf The functions @@ -281,7 +292,8 @@ The functions are present. .fi .SS "RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS" -Realtime signals are supported. The functions +Realtime signals are supported. +The functions .br .nf .in +4 @@ -579,7 +591,8 @@ Affected functions are .br .fi .SS "THR - _POSIX_THREADS - _SC_THREADS" -Basic support for POSIX threads is available. The functions +Basic support for POSIX threads is available. +The functions .br .nf .in +4 @@ -670,7 +683,8 @@ The functions .fi are present. .SS "TRC - _POSIX_TRACE - _SC_TRACE" -POSIX tracing is available. The functions +POSIX tracing is available. +The functions .br .nf .in +4 @@ -771,7 +785,8 @@ The functions .fi are present. .SS "--- - _POSIX_VDISABLE" -Always present (probably 0). Value to set a changeable special control +Always present (probably 0). +Value to set a changeable special control character to indicate that it is disabled. .SH "XOPEN EXTENSIONS" .BR _XOPEN_CRYPT , diff --git a/man7/pthreads.7 b/man7/pthreads.7 index 02ad57a50..b4c384a18 100644 --- a/man7/pthreads.7 +++ b/man7/pthreads.7 @@ -137,7 +137,7 @@ latter being the default (if supported by the underlying kernel). .SS LinuxThreads The notable features of this implementation are the following: .IP \- 3 -In addition to the main (initial) thread, +In addition to the main (initial) thread, and the threads that the program creates using .BR pthread_create (), the implementation creates a "manager" thread. @@ -265,7 +265,7 @@ Only the main thread is permitted to start a new session using .IP \- 3 Only the main thread is permitted to make the process into a process group leader using -.BR setpgid (2) +.BR setpgid (2) (fixed in kernel 2.6.16). .IP \- 3 Threads have distinct alternate signal stack settings. @@ -277,7 +277,7 @@ the threads initially share an alternate signal stack Note the following further points about the NPTL implementation: .IP \- 3 If the stack size soft resource limit (see the description of -.B RLIMIT_STACK +.B RLIMIT_STACK in .BR setrlimit (2)) is set to a value other than @@ -286,7 +286,7 @@ then this value defines the default stack size for new threads. To be effective, this limit must be set before the program is executed, perhaps using the .I ulimit -s -shell built-in command +shell built-in command .RI ( "limit stacksize" in the C shell). .SS "Determining the Threading Implementation" diff --git a/man7/pty.7 b/man7/pty.7 index 55f1bd7ca..ea11779b8 100644 --- a/man7/pty.7 +++ b/man7/pty.7 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -23,25 +23,25 @@ .SH NAME pty \- pseudo-terminal interfaces .SH DESCRIPTION -A pseudo-terminal is a pair of virtual character devices that -provide a bidirectional communication channel. -One end of the channel is called the +A pseudo-terminal is a pair of virtual character devices that +provide a bidirectional communication channel. +One end of the channel is called the .IR master ; -the other end is called the +the other end is called the .IR slave . The slave end of the pseudo-terminal provides an interface that behaves exactly like a classical terminal. A process that expects to be connected to a terminal, can open the slave end of a pseudo-terminal and then be driven by a program that has opened the master end. -Anything that is written on the master end is provided to the process -on the slave end as though it was input typed on a terminal. +Anything that is written on the master end is provided to the process +on the slave end as though it was input typed on a terminal. For example, writing the interrupt character (usually control-C) to the master device would cause an interrupt signal (SIGINT) -to be generated for the foreground process group +to be generated for the foreground process group that is connected to the slave. -Conversely, anything that is written to the slave end of the -pseudo-terminal can be read by the process that is connected to +Conversely, anything that is written to the slave end of the +pseudo-terminal can be read by the process that is connected to the master end. Pseudo-terminals are used by applications such as network login services .RB ( ssh "(1), " rlogin "(1), " telnet (1)), @@ -53,30 +53,30 @@ and Historically, two pseudo-terminal APIs have evolved: BSD and System V. SUSv1 standardized a pseudo-terminal API based on the System V API, -and this API should be employed in all new programs that use +and this API should be employed in all new programs that use pseudo-terminals. -Linux provides both BSD-style and (standardised) System V-style +Linux provides both BSD-style and (standardised) System V-style pseudo-terminals. -System V-style terminals are commonly called Unix 98 pseudo-terminals +System V-style terminals are commonly called Unix 98 pseudo-terminals on Linux systems. Since kernel 2.6.4, BSD-style pseudo-terminals are considered deprecated -(they can be disabled when configuring the kernel); +(they can be disabled when configuring the kernel); Unix 98 pseudo-terminals should be used in new applications. .SS "Unix 98 pseudo-terminals" -An unused Unix 98 pseudo-terminal master is opened by calling +An unused Unix 98 pseudo-terminal master is opened by calling .BR posix_openpt (3). (This function opens the master clone device, -.IR /dev/ptmx ; -see +.IR /dev/ptmx ; +see .BR pts (4).) After performing any program-specific initialisations, -changing the ownership and permissions of the slave device using +changing the ownership and permissions of the slave device using .BR grantpt (3), -and unlocking the slave using +and unlocking the slave using .BR unlockpt (3)), the corresponding slave device can be opened by passing -the name returned by +the name returned by .BR ptsname (3) in a call to .BR open (2). @@ -84,10 +84,10 @@ in a call to The Linux kernel imposes a limit on the number of available Unix 98 pseudo-terminals. In kernels up to and including 2.6.3, this limit is configured -at kernel compilation time (CONFIG_UNIX98_PTYS), +at kernel compilation time (CONFIG_UNIX98_PTYS), and the permitted number of pseudo-terminals can be up to 2048, with a default setting of 256. -Since kernel 2.6.4, the limit is dynamically adjustable via +Since kernel 2.6.4, the limit is dynamically adjustable via .IR /proc/sys/kernel/pty/max , and a corresponding file, .IR /proc/sys/kernel/pty/nr , @@ -96,45 +96,45 @@ For further details on these two files, see .BR proc (5). .SS "BSD pseudo-terminals" BSD-style pseudo-terminals are provided as pre-created pairs, with -names of the form +names of the form .I /dev/ptyXY (master) and .I /dev/ttyXY (slave), where X is a letter from the 16-character set [p-za-e], and Y is a letter from the 16-character set [0-9a-f]. -(The precise range of letters in these two sets varies across Unix +(The precise range of letters in these two sets varies across Unix implementations.) For example, .I /dev/ptyp1 and .I /dev/ttyp1 constitute a BSD pseudo-terminal pair. -A process finds an unused pseudo-terminal pair by trying to +A process finds an unused pseudo-terminal pair by trying to .BR open (2) each pseudo-terminal master until an open succeeds. -The corresponding pseudo-terminal slave (substitute "tty" +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 (), +A description of the +.B TIOCPKT +.BR ioctl (), which controls packet mode operation, can be found in .BR tty_ioctl (4). The BSD ioctl()s TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE have not been implemented under Linux. .SH "FILES" -.I /dev/ptmx +.I /dev/ptmx (Unix 98 master clone device) .br .I /dev/pts/* (Unix 98 slave devices) .br -.I /dev/pty[p-za-e][0-9a-f] +.I /dev/pty[p-za-e][0-9a-f] (BSD master devices) .br -.I /dev/tty[p-za-e][0-9a-f] +.I /dev/tty[p-za-e][0-9a-f] (BSD slave devices) .I .SH "SEE ALSO" diff --git a/man7/raw.7 b/man7/raw.7 index f62dd7126..1a4e81e52 100644 --- a/man7/raw.7 +++ b/man7/raw.7 @@ -6,7 +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 $ -.TH RAW 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.TH RAW 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME raw, SOCK_RAW \- Linux IPv4 raw sockets .SH SYNOPSIS @@ -14,10 +14,10 @@ raw, SOCK_RAW \- Linux IPv4 raw sockets .br .B #include .br -.BI "raw_socket = socket(PF_INET, SOCK_RAW, int " protocol ); +.BI "raw_socket = socket(PF_INET, SOCK_RAW, int " protocol ); .SH DESCRIPTION Raw sockets allow new IPv4 protocols to be implemented in user space. -A raw socket receives or sends the raw datagram not +A raw socket receives or sends the raw datagram not including link level headers. The IPv4 layer generates an IP header when sending a packet unless the @@ -26,22 +26,22 @@ socket option is enabled on the socket. When it is enabled, the packet must contain an IP header. For receiving the IP header is always included in the packet. -Only processes with an effective user ID of 0 or the -.B CAP_NET_RAW +Only processes with an effective user ID of 0 or the +.B CAP_NET_RAW capability are allowed to open raw sockets. All packets or errors matching the .I protocol number specified -for the raw socket are passed to this socket. For a list of the -allowed protocols see RFC\ 1700 assigned numbers and +for the raw socket are passed to this socket. +For a list of the allowed protocols see RFC\ 1700 assigned numbers and .BR getprotobyname (3). A protocol of .B IPPROTO_RAW implies enabled -.B IP_HDRINCL -and is able to send any IP protocol that is specified in the passed +.B IP_HDRINCL +and is able to send any IP protocol that is specified in the passed header. Receiving of all IP protocols via .B IPPROTO_RAW @@ -60,10 +60,11 @@ Total Length:Always filled in. .RE .sp .PP -If +If .B IP_HDRINCL is specified and the IP header has a non-zero destination address then -the destination address of the socket is used to route the packet. When +the destination address of the socket is used to route the packet. +When .B MSG_DONTROUTE is specified the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes @@ -74,78 +75,81 @@ If isn't set then IP header options can be set on raw sockets with .BR setsockopt (2); see -.BR ip (7) +.BR ip (7) for more information. In Linux 2.2 all IP header fields and options can be set using -IP socket options. This means raw sockets are usually only needed for new +IP socket options. +This means raw sockets are usually only needed for new 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). +(e.g. kernel protocol modules). .SH "ADDRESS FORMAT" -Raw sockets use the standard -.I sockaddr_in -address structure defined in +Raw sockets use the standard +.I sockaddr_in +address structure defined in .BR ip (7). -The +The .I sin_port -field could be used to specify the IP protocol number, +field could be used to specify the IP protocol number, but it is ignored for sending in Linux 2.2 and should be always set to 0 (see BUGS) -For incoming packets -.I sin_port -is set to the protocol of the packet. +For incoming packets +.I sin_port +is set to the protocol of the packet. See the .I -include file for valid IP protocols. +include file for valid IP protocols. .SH "SOCKET OPTIONS" Raw socket options can be set with .BR setsockopt (2) and read with .BR getsockopt (2) -by passing the +by passing the .B IPPROTO_RAW .\" Or SOL_RAW on Linux -family flag. +family flag. .TP .B ICMP_FILTER -Enable a special filter for raw sockets bound to the -.B IPPROTO_ICMP -protocol. The value has a bit set for each ICMP message type which -should be filtered out. The default is to filter no ICMP messages. +Enable a special filter for raw sockets bound to the +.B IPPROTO_ICMP +protocol. +The value has a bit set for each ICMP message type which +should be filtered out. +The default is to filter no ICMP messages. .PP -In addition all +In addition all .BR ip (7) -.B IPPROTO_IP +.B IPPROTO_IP socket options valid for datagram sockets are supported. .SH NOTES -By default raw sockets do path MTU (Maximum Transmission Unit) discovery. +By default raw sockets do path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return .I EMSGSIZE -when a raw packet write exceeds it. -When this happens the application should decrease the packet size. +when a raw packet write exceeds it. +When this happens the application should decrease the packet size. Path MTU discovery can be also turned off using the .B IP_MTU_DISCOVER -socket option or the +socket option or the .B ip_no_pmtu_disc -sysctl, see -.BR ip(7) -for details. +sysctl, see +.BR ip(7) +for details. When turned off raw sockets will fragment outgoing packets -that exceed the interface MTU. +that exceed the interface MTU. However disabling it is not recommended for performance and reliability reasons. -A raw socket can be bound to a specific local address using the +A raw socket can be bound to a specific local address using the .BR bind (2) -call. +call. If it isn't bound all packets with the specified IP protocol are received. In addition a RAW socket can be bound to a specific network device using .BR SO_BINDTODEVICE ; -see +see .BR socket (7). An @@ -155,56 +159,60 @@ If you really want to receive all IP packets use a .BR packet (7) socket with the .B ETH_P_IP -protocol. Note that packet sockets don't reassemble IP fragments, +protocol. +Note that packet sockets don't reassemble IP fragments, unlike raw sockets. -If you want to receive all ICMP packets for a datagram socket +If you want to receive all ICMP packets for a datagram socket it is often better to use .B IP_RECVERR on that particular socket; see .BR ip (7). Raw sockets may tap all IP protocols in Linux, even -protocols like ICMP or TCP which have a protocol module in the kernel. +protocols like ICMP or TCP which have a protocol module in the kernel. In this case the packets are passed to both the kernel module and the raw -socket(s). -This should not be relied upon in portable programs, many other BSD +socket(s). +This should not be relied upon in portable programs, many other BSD socket implementation have limitations here. -Linux never changes headers passed from the user (except for filling +Linux never changes headers passed from the user (except for filling in some zeroed fields as described for .BR IP_HDRINCL ). This differs from many other implementations of raw sockets. -RAW sockets are generally rather unportable and should be avoided in +RAW sockets are generally rather unportable and should be avoided in programs intended to be portable. -Sending on raw sockets should take the IP protocol from +Sending on raw sockets should take the IP protocol from .IR sin_port ; -this ability was lost in Linux 2.2. +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 +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 +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. +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 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. +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 +User tried to send to a broadcast address without having the broadcast flag set on the socket. .TP .B EPROTO @@ -214,45 +222,45 @@ An ICMP error has arrived reporting a parameter problem. An invalid memory address was supplied. .TP .B EOPNOTSUPP -Invalid flag has been passed to a socket call (like +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 +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. +.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, +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. -When the +When the .B IP_HDRINCL -option is set datagrams will not be fragmented and are limited to -the interface MTU. +option is set datagrams will not be fragmented and are limited to +the interface MTU. Setting the IP protocol for sending in .I sin_port -got lost in Linux 2.2. +got lost in Linux 2.2. The protocol that the socket was bound to or that -was specified in the initial +was specified in the initial .BR socket (2) call is always used. .SH AUTHORS -This man page was written by Andi Kleen. +This man page was written by Andi Kleen. .SH "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), @@ -260,10 +268,10 @@ This man page was written by Andi Kleen. .BR ip (7), .BR socket (7) -.B RFC\ 1191 +.B RFC\ 1191 for path MTU discovery. -.B RFC\ 791 +.B RFC\ 791 and the .I include file for the IP protocol. diff --git a/man7/regex.7 b/man7/regex.7 index 201dfb174..672bfff3e 100644 --- a/man7/regex.7 +++ b/man7/regex.7 @@ -4,24 +4,24 @@ .\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved. .\" This software is not subject to any license of the American Telephone .\" and Telegraph Company or of the Regents of the University of California. -.\" +.\" .\" Permission is granted to anyone to use this software for any purpose .\" on any computer system, and to alter it and redistribute it, subject .\" to the following restrictions: -.\" +.\" .\" 1. The author is not responsible for the consequences of use of this .\" software, no matter how awful, even if they arise from flaws in it. -.\" +.\" .\" 2. The origin of this software must not be misrepresented, either by .\" explicit claim or by omission. Since few users ever read sources, .\" credits must appear in the documentation. -.\" +.\" .\" 3. Altered versions must be plainly marked as such, and must not be .\" misrepresented as being the original software. Since few users .\" ever read sources, credits must appear in the documentation. -.\" +.\" .\" 4. This notice may not be removed or altered. -.\" +.\" .\" In order to comply with `credits must appear in the documentation' .\" I added an AUTHOR paragraph below - aeb. .\" @@ -32,7 +32,7 @@ .\" .ie t .ds dg \(dg .el .ds dg (!) -.TH REGEX 7 1994-02-07 +.TH REGEX 7 1994-02-07 .SH NAME regex \- POSIX.2 regular expressions .SH DESCRIPTION @@ -126,7 +126,7 @@ or a collating-sequence name for either) enclosed in `[.' and `.]' stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. -A bracket expression containing a multi-character collating element +A bracket expression containing a multi-character collating element can thus match more than one character, e.g. if the collating sequence includes a `ch' collating element, then the RE `[[.ch.]]*c' matches the first five characters diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 index 35c5a7080..f21a3490e 100644 --- a/man7/rtnetlink.7 +++ b/man7/rtnetlink.7 @@ -6,9 +6,9 @@ .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" Based on the original comments from Alexey Kuznetsov, written with -.\" help from Matthew Wilcox. +.\" help from Matthew Wilcox. .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ -.TH RTNETLINK 7 1999-04-30 "Linux Man Page" "Linux Programmer's Manual" +.TH RTNETLINK 7 1999-04-30 "Linux Man Page" "Linux Programmer's Manual" .SH NAME rtnetlink, NETLINK_ROUTE \- Linux IPv4 routing socket .SH SYNOPSIS @@ -22,18 +22,19 @@ rtnetlink, NETLINK_ROUTE \- Linux IPv4 routing socket .BI "rtnetlink_socket = socket(PF_NETLINK, int " socket_type ", NETLINK_ROUTE);" .SH DESCRIPTION -Rtnetlink allows the kernel's routing tables to be read and altered. +Rtnetlink allows the kernel's routing tables to be read and altered. It is used within the kernel to communicate between -various subsystems, though this usage is not documented here, and for +various subsystems, though this usage is not documented here, and for communication with user-space programs. Network routes, ip addresses, link parameters, neighbour setups, queueing disciplines, traffic classes and packet classifiers may all be controlled through .B NETLINK_ROUTE -sockets. It is based on netlink messages, see +sockets. +It is based on netlink messages, see .BR netlink (7) -for more information. -.\" FIXME all these macros could be moved to rtnetlink(3) +for more information. +.\" FIXME all these macros could be moved to rtnetlink(3) .SH "ROUTING ATTRIBUTES" Some rtnetlink messages have optional attributes after the initial header: @@ -41,11 +42,11 @@ Some rtnetlink messages have optional attributes after the initial header: struct rtattr { unsigned short rta_len; /* Length of option */ unsigned short rta_type; /* Type of option */ - /* Data follows */ + /* Data follows */ }; .fi -These attributes should be only manipulated using the RTA_* macros +These attributes should be only manipulated using the RTA_* macros or libnetlink, see .BR rtnetlink (3). .SH MESSAGES @@ -53,7 +54,7 @@ Rtnetlink consists of these message types (in addition to standard netlink messages): .TP .BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK -Create, remove or get information about a specific network interface. +Create, remove or get information about a specific network interface. These messages contain an .B ifinfomsg structure followed by a series of @@ -63,7 +64,7 @@ structures. .nf struct ifinfomsg { unsigned char ifi_family; /* AF_UNSPEC */ - unsigned short ifi_type; /* Device type */ + unsigned short ifi_type; /* Device type */ int ifi_index; /* Interface index */ unsigned int ifi_flags; /* Device flags */ unsigned int ifi_change; /* change mask */ @@ -71,13 +72,13 @@ struct ifinfomsg { .fi .\" FIXME ifi_type -.B ifi_flags +.B ifi_flags contains the device flags, see .BR netdevice(7); .B ifi_index is the unique interface index, .B ifi_change -is reserved for future use and should be always set to 0xFFFFFFFF. +is reserved for future use and should be always set to 0xFFFFFFFF. .TS tab(:); c @@ -86,7 +87,7 @@ Routing attributes rta_type:value type:description _ IFLA_UNSPEC:-:unspecified. -IFLA_ADDRESS:hardware address:interface L2 address +IFLA_ADDRESS:hardware address:interface L2 address IFLA_BROADCAST:hardware address:L2 broadcast address. IFLA_IFNAME:asciiz string:Device name. IFLA_MTU:unsigned int:MTU of the device. @@ -98,10 +99,13 @@ T}:Interface Statistics. .TE .TP .BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR -Add, remove or receive information about an IP address associated with -an interface. In Linux 2.2 an interface can carry multiple IP addresses, -this replaces the alias device concept in 2.0. In Linux 2.2 these messages -support IPv4 and IPv6 addresses. They contain an +Add, remove or receive information about an IP address associated with +an interface. +In Linux 2.2 an interface can carry multiple IP addresses, +this replaces the alias device concept in 2.0. +In Linux 2.2 these messages +support IPv4 and IPv6 addresses. +They contain an .B ifaddrmsg structure, optionally followed by .B rtaddr @@ -118,21 +122,21 @@ struct ifaddrmsg { .fi .B ifa_family -is the address family type (currently +is the address family type (currently .B AF_INET or -.BR AF_INET6 ), +.BR AF_INET6 ), .B ifa_prefixlen -is the length of the address mask of the address if defined for the -family (like for IPv4), +is the length of the address mask of the address if defined for the +family (like for IPv4), .B ifa_scope is the address scope, .B ifa_index -is the interface index of the interface the address is associated with. +is the interface index of the interface the address is associated with. .B ifa_flags is a flag word of .B IFA_F_SECONDARY -for secondary address (old alias interface), +for secondary address (old alias interface), .B IFA_F_PERMANENT for a permanent address set by the user and other undocumented flags. @@ -149,7 +153,7 @@ IFA_LOCAL:raw protocol address:local address IFA_LABEL:asciiz string:name of the interface IFA_BROADCAST:raw protocol address:broadcast address. IFA_ANYCAST:raw protocol address:anycast address -IFA_CACHEINFO:struct ifa_cacheinfo:Address information. +IFA_CACHEINFO:struct ifa_cacheinfo:Address information. .TE .\" FIXME struct ifa_cacheinfo .TP @@ -157,18 +161,19 @@ IFA_CACHEINFO:struct ifa_cacheinfo:Address information. Create, remove or receive information about a network route. These messages contain an .B rtmsg -structure with an optional sequence of +structure with an optional sequence of .B rtattr -structures following. For +structures following. +For .B RTM_GETROUTE -setting -.B rtm_dst_len -and -.B rtm_src_len +setting +.B rtm_dst_len +and +.B rtm_src_len to 0 means you get all entries for the specified routing table. -For the other fields except -.B rtm_table -and +For the other fields except +.B rtm_table +and .B rtm_protocol 0 is the wildcard. @@ -176,12 +181,12 @@ and struct rtmsg { unsigned char rtm_family; /* Address family of route */ unsigned char rtm_dst_len; /* Length of source */ - unsigned char rtm_src_len; /* Length of destination */ + unsigned char rtm_src_len; /* Length of destination */ unsigned char rtm_tos; /* TOS filter */ unsigned char rtm_table; /* Routing table ID */ unsigned char rtm_protocol; /* Routing protocol; see below */ - unsigned char rtm_scope; /* See below */ + unsigned char rtm_scope; /* See below */ unsigned char rtm_type; /* See below */ unsigned int rtm_flags; @@ -231,13 +236,14 @@ RTPROT_STATIC:by the administrator Values larger than .B RTPROT_STATIC are not interpreted by the kernel, they are just for user information. -They may be used to tag the source of a routing information or to -distinguish between multiple routing daemons. See +They may be used to tag the source of a routing information or to +distinguish between multiple routing daemons. +See .IR -for the routing daemon identifiers which are already assigned. +for the routing daemon identifiers which are already assigned. -.B rtm_scope -is the distance to the destination: +.B rtm_scope +is the distance to the destination: .TS tab(:); @@ -313,8 +319,9 @@ RTA_CACHEINFO:: .B Fill these values in! .TP .BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH -Add, remove or receive information about a neighbour table -entry (e.g. an ARP entry). The message contains an +Add, remove or receive information about a neighbour table +entry (e.g. an ARP entry). +The message contains an .B ndmsg structure. @@ -322,9 +329,9 @@ structure. struct ndmsg { unsigned char ndm_family; int ndm_ifindex; /* Interface index */ - __u16 ndm_state; /* State */ + __u16 ndm_state; /* State */ __u8 ndm_flags; /* Flags */ - __u8 ndm_type; + __u8 ndm_type; }; struct nda_cacheinfo { @@ -336,7 +343,7 @@ struct nda_cacheinfo { .fi .B ndm_state -is a bitmask of the following states: +is a bitmask of the following states: .TS tab(:); @@ -388,11 +395,13 @@ then a header follows .TP .BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE -Add, delete or retrieve a routing rule. Carries a +Add, delete or retrieve a routing rule. +Carries a .I struct rtmsg .TP .BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC -Add, remove or get a queueing discipline. The message contains a +Add, remove or get a queueing discipline. +The message contains a .I struct tcmsg and may be followed by a series of attributes. @@ -401,7 +410,7 @@ attributes. struct tcmsg { unsigned char tcm_family; int tcm_ifindex; /* interface index */ - __u32 tcm_handle; /* Qdisc handle */ + __u32 tcm_handle; /* Qdisc handle */ __u32 tcm_parent; /* Parent qdisc */ __u32 tcm_info; }; @@ -426,17 +435,18 @@ In addition various other qdisc module specific attributes are allowed. For more information see the appropriate include files. .TP .BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS -Add, remove or get a traffic class. These messages contain a +Add, remove or get a traffic class. +These messages contain a .I struct tcmsg as described above. .TP .BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER -Add, remove or receive information about a traffic filter. These -messages contain a +Add, remove or receive information about a traffic filter. +These messages contain a .I struct tcmsg as described above. .SH VERSIONS -.B rtnetlink +.B rtnetlink is a new feature of Linux 2.2. .SH BUGS This manual page is lacking and incomplete. diff --git a/man7/sem_overview.7 b/man7/sem_overview.7 index 1c4b1253d..6cc2ca5fe 100644 --- a/man7/sem_overview.7 +++ b/man7/sem_overview.7 @@ -11,12 +11,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from -.\" the use of the information contained herein. -.\" +.\" the use of the information contained herein. +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -27,27 +27,27 @@ sem_overview \- Overview of POSIX semaphores POSIX semaphores allow processes and threads to synchronise their actions. A semaphore is an integer whose value is never allowed to fall below zero. -Two operations can be performed on semaphores: -increment the semaphore value by one +Two operations can be performed on semaphores: +increment the semaphore value by one .RB ( sem_post (3)); and decrement the semaphore value by one .RB ( sem_wait (3)). -If the value of a semaphore is currently zero, then a +If the value of a semaphore is currently zero, then a .BR sem_wait (3) operation will block until the value becomes greater than zero. -POSIX semaphores come in two forms: named semaphores and +POSIX semaphores come in two forms: named semaphores and unnamed semaphores. .SS Named semaphores -A named semaphore is identified by a name of the form +A named semaphore is identified by a name of the form .IR /somename . -Two processes can operate on the same named semaphore by passing +Two processes can operate on the same named semaphore by passing the same name to .BR sem_open (3). -The +The .BR sem_open (3) -function creates a new named semaphore or opens an existing +function creates a new named semaphore or opens an existing named semaphore. After the semaphore has been opened, it can be operated on using .BR sem_post (3) @@ -56,20 +56,20 @@ and When a process has finished using the semaphore, it can use .BR sem_close (3) to close the semaphore. -When all processes have finished using the semaphore, +When all processes have finished using the semaphore, it can be removed from the system using .BR sem_unlink (3). .SS Unnamed semaphores (memory-based semaphores) An unnamed semaphore does not have a name. Instead the semaphore is placed in a region of memory that -is shared between multiple threads (a +is shared between multiple threads (a .IR "thread-shared semaphore" ) -or processes (a +or processes (a .IR "process-shared semaphore" ). -A thread-shared semaphore is placed in an area of memory shared +A thread-shared semaphore is placed in an area of memory shared between by the threads of a process, for example, a global variable. -A process-shared semaphore must be placed in a shared memory region -(e.g., a System V shared memory segment created using +A process-shared semaphore must be placed in a shared memory region +(e.g., a System V shared memory segment created using .BR semget (2), or a POSIX shared memory object built created using .BR shm_open (3)). @@ -86,9 +86,9 @@ the semaphore should be destroyed using .BR sem_destroy (3). .SH LINUX SPECIFIC DETAILS .SS Versions -Prior to kernel 2.6, Linux only supported unnamed, +Prior to kernel 2.6, Linux only supported unnamed, thread-shared semaphores. -On a system with Linux 2.6 and a glibc that provides the NPTL +On a system with Linux 2.6 and a glibc that provides the NPTL threading implementation, a complete implementation of POSIX semaphores is provided. .SS Persistence @@ -102,10 +102,10 @@ Programs using the POSIX semaphores API must be compiled with to link against the real-time library, .IR librt . .SS Accessing named semaphores via the file system -On Linux, named semaphores are created in a virtual file system, +On Linux, named semaphores are created in a virtual file system, normally mounted under .IR /dev/shm , -with names of the form +with names of the form .IR \fBsem.\fPname . .SH "CONFORMING TO" POSIX.1-2001. @@ -115,8 +115,8 @@ System V semaphores .BR semop (2), etc.) are an older semaphore API. POSIX semaphores provide a simpler, and better designed interface than -System V semaphores; -on the other hand POSIX semaphores are less widely available +System V semaphores; +on the other hand POSIX semaphores are less widely available (especially on older systems) than System V semaphores. .SH EXAMPLE An example of the use of various POSIX semaphore functions is shown in diff --git a/man7/signal.7 b/man7/signal.7 index 5f3f0e623..83a7d1be1 100644 --- a/man7/signal.7 +++ b/man7/signal.7 @@ -10,7 +10,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -18,7 +18,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -42,9 +42,9 @@ signal \- list of available signals Linux supports both POSIX reliable signals (hereinafter "standard signals") and POSIX real-time signals. .SS "Signal Dispositions" -Each signal has a current +Each signal has a current .IR disposition , -which determines how the process behaves when it is delivered +which determines how the process behaves when it is delivered the signal. The entries in the "Action" column of the tables below specify @@ -65,55 +65,56 @@ A process can change the disposition of a signal using .BR sigaction (2) or (less portably) .BR signal (2). -Using these system calls, a process can elect one of the -following behaviours to occur on delivery of the signal: -perform the default action; ignore the signal; +Using these system calls, a process can elect one of the +following behaviours to occur on delivery of the signal: +perform the default action; ignore the signal; or catch the signal with a -.IR "signal handler" , -a programmer-defined function that is automatically invoked +.IR "signal handler" , +a programmer-defined function that is automatically invoked when the signal is delivered. The signal disposition is a per-process attribute: -in a multithreaded application, the disposition of a +in a multithreaded application, the disposition of a particular signal is the same for all threads. .SS "Signal Mask and Pending Signals" A signal may be .IR blocked , which means that it will not be delivered until it is later unblocked. Between the time when it is generated and when it is delivered -a signal is said to be +a signal is said to be .IR pending . -Each thread in a process has an independent -.IR "signal mask" , +Each thread in a process has an independent +.IR "signal mask" , which indicates the set of signals that the thread is currently blocking. A thread can manipulate its signal mask using .BR pthread_sigmask (3). -In a traditional single-threaded application, +In a traditional single-threaded application, .BR sigprocmask (2) can be used to manipulate the signal mask. A signal may be generated (and thus pending) for a process as a whole (e.g., when sent using -.BR kill (2)) -or for a specific thread (e.g., certain signals, -such as SIGSEGV and SIGFPE, generated as a -consequence of executing a specific machine-language instruction +.BR kill (2)) +or for a specific thread (e.g., certain signals, +such as SIGSEGV and SIGFPE, generated as a +consequence of executing a specific machine-language instruction are thread directed, as are signals targeted at a specific thread using .BR pthread_kill (2)). A process-directed signal may be delivered to any one of the threads that does not currently have the signal blocked. -If more than one of the threads has the signal unblocked, then the +If more than one of the threads has the signal unblocked, then the kernel chooses an arbitrary thread to which to deliver the signal. A thread can obtain the set of signals that it currently has pending using .BR sigpending (2). -This set will consist of the union of the set of pending -process-directed signals and the set of signals pending for +This set will consist of the union of the set of pending +process-directed signals and the set of signals pending for the calling thread. .SS "Standard Signals" -Linux supports the standard signals listed below. Several signal numbers +Linux supports the standard signals listed below. +Several signal numbers are architecture dependent, as indicated in the "Value" column. (Where three values are given, the first one is usually valid for alpha and sparc, the middle one for i386, ppc and sh, and @@ -154,7 +155,7 @@ and .B SIGSTOP cannot be caught, blocked, or ignored. -Next the signals not in the POSIX.1-1990 standard but described in +Next the signals not in the POSIX.1-1990 standard but described in SUSv2 and POSIX.1-2001. .TS l c c l @@ -211,7 +212,7 @@ on a sparc.) .B SIGEMT is not specified in POSIX.1-2001, but nevertheless appears -on most other Unix systems, +on most other Unix systems, where its default action is typically to terminate the process with a core dump. diff --git a/man7/socket.7 b/man7/socket.7 index ed5504197..f2683f2d8 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -1,7 +1,7 @@ '\" t .\" Don't change the first line, it tells man that we need tbl. .\" This man page is Copyright (C) 1999 Andi Kleen . -.\" and copyright (c) 1999 Matthew Wilcox. +.\" and copyright (c) 1999 Matthew Wilcox. .\" Permission is granted to distribute possibly modified copies .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date @@ -13,7 +13,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" A few small grammar fixes -.\" +.\" .\" FIXME probably all PF_* should be AF_* in this page, since .\" POSIX only specifies the latter values. .\" @@ -25,11 +25,12 @@ socket \- Linux socket interface .br .IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol ); .SH DESCRIPTION -This manual page describes the Linux networking socket layer user -interface. The BSD compatible sockets +This manual page describes the Linux networking socket layer user +interface. +The BSD compatible sockets are the uniform interface between the user process and the network protocol stacks in the kernel. -The protocol modules are grouped into +The protocol modules are grouped into .I protocol families like .BR PF_INET ", " PF_IPX ", " PF_PACKET @@ -39,19 +40,19 @@ like .B SOCK_STREAM or .BR SOCK_DGRAM . -See +See .BR socket (2) for more information on families and types. .SH "SOCKET LAYER FUNCTIONS" -These functions are used by the user process to send or receive packets -and to do other socket operations. +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. .BR socket (2) creates a socket, .BR connect (2) connects a socket to a remote socket address, -the +the .BR bind (2) function binds a socket to a local socket address, .BR listen (2) @@ -76,13 +77,13 @@ receive data from a socket. and .BR select (2) wait for arriving data or a readiness to send data. -In addition, the standard I/O operations like +In addition, the standard I/O operations like .BR write (2), .BR writev (2), .BR sendfile (2), .BR read (2), -and -.BR readv (2) +and +.BR readv (2) can be used to read and write data. .PP .BR getsockname (2) @@ -92,37 +93,37 @@ returns the remote socket address. .BR getsockopt (2) and .BR setsockopt (2) -are used to set or get socket layer or protocol options. +are used to set or get socket layer or protocol options. .BR ioctl (2) can be used to set or read some other options. .PP .BR close (2) is used to close a socket. .BR shutdown (2) -closes parts of a full duplex socket connection. +closes parts of a full duplex socket connection. .PP -Seeking, or calling -.BR pread (2) -or +Seeking, or calling +.BR pread (2) +or .BR pwrite (2) with a non-zero position is not supported on sockets. .PP -It is possible to do non-blocking I/O on sockets by setting the +It is possible to do non-blocking I/O on sockets by setting the .B O_NONBLOCK flag on a socket file descriptor using .BR fcntl (2). Then all operations that would block will (usually) return with -.B EAGAIN +.B EAGAIN (operation should be retried later); -.BR connect (2) -will return +.BR connect (2) +will return .B EINPROGRESS -error. +error. The user can then wait for various events via .BR poll (2) or -.BR select (2). +.BR select (2). .TS tab(:) allbox; c s s @@ -130,19 +131,19 @@ l l l. I/O events Event:Poll flag:Occurrence Read:POLLIN:T{ -New data arrived. +New data arrived. T} Read:POLLIN:T{ A connection setup has been completed (for connection-oriented sockets) T} Read:POLLHUP:T{ -A disconnection request has been initiated by the other end. +A disconnection request has been initiated by the other end. T} Read:POLLHUP:T{ -A connection is broken (only for connection-oriented protocols). +A connection is broken (only for connection-oriented protocols). When the socket is written -.B SIGPIPE +.B SIGPIPE is also sent. T} Write:POLLOUT:T{ @@ -160,46 +161,47 @@ T} Read/Write:POLLERR:An asynchronous error occurred. Read/Write:POLLHUP:The other end has shut down one direction. Exception:POLLPRI:T{ -Urgent data arrived. +Urgent data arrived. .B SIGURG is sent then. T} .\" FIXME The following is not true currently: .\" It is no I/O event when the connection -.\" is broken from the local end using +.\" is broken from the local end using .\" .BR shutdown (2) -.\" or +.\" or .\" .BR close (2). .TE .PP -An alternative to +An alternative to .BR poll () and .BR select () is to let the kernel inform the application about events via a .B SIGIO -signal. For that the +signal. +For that the .B FASYNC flag must be set on a socket file descriptor via .BR fcntl (2) -and a valid signal handler for +and a valid signal handler for .B SIGIO -must be installed via -.BR sigaction (2). +must be installed via +.BR sigaction (2). See the .I SIGNALS discussion below. .SH "SOCKET OPTIONS" These socket options can be set by using .BR setsockopt (2) -and read with +and read with .BR getsockopt (2) -with the socket level set to -.B SOL_SOCKET +with the socket level set to +.B SOL_SOCKET for all sockets: -.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in +.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in .\" W R Stevens, UNPv1 .TP .B SO_ACCEPTCONN @@ -209,69 +211,78 @@ to accept connections with The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. Can only be read -with -.BR getsockopt (). +with +.BR getsockopt (). .TP .B SO_BINDTODEVICE Bind this socket to a particular device like \(lqeth0\(rq, -as specified in the passed interface name. If the +as specified in the passed interface name. +If the name is an empty string or the option length is zero, the socket device -binding is removed. The passed option is a variable-length null terminated -interface name string with the maximum size of +binding is removed. +The passed option is a variable-length null terminated +interface name string with the maximum size of .BR IFNAMSIZ . If a socket is bound to an interface, -only packets received from that particular interface are processed by the -socket. Note that this only works for some socket types, particularly +only packets received from that particular interface are processed by the +socket. +Note that this only works for some socket types, particularly .B AF_INET -sockets. It is not supported for packet sockets (use normal +sockets. +It is not supported for packet sockets (use normal .BR bind (8) there). .TP .B SO_BROADCAST -Set or get the broadcast flag. When enabled, datagram sockets -receive packets sent to a broadcast address and they are allowed to send +Set or get the broadcast flag. +When enabled, datagram sockets +receive packets sent to a broadcast address and they are allowed to send packets to a broadcast address. This option has no effect on stream-oriented sockets. .TP .B SO_BSDCOMPAT -Enable BSD bug-to-bug compatibility. +Enable BSD bug-to-bug compatibility. This is used by the UDP protocol module in Linux 2.0 and 2.2. If enabled ICMP errors received for a UDP socket will not be passed -to the user program. +to the user program. In later kernel versions, support for this option has been phased out: Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning (printk()) if a program uses this option. -Linux 2.0 also enabled BSD bug-to-bug compatibility +Linux 2.0 also enabled BSD bug-to-bug compatibility options (random header changing, skipping of the broadcast flag) for raw -sockets with this option, but that was removed in Linux 2.2. +sockets with this option, but that was removed in Linux 2.2. .TP -.B SO_DEBUG -Enable socket debugging. Only allowed for processes with the +.B SO_DEBUG +Enable socket debugging. +Only allowed for processes with the .B CAP_NET_ADMIN capability or an effective user ID of 0. .TP .B SO_ERROR -Get and clear the pending socket error. Only valid as a +Get and clear the pending socket error. +Only valid as a .BR getsockopt (). -Expects an integer. +Expects an integer. .TP .B SO_DONTROUTE Don't send via a gateway, only send to directly connected hosts. -The same effect can be achieved by setting the +The same effect can be achieved by setting the .B MSG_DONTROUTE -flag on a socket +flag on a socket .BR send (2) -operation. Expects an integer boolean flag. +operation. +Expects an integer boolean flag. .TP .B SO_KEEPALIVE -Enable sending of keep-alive messages on connection-oriented sockets. -Expects an integer boolean flag. +Enable sending of keep-alive messages on connection-oriented sockets. +Expects an integer boolean flag. .TP .B SO_LINGER -Sets or gets the -.B SO_LINGER -option. The argument is a -.I linger +Sets or gets the +.B SO_LINGER +option. +The argument is a +.I linger structure. .sp .in +0.25i @@ -283,99 +294,101 @@ struct linger { .fi .in -0.25i .IP -When enabled, a +When enabled, a .BR close (2) or .BR shutdown (2) will not return until all queued messages for the socket have been -successfully sent or the linger timeout has been reached. Otherwise, +successfully sent or the linger timeout has been reached. +Otherwise, the call returns immediately and the closing is done in the background. When the socket is closed as part of .BR exit (2), it always lingers in the background. .TP .B SO_OOBINLINE -If this option is enabled, -out-of-band data is directly placed into the receive data stream. -Otherwise out-of-band data is only passed when the -.B MSG_OOB -flag is set during receiving. +If this option is enabled, +out-of-band data is directly placed into the receive data stream. +Otherwise out-of-band data is only passed when the +.B MSG_OOB +flag is set during receiving. .\" don't document it because it can do too much harm. .\".B SO_NO_CHECK .TP .B SO_PASSCRED Enable or disable the receiving of the .B SCM_CREDENTIALS -control message. For more information see -.BR unix (7). +control message. +For more information see +.BR unix (7). .TP .B SO_PEERCRED -Return the credentials of the foreign process connected to this socket. +Return the credentials of the foreign process connected to this socket. This is only possible for connected -.B PF_UNIX +.B PF_UNIX stream sockets and -.B PF_UNIX +.B PF_UNIX stream and datagram socket pairs created using -.BR socketpair (2); -see -.BR unix (7). +.BR socketpair (2); +see +.BR unix (7). The returned credentials are those that were in effect at the time of the call to .BR connect (2) or .BR socketpair (2). Argument is a -.I ucred -structure. -Only valid as a +.I ucred +structure. +Only valid as a .BR getsockopt (). .TP .B SO_PRIORITY -Set the protocol-defined priority for all packets to be sent on +Set the protocol-defined priority for all packets to be sent on this socket. -Linux uses this value to order the networking queues: -packets with a higher priority may be processed first depending -on the selected device queueing discipline. +Linux uses this value to order the networking queues: +packets with a higher priority may be processed first depending +on the selected device queueing discipline. For .BR ip (7), -this also sets the IP type-of-service (TOS) field for outgoing packets. +this also sets the IP type-of-service (TOS) field for outgoing packets. Setting a priority outside the range 0 to 6 requires the .B CAP_NET_ADMIN capability. .TP .B SO_RCVBUF -Sets or gets the maximum socket receive buffer in bytes. -The kernel doubles this value (to allow space for bookkeeping overhead) +Sets or gets the maximum socket receive buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using .\" Most (all?) other implementations do not do this -- MTK, Dec 05 .BR setsockopt (), and this doubled value is returned by .BR getsockopt (). -The default value is set by the -.B rmem_default -sysctl and the maximum allowed value is set by the +The default value is set by the +.B rmem_default +sysctl and the maximum allowed value is set by the .B rmem_max -sysctl. +sysctl. The minimum (doubled) value for this option is 256. .TP .BR SO_RCVBUFFORCE " (since Linux 2.6.14") Using this socket option, a privileged .RB ( CAP_NET_ADMIN ) -process can perform the same task as +process can perform the same task as .BR SO_RCVBUF , -but the +but the .B rmem_max limit can be overridden. .TP .BR SO_RCVLOWAT " and " SO_SNDLOWAT Specify the minimum number of bytes in the buffer until the socket layer -will pass the data to the protocol -.RB ( SO_SNDLOWAT ) -or the user on receiving +will pass the data to the protocol +.RB ( SO_SNDLOWAT ) +or the user on receiving .RB ( SO_RCVLOWAT ). These two values are initialised to 1. .B SO_SNDLOWAT -is not changeable on Linux +is not changeable on Linux .RB ( setsockopt fails with the error .BR ENOPROTOOPT ). @@ -390,7 +403,7 @@ system calls currently do not respect the .B SO_RCVLOWAT setting on Linux, and mark a socket readable when even a single byte of data is available. -A subsequent read from the socket will block until +A subsequent read from the socket will block until .BR SO_RCVLOWAT bytes are available. .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2 @@ -415,9 +428,10 @@ If the timeout is set to zero (the default) then the operation will never timeout. .TP .B SO_REUSEADDR -Indicates that the rules used in validating addresses supplied in a -.BR bind (2) -call should allow reuse of local addresses. For +Indicates that the rules used in validating addresses supplied in a +.BR bind (2) +call should allow reuse of local addresses. +For .B PF_INET sockets this means that a socket may bind, except when there @@ -427,39 +441,39 @@ When the listening socket is bound to with a specific port then it is not possible to bind to this port for any local address. .TP -.B SO_SNDBUF -Sets or gets the maximum socket send buffer in bytes. -The kernel doubles this value (to allow space for bookkeeping overhead) +.B SO_SNDBUF +Sets or gets the maximum socket send buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using .\" Most (all?) other implementations do not do this -- MTK, Dec 05 .BR setsockopt (), and this doubled value is returned by .BR getsockopt (). -The default value is set by the -.B wmem_default -sysctl and the maximum allowed value is set by the +The default value is set by the +.B wmem_default +sysctl and the maximum allowed value is set by the .B wmem_max -sysctl. +sysctl. The minimum (doubled) value for this option is 2048. .TP .BR SO_SNDBUFFORCE " (since Linux 2.6.14") Using this socket option, a privileged .RB ( CAP_NET_ADMIN ) -process can perform the same task as +process can perform the same task as .BR SO_SNDBUF , -but the +but the .B wmem_max limit can be overridden. .TP .B SO_TIMESTAMP Enable or disable the receiving of the .B SO_TIMESTAMP -control message. +control message. The timestamp control message is sent with level .B SOL_SOCKET -and the -.I cmsg_data -field is a +and the +.I cmsg_data +field is a .I "struct timeval" indicating the reception time of the last packet passed to the user in this call. @@ -468,33 +482,34 @@ See for details on control messages. .TP .B SO_TYPE -Gets the socket type as an integer (like -.BR SOCK_STREAM ). +Gets the socket type as an integer (like +.BR SOCK_STREAM ). Can only be read -with -.BR getsockopt (). +with +.BR getsockopt (). .SH SIGNALS When writing onto a connection-oriented socket that has been shut down -(by the local or the remote end) +(by the local or the remote end) .B SIGPIPE -is sent to the writing process and +is sent to the writing process and .B EPIPE -is returned. +is returned. The signal is not sent when the write call specified the -.B MSG_NOSIGNAL +.B MSG_NOSIGNAL flag. .PP -When requested with the -.B FIOSETOWN +When requested with the +.B FIOSETOWN .BR fcntl () -or -.B SIOCSPGRP +or +.B SIOCSPGRP .BR ioctl (), -.B SIGIO -is sent when an I/O event occurs. It is possible to use +.B SIGIO +is sent when an I/O event occurs. +It is possible to use .BR poll (2) -or +or .BR select (2) in the signal handler to find out which socket the event occurred on. An alternative (in Linux 2.2) is to set a realtime signal using the @@ -503,57 +518,57 @@ An alternative (in Linux 2.2) is to set a realtime signal using the the handler of the real time signal will be called with the file descriptor in the .I si_fd -field of its +field of its .IR siginfo_t . -See +See .BR fcntl (2) for more information. .PP -Under some circumstances (e.g. multiple processes accessing a +Under some circumstances (e.g. multiple processes accessing a single socket), the condition that caused the .B SIGIO may have already disappeared when the process reacts to the signal. -If this happens, the process should wait again because Linux +If this happens, the process should wait again because Linux will resend the signal later. .\" .SH ANCILLARY MESSAGES .SH SYSCTLS -The core socket networking sysctls can be accessed using the -.I /proc/sys/net/core/* -files or with the -.BR sysctl (2) -interface. +The core socket networking sysctls can be accessed using the +.I /proc/sys/net/core/* +files or with the +.BR sysctl (2) +interface. .TP .B rmem_default contains the default setting in bytes of the socket receive buffer. .TP .B rmem_max contains the maximum socket receive buffer size in bytes which a user may -set by using the +set by using the .B SO_RCVBUF -socket option. +socket option. .TP .B wmem_default contains the default setting in bytes of the socket send buffer. .TP .B wmem_max contains the maximum socket send buffer size in bytes which a user may -set by using the +set by using the .B SO_SNDBUF -socket option. +socket option. .TP -.BR message_cost " and " message_burst +.BR message_cost " and " message_burst configure the token bucket filter used to load limit warning messages caused by external network events. .TP -.B netdev_max_backlog +.B netdev_max_backlog Maximum number of packets in the global input queue. .TP .B optmem_max -Maximum length of ancillary data and user control data like the iovecs -per socket. +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 -These operations can be accessed using +These operations can be accessed using .BR ioctl (2): .in +0.25i @@ -563,40 +578,41 @@ These operations can be accessed using .in -0.25i .TP .B SIOCGSTAMP -Return a -.I struct timeval -with the receive timestamp of the last packet passed to the user. -This is useful for accurate round trip time measurements. -See -.BR setitimer (2) -for a description of +Return a +.I struct timeval +with the receive timestamp of the last packet passed to the user. +This is useful for accurate round trip time measurements. +See +.BR setitimer (2) +for a description of .IR "struct timeval" . .\" This ioctl should only be used if the socket option .B SO_TIMESTAMP -is not set on the socket. +is not set on the socket. Otherwise, it returns the timestamp of the last packet that was received while .B SO_TIMESTAMP was not set, or it fails if no such packet has been received, -(i.e., -.BR ioctl () -returns \-1 with -.I errno -set to +(i.e., +.BR ioctl () +returns \-1 with +.I errno +set to .BR ENOENT ). .TP .BR SIOCSPGRP -Set the process or process group to send +Set the process or process group to send .B SIGIO -or +or .B SIGURG -signals +signals to when an asynchronous I/O operation has finished or urgent data is available. -The argument is a pointer to a -.BR pid_t . -If the argument is positive, send the signals to that process. If the +The argument is a pointer to a +.BR pid_t . +If the argument is positive, send the signals to that process. +If the argument is negative, send the signals to the process group with the ID of the absolute value of the argument. The process may only choose itself or its own process group to receive @@ -607,35 +623,35 @@ capability or an effective UID of 0. .B FIOASYNC Change the .B O_ASYNC -flag to enable or disable asynchronous I/O mode of the socket. +flag to enable or disable asynchronous I/O mode of the socket. Asynchronous I/O mode means that the -.B SIGIO -signal or the signal set with +.B SIGIO +signal or the signal set with .B F_SETSIG is raised when a new I/O event occurs. .IP -Argument is an integer boolean flag. +Argument is an integer boolean flag. .\" .TP .BR SIOCGPGRP Get the current process or process group that receives -.B SIGIO -or +.B SIGIO +or .B SIGURG -signals, +signals, or 0 -when none is set. +when none is set. .PP Valid .BR fcntl () operations: .TP -.BR FIOGETOWN -The same as the SIOCGPGRP +.BR FIOGETOWN +The same as the SIOCGPGRP .BR ioctl (). .TP .BR FIOSETOWN -The same as the SIOCSPGRP +The same as the SIOCSPGRP .BR ioctl (). .SH NOTES Linux assumes that half of the send/receive buffer is used for internal @@ -643,33 +659,35 @@ kernel structures; thus the sysctls are twice what can be observed on the wire. Linux will only allow port re-use with the SO_REUSEADDR option -when this option was set both in the previous program that performed a -.BR bind () +when this option was set both in the previous program that performed a +.BR bind () to the port and in the program that wants to re-use the port. This differs from some implementations (e.g., FreeBSD) where only the later program needs to set the SO_REUSEADDR option. Typically this difference is invisible, since, for example, a server program is designed to always set this option. .SH BUGS -The -.B CONFIG_FILTER -socket options -.B SO_ATTACH_FILTER -and -.B SO_DETACH_FILTER -are -not documented. The suggested interface to use them is via the libpcap +The +.B CONFIG_FILTER +socket options +.B SO_ATTACH_FILTER +and +.B SO_DETACH_FILTER +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 +.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 +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. diff --git a/man7/standards.7 b/man7/standards.7 index 1ee8d76ff..80149e2dd 100644 --- a/man7/standards.7 +++ b/man7/standards.7 @@ -1,5 +1,5 @@ .\" Copyright (c) 2006, Michael Kerrisk -.\" includes some material by other authors that was formerly +.\" includes some material by other authors that was formerly .\" in intro.2. .\" .\" This is free documentation; you can redistribute it and/or @@ -26,7 +26,7 @@ .SH NAME Standards \- C and UNIX Standards .SH DESCRIPTION -The +The .B "CONFORMING TO" section that appears in many manual pages identifies various standards to which the documented interface conforms. @@ -34,10 +34,10 @@ The following list briefly describes these standards. .TP .B V7 Version 7, the ancestral UNIX from Bell Labs. -.TP +.TP .B 4.2BSD This is an implementation standard defined by the 4.2 release -of the +of the .IR "Berkeley Software Distribution", released by the University of California at Berkeley. This was the first Berkeley release that contained a TCP/IP @@ -46,10 +46,10 @@ stack and the sockets API. .sp Earlier major BSD releases included \fI3BSD\fP (1980), \fI4BSD\fP (1980), and \fI4.1BSD\fP (1981). -.TP +.TP .B 4.3BSD The successor to 4.2BSD, released in 1986. -.TP +.TP .B 4.4BSD The successor to 4.3BSD, released in 1993. This was the last major Berkeley release. @@ -57,21 +57,21 @@ This was the last major Berkeley release. .B System V This is an implementation standard defined by AT&T's milestone 1983 release of its commercial System V (five) release. -The previous major AT&T release was +The previous major AT&T release was .IR "System III" , released in 1981. .TP .B System V release 2 (SVr2) This was the next System V release, made in 1985. The SVr2 was formally described in the -.IR "System V Interface Definition version 1" +.IR "System V Interface Definition version 1" .RI ( "SVID 1" ) published in 1985. .TP .B System V release 3 (SVr3) This was the successor to SVr2, released in 1986. This release was formally described in the -.IR "System V Interface Definition version 2" +.IR "System V Interface Definition version 2" .RI ( "SVID 2" ). .TP .B System V release 4 (SVr4) @@ -80,48 +80,48 @@ This version of System V is described in the "Programmer's Reference Manual: Operating System API (Intel processors)" (Prentice-Hall 1992, ISBN 0-13-951294-2) This release was formally described in the -.IR "System V Interface Definition version 3" +.IR "System V Interface Definition version 3" .RI ( "SVID 3" ), and is considered the definitive System V release. .TP .B SVID 4 System V Interface Definition version 4, issued in 1995. Available online at http://www.sco.com/developers/devspecs/ . -.TP -.B C89 -This was the first C language standard, ratified by ANSI -(American National Standards Institute) in 1989 +.TP +.B C89 +This was the first C language standard, ratified by ANSI +(American National Standards Institute) in 1989 .RI ( X3.159-1989 ). -Sometimes this is known as -.IR "ANSI C" , +Sometimes this is known as +.IR "ANSI C" , but since C99 is also an ANSI standard, this term is ambiguous. -This standard was also ratified by -ISO (International Standards Organization) in 1990 +This standard was also ratified by +ISO (International Standards Organization) in 1990 .RI ( "ISO/IEC 9899:1990" ), -and is thus occasionally referred to as +and is thus occasionally referred to as .IR "ISO C90" . .TP .B C99 -This revision of the C language standard was ratified by ISO in 1999 +This revision of the C language standard was ratified by ISO in 1999 .RI ( "ISO/IEC 9899:1999" ). .TP .B POSIX.1-1990 "Portable Operating System Interface for Computing Environments". IEEE 1003.1-1990 part 1, ratified by ISO in 1990 .RI ( "ISO/IEC 9945-1:1990" ). -Further information can be found +Further information can be found in Donald Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, Inc., 1991, ISBN 0-937175-73-0). The term "POSIX" was coined by Richard Stallman. -.TP +.TP .B POSIX.2 -IEEE Std 1003.2-1992, +IEEE Std 1003.2-1992, describing commands and utilities, ratified by ISO in 1993 .RI ( "ISO/IEC 9945-2:1993" ). .TP .BR POSIX.1b " (formerly known as \fIPOSIX.4\fP)" -IEEE Std 1003.1b-1993 +IEEE Std 1003.1b-1993 describing real-time facilities for portable operating systems, ratified by ISO in 1996 .RI ( "ISO/IEC 9945-1:1996" ). @@ -158,13 +158,13 @@ A revision of the X/Open Portability Guide, released in 1992. A 1994 revision of XPG4. This is also referred to as .IR "Spec 1170" , -where 1170 referred to the number of interfaces +where 1170 referred to the number of interfaces defined by this standard. .TP .B SUS (SUSv1) Single UNIX Specification. This was a repackaging of XPG4v2 and other X/Open standards -(X/Open Curses Issue 4 version 2, +(X/Open Curses Issue 4 version 2, X/Open Networking Service (XNS) Issue 4). Systems conforming to this standard can be branded .IR "UNIX 95" . @@ -180,22 +180,22 @@ See also http://www.UNIX-systems.org/version2/ .) .TP .B POSIX.1-2001, SUSv3 -This was a 2001 revision and consolidation of the -POSIX.1, POSIX.2, and SUS standards into a single document, +This was a 2001 revision and consolidation of the +POSIX.1, POSIX.2, and SUS standards into a single document, conducted under the auspices of the Austin group -(http://www.opengroup.org/austin/ .) -The standard is available online at -http://www.unix-systems.org/version3/ , -and the interfaces that it describes are also available in the Linux +(http://www.opengroup.org/austin/ .) +The standard is available online at +http://www.unix-systems.org/version3/ , +and the interfaces that it describes are also available in the Linux manual pages package under sections 1p and 3p (e.g., "man 3p open"). .sp -The standard defines two levels of conformance: +The standard defines two levels of conformance: .IR "POSIX conformance" , -which is a baseline set of interfaces required of a conforming system; +which is a baseline set of interfaces required of a conforming system; and -.IR "XSI Conformance", +.IR "XSI Conformance", which additionally mandates a set of interfaces -(the "XSI extension") which are only optional for POSIX conformance. +(the "XSI extension") which are only optional for POSIX conformance. XSI-conformant systems can be branded .IR "UNIX 03" . (XSI conformance constitutes the @@ -208,7 +208,7 @@ The POSIX.1-2001 document is broken into four parts: Definitions, terms and concepts, header file specifications. .sp .BR XSH : -Specifications of functions (i.e., system calls and library +Specifications of functions (i.e., system calls and library functions in actual implementations). .sp .BR XCU : @@ -222,11 +222,11 @@ POSIX.1-2001 is aligned with C99, so that all of the library functions standardised in C99 are also standardised in POSIX.1-1001. .sp -Two Technical Corrigenda (minor fixes and improvements) +Two Technical Corrigenda (minor fixes and improvements) of the original 2001 standard have occurred: -TC1 in 2003 (referred to as -.IR POSIX.1-2003 ), -and TC2 in 2004 (referred to as +TC1 in 2003 (referred to as +.IR POSIX.1-2003 ), +and TC2 in 2004 (referred to as .IR POSIX.1-2004 ). .SH "SEE ALSO" .BR feature_test_macros (7) diff --git a/man7/suffixes.7 b/man7/suffixes.7 index 9fd42395b..d5dbfff20 100644 --- a/man7/suffixes.7 +++ b/man7/suffixes.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. @@ -36,16 +36,17 @@ suffixes \- list of file suffixes .SH DESCRIPTION It is customary to indicate the contents of a file with the file suffix, -which consists of a period, followed by one or more letters. Many -standard utilities, such as compilers, use this to recognize the type of -file they are dealing with. The +which consists of a period, followed by one or more letters. +Many standard utilities, such as compilers, use this to recognize the type of +file they are dealing with. +The .BR make (1) utility is driven by rules based on file suffix. .PP Following is a list of suffixes which are likely to be found on a Linux system. .PP -.TS +.TS l | l _ | _ lI | l . diff --git a/man7/svipc.7 b/man7/svipc.7 index 1aeca8fef..5f3e80ad6 100644 --- a/man7/svipc.7 +++ b/man7/svipc.7 @@ -8,7 +8,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -16,13 +16,13 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" -.\" FIXME There is now duplication of some of the information +.\" FIXME There is now duplication of some of the information .\" below in semctl.2, msgctl.2, and shmctl.2 -- MTK, Nov 04 -.TH SVIPC 7 1993-11-01 "Linux 0.99.13" "Linux Programmer's Manual" +.TH SVIPC 7 1993-11-01 "Linux 0.99.13" "Linux Programmer's Manual" .SH NAME svipc \- System V interprocess communication mechanisms .SH SYNOPSIS @@ -56,15 +56,15 @@ structure, defined by the system header file, includes the following members: .sp .B - uid_t cuid; + uid_t cuid; /* creator user ID */ .br .B - gid_t cgid; + gid_t cgid; /* creator group ID */ .br .B - uid_t uid; + uid_t uid; /* owner user ID */ .br .B diff --git a/man7/tcp.7 b/man7/tcp.7 index 82d5fdf5c..1adfaba4d 100644 --- a/man7/tcp.7 +++ b/man7/tcp.7 @@ -7,12 +7,12 @@ .\" 2.4 Updates by Nivedita Singhvi 4/20/02 . .\" Modified, 2004-11-11, Michael Kerrisk and Andries Brouwer .\" Updated details of interaction of TCP_CORK and TCP_NODELAY. -.\" +.\" .\" FIXME 2.6.17-rc1 adds the following /proc files, which need to be .\" documented: tcp_mtu_probing, tcp_base_mss, and .\" tcp_workaround_signed_windows .\" -.TH TCP 7 2005-06-15 "Linux Man Page" "Linux Programmer's Manual" +.TH TCP 7 2005-06-15 "Linux Man Page" "Linux Programmer's Manual" .SH NAME tcp \- TCP protocol .SH SYNOPSIS @@ -22,141 +22,153 @@ tcp \- TCP protocol .br .B #include .br -.B tcp_socket = socket(PF_INET, SOCK_STREAM, 0); +.B tcp_socket = socket(PF_INET, SOCK_STREAM, 0); .SH DESCRIPTION This is an implementation of the TCP protocol defined in RFC\ 793, RFC\ 1122 and RFC\ 2001 with the NewReno and SACK -extensions. It provides a reliable, stream-oriented, +extensions. +It provides a reliable, stream-oriented, full-duplex connection between two sockets on top of .BR ip (7), for both v4 and v6 versions. TCP guarantees that the data arrives in order and retransmits lost packets. -It generates and checks a per-packet checksum to catch +It generates and checks a per-packet checksum to catch transmission errors. TCP does not preserve record boundaries. A newly created TCP socket has no remote or local address and is not -fully specified. To create an outgoing TCP connection use +fully specified. +To create an outgoing TCP connection use .BR connect (2) to establish a connection to another TCP socket. To receive new incoming connections, first -.BR bind (2) -the socket to a local address and port and then call +.BR bind (2) +the socket to a local address and port and then call .BR listen (2) -to put the socket into the listening state. After that a new -socket for each incoming connection can be accepted +to put the socket into the listening state. +After that a new +socket for each incoming connection can be accepted using .BR accept (2). A socket which has had .BR accept () -or +or .BR connect () successfully called on it is fully specified and may -transmit data. Data cannot be transmitted on listening or +transmit data. +Data cannot be transmitted on listening or not yet connected sockets. Linux supports RFC\ 1323 TCP high performance -extensions. These include Protection Against Wrapped -Sequence Numbers (PAWS), Window Scaling and -Timestamps. Window scaling allows the use -of large (> 64K) TCP windows in order to support links with high -latency or bandwidth. To make use of them, the send and -receive buffer sizes must be increased. +extensions. +These include Protection Against Wrapped +Sequence Numbers (PAWS), Window Scaling and +Timestamps. +Window scaling allows the use +of large (> 64K) TCP windows in order to support links with high +latency or bandwidth. +To make use of them, the send and +receive buffer sizes must be increased. They can be set globally with the .B net.ipv4.tcp_wmem and .B net.ipv4.tcp_rmem -sysctl variables, or on individual sockets by using the -.B SO_SNDBUF -and -.B SO_RCVBUF -socket options with the +sysctl variables, or on individual sockets by using the +.B SO_SNDBUF +and +.B SO_RCVBUF +socket options with the .BR setsockopt (2) call. The maximum sizes for socket buffers declared via the .B SO_SNDBUF -and -.B SO_RCVBUF +and +.B SO_RCVBUF mechanisms are limited by the global .B net.core.rmem_max and .B net.core.wmem_max -sysctls. Note that TCP actually allocates twice the size of +sysctls. +Note that TCP actually allocates twice the size of the buffer requested in the .BR setsockopt (2) -call, and so a succeeding -.BR getsockopt (2) +call, and so a succeeding +.BR getsockopt (2) call will not return the same size of buffer as requested -in the -.BR setsockopt (2) -call. +in the +.BR setsockopt (2) +call. TCP uses the extra space for administrative purposes and internal kernel structures, and the sysctl variables reflect the -larger sizes compared to the actual TCP windows. +larger sizes compared to the actual TCP windows. On individual connections, the socket buffer size must be set prior to the .BR listen () -or +or .BR connect () -calls in order to have it take effect. See +calls in order to have it take effect. +See .BR socket (7) -for more information. -.PP -TCP supports urgent data. Urgent data is used to signal the +for more information. +.PP +TCP supports urgent data. +Urgent data is used to signal the receiver that some important message is part of the data stream and that it should be processed as soon as possible. To send urgent data specify the .B MSG_OOB -option to +option to .BR send (2). When urgent data is received, the kernel sends a .B SIGURG -signal to the process or process group that has been set as the +signal to the process or process group that has been set as the socket "owner" using the .B SIOCSPGRP -or -.B FIOSETOWN +or +.B FIOSETOWN ioctls (or the POSIX.1-2001-specified .BR fcntl (2) .B F_SETOWN operation). -When the +When the .B SO_OOBINLINE socket option is enabled, urgent data is put into the normal data stream (a program can test for its location using the .B SIOCATMARK -ioctl described below), +ioctl described below), otherwise it can be only received when the .B MSG_OOB -flag is set for +flag is set for .BR recv (2) or -.BR recvmsg (2). +.BR recvmsg (2). Linux 2.4 introduced a number of changes for improved throughput and scaling, as well as enhanced functionality. Some of these features include support for zero-copy -.BR sendfile (2), +.BR sendfile (2), Explicit Congestion Notification, new management of TIME_WAIT sockets, keep-alive socket options and support for Duplicate SACK extensions. .SH "ADDRESS FORMATS" -TCP is built on top of IP (see +TCP is built on top of IP (see .BR ip (7)). The address formats defined by .BR ip (7) -apply to TCP. TCP only supports point-to-point +apply to TCP. +TCP only supports point-to-point communication; broadcasting and multicasting are not supported. .SH SYSCTLS -These variables can be accessed by the -.I /proc/sys/net/ipv4/* -files or with the +These variables can be accessed by the +.I /proc/sys/net/ipv4/* +files or with the .BR sysctl (2) -interface. In addition, most IP sysctls also apply to TCP; see -.BR ip (7). +interface. +In addition, most IP sysctls also apply to TCP; see +.BR ip (7). Variables described as .I Boolean take an integer value, with a non-zero value ("true") meaning that @@ -176,11 +188,13 @@ meaning that the option is disabled. Enable resetting connections if the listening service is too slow and unable to keep up and accept them. It means that if overflow occurred due -to a burst, the connection will recover. Enable this option +to a burst, the connection will recover. +Enable this option .I only if you are really sure that the listening daemon -cannot be tuned to accept connections faster. Enabling this -option can harm the clients of your server. +cannot be tuned to accept connections faster. +Enabling this +option can harm the clients of your server. .TP .BR tcp_adv_win_scale " (integer; default: 2)" Count buffering overhead as bytes/2^tcp_adv_win_scale @@ -188,23 +202,27 @@ Count buffering overhead as bytes/2^tcp_adv_win_scale if it is <= 0. The socket receive buffer space is shared between the -application and kernel. TCP maintains part of the buffer as +application and kernel. +TCP maintains part of the buffer as the TCP window, this is the size of the receive window -advertised to the other end. The rest of the space is used +advertised to the other end. +The rest of the space is used as the "application" buffer, used to isolate the network -from scheduling and application latencies. The -.BR tcp_adv_win_scale +from scheduling and application latencies. +The +.BR tcp_adv_win_scale default value of 2 implies that the space used for the application buffer is one fourth that of the -total. -.TP +total. +.TP .BR tcp_app_win " (integer; default: 31)" This variable defines how many bytes of the TCP window are reserved for buffering overhead. A maximum of (window/2^tcp_app_win, mss) bytes in the window -are reserved for the application buffer. A value of 0 +are reserved for the application buffer. +A value of 0 implies that no amount is reserved. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt @@ -213,29 +231,34 @@ implies that no amount is reserved. Enable BIC TCP congestion control algorithm. BIC-TCP is a sender-side only change that ensures a linear RTT fairness under large windows while offering both scalability and -bounded TCP-friendliness. The protocol combines two schemes -called additive increase and binary search increase. When the +bounded TCP-friendliness. +The protocol combines two schemes +called additive increase and binary search increase. +When the congestion window is large, additive increase with a large increment ensures linear RTT fairness as well as good -scalability. Under small congestion windows, binary search +scalability. +Under small congestion windows, binary search increase provides TCP friendliness. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR tcp_bic_low_window " (integer; default: 14)" Sets the threshold window (in packets) where BIC TCP starts to -adjust the congestion window. Below this threshold BIC TCP behaves +adjust the congestion window. +Below this threshold BIC TCP behaves the same as the default TCP Reno. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR tcp_bic_fast_convergence " (Boolean; default: enabled)" Forces BIC TCP to more quickly respond to changes in congestion -window. Allows two flows sharing the same connection to converge +window. +Allows two flows sharing the same connection to converge more rapidly. .TP .BR tcp_dsack " (Boolean; default: enabled)" -Enable RFC\ 2883 TCP Duplicate SACK support. +Enable RFC\ 2883 TCP Duplicate SACK support. .TP .BR tcp_ecn " (Boolean; default: disabled)" Enable RFC\ 2884 Explicit Congestion Notification. @@ -248,16 +271,18 @@ Enable TCP Forward Acknowledgement support. .TP .BR tcp_fin_timeout " (integer; default: 60)" This specifies how many seconds to wait for a final FIN packet before the -socket is forcibly closed. This is strictly a violation of +socket is forcibly closed. +This is strictly a violation of the TCP specification, but required to prevent -denial-of-service attacks. +denial-of-service attacks. In Linux 2.2, the default value was 180. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP .BR tcp_frto " (Boolean; default: disabled)" Enables F-RTO, an enhanced recovery algorithm for TCP retransmission -timeouts. It is particularly beneficial in wireless environments +timeouts. +It is particularly beneficial in wireless environments where packet loss is typically due to random radio interference rather than intermediate router congestion. .TP @@ -265,21 +290,22 @@ rather than intermediate router congestion. The number of seconds between TCP keep-alive probes. .TP .BR tcp_keepalive_probes " (integer; default: 9)" -The maximum number of TCP keep-alive probes to send +The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end. .TP .BR tcp_keepalive_time " (integer; default: 7200)" The number of seconds a connection needs to be idle -before TCP begins sending out keep-alive probes. -Keep-alives are only sent when the -.B SO_KEEPALIVE -socket option is enabled. The default value is 7200 seconds -(2 hours). An idle connection is terminated after +before TCP begins sending out keep-alive probes. +Keep-alives are only sent when the +.B SO_KEEPALIVE +socket option is enabled. +The default value is 7200 seconds (2 hours). +An idle connection is terminated after approximately an additional 11 minutes (9 probes an interval of 75 seconds apart) when keep-alive is enabled. -Note that underlying connection tracking mechanisms and +Note that underlying connection tracking mechanisms and application timeouts may be much shorter. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt @@ -293,24 +319,29 @@ changed would be a Beowulf compute cluster. .TP .BR tcp_max_orphans " (integer; default: see below)" The maximum number of orphaned (not attached to any user file -handle) TCP sockets allowed in the system. When this number +handle) TCP sockets allowed in the system. +When this number is exceeded, the orphaned connection is reset and a warning -is printed. This limit exists only to prevent simple denial-of-service -attacks. Lowering this limit is not recommended. Network -conditions might require you to increase the number of +is printed. +This limit exists only to prevent simple denial-of-service attacks. +Lowering this limit is not recommended. +Network conditions might require you to increase the number of orphans allowed, but note that each orphan can eat up to ~64K -of unswappable memory. The default initial value is set -equal to the kernel parameter NR_FILE. This initial default -is adjusted depending on the memory in the system. +of unswappable memory. +The default initial value is set +equal to the kernel parameter NR_FILE. +This initial default is adjusted depending on the memory in the system. .TP .BR tcp_max_syn_backlog " (integer; default: see below)" The maximum number of queued connection requests which have -still not received an acknowledgement from the connecting -client. If this number is exceeded, the kernel will begin -dropping requests. The default value of 256 is increased to +still not received an acknowledgement from the connecting client. +If this number is exceeded, the kernel will begin +dropping requests. +The default value of 256 is increased to 1024 when the memory present in the system is adequate or greater (>= 128Mb), and reduced to 128 for those systems with -very low memory (<= 32Mb). It is recommended that if this +very low memory (<= 32Mb). +It is recommended that if this needs to be increased above 1024, TCP_SYNQ_HSIZE in include/net/tcp.h be modified to keep TCP_SYNQ_HSIZE*16<=tcp_max_syn_backlog, and the kernel be @@ -318,38 +349,43 @@ recompiled. .TP .BR tcp_max_tw_buckets " (integer; default: see below)" The maximum number of sockets in TIME_WAIT state allowed in -the system. This limit exists only to prevent simple denial-of-service -attacks. The default value of NR_FILE*2 is adjusted -depending on the memory in the system. If this number is +the system. +This limit exists only to prevent simple denial-of-service +attacks. +The default value of NR_FILE*2 is adjusted +depending on the memory in the system. +If this number is exceeded, the socket is closed and a warning is printed. -.TP +.TP .BR tcp_mem -This is a vector of 3 integers: [low, pressure, high]. These -bounds are used by TCP to track its memory usage. The +This is a vector of 3 integers: [low, pressure, high]. +These bounds are used by TCP to track its memory usage. +The defaults are calculated at boot time from the amount of available memory. -(TCP can only use +(TCP can only use .I "low memory" for this, which is limited to around 900 megabytes on 32-bit systems. 64-bit systems do not suffer this limitation.) -.I low +.I low - TCP doesn't regulate its memory allocation when the number of pages it has allocated globally is below this number. .I pressure - when the amount of memory allocated by TCP -exceeds this number of pages, TCP moderates its memory -consumption. This memory pressure state is exited +exceeds this number of pages, TCP moderates its memory consumption. +This memory pressure state is exited once the number of pages allocated falls below -the -.I low +the +.I low mark. .I high - the maximum number of pages, globally, that TCP -will allocate. This value overrides any other limits -imposed by the kernel. +will allocate. +This value overrides any other limits +imposed by the kernel. .TP .BR tcp_orphan_retries " (integer; default: 8)" The maximum number of attempts made to probe the other @@ -364,68 +400,78 @@ minimize unnecessary back off and retransmits provoked by reordering of packets on a connection. .TP .BR tcp_retrans_collapse " (Boolean; default: enabled)" -Try to send full-sized packets during retransmit. +Try to send full-sized packets during retransmit. .TP .BR tcp_retries1 " (integer; default: 3)" The number of times TCP will attempt to retransmit a packet on an established connection normally, without the extra effort of getting the network -layers involved. Once we exceed this number of +layers involved. +Once we exceed this number of retransmits, we first have the network layer update the route if possible before each new retransmit. The default is the RFC specified minimum of 3. .TP .BR tcp_retries2 " (integer; default: 15)" The maximum number of times a TCP packet is retransmitted -in established state before giving up. The default +in established state before giving up. +The default value is 15, which corresponds to a duration of approximately between 13 to 30 minutes, depending -on the retransmission timeout. The RFC\ 1122 specified +on the retransmission timeout. +The RFC\ 1122 specified minimum limit of 100 seconds is typically deemed too short. .TP .BR tcp_rfc1337 " (Boolean; default: disabled)" Enable TCP behaviour conformant with RFC\ 1337. When disabled, -if a RST is received in TIME_WAIT state, we close +if a RST is received in TIME_WAIT state, we close the socket immediately without waiting for the end -of the TIME_WAIT period. +of the TIME_WAIT period. .TP -.BR tcp_rmem +.BR tcp_rmem This is a vector of 3 integers: [min, default, -max]. These parameters are used by TCP to regulate receive -buffer sizes. TCP dynamically adjusts the size of the +max]. +These parameters are used by TCP to regulate receive +buffer sizes. +TCP dynamically adjusts the size of the receive buffer from the defaults listed below, in the range of these sysctl variables, depending on memory available in the system. .I min -- minimum size of the receive buffer used by each TCP -socket. The default value is 4K, and is lowered to -PAGE_SIZE bytes in low-memory systems. This value +- minimum size of the receive buffer used by each TCP socket. +The default value is 4K, and is lowered to +PAGE_SIZE bytes in low-memory systems. +This value is used to ensure that in memory pressure mode, -allocations below this size will still succeed. This is not +allocations below this size will still succeed. +This is not used to bound the size of the receive buffer declared using .B SO_RCVBUF -on a socket. +on a socket. .I default - the default size of the receive buffer for a TCP socket. This value overwrites the initial default buffer size from -the generic global +the generic global .B net.core.rmem_default -defined for all protocols. The default value is 87380 -bytes, and is lowered to 43689 in low-memory systems. If -larger receive buffer sizes are desired, this value should -be increased (to affect all sockets). To employ large TCP +defined for all protocols. +The default value is 87380 +bytes, and is lowered to 43689 in low-memory systems. +If larger receive buffer sizes are desired, this value should +be increased (to affect all sockets). +To employ large TCP windows, the -.B net.ipv4.tcp_window_scaling +.B net.ipv4.tcp_window_scaling must be enabled (default). .I max - the maximum size of the receive buffer used by -each TCP socket. This value does not override the global +each TCP socket. +This value does not override the global .BR net.core.rmem_max . This is not used to limit the size of the receive buffer declared using @@ -435,7 +481,7 @@ The default value of 87380*2 bytes is lowered to 87380 in low-memory systems. .TP .BR tcp_sack " (Boolean; default: enabled)" -Enable RFC\ 2018 TCP Selective Acknowledgements. +Enable RFC\ 2018 TCP Selective Acknowledgements. .TP .BR tcp_stdurg " (Boolean; default: disabled)" If this option is enabled, then use the RFC\ 1122 interpretation @@ -445,7 +491,7 @@ of the TCP urgent-pointer field. .\" resolution of this ambiguity (unfortunately the "wrong" one). According to this interpretation, the urgent pointer points to the last byte of urgent data. -If this option is disabled, then use the BSD-compatible interpretation of +If this option is disabled, then use the BSD-compatible interpretation of the urgent pointer: the urgent pointer points to the first byte after the urgent data. Enabling this option may lead to interoperability problems. @@ -456,17 +502,23 @@ for a passive TCP connection will be retransmitted. This number should not be higher than 255. .TP .BR tcp_syncookies " (Boolean)" -Enable TCP syncookies. The kernel must be compiled with +Enable TCP syncookies. +The kernel must be compiled with .BR CONFIG_SYN_COOKIES . Send out syncookies when the syn backlog queue of a socket -overflows. The syncookies feature attempts to protect a -socket from a SYN flood attack. This should be used as a -last resort, if at all. This is a violation of the TCP +overflows. +The syncookies feature attempts to protect a +socket from a SYN flood attack. +This should be used as a +last resort, if at all. +This is a violation of the TCP protocol, and conflicts with other areas of TCP such as TCP -extensions. It can cause problems for clients and relays. +extensions. +It can cause problems for clients and relays. It is not recommended as a tuning mechanism for heavily loaded servers to help with overloaded or misconfigured -conditions. For recommended alternatives see +conditions. +For recommended alternatives see .BR tcp_max_syn_backlog , .BR tcp_synack_retries , and @@ -474,8 +526,10 @@ and .TP .BR tcp_syn_retries " (integer; default: 5)" The maximum number of times initial SYNs for an active TCP -connection attempt will be retransmitted. This value should -not be higher than 255. The default value is 5, which +connection attempt will be retransmitted. +This value should +not be higher than 255. +The default value is 5, which corresponds to approximately 180 seconds. .TP .BR tcp_timestamps " (Boolean; default: enabled)" @@ -485,7 +539,7 @@ Enable RFC\ 1323 TCP timestamps. Enable fast recycling of TIME-WAIT sockets. Enabling this option is not recommended since this causes problems when working -with NAT (Network Address Translation). +with NAT (Network Address Translation). .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt .TP @@ -500,11 +554,13 @@ Enable RFC\ 1323 TCP window scaling. This feature allows the use of a large window (> 64K) on a TCP connection, should the other end support it. Normally, the 16 bit window length field in the TCP header -limits the window size to less than 64K bytes. If larger +limits the window size to less than 64K bytes. +If larger windows are desired, applications can increase the size of their socket buffers and the window scaling option will be -employed. If -.BR tcp_window_scaling +employed. +If +.BR tcp_window_scaling is disabled, TCP will not negotiate the use of window scaling with the other end during connection setup. .\" @@ -513,9 +569,11 @@ scaling with the other end during connection setup. .BR tcp_vegas_cong_avoid " (Boolean; default: disabled)" Enable TCP Vegas congestion avoidance algorithm. TCP Vegas is a sender-side only change to TCP that anticipates -the onset of congestion by estimating the bandwidth. TCP Vegas +the onset of congestion by estimating the bandwidth. +TCP Vegas adjusts the sending rate by modifying the congestion -window. TCP Vegas should provide less packet loss, but it is +window. +TCP Vegas should provide less packet loss, but it is not as aggressive as TCP Reno. .\" .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt @@ -524,17 +582,19 @@ not as aggressive as TCP Reno. Enable TCP Westwood+ congestion control algorithm. TCP Westwood+ is a sender-side only modification of the TCP Reno protocol stack that optimizes the performance of TCP congestion -control. It is based on end-to-end bandwidth estimation to set +control. +It is based on end-to-end bandwidth estimation to set congestion window and slow start threshold after a congestion -episode. Using this estimation, TCP Westwood+ adaptively sets a +episode. +Using this estimation, TCP Westwood+ adaptively sets a slow start threshold and a congestion window which takes into account the bandwidth used at the time congestion is experienced. TCP Westwood+ significantly increases fairness with respect to TCP Reno in wired networks and throughput over wireless links. .TP .BR tcp_wmem -This is a vector of 3 integers: [min, default, max]. These -parameters are used by TCP to regulate send buffer sizes. +This is a vector of 3 integers: [min, default, max]. +These parameters are used by TCP to regulate send buffer sizes. TCP dynamically adjusts the size of the send buffer from the default values listed below, in the range of these sysctl variables, depending on memory available. @@ -543,7 +603,8 @@ variables, depending on memory available. - minimum size of the send buffer used by each TCP socket. The default value is 4K bytes. This value is used to ensure that in memory pressure mode, -allocations below this size will still succeed. This is not +allocations below this size will still succeed. +This is not used to bound the size of the send buffer declared using .B SO_SNDBUF @@ -554,46 +615,50 @@ on a socket. This value overwrites the initial default buffer size from the generic global .B net.core.wmem_default -defined for all protocols. The default value is 16K bytes. +defined for all protocols. +The default value is 16K bytes. If larger send buffer sizes are desired, this value -should be increased (to affect all sockets). To employ -large TCP windows, the sysctl variable +should be increased (to affect all sockets). +To employ large TCP windows, the sysctl variable .B net.ipv4.tcp_window_scaling must be enabled (default). .I max - the maximum size of the send buffer used by -each TCP socket. This value does not override the global +each TCP socket. +This value does not override the global .BR net.core.wmem_max . This is not used to limit the size of the send buffer declared using .B SO_SNDBUF on a socket. -The default value is 128K bytes. It is lowered to 64K +The default value is 128K bytes. +It is lowered to 64K depending on the memory available in the system. .SH "SOCKET OPTIONS" To set or get a TCP socket option, call .BR getsockopt (2) to read or .BR setsockopt (2) -to write the option with the option level argument set to +to write the option with the option level argument set to .BR IPPROTO_TCP . .\" or SOL_TCP on Linux In addition, -most -.B IPPROTO_IP -socket options are valid on TCP sockets. For more -information see +most +.B IPPROTO_IP +socket options are valid on TCP sockets. +For more information see .BR ip (7). .\" FIXME Document TCP_CONGESTION (new in 2.6.13) .TP .B TCP_CORK -If set, don't send out partial frames. All queued +If set, don't send out partial frames. +All queued partial frames are sent when the option is cleared again. This is useful for prepending headers before calling .BR sendfile (2), or for throughput optimization. -As currently implemented, there is a 200 millisecond ceiling on the time +As currently implemented, there is a 200 millisecond ceiling on the time for which output is corked by .BR TCP_CORK . If this ceiling is reached, then queued data is automatically transmitted. @@ -606,27 +671,30 @@ portable. .TP .B TCP_DEFER_ACCEPT Allows a listener to be awakened only when data arrives on -the socket. Takes an integer value (seconds), this can +the socket. +Takes an integer value (seconds), this can bound the maximum number of attempts TCP will make to -complete the connection. This option should not be used in +complete the connection. +This option should not be used in code intended to be portable. .TP .B TCP_INFO -Used to collect information about this socket. The kernel -returns a \fIstruct tcp_info\fP as defined in the file -/usr/include/linux/tcp.h. This option should not be used in -code intended to be portable. +Used to collect information about this socket. +The kernel returns a \fIstruct tcp_info\fP as defined in the file +/usr/include/linux/tcp.h. +This option should not be used in code intended to be portable. .TP .B TCP_KEEPCNT The maximum number of keepalive probes TCP should send -before dropping the connection. This option should not be +before dropping the connection. +This option should not be used in code intended to be portable. .TP .B TCP_KEEPIDLE The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes, if the socket -option SO_KEEPALIVE has been set on this socket. This -option should not be used in code intended to be portable. +option SO_KEEPALIVE has been set on this socket. +This option should not be used in code intended to be portable. .TP .B TCP_KEEPINTVL The time (in seconds) between individual keepalive probes. @@ -634,33 +702,37 @@ This option should not be used in code intended to be portable. .TP .B TCP_LINGER2 -The lifetime of orphaned FIN_WAIT2 state sockets. This -option can be used to override the system wide sysctl +The lifetime of orphaned FIN_WAIT2 state sockets. +This option can be used to override the system wide sysctl .B tcp_fin_timeout -on this socket. This is not to be confused with the +on this socket. +This is not to be confused with the .BR socket (7) -level option +level option .BR SO_LINGER . This option should not be used in code intended to be portable. .TP .B TCP_MAXSEG -The maximum segment size for outgoing TCP packets. If this -option is set before connection establishment, it also +The maximum segment size for outgoing TCP packets. +If this option is set before connection establishment, it also changes the MSS value announced to the other end in the -initial packet. Values greater than the (eventual) -interface MTU have no effect. TCP will also impose +initial packet. +Values greater than the (eventual) interface MTU have no effect. +TCP will also impose its minimum and maximum bounds over the value provided. .TP .B TCP_NODELAY -If set, disable the Nagle algorithm. This means that segments +If set, disable the Nagle algorithm. +This means that segments are always sent as soon as possible, even if there is only a -small amount of data. When not set, data is buffered until there +small amount of data. +When not set, data is buffered until there is a sufficient amount to send out, thereby avoiding the frequent sending of small packets, which results in poor utilization of the network. This option is overridden by -.BR TCP_CORK ; +.BR TCP_CORK ; however, setting this option forces an explicit flush of pending output, even if .B TCP_CORK @@ -668,9 +740,11 @@ is currently set. .TP .B TCP_QUICKACK Enable quickack mode if set or disable quickack -mode if cleared. In quickack mode, acks are sent +mode if cleared. +In quickack mode, acks are sent immediately, rather than delayed if needed in accordance -to normal TCP operation. This flag is not permanent, +to normal TCP operation. +This flag is not permanent, it only enables a switch to or from quickack mode. Subsequent operation of the TCP protocol will once again enter/leave quickack mode depending on @@ -681,13 +755,14 @@ portable. .TP .B TCP_SYNCNT Set the number of SYN retransmits that TCP should send before -aborting the attempt to connect. It cannot exceed 255. +aborting the attempt to connect. +It cannot exceed 255. This option should not be used in code intended to be portable. .TP .B TCP_WINDOW_CLAMP -Bound the size of the advertised window to this value. The -kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. +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 @@ -713,19 +788,19 @@ The socket must not be in LISTEN state, otherwise an error (EINVAL) is returned. .TP .B SIOCATMARK -Returns true (i.e., +Returns true (i.e., .I value is non-zero) if the inbound data stream is at the urgent mark. .sp -If the -.BR SO_OOBINLINE -socket option is set, and +If the +.BR SO_OOBINLINE +socket option is set, and .B SIOCATMARK returns true, then the next read from the socket will return the urgent data. -If the -.BR SO_OOBINLINE -socket option is not set, and +If the +.BR SO_OOBINLINE +socket option is not set, and .B SIOCATMARK returns true, then the next read from the socket will return the bytes following @@ -741,7 +816,7 @@ If an application is informed of the presence of urgent data via argument) or through delivery of a .B SIGURG signal, -then it can advance up to the mark using a loop which repeatedly tests +then it can advance up to the mark using a loop which repeatedly tests .B SIOCATMARK and performs a read (requesting any number of bytes) as long as .B SIOCATMARK @@ -752,32 +827,36 @@ 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" -When a network error occurs, TCP tries to resend the -packet. If it doesn't succeed after some time, either -.B ETIMEDOUT +When a network error occurs, TCP tries to resend the packet. +If it doesn't succeed after some time, either +.B ETIMEDOUT or the last received error on this connection is reported. .PP Some applications require a quicker error notification. This can be enabled with the -.B IPPROTO_IP -level -.B IP_RECVERR -socket option. When this option is enabled, all incoming -errors are immediately passed to the user program. Use this +.B IPPROTO_IP +level +.B IP_RECVERR +socket option. +When this option is enabled, all incoming +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 +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. +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 +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 @@ -792,34 +871,34 @@ some time. .TP .B EAFNOTSUPPORT Passed socket address type in -.I sin_family -was not +.I sin_family +was not .BR AF_INET . .PP 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. +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 (), +Support for Explicit Congestion Notification, zero-copy +.BR sendfile (), reordering support and some SACK extensions (DSACK) were introduced in 2.4. -Support for forward acknowledgement (FACK), TIME_WAIT recycling, +Support for forward acknowledgement (FACK), TIME_WAIT recycling, per connection keepalive socket options and sysctls were introduced in 2.3. -The default values and descriptions for the sysctl variables +The default values and descriptions for the sysctl variables given above are applicable for the 2.4 kernel. .SH AUTHORS -This man page was originally written by Andi Kleen. -It was updated for 2.4 by Nivedita Singhvi with input from +This man page was originally written by Andi Kleen. +It was updated for 2.4 by Nivedita Singhvi with input from Alexey Kuznetsov's Documentation/networking/ip-sysctls.txt document. .SH "SEE ALSO" @@ -838,7 +917,7 @@ document. .sp RFC\ 793 for the TCP specification. .br -RFC\ 1122 for the TCP requirements and a description +RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. .br RFC\ 1323 for TCP timestamp and window scaling options. diff --git a/man7/termio.7 b/man7/termio.7 index 42dfcfe70..42def74f0 100644 --- a/man7/termio.7 +++ b/man7/termio.7 @@ -25,7 +25,7 @@ termio \- the System V terminal driver interface .SH DESCRIPTION .B termio is the name of the old System V terminal driver interface. -This interface defined a +This interface defined a .I termio structure used to store terminal settings, and a range of .BR ioctl (2) @@ -36,7 +36,7 @@ The interface is now obsolete: POSIX.1-1990 standardized a modified version of this interface, under the name .BR termios . -The POSIX.1 data structure differs slightly from the +The POSIX.1 data structure differs slightly from the System V version, and POSIX.1 defined a suite of functions to replace the various .BR ioctl () diff --git a/man7/time.7 b/man7/time.7 index 38e671a8a..68a5e287f 100644 --- a/man7/time.7 +++ b/man7/time.7 @@ -24,14 +24,14 @@ time \- overview of time .SS "Real time and process time" .I "Real time" is defined as time measured from some fixed point, -either from a standard point in the past +either from a standard point in the past (see the description of the Epoch and calendar time below), or from some point (e.g., the start) in the life of a process .RI ( "elapsed time" ). .I "Process time" is defined as the amount of CPU time used by a process. -This is sometimes divided into +This is sometimes divided into .I user and .I system @@ -41,7 +41,7 @@ System CPU time is the time spent by the kernel executing in system mode on behalf of the process (e.g., executing system calls). The .BR time (1) -command can be used to determine the amount of CPU time consumed +command can be used to determine the amount of CPU time consumed during the execution of a program. A program can determine the amount of CPU time it has consumed using .BR times (2), @@ -56,10 +56,10 @@ For further details, see and .BR hwclock (8). .SS "The Software Clock, HZ, and Jiffies" -The accuracy of many system calls and timestamps is limited by +The accuracy of many system calls and timestamps is limited by the resolution of the .IR "software clock" , -a clock maintained by the kernel which measures time in +a clock maintained by the kernel which measures time in .IR jiffies . The size of a jiffy is determined by the value of the kernel constant .IR HZ . @@ -67,52 +67,52 @@ The value of .I HZ varies across kernel versions and hardware platforms. On x86 the situation is as follows: -on kernels up to and including 2.4.x, HZ was 100, +on kernels up to and including 2.4.x, HZ was 100, giving a jiffy value of 0.01 seconds; starting with 2.6.0, HZ was raised to 1000, giving a jiffy of 0.001 seconds; since kernel 2.6.13, the HZ value is a kernel configuration parameter and can be 100, 250 (the default) or 1000, yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. -Since kernel 2.6.20, a further frequency is available: -300, a number that divides evenly for the common video +Since kernel 2.6.20, a further frequency is available: +300, a number that divides evenly for the common video frame rates (PAL, 25 HZ; NTSC, 30 HZ). .SS "The Epoch" Unix systems represent time in seconds since the .IR Epoch , which is defined as 0:00:00 UTC on the morning of 1 January 1970. -A program can determine the +A program can determine the .IR "calendar time" -using +using .BR gettimeofday (2), which returns time (in seconds and microseconds) that have -elapsed since the Epoch; +elapsed since the Epoch; .BR time (2) -provides similar information, but only with accuracy to the +provides similar information, but only with accuracy to the nearest second. The system time can be changed using .BR settimeofday (2). .SS "Broken-down time" Certain library functions use a structure of -type +type .I tm -to represent +to represent .IR "broken-down time" , -which stores time value separated out into distinct components +which stores time value separated out into distinct components (year, month, day, hour, minute, second, etc.). This structure is described in .BR ctime (3), -which also describes functions that convert between calendar time and +which also describes functions that convert between calendar time and broken-down time. -Functions for converting between broken-down time and printable +Functions for converting between broken-down time and printable string representations of the time are described in .BR ctime (3), .BR strftime (3), and .BR strptime (3). .SS "Sleeping and Setting Timers" -Various system calls and functions allow a program to sleep -(suspend execution) for a specified period of time; see +Various system calls and functions allow a program to sleep +(suspend execution) for a specified period of time; see .BR nanosleep (2) and .BR sleep (3). diff --git a/man7/udp.7 b/man7/udp.7 index 0830b57c0..a436b57e7 100644 --- a/man7/udp.7 +++ b/man7/udp.7 @@ -5,7 +5,7 @@ .\" of the modification is added to the header. .\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ .\" -.TH UDP 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" +.TH UDP 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual" .SH NAME udp \- User Datagram Protocol for IPv4 .SH SYNOPSIS @@ -13,29 +13,30 @@ udp \- User Datagram Protocol for IPv4 .br .B #include .br -.B udp_socket = socket(PF_INET, SOCK_DGRAM, 0); +.B udp_socket = socket(PF_INET, SOCK_DGRAM, 0); .SH DESCRIPTION -This is an implementation of the User Datagram Protocol -described in RFC\ 768. +This is an implementation of the User Datagram Protocol +described in RFC\ 768. It implements a connectionless, unreliable datagram packet service. -Packets may be reordered or duplicated before they arrive. UDP -generates and checks checksums to catch transmission errors. +Packets may be reordered or duplicated before they arrive. +UDP generates and checks checksums to catch transmission errors. -When a UDP socket is created, +When a UDP socket is created, its local and remote addresses are unspecified. -Datagrams can be sent immediately using +Datagrams can be sent immediately using .BR sendto (2) or .BR sendmsg (2) -with a valid destination address as an argument. When -.BR connect (2) -is called on the socket the default destination address is set and -datagrams can now be sent using +with a valid destination address as an argument. +When +.BR connect (2) +is called on the socket the default destination address is set and +datagrams can now be sent using .BR send (2) -or +or .BR write (2) without specifying an destination address. -It is still possible to send to other destinations by passing an +It is still possible to send to other destinations by passing an address to .BR sendto (2) or @@ -49,77 +50,79 @@ a free local port out of the range defined by and bind the socket to .IR INADDR_ANY . -All receive operations return only one packet. -When the packet is smaller than the passed buffer only that much +All receive operations return only one packet. +When the packet is smaller than the passed buffer only that much data is returned, when it is bigger the packet is truncated and the .B MSG_TRUNC flag is set. .I MSG_WAITALL is not supported. -IP options may be sent or received using the socket options described in +IP options may be sent or received using the socket options described in .BR ip (7). They are only processed by the kernel when the appropriate sysctl -is enabled (but still passed to the user even when it is turned off). +is enabled (but still passed to the user even when it is turned off). See .BR ip (7). -When the +When the .B MSG_DONTROUTE -flag is set on sending the destination address must refer to an local -interface address and the packet is only sent to that interface. +flag is set on sending the destination address must refer to an local +interface address and the packet is only sent to that interface. -By default Linux UDP does path MTU (Maximum Transmission Unit) discovery. +By default Linux UDP does path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return .I EMSGSIZE -when a UDP packet write exceeds it. -When this happens the application should decrease the packet size. +when a UDP packet write exceeds it. +When this happens the application should decrease the packet size. Path MTU discovery can be also turned off using the .B IP_MTU_DISCOVER -socket option or the +socket option or the .B ip_no_pmtu_disc -sysctl, see -.BR ip(7) -for details. +sysctl, see +.BR ip(7) +for details. When turned off UDP will fragment outgoing UDP packets -that exceed the interface MTU. +that exceed the interface MTU. However disabling it is not recommended for performance and reliability reasons. .SH "ADDRESS FORMAT" -UDP uses the IPv4 -.B sockaddr_in -address format described in -.BR ip (7). +UDP uses the IPv4 +.B sockaddr_in +address format described in +.BR ip (7). .SH "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 -received from the network. You may get an error for an earlier packet +All fatal errors will be passed to the user as an error return even +when the socket is not connected. +This includes asynchronous errors +received from the network. +You may get an error for an earlier packet that was sent on the same socket. This behaviour differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. -Linux's behaviour is mandated by +Linux's behaviour is mandated by .BR RFC\ 1122 . -For compatibility with legacy code in Linux 2.0 and 2.2 +For compatibility with legacy code in Linux 2.0 and 2.2 it was possible to set the -.B SO_BSDCOMPAT -SOL_SOCKET option to receive remote errors only when the socket has been +.B SO_BSDCOMPAT +SOL_SOCKET option to receive remote errors only when the socket has been connected (except for .B EPROTO and .BR EMSGSIZE ). Locally generated errors are always passed. -Support for this socket option was removed in later kernels; see +Support for this socket option was removed in later kernels; see .BR socket (7) for further information. -When the +When the .B IP_RECVERR option is enabled all errors are stored in the socket error queue and can be received by .BR recvmsg (2) -with the +with the .B MSG_ERRQUEUE flag set. .SH "SOCKET OPTIONS" @@ -127,7 +130,7 @@ To set or get a UDP socket option, call .BR getsockopt (2) to read or .BR setsockopt (2) -to write the option with the option level argument set to +to write the option with the option level argument set to .BR IPPROTO_UDP . .TP .BR UDP_CORK " (since Linux 2.5.44)" @@ -150,12 +153,12 @@ The correct syntax is: .RE .TP .BR FIONREAD " (" SIOCINQ ) -Gets a pointer to an integer as argument. -Returns the size of the next pending datagram in the integer in bytes, +Gets a pointer to an integer as argument. +Returns the size of the next pending datagram in the integer in bytes, or 0 when no datagram is pending. .TP .BR TIOCOUTQ " (" SIOCOUTQ ) -Returns the number of data bytes in the local send queue. +Returns the number of data bytes in the local send queue. Only supported with Linux 2.4 and above. .PP In addition all ioctls documented in @@ -164,14 +167,14 @@ and .BR socket (7) are supported. .SH ERRORS -All errors documented for +All errors documented for .BR socket (7) -or +or .BR ip (7) -may be returned by a send or receive on a UDP socket. +may be returned by a send or receive on a UDP socket. .B ECONNREFUSED -No receiver was associated with the destination address. +No receiver was associated with the destination address. This might be caused by a previous packet sent over the socket. .SH VERSIONS IP_RECVERR is a new feature in Linux 2.2. diff --git a/man7/unicode.7 b/man7/unicode.7 index ead23a80b..cb12af684 100644 --- a/man7/unicode.7 +++ b/man7/unicode.7 @@ -35,25 +35,29 @@ The international standard .B ISO 10646 defines the .BR "Universal Character Set (UCS)" . -UCS contains all characters of all other character set standards. It -also guarantees +UCS contains all characters of all other character set standards. +It also guarantees .BR "round-trip compatibility" , i.e., conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back. UCS contains the characters required to represent practically all -known languages. This includes not only the Latin, Greek, Cyrillic, +known languages. +This includes not only the Latin, Greek, Cyrillic, Hebrew, Arabic, Armenian, and Georgian scripts, but also Chinese, Japanese and Korean Han ideographs as well as scripts such as Hiragana, Katakana, Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, Tibetan, Runic, Ethiopic, Canadian Syllabics, Cherokee, Mongolian, -Ogham, Myanmar, Sinhala, Thaana, Yi, and others. For scripts not yet +Ogham, Myanmar, Sinhala, Thaana, Yi, and others. +For scripts not yet covered, research on how to best encode them for computer usage is -still going on and they will be added eventually. This might +still going on and they will be added eventually. +This might eventually include not only Hieroglyphs and various historic Indo-European languages, but even some selected artistic scripts such -as Tengwar, Cirth, and Klingon. UCS also covers a large number of +as Tengwar, Cirth, and Klingon. +UCS also covers a large number of graphical, typographical, mathematical and scientific symbols, including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR fonts, as well as many word processing and publishing @@ -69,20 +73,25 @@ made up of 256 8-bit .I rows with 256 .I column -positions, one for each character. Part 1 of the standard +positions, one for each character. +Part 1 of the standard .RB ( "ISO 10646-1" ) defines the first 65534 code positions (0x0000 to 0xfffd), which form the .IR "Basic Multilingual Plane (BMP)" , -that is plane 0 in group 0. Part 2 of the standard +that is plane 0 in group 0. +Part 2 of the standard .RB ( "ISO 10646-2" ) adds characters to group 0 outside the BMP in several .I "supplementary planes" -in the range 0x10000 to 0x10ffff. There are no plans to add characters +in the range 0x10000 to 0x10ffff. +There are no plans to add characters beyond 0x10ffff to the standard, therefore of the entire code space, only a small fraction of group 0 will ever be actually used in the -foreseeable future. The BMP contains all characters found in the -commonly used other character sets. The supplemental planes added by +foreseeable future. +The BMP contains all characters found in the +commonly used other character sets. +The supplemental planes added by ISO 10646-2 cover only more exotic characters for special scientific, dictionary printing, publishing industry, higher-level protocol and enthusiast needs. @@ -111,12 +120,14 @@ Some code points in .B UCS have been assigned to .IR "combining characters" . -These are similar to the non-spacing accent keys on a typewriter. A -combining character just adds an accent to the previous character. The -most important accented characters have codes of their own in UCS, +These are similar to the non-spacing accent keys on a typewriter. +A combining character just adds an accent to the previous character. +The most important accented characters have codes of their own in UCS, however, the combining character mechanism allows us to add accents -and other diacritical marks to any character. The combining characters -always follow the character which they modify. For example, the German +and other diacritical marks to any character. +The combining characters +always follow the character which they modify. +For example, the German character Umlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed UCS code 0x00c4, or alternatively as the combination of a normal "Latin capital letter A" @@ -132,7 +143,7 @@ combining characters, ISO 10646-1 specifies the following three of UCS: .TP 0.9i Level 1 -Combining characters and +Combining characters and .B Hangul Jamo (a variant encoding of the Korean script, where a Hangul syllable glyph is coded as a triplet or pair of vovel/consonant codes) are not @@ -156,16 +167,19 @@ contains exactly the .B UCS Basic Multilingual Plane at implementation level 3, as described in ISO 10646-1:2000. .B Unicode 3.1 -added the supplemental planes of ISO 10646-2. The Unicode standard and +added the supplemental planes of ISO 10646-2. +The Unicode standard and technical reports published by the Unicode Consortium provide much additional information on the semantics and recommended usages of -various characters. They provide guidelines and algorithms for +various characters. +They provide guidelines and algorithms for editing, sorting, comparing, normalizing, converting and displaying Unicode strings. .SH "UNICODE UNDER LINUX" Under GNU/Linux, the C type .B wchar_t -is a signed 32-bit integer type. Its values are always interpreted +is a signed 32-bit integer type. +Its values are always interpreted by the C library as .B UCS code values (in all locales), a convention that is signaled by the GNU @@ -177,7 +191,8 @@ UCS/Unicode can be used just like ASCII in input/output streams, terminal communication, plaintext files, filenames, and environment variables in the ASCII compatible .B UTF-8 -multi-byte encoding. To signal the use of UTF-8 as the character +multi-byte encoding. +To signal the use of UTF-8 as the character encoding to all applications, a suitable .B locale has to be selected via environment variables (e.g., @@ -185,8 +200,8 @@ has to be selected via environment variables (e.g., .PP The .B nl_langinfo(CODESET) -function returns the name of the selected encoding. Library functions -such as +function returns the name of the selected encoding. +Library functions such as .BR wctomb (3) and .BR mbsrtowcs (3) @@ -199,7 +214,8 @@ tells, how many positions (0\(en2) the cursor is advanced by the output of a character. .PP Under Linux, in general only the BMP at implementation level 1 should -be used at the moment. Up to two combining characters per base +be used at the moment. +Up to two combining characters per base character for certain scripts (in particular Thai) are also supported by some UTF-8 terminal emulators and ISO 10646 fonts (level 2), but in general precomposed characters should be preferred where available @@ -209,11 +225,13 @@ general precomposed characters should be preferred where available In the .BR BMP , the range 0xe000 to 0xf8ff will never be assigned to any characters by -the standard and is reserved for private usage. For the Linux +the standard and is reserved for private usage. +For the Linux community, this private area has been subdivided further into the range 0xe000 to 0xefff which can be used individually by any end-user and the Linux zone in the range 0xf000 to 0xf8ff where extensions are -coordinated among all Linux users. The registry of the characters +coordinated among all Linux users. +The registry of the characters assigned to the Linux zone is currently maintained by H. Peter Anvin . .SH LITERATURE @@ -237,7 +255,8 @@ Reading, MA, 2000, ISBN 0-201-61633-5. S. Harbison, G. Steele. C: A Reference Manual. Fourth edition, Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3. -A good reference book about the C programming language. The fourth +A good reference book about the C programming language. +The fourth edition covers the 1994 Amendment 1 to the ISO C 90 standard, which adds a large number of new C library functions for handling wide and multi-byte character encodings, but it does not yet cover ISO C 99, @@ -271,13 +290,15 @@ When this man page was last revised, the GNU C Library support for locales was mature and XFree86 support was in an advanced state, but work on making applications (most notably editors) suitable for use in .B UTF-8 -locales was still fully in progress. Current general +locales was still fully in progress. +Current general .B UCS support under Linux usually provides for CJK double-width characters and sometimes even simple overstriking combining characters, but usually does not include support for scripts with right-to-left writing direction or ligature substitution requirements such as -Hebrew, Arabic, or the Indic scripts. These scripts are currently only +Hebrew, Arabic, or the Indic scripts. +These scripts are currently only supported in certain GUI applications (HTML viewers, word processors) with sophisticated text rendering engines. .SH AUTHOR diff --git a/man7/units.7 b/man7/units.7 index d332bd250..43b7c3a10 100644 --- a/man7/units.7 +++ b/man7/units.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -65,7 +65,8 @@ http://physics.nist.gov/cuu/Units/prefixes.html .RE .SS Binary prefixes The binary prefixes resemble the decimal ones, but have an additional 'i' -(and "Ki" starts with a capital 'K'). The names are formed by taking the +(and "Ki" starts with a capital 'K'). +The names are formed by taking the first syllable of the names of the decimal prefix with roughly the same size, followed by "bi" for "binary". .RS @@ -95,7 +96,8 @@ capitalized to indicate binary-ness. At first that didn't matter too much, since memory modules and disks came in sizes that were powers of two, so everyone knew that in such contexts "kilobyte" and "megabyte" meant -1024 and 1048576 bytes, respectively. What originally was a +1024 and 1048576 bytes, respectively. +What originally was a sloppy use of the prefixes "kilo" and "mega" started to become regarded as the "real true meaning" when computers were involved. But then disk technology changed, and disk sizes became arbitrary numbers. @@ -104,14 +106,16 @@ standard, namely k=1000, M=1000k, G=1000M. The situation was messy: in the 14k4 modems, k=1000; in the 1.44MB .\" also common: 14.4k modem -diskettes, M=1024000; etc. In 1998 the IEC approved the standard +diskettes, M=1024000; etc. +In 1998 the IEC approved the standard that defines the binary prefixes given above, enabling people to be precise and unambiguous. Thus, today, MB = 1000000B and MiB = 1048576B. In the free software world programs are slowly -being changed to conform. When the Linux kernel boots and says +being changed to conform. +When the Linux kernel boots and says .RS .nf diff --git a/man7/unix.7 b/man7/unix.7 index 05b0b6aff..0d17fe96f 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -9,9 +9,9 @@ .\" Modified, 2004-05-27, Michael Kerrisk, .\" Added SOCK_SEQPACKET .\" -.TH UNIX 7 2004-05-27 "Linux Man Page" "Linux Programmer's Manual" +.TH UNIX 7 2004-05-27 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local +unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local interprocess communication .SH SYNOPSIS .B #include @@ -27,9 +27,10 @@ The (also known as .BR PF_LOCAL ) socket family is used to communicate between processes on the same machine -efficiently. Unix sockets can be either anonymous (created by +efficiently. +Unix sockets can be either anonymous (created by .BR socketpair (2)) -or associated with a file of type socket. +or associated with a file of type socket. Linux also supports an abstract namespace which is independent of the file system. @@ -43,21 +44,23 @@ sockets are always reliable and don't reorder datagrams); and (since kernel 2.6.4) .BR SOCK_SEQPACKET , for a connection-oriented socket that preserves message boundaries -and delivers messages in the order that they were sent. +and delivers messages in the order that they were sent. -Unix sockets support passing file descriptors or process credentials +Unix sockets support passing file descriptors or process credentials to other processes using ancillary data. .SH "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 +A Unix address is defined as a filename in the filesystem or +as a unique string in the abstract namespace. +Sockets created by .BR socketpair (2) -are anonymous. For non-anonymous sockets the target address can be set +are anonymous. +For non-anonymous sockets the target address can be set using -.BR connect (2). +.BR connect (2). The local address can be set using -.BR bind (2). +.BR bind (2). When a socket is connected and it doesn't already have a local address a -unique address in the abstract namespace will be generated automatically. +unique address in the abstract namespace will be generated automatically. .in +0.25i .nf @@ -70,41 +73,41 @@ struct sockaddr_un { .fi .in -0.25i -.B sun_family +.B sun_family always contains .BR AF_UNIX . .B sun_path contains the zero-terminated pathname of the socket in the file system. -If +If .B sun_path -starts with a null byte (''\0'), +starts with a null byte (''\0'), then it refers to the abstract namespace maintained by the Unix protocol module. -The socket's address in this namespace is given by the rest of the +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" -For historical reasons these socket options are specified with a +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 +They can be set with .BR setsockopt (2) -and read with +and read with .BR getsockopt (2) by specifying SOL_SOCKET as the socket family. .TP .B SO_PASSCRED -Enables the receiving of the credentials of the sending process -ancillary message. +Enables the receiving of the credentials of the sending process +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. +Expects an integer boolean flag. .SH "(UN)SUPPORTED FEATURES" -The following paragraphs describe domain-specific details and +The following paragraphs describe domain-specific details and unsupported features of the sockets API for Unix domain sockets on Linux. -Unix domain sockets do not support the transmission of -out-of-band data (the +Unix domain sockets do not support the transmission of +out-of-band data (the .B MSG_OOB flag for .BR send (2) @@ -133,69 +136,72 @@ Ancillary data is sent and received using and .BR recvmsg (2). For historical reasons the ancillary message types listed below -are specified with a SOL_SOCKET type even though they are PF_UNIX +are specified with a SOL_SOCKET type even though they are PF_UNIX specific. To send them set the .B cmsg_level -field of the struct +field of the struct .B cmsghdr -to SOL_SOCKET and the -.B cmsg_type -field to the type. For more information see -.BR cmsg (3). +to SOL_SOCKET and the +.B cmsg_type +field to the type. +For more information see +.BR cmsg (3). .TP .B SCM_RIGHTS -Send or receive a set of open file descriptors from another process. +Send or receive a set of open file descriptors from another process. The data portion contains an integer array of the file descriptors. The passed file descriptors behave as though they have been created with .BR dup (2). .TP .B SCM_CREDENTIALS -Send or receive Unix credentials. This can be used for authentication. -The credentials are passed as a +Send or receive Unix credentials. +This can be used for authentication. +The credentials are passed as a .I struct ucred ancillary message. .in +0.25i .nf struct ucred { - pid_t pid; /* process ID of the sending process */ - uid_t uid; /* user ID of the sending process */ - gid_t gid; /* group ID of the sending process */ + pid_t pid; /* process ID of the sending process */ + uid_t uid; /* user ID of the sending process */ + gid_t gid; /* group ID of the sending process */ }; .fi .in -0.25i - + The credentials which the sender specifies are checked by the kernel. -A process with effective user ID 0 is allowed to specify values that do -not match its own. +A process with effective user ID 0 is allowed to specify values that do +not match its own. The sender must specify its own process ID (unless it has the capability .BR CAP_SYS_ADMIN ), its user ID, effective user ID, or saved set-user-ID (unless it has .BR CAP_SETUID ), -and its group ID, effective group ID, or saved set-group-ID +and its group ID, effective group ID, or saved set-group-ID (unless it has .BR CAP_SETGID ). To receive a .I struct ucred message the -.B SO_PASSCRED +.B SO_PASSCRED option must be enabled on the socket. .SH VERSIONS -.B SCM_CREDENTIALS +.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. +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 +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 @@ -203,14 +209,14 @@ 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 +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 () +.BR sendmsg () or -.BR recvmsg () +.BR recvmsg () call. Unix domain stream sockets do not support the notion of out-of-band data. @@ -221,18 +227,20 @@ Out of memory. .TP .B ECONNREFUSED .BR connect (2) -called with a socket object that isn't listening. This can happen when +called with a socket object that isn't listening. +This can happen when the remote socket does not exist or the filename is not a socket. .TP .B EINVAL -Invalid argument passed. A common cause is the missing setting of AF_UNIX -in the -.I sun_type -field of passed addresses or the socket being in an +Invalid argument passed. +A common cause is the missing setting of AF_UNIX +in the +.I sun_type +field of passed addresses or the socket being in an invalid state for the applied operation. .TP .B EOPNOTSUPP -Stream operation called on non-stream oriented socket or tried to +Stream operation called on non-stream oriented socket or tried to use the out-of-band data option. .TP .B EPROTONOSUPPORT @@ -240,14 +248,14 @@ Passed protocol is not PF_UNIX. .TP .B ESOCKTNOSUPPORT Unknown socket type. -.TP +.TP .B EPROTOTYPE Remote socket does not match the local socket type (SOCK_DGRAM vs. SOCK_STREAM) .TP .B EADDRINUSE -Selected local address is already taken or filesystem socket -object already exists. +Selected local address is already taken or filesystem socket +object already exists. .TP .B EISCONN .BR connect (2) @@ -261,9 +269,11 @@ Socket operation needs a target address, but the socket is not connected. Remote socket was unexpectedly closed. .TP .B EPIPE -Remote socket was closed on a stream socket. If enabled, a -.B SIGPIPE -is sent as well. This can be avoided by passing the +Remote socket was closed on a stream socket. +If enabled, a +.B SIGPIPE +is sent as well. +This can be avoided by passing the .B MSG_NOSIGNAL flag to .BR sendmsg (2) @@ -277,9 +287,9 @@ User memory address was not valid. The sender passed invalid credentials in the .IR "struct ucred" . .PP -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. +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 "SEE ALSO" .BR recvmsg (2), .BR sendmsg (2), diff --git a/man7/uri.7 b/man7/uri.7 index 6aca5d977..2ecb1b38f 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -194,7 +194,8 @@ which case the delimiting "/" is also optional and the gophertype defaults to "1". .PP .I selector -is the Gopher selector string. In the Gopher protocol, +is the Gopher selector string. +In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR). @@ -236,7 +237,8 @@ presence of the "@" character. .RI telnet:// ip_server / .PP The Telnet URL scheme is used to designate interactive text services that -may be accessed by the Telnet protocol. The final "/" character may be omitted. +may be accessed by the Telnet protocol. +The final "/" character may be omitted. The default port is 23. An example is . .SS "file \- Normal file" @@ -263,7 +265,8 @@ and .PP The second format (e.g., ) is a correct format for referring to -a local file. However, older standards did not permit this format, +a local file. +However, older standards did not permit this format, and some programs don't recognize this as a URI. A more portable syntax is to use an empty string as the server name, e.g., ; this form does the same thing @@ -353,7 +356,7 @@ The components of this URL are: .IP hostport 12 the LDAP server to query, written as a hostname optionally followed by a colon and the port number. -The default LDAP port is TCP port 389. +The default LDAP port is TCP port 389. If empty, the client determines which the LDAP server to use. .IP dn the LDAP Distinguished Name, which identifies @@ -364,15 +367,17 @@ RFC\ 2253 section 3). .IP attributes a comma-separated list of attributes to be returned; -see RFC\ 2251 section 4.1.5. +see RFC\ 2251 section 4.1.5. If omitted, all attributes should be returned. .IP scope specifies the scope of the search, which can be one of "base" (for a base object search), "one" (for a one-level search), -or "sub" (for a subtree search). If scope is omitted, "base" is assumed. +or "sub" (for a subtree search). +If scope is omitted, "base" is assumed. .IP filter specifies the search filter (subset of entries -to return). If omitted, all entries should be returned. +to return). +If omitted, all entries should be returned. See .UR http://www.ietf.org/rfc/rfc2254.txt RFC\ 2254 @@ -381,7 +386,8 @@ section 4. .IP extensions a comma-separated list of type=value pairs, where the =value portion may be omitted for options not -requiring it. An extension prefixed with a '!' is critical +requiring it. +An extension prefixed with a '!' is critical (must be supported to be valid), otherwise it's non-critical (optional). .PP LDAP queries are easiest to explain by example. @@ -463,7 +469,8 @@ All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits representing the octet code (you can use upper or lower case letters -for the hexadecimal digits). For example, a blank space must be escaped +for the hexadecimal digits). +For example, a blank space must be escaped as "%20", a tab character as "%09", and the "&" as "%26". Because the percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25". @@ -509,7 +516,7 @@ is preferred practice in Great Britain and hackers worldwide Jargon File's section on Hacker Writing Style, .IR http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html , for more information). -Older documents suggested inserting the prefix "URL:" +Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. .PP The URI syntax was designed to be unambiguous. @@ -574,7 +581,8 @@ Efforts to aid this convergence are encouraged. .PP A URI does not in itself pose a security threat. There is no general guarantee that a URL, which at one time -located a given resource, will continue to do so. Nor is there any +located a given resource, will continue to do so. +Nor is there any guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can only be obtained from the person(s) controlling that namespace and the @@ -583,13 +591,16 @@ resource in question. It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact -cause a possibly damaging remote operation to occur. The unsafe URL +cause a possibly damaging remote operation to occur. +The unsafe URL is typically constructed by specifying a port number other than that -reserved for the network protocol in question. The client -unwittingly contacts a site that is in fact running a different -protocol. The content of the URL contains instructions that, when +reserved for the network protocol in question. +The client unwittingly contacts a site that is in fact +running a different protocol. +The content of the URL contains instructions that, when interpreted according to this other protocol, cause an unexpected -operation. An example has been the use of a gopher URL to cause an +operation. +An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server. .PP Caution should be used when using any URL that specifies a port @@ -598,14 +609,15 @@ a number within the reserved space. .PP Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet -protocols) that these are not unescaped before transmission. This -might violate the protocol, but avoids the potential for such +protocols) that these are not unescaped before transmission. +This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed. .PP It is clearly unwise to use a URI that contains a password which is -intended to be secret. In particular, the use of a password within +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" diff --git a/man7/utf-8.7 b/man7/utf-8.7 index e978f9616..f6ff53da9 100644 --- a/man7/utf-8.7 +++ b/man7/utf-8.7 @@ -33,20 +33,22 @@ UTF-8 \- an ASCII compatible multi-byte Unicode encoding .SH DESCRIPTION The .B Unicode 3.0 -character set occupies a 16-bit code space. The most obvious +character set occupies a 16-bit code space. +The most obvious Unicode encoding (known as .BR UCS-2 ) -consists of a sequence of 16-bit words. Such strings can contain as +consists of a sequence of 16-bit words. +Such strings can contain as parts of many 16-bit characters bytes like '\\0' or '/' which have a special meaning in filenames and other C library function parameters. In addition, the majority of UNIX tools expects ASCII files and can't -read 16-bit words as characters without major modifications. For these -reasons, +read 16-bit words as characters without major modifications. +For these reasons, .B UCS-2 is not a suitable external encoding of .B Unicode -in filenames, text files, environment variables, etc. The -.BR "ISO 10646 Universal Character Set (UCS)" , +in filenames, text files, environment variables, etc. +The .BR "ISO 10646 Universal Character Set (UCS)" , a superset of Unicode, occupies even a 31-bit code space and the obvious .B UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. @@ -61,8 +63,8 @@ does not have these problems and is the common way in which .B Unicode is used on Unix-style operating systems. .SH PROPERTIES -The -.B UTF-8 +The +.B UTF-8 encoding has the following nice properties: .TP 0.2i * @@ -70,8 +72,9 @@ encoding has the following nice properties: characters 0x00000000 to 0x0000007f (the classic .B US-ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII -compatibility). This means that files and strings which contain only -7-bit ASCII characters have the same encoding under both +compatibility). +This means that files and strings which contain only +7-bit ASCII characters have the same encoding under both .B ASCII and .BR UTF-8 . @@ -90,7 +93,7 @@ The lexicographic sorting order of strings is preserved. .TP * -All possible 2^31 UCS codes can be encoded using +All possible 2^31 UCS codes can be encoded using .BR UTF-8 . .TP * @@ -98,12 +101,14 @@ The bytes 0xfe and 0xff are never used in the .B UTF-8 encoding. .TP -* +* The first byte of a multi-byte sequence which represents a single non-ASCII .B UCS character is always in the range 0xc0 to 0xfd and indicates how long -this multi-byte sequence is. All further bytes in a multi-byte sequence -are in the range 0x80 to 0xbf. This allows easy resynchronization and +this multi-byte sequence is. +All further bytes in a multi-byte sequence +are in the range 0x80 to 0xbf. +This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. .TP * @@ -116,14 +121,14 @@ standard specifies no characters above 0x10ffff, so Unicode characters can only be up to four bytes long in .BR UTF-8 . .SH ENCODING -The following byte sequences are used to represent a character. The -sequence to be used depends on the UCS code number of the character: +The following byte sequences are used to represent a character. +The sequence to be used depends on the UCS code number of the character: .TP 0.4i 0x00000000 \- 0x0000007F: .RI 0 xxxxxxx .TP 0x00000080 \- 0x000007FF: -.RI 110 xxxxx +.RI 110 xxxxx .RI 10 xxxxxx .TP 0x00000800 \- 0x0000FFFF: @@ -155,7 +160,8 @@ sequence to be used depends on the UCS code number of the character: The .I xxx bit positions are filled with the bits of the character code number in -binary representation. Only the shortest possible multi-byte sequence +binary representation. +Only the shortest possible multi-byte sequence which can represent the code number of the character can be used. .PP The @@ -181,7 +187,7 @@ encoded as: 11100010 10001001 10100000 = 0xe2 0x89 0xa0 .RE .SH "APPLICATION NOTES" -Users have to select a +Users have to select a .B UTF-8 locale, for example with .PP @@ -189,7 +195,7 @@ locale, for example with export LANG=en_GB.UTF-8 .RE .PP -in order to activate the +in order to activate the .B UTF-8 support in applications. .PP @@ -206,12 +212,12 @@ and programmers can then test the expression strcmp(nl_langinfo(CODESET), "UTF-8") == 0 .RE .PP -to determine whether a +to determine whether a .B UTF-8 locale has been selected and whether therefore all plaintext standard input and output, terminal communication, plaintext file content, filenames and environment -variables are encoded in +variables are encoded in .BR UTF-8 . .PP Programmers accustomed to single-byte encodings such as @@ -221,16 +227,18 @@ or have to be aware that two assumptions made so far are no longer valid in .B UTF-8 -locales. Firstly, a single byte does not necessarily correspond any -more to a single character. Secondly, since modern terminal emulators -in +locales. +Firstly, a single byte does not necessarily correspond any +more to a single character. +Secondly, since modern terminal emulators +in .B UTF-8 mode also support Chinese, Japanese, and Korean .B double-width characters as well as non-spacing .BR "combining characters" , outputting a single character does not necessarily advance the cursor -by one position as it did in +by one position as it did in .BR ASCII . Library functions such as .BR mbsrtowcs (3) @@ -243,9 +251,11 @@ The official ESC sequence to switch from an encoding scheme (as used for instance by VT100 terminals) to .B UTF-8 is ESC % G -("\\x1b%G"). The corresponding return sequence from +("\\x1b%G"). +The corresponding return sequence from .B UTF-8 -to ISO 2022 is ESC % @ ("\\x1b%@"). Other ISO 2022 sequences (such as +to ISO 2022 is ESC % @ ("\\x1b%@"). +Other ISO 2022 sequences (such as for switching the G0 and G1 sets) are not applicable in UTF-8 mode. .PP It can be hoped that in the foreseeable future, @@ -259,13 +269,14 @@ leading to a significantly richer environment for handling plain text. .SH SECURITY The .BR Unicode " and " UCS -standards require that producers of +standards require that producers of .B UTF-8 shall use the shortest form possible, e.g., producing a two-byte sequence with first byte 0xc0 is non-conforming. .B Unicode 3.1 has added the requirement that conforming programs must not accept -non-shortest forms in their input. This is for security reasons: if +non-shortest forms in their input. +This is for security reasons: if user input is checked for possible security violations, a program might check only for the .B ASCII diff --git a/man7/x25.7 b/man7/x25.7 index 6bc4a8c33..7df617a91 100644 --- a/man7/x25.7 +++ b/man7/x25.7 @@ -1,42 +1,47 @@ -.\" This man page is Copyright (C) 1998 Heiner Eisen. +.\" This man page is Copyright (C) 1998 Heiner Eisen. .\" Permission is granted to distribute possibly modified copies .\" of this page provided the header is included verbatim, .\" 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 $ -.TH X25 7 1998-12-01 "Linux Man Page" "Linux Programmer's Manual" +.TH X25 7 1998-12-01 "Linux Man Page" "Linux Programmer's Manual" .SH NAME -x25, PF_X25 \- ITU-T X.25 / ISO-8208 protocol interface. +x25, PF_X25 \- ITU-T X.25 / ISO-8208 protocol interface. .SH SYNOPSIS .B #include .br .B #include .sp -.B x25_socket = socket(PF_X25, SOCK_SEQPACKET, 0); +.B x25_socket = socket(PF_X25, SOCK_SEQPACKET, 0); .SH DESCRIPTION X25 sockets provide an interface to the X.25 packet layer protocol. This allows applications to communicate over a public X.25 data network as standardised by International Telecommunication Union's recommendation X.25 -(X.25 DTE-DCE mode). X25 sockets can also be used for communication +(X.25 DTE-DCE mode). +X25 sockets can also be used for communication without an intermediate X.25 network (X.25 DTE-DTE mode) as described in ISO-8208. .PP -Message boundaries are preserved \(em a -.BR read (2) +Message boundaries are preserved \(em a +.BR read (2) from a socket will retrieve the same chunk of data as output with the corresponding -.BR write (2) -to the peer socket. When necessary, the kernel takes care +.BR write (2) +to the peer socket. +When necessary, the kernel takes care of segmenting and re-assembling long messages by means of -the X.25 M-bit. There is no hard-coded upper limit for the -message size. However, re-assembling of a long message might fail if +the X.25 M-bit. +There is no hard-coded upper limit for the +message size. +However, re-assembling of a long message might fail if there is a temporary lack of system resources or when other constraints -(such as socket memory or buffer size limits) become effective. If that +(such as socket memory or buffer size limits) become effective. +If that occurs, the X.25 connection will be reset. .SH "SOCKET ADDRESSES" -The -.B AF_X25 +The +.B AF_X25 socket address family uses the .I struct sockaddr_x25 for representing network addresses as defined in ITU-T @@ -53,7 +58,7 @@ struct sockaddr_x25 { .PP .I sx25_addr contains a char array -.I x25_addr[] +.I x25_addr[] to be interpreted as a null-terminated string. .I sx25_addr.x25_addr[] consists of up to 15 (not counting the terminating 0) ASCII @@ -62,43 +67,50 @@ Only the decimal digit characters from `0' to `9' are allowed. .SH "SOCKET OPTIONS" The following X.25 specific socket options can be set by using .BR setsockopt (2) -and read with +and read with .BR getsockopt (2) -with the level parameter set to +with the level parameter set to .BR SOL_X25 . .TP .B X25_QBITINCL Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible by the -user. It expects an integer argument. If set to 0 (default), +user. +It expects an integer argument. +If set to 0 (default), the Q-bit is never set for outgoing packets and the Q-bit of incoming -packets is ignored. If set to 1, an additional first byte is prepended -to each message read from or written to the socket. For data read from +packets is ignored. +If set to 1, an additional first byte is prepended +to each message read from or written to the socket. +For data read from the socket, a 0 first byte indicates that the Q-bits of the corresponding -incoming data packets were not set. A first byte with value 1 indicates +incoming data packets were not set. +A first byte with value 1 indicates that the Q-bit of the corresponding incoming data packets was set. 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 +corresponding outgoing data packets will be set. +If the first byte is 0 the Q-bit will not be set. .SH BUGS -Plenty, as the X.25 PLP implementation is +Plenty, as the X.25 PLP implementation is .BR CONFIG_EXPERIMENTAL . .PP This man page is incomplete. .PP There is no dedicated application programmer's header file yet; -you need to include the kernel header file +you need to include the kernel header file .IR . -.B CONFIG_EXPERIMENTAL +.B CONFIG_EXPERIMENTAL might also imply that future versions of the -interface are not binary compatible. +interface are not binary compatible. .PP -X.25 N-Reset events are not propagated to the user process yet. Thus, -if a reset occurred, data might be lost without notice. +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 "SEE ALSO" .BR socket (2), .BR socket (7) .PP -Jonathan Simon Naylor: +Jonathan Simon Naylor: \(lqThe Re-Analysis and Re-Implementation of X.25.\(rq The URL is .RS diff --git a/man8/intro.8 b/man8/intro.8 index 6506fee77..7b4cccbbe 100644 --- a/man8/intro.8 +++ b/man8/intro.8 @@ -19,7 +19,7 @@ .\" License along with this manual; if not, write to the Free .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. -.\" +.\" .\" Modified Sat Jul 24 17:35:48 1993 by Rik Faith (faith@cs.unc.edu) .TH INTRO 8 1993-07-24 "Linux" "Linux Programmer's Manual" .SH NAME @@ -29,4 +29,5 @@ This chapter describes commands which either can be or are only used by the superuser, like daemons and hardware related commands. .SH AUTHORS Look at the header of the manual page for the author(s) and copyright -conditions. Note that these can be different from page to page! +conditions. +Note that these can be different from page to page! diff --git a/man8/ld.so.8 b/man8/ld.so.8 index 524cbc76e..917214b7d 100644 --- a/man8/ld.so.8 +++ b/man8/ld.so.8 @@ -39,7 +39,7 @@ Use of DT_RPATH is deprecated. .IP o Using the environment variable .BR LD_LIBRARY_PATH . -Except if the executable is a set-user-ID/set-group-ID binary, +Except if the executable is a set-user-ID/set-group-ID binary, in which case it is ignored. .IP o (ELF only) Using the DT_RUNPATH dynamic section attribute @@ -48,7 +48,8 @@ of the binary if present. From the cache file .IR /etc/ld.so.cache which contains a compiled list of candidate libraries previously found -in the augmented library path. If, however, the binary was linked with +in the augmented library path. +If, however, the binary was linked with .B \-z nodeflib linker option, libraries in the default library paths are skipped. .IP o @@ -95,12 +96,12 @@ There are four important environment variables. .B LD_LIBRARY_PATH A colon-separated list of directories in which to search for ELF libraries at execution-time. -Similar to the +Similar to the .B PATH environment variable. .TP .B LD_PRELOAD -A whitespace-separated list of additional, user-specified, ELF shared +A whitespace-separated list of additional, user-specified, ELF shared libraries to be loaded before all others. This can be used to selectively override functions in other shared libraries. For set-user-ID/set-group-ID ELF binaries, @@ -130,7 +131,7 @@ If set to non-empty string, warn about unresolved symbols. .TP .B LD_NOWARN (a.out only)(libc5) -Suppress warnings about a.out libraries with incompatible minor +Suppress warnings about a.out libraries with incompatible minor version numbers. .TP .B LD_BIND_NOT diff --git a/man8/ldconfig.8 b/man8/ldconfig.8 index 4e1759073..b5578ec07 100644 --- a/man8/ldconfig.8 +++ b/man8/ldconfig.8 @@ -71,22 +71,27 @@ determining which versions should have their links updated. .PP .B ldconfig will attempt to deduce the type of ELF libs (ie. libc5 or libc6/glibc) -based on what C libs, if any, the library was linked against. -.\" FIXME The following sentence looks suspect +based on what C libs, if any, the library was linked against. +.\" FIXME The following sentence looks suspect .\" (perhaps historical cruft) -- MTK, Jul 2005 Therefore, when making dynamic libraries, it is wise to explicitly link against libc (use \-lc). .PP Some existing libs do not contain enough information to allow the deduction of -their type. Therefore, the +their type. +Therefore, the .IR /etc/ld.so.conf -file format allows the specification of an expected type. This is +file format allows the specification of an expected type. +This is .I only -used for those ELF libs which we can not work out. The format +used for those ELF libs which we can not work out. +The format is "dirname=TYPE", where TYPE can be libc4, libc5, or libc6. -(This syntax also works on the command line.) Spaces are +(This syntax also works on the command line.) +Spaces are .I not -allowed. Also see the +allowed. +Also see the .B \-p option. .B ldconfig @@ -141,8 +146,9 @@ Change to and use as the root directory. .TP .B \-l -Library mode. Manually link individual libraries. Intended for -use by experts only. +Library mode. +Manually link individual libraries. +Intended for use by experts only. .TP .B \-p Print the lists of directories and candidate libraries stored in diff --git a/man8/nscd.8 b/man8/nscd.8 index 2ee5395ff..295f6f01c 100644 --- a/man8/nscd.8 +++ b/man8/nscd.8 @@ -22,9 +22,11 @@ /usr/sbin/nscd \- name service cache daemon .SH DESCRIPTION Nscd is a daemon that provides a cache for the most common name service -requests. The default configuration file, +requests. +The default configuration file, .IR /etc/nscd.conf , -determines the behavior of the cache daemon. See +determines the behavior of the cache daemon. +See .BR nscd.conf (5). Nscd provides cacheing for accesses of the @@ -42,7 +44,8 @@ and others. There are two caches for each database: a positive one for items found, and a negative one -for items not found. Each cache has a separate TTL (time-to-live) +for items not found. +Each cache has a separate TTL (time-to-live) period for its data. Note that the shadow file is specifically not cached. .BR getspnam (3) @@ -53,12 +56,14 @@ calls remain uncached as a result. will give you a list with all options and what they do. .SH NOTES Nscd doesn't know anything about the underlaying protocols for a -service. This also means, that if you change +service. +This also means, that if you change .I /etc/resolv.conf for DNS queries, nscd will continue to use the old one if you have configured .I /etc/nsswitch.conf -to use DNS for host lookups. In such a case, you need to restart +to use DNS for host lookups. +In such a case, you need to restart nscd. .SH "SEE ALSO" .BR nscd.conf (5), diff --git a/man8/sync.8 b/man8/sync.8 index 5aa839319..a9e3954bc 100644 --- a/man8/sync.8 +++ b/man8/sync.8 @@ -10,9 +10,10 @@ sync \- synchronize data on disk with memory .B "sync [\-\-help] [\-\-version]" .SH DESCRIPTION .B sync -writes any data buffered in memory out to disk. This can -include (but is not limited to) modified superblocks, modified inodes, -and delayed reads and writes. This must be implemented by the kernel; +writes any data buffered in memory out to disk. +This can include (but is not limited to) modified superblocks, +modified inodes, and delayed reads and writes. +This must be implemented by the kernel; The .B sync program does nothing but exercise the @@ -20,7 +21,8 @@ program does nothing but exercise the system call. .PP The kernel keeps data in memory to avoid doing (relatively slow) disk -reads and writes. This improves performance, but if the computer +reads and writes. +This improves performance, but if the computer crashes, data may be lost or the filesystem corrupted as a result. .B sync ensures that everything in memory is written to disk. diff --git a/man8/tzselect.8 b/man8/tzselect.8 index ec5f17d3f..d1990668c 100644 --- a/man8/tzselect.8 +++ b/man8/tzselect.8 @@ -37,7 +37,7 @@ descriptive comments. \fBTZDIR\fP\fI/\fP\fITZ\fP Time zone data file for time zone \fITZ\fP. .SH "EXIT STATUS" -The exit status is zero if a time zone was successfully obtained +The exit status is zero if a time zone was successfully obtained from the user, non-zero otherwise. .SH "SEE ALSO" .BR tzfile (5), diff --git a/man9/ksoftirqd.9 b/man9/ksoftirqd.9 index 8db23df10..94183e978 100644 --- a/man9/ksoftirqd.9 +++ b/man9/ksoftirqd.9 @@ -10,12 +10,12 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel is constantly changing, this manual page may .\" be incorrect or out-of-date. The author(s) assume no responsibility .\" for errors or omissions, or for damages resulting from the use of the .\" information contained herein. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -25,9 +25,11 @@ ksoftirqd \- Softirq daemon .SH DESCRIPTION .B ksoftirqd is a per-cpu kernel thread that runs when the machine is under heavy -soft-interrupt load. Soft interrupts are normally serviced on return from +soft-interrupt load. +Soft interrupts are normally serviced on return from a hard interrupt, but it's possible for soft interrupts to be triggered -more quickly than they can be serviced. If a soft interrupt is triggered +more quickly than they can be serviced. +If a soft interrupt is triggered for a second time while soft interrupts are being handled, the .B ksoftirq daemon is triggered to handle the soft interrupts in process context.