diff options
Diffstat (limited to 'lib/libc/sys')
63 files changed, 345 insertions, 176 deletions
diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 index 387c7fc..5b844c6 100644 --- a/lib/libc/sys/accept.2 +++ b/lib/libc/sys/accept.2 @@ -76,7 +76,8 @@ connections are present on the queue, returns an error as described below. The accepted socket may not be used -to accept more connections. The original socket +to accept more connections. +The original socket .Fa s remains open. .Pp @@ -130,7 +131,8 @@ For some applications, performance may be enhanced by using an .Xr accept_filter 9 to pre-process incoming connections. .Sh RETURN VALUES -The call returns \-1 on error. If it succeeds, it returns a non-negative +The call returns \-1 on error. +If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. .Sh ERRORS The diff --git a/lib/libc/sys/aio_error.2 b/lib/libc/sys/aio_error.2 index 02b0caa..91bb097 100644 --- a/lib/libc/sys/aio_error.2 +++ b/lib/libc/sys/aio_error.2 @@ -45,9 +45,11 @@ associated with the structure pointed to by .Sh RETURN VALUES If the asynchronous I/O request has completed successfully, .Fn aio_error -returns 0. If the request has not yet completed, +returns 0. +If the request has not yet completed, .Er EINPROGRESS -is returned. If the request has completed unsuccessfully the error +is returned. +If the request has completed unsuccessfully the error status is returned as described in .Xr read 2 , .Xr write 2 , diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 index 0358b23..047661b 100644 --- a/lib/libc/sys/aio_read.2 +++ b/lib/libc/sys/aio_read.2 @@ -85,7 +85,8 @@ The Asynchronous I/O Control Block structure pointed to by and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the -operation has completed. For this reason, use of auto (stack) variables +operation has completed. +For this reason, use of auto (stack) variables for these objects is discouraged. .Pp The asynchronous I/O control buffer @@ -122,7 +123,8 @@ system call is not supported. .Pp The following conditions may be synchronously detected when the .Fn aio_read -system call is made, or asynchronously, at any time thereafter. If they +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, .Fn aio_read returns -1 and sets diff --git a/lib/libc/sys/aio_suspend.2 b/lib/libc/sys/aio_suspend.2 index ec5e5db..06d278a 100644 --- a/lib/libc/sys/aio_suspend.2 +++ b/lib/libc/sys/aio_suspend.2 @@ -50,7 +50,8 @@ The argument is an array of .Fa niocb -pointers to asynchronous I/O requests. Array members containing +pointers to asynchronous I/O requests. +Array members containing NULL will be silently ignored. .Pp If @@ -58,7 +59,8 @@ If is a non-nil pointer, it specifies a maximum interval to suspend. If .Fa timeout -is a nil pointer, the suspend blocks indefinitely. To effect a +is a nil pointer, the suspend blocks indefinitely. +To effect a poll, the .Fa timeout should point to a zero-value timespec structure. @@ -66,7 +68,8 @@ should point to a zero-value timespec structure. If one or more of the specified asynchronous I/O requests have completed, .Fn aio_suspend -returns 0. Otherwise it returns -1 and sets +returns 0. +Otherwise it returns -1 and sets .Va errno to indicate the error, as enumerated below. .Sh ERRORS diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2 index e417f82..5fe8d98 100644 --- a/lib/libc/sys/aio_write.2 +++ b/lib/libc/sys/aio_write.2 @@ -47,7 +47,8 @@ to the descriptor .Fa iocb->aio_fildes . The call returns immediately after the write request has been enqueued to the descriptor; the write may or may not have completed at the time -the call returns. If the request could not be enqueued, generally due +the call returns. +If the request could not be enqueued, generally due to invalid arguments, the call returns without having enqueued the request. .Pp @@ -57,7 +58,8 @@ is set for .Fa iocb->aio_fildes , .Fn aio_write operations append to the file in the same order as the calls were -made. If +made. +If .Dv O_APPEND is not set for the file descriptor, the write operation will occur at the absolute position from the beginning of the file plus @@ -89,7 +91,8 @@ The Asynchronous I/O Control Block structure pointed to by and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the -operation has completed. For this reason, use of auto (stack) variables +operation has completed. +For this reason, use of auto (stack) variables for these objects is discouraged. .Pp The asynchronous I/O control buffer @@ -124,7 +127,8 @@ system call is not supported. .Pp The following conditions may be synchronously detected when the .Fn aio_write -system call is made, or asynchronously, at any time thereafter. If they +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, .Fn aio_write returns -1 and sets diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 index 66b4d56..7da7092 100644 --- a/lib/libc/sys/chmod.2 +++ b/lib/libc/sys/chmod.2 @@ -132,7 +132,8 @@ then the owner of any new files and sub-directories created within this directory are set to be the same as the owner of that directory. If this function is enabled, new directories will inherit -the bit from their parents. Execute bits are removed from +the bit from their parents. +Execute bits are removed from the file, and it will not be given to root. This behavior does not change the requirements for the user to be allowed to write the file, but only the eventual diff --git a/lib/libc/sys/chroot.2 b/lib/libc/sys/chroot.2 index b2c3b4e..7142e0d 100644 --- a/lib/libc/sys/chroot.2 +++ b/lib/libc/sys/chroot.2 @@ -97,7 +97,8 @@ Any other value for .Ql kern.chroot_allow_open_directories will bypass the check for open directories .Pp -Upon successful completion, a value of 0 is returned. Otherwise, +Upon successful completion, a value of 0 is returned. +Otherwise, a value of -1 is returned and .Va errno is set to indicate an error. diff --git a/lib/libc/sys/clock_gettime.2 b/lib/libc/sys/clock_gettime.2 index f519094..a608870 100644 --- a/lib/libc/sys/clock_gettime.2 +++ b/lib/libc/sys/clock_gettime.2 @@ -95,7 +95,8 @@ system call even when the system is secure. .Pp The resolution (granularity) of a clock is returned by the .Fn clock_getres -system call. This value is placed in a (non-NULL) +system call. +This value is placed in a (non-NULL) .Fa *tp . .Sh RETURN VALUES .Rv -std diff --git a/lib/libc/sys/close.2 b/lib/libc/sys/close.2 index 26b4fbd..04dbe3d 100644 --- a/lib/libc/sys/close.2 +++ b/lib/libc/sys/close.2 @@ -83,7 +83,8 @@ all descriptors for the new child process reference the same objects as they did in the parent before the fork. If a new process is then to be run using .Xr execve 2 , -the process would normally inherit these descriptors. Most +the process would normally inherit these descriptors. +Most of the descriptors can be rearranged with .Xr dup2 2 or deleted with diff --git a/lib/libc/sys/dup.2 b/lib/libc/sys/dup.2 index f4da9f5..ef903f9 100644 --- a/lib/libc/sys/dup.2 +++ b/lib/libc/sys/dup.2 @@ -59,7 +59,8 @@ the calling process The argument .Fa oldd is a small non-negative integer index in -the per-process descriptor table. The value must be less +the per-process descriptor table. +The value must be less than the size of the table, which is returned by .Xr getdtablesize 2 . The new descriptor returned by the call @@ -96,7 +97,8 @@ In .Fn dup2 , the value of the new descriptor .Fa newd -is specified. If this descriptor is already in use and +is specified. +If this descriptor is already in use and .Fa oldd \*(Ne .Fa newd , diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 index 9b0f22c..427f9ab 100644 --- a/lib/libc/sys/execve.2 +++ b/lib/libc/sys/execve.2 @@ -58,7 +58,8 @@ This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) -and initialized data pages. Additional pages may be specified +and initialized data pages. +Additional pages may be specified by the header to be initialized with zero data; see .Xr elf 5 and @@ -87,7 +88,8 @@ and the name of the originally file becomes the second argument; otherwise, the name of the originally .Sy execve Ap d -file becomes the first argument. The original arguments are shifted over to +file becomes the first argument. +The original arguments are shifted over to become the subsequent arguments. The zeroth argument is set to the specified .Em interpreter . @@ -97,7 +99,8 @@ The argument is a pointer to a null-terminated array of character pointers to null-terminated character strings. These strings construct the argument list to be made available to the new -process. At least one argument must be present in +process. +At least one argument must be present in the array; by custom, the first element should be the name of the executed program (for example, the last component of .Fa path ) . @@ -159,7 +162,8 @@ These values may be used in changing the effective IDs later (see .Pp The set-ID bits are not honored if the respective file system has the .Cm nosuid -option enabled or if the new process file is an interpreter file. Syscall +option enabled or if the new process file is an interpreter file. +Syscall tracing is disabled if effective IDs are changed. .Pp The new process also inherits the following attributes from diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 index 92b7440..804b4ab 100644 --- a/lib/libc/sys/fcntl.2 +++ b/lib/libc/sys/fcntl.2 @@ -52,7 +52,8 @@ The argument .Fa fd is a descriptor to be operated on by .Fa cmd -as described below. Depending on the value of +as described below. +Depending on the value of .Fa cmd , .Fn fcntl can take an additional third argument @@ -157,8 +158,10 @@ corresponds to the flag of .Xr open 2 . .It Dv O_DIRECT -Minimize or eliminate the cache effects of reading and writing. The system -will attempt to avoid caching the data you read or write. If it cannot +Minimize or eliminate the cache effects of reading and writing. +The system +will attempt to avoid caching the data you read or write. +If it cannot avoid caching the data, it will minimize the impact the data has on the cache. Use of this flag can drastically reduce performance if not used with care. .It Dv O_ASYNC diff --git a/lib/libc/sys/flock.2 b/lib/libc/sys/flock.2 index 1d095bd..acb9741 100644 --- a/lib/libc/sys/flock.2 +++ b/lib/libc/sys/flock.2 @@ -93,7 +93,8 @@ after other processes have gained and released the lock). .Pp Requesting a lock on an object that is already locked normally causes the caller to be blocked until the lock may be -acquired. If +acquired. +If .Dv LOCK_NB is included in .Fa operation , @@ -102,13 +103,15 @@ the error .Er EWOULDBLOCK will be returned. .Sh NOTES -Locks are on files, not file descriptors. That is, file descriptors +Locks are on files, not file descriptors. +That is, file descriptors duplicated through .Xr dup 2 or .Xr fork 2 do not result in multiple instances of a lock, but rather multiple -references to a single lock. If a process holding a lock on a file +references to a single lock. +If a process holding a lock on a file forks and the child explicitly unlocks the file, the parent will lose its lock. .Pp diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 index a1adafd..5dd6413 100644 --- a/lib/libc/sys/fork.2 +++ b/lib/libc/sys/fork.2 @@ -84,7 +84,8 @@ Upon successful completion, .Fn fork returns a value of 0 to the child process and returns the process ID of the child -process to the parent process. Otherwise, a value of -1 is returned +process to the parent process. +Otherwise, a value of -1 is returned to the parent process, no child process is created, and the global variable .Va errno diff --git a/lib/libc/sys/getdtablesize.2 b/lib/libc/sys/getdtablesize.2 index cda45fa..b53571e 100644 --- a/lib/libc/sys/getdtablesize.2 +++ b/lib/libc/sys/getdtablesize.2 @@ -46,7 +46,8 @@ .Fn getdtablesize void .Sh DESCRIPTION Each process has a fixed size descriptor table, -which is guaranteed to have at least 20 slots. The entries in +which is guaranteed to have at least 20 slots. +The entries in the descriptor table are numbered with small integers starting at 0. The .Fn getdtablesize diff --git a/lib/libc/sys/getitimer.2 b/lib/libc/sys/getitimer.2 index 9949983..babcd3b 100644 --- a/lib/libc/sys/getitimer.2 +++ b/lib/libc/sys/getitimer.2 @@ -102,7 +102,8 @@ system clock are rounded up to this resolution .Pp The .Dv ITIMER_REAL -timer decrements in real time. A +timer decrements in real time. +A .Dv SIGALRM signal is delivered when this timer expires. @@ -110,7 +111,8 @@ delivered when this timer expires. The .Dv ITIMER_VIRTUAL timer decrements in process virtual time. -It runs only when the process is executing. A +It runs only when the process is executing. +A .Dv SIGVTALRM signal is delivered when it expires. @@ -118,7 +120,8 @@ is delivered when it expires. The .Dv ITIMER_PROF timer decrements both in process virtual time and -when the system is running on behalf of the process. It is designed +when the system is running on behalf of the process. +It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. Each time the @@ -126,7 +129,8 @@ Each time the timer expires, the .Dv SIGPROF signal is -delivered. Because this signal may interrupt in-progress +delivered. +Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls. .Pp diff --git a/lib/libc/sys/getlogin.2 b/lib/libc/sys/getlogin.2 index c7d03c7..9a254f3 100644 --- a/lib/libc/sys/getlogin.2 +++ b/lib/libc/sys/getlogin.2 @@ -76,7 +76,8 @@ except the caller must provide the buffer with length .Fa len bytes -to hold the result. The buffer should be at least +to hold the result. +The buffer should be at least .Dv MAXLOGNAME bytes in length. .Pp @@ -103,7 +104,8 @@ Making a .Fn setsid system call is the .Em ONLY -way to do this. The +way to do this. +The .Xr daemon 3 function calls .Fn setsid diff --git a/lib/libc/sys/getpriority.2 b/lib/libc/sys/getpriority.2 index 0b580dc..6e7ab2a 100644 --- a/lib/libc/sys/getpriority.2 +++ b/lib/libc/sys/getpriority.2 @@ -84,16 +84,19 @@ denotes the current process, process group, or user. The .Fa prio argument -is a value in the range -20 to 20. The default priority is 0; +is a value in the range -20 to 20. +The default priority is 0; lower priorities cause more favorable scheduling. .Pp The .Fn getpriority system call returns the highest priority (lowest numerical value) -enjoyed by any of the specified processes. The +enjoyed by any of the specified processes. +The .Fn setpriority system call sets the priorities of all of the specified processes -to the specified value. Only the super-user may lower priorities. +to the specified value. +Only the super-user may lower priorities. .Sh RETURN VALUES Since .Fn getpriority diff --git a/lib/libc/sys/getrlimit.2 b/lib/libc/sys/getrlimit.2 index 159989a..1e67083 100644 --- a/lib/libc/sys/getrlimit.2 +++ b/lib/libc/sys/getrlimit.2 @@ -103,11 +103,13 @@ this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system. .El .Pp -A resource limit is specified as a soft limit and a hard limit. When a +A resource limit is specified as a soft limit and a hard limit. +When a soft limit is exceeded a process may receive a signal (for example, if the cpu time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies -its resource limit). The +its resource limit). +The .Vt rlimit structure is used to specify the hard and soft limits on a resource, .Bd -literal -offset indent @@ -117,7 +119,8 @@ struct rlimit { }; .Ed .Pp -Only the super-user may raise the maximum limits. Other users +Only the super-user may raise the maximum limits. +Other users may only alter .Fa rlim_cur within the range from 0 to @@ -152,7 +155,8 @@ A file I/O operation that would create a file larger that the process' soft limit will cause the write to fail and a signal .Dv SIGXFSZ to be -generated; this normally terminates the process, but may be caught. When +generated; this normally terminates the process, but may be caught. +When the soft cpu time limit is exceeded, a signal .Dv SIGXCPU is sent to the diff --git a/lib/libc/sys/getrusage.2 b/lib/libc/sys/getrusage.2 index 6a529c1..9bafce3 100644 --- a/lib/libc/sys/getrusage.2 +++ b/lib/libc/sys/getrusage.2 @@ -99,7 +99,8 @@ an .Dq integral value indicating the amount of memory used by the text segment -that was also shared among other processes. This value is expressed +that was also shared among other processes. +This value is expressed in units of kilobytes * ticks-of-execution. Ticks are statistics clock ticks. The statistics clock has a frequency of diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2 index 68c5bdb..0c285ad 100644 --- a/lib/libc/sys/getsockname.2 +++ b/lib/libc/sys/getsockname.2 @@ -51,7 +51,8 @@ The system call returns the current .Fa name -for the specified socket. The +for the specified socket. +The .Fa namelen argument should be initialized to indicate the amount of space pointed to by diff --git a/lib/libc/sys/getsockopt.2 b/lib/libc/sys/getsockopt.2 index b30eba9..ccc71e3 100644 --- a/lib/libc/sys/getsockopt.2 +++ b/lib/libc/sys/getsockopt.2 @@ -56,7 +56,8 @@ and system calls manipulate the .Em 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 .Dq socket level. @@ -69,7 +70,8 @@ is specified as .Dv 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 .Tn TCP protocol, @@ -89,14 +91,16 @@ are used to access option values for For .Fn 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 .Fn getsockopt , .Fa optlen is a value-result argument, initially containing the size of the buffer pointed to by .Fa optval , and modified on return to indicate the actual size of -the value returned. If no option value is +the value returned. +If no option value is to be supplied or returned, .Fa optval may be NULL. @@ -179,14 +183,16 @@ This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. .Dv SO_KEEPALIVE enables the -periodic transmission of messages on a connected socket. Should the +periodic transmission of messages on a connected socket. +Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a .Dv SIGPIPE signal when attempting to send data. .Dv SO_DONTROUTE indicates that outgoing messages should -bypass the standard routing facilities. Instead, messages are directed +bypass the standard routing facilities. +Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. .Pp diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 index 3812e54..f104253 100644 --- a/lib/libc/sys/gettimeofday.2 +++ b/lib/libc/sys/gettimeofday.2 @@ -58,8 +58,10 @@ zone is obtained with the .Fn gettimeofday system call, and set with the .Fn settimeofday -system call. The time is expressed in seconds and microseconds -since midnight (0 hour), January 1, 1970. The resolution of the system +system call. +The time is expressed in seconds and microseconds +since midnight (0 hour), January 1, 1970. +The resolution of the system clock is hardware dependent, and the time may be updated continuously or in .Dq ticks . diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 index 6be0ac0..b16c3ea 100644 --- a/lib/libc/sys/intro.2 +++ b/lib/libc/sys/intro.2 @@ -322,7 +322,8 @@ The host you were connected to crashed and rebooted. .It Er 53 ECONNABORTED Em "Software caused connection abort" . A connection abort was caused internal to your host machine. .It Er 54 ECONNRESET Em "Connection reset by peer" . -A connection was forcibly closed by a peer. This normally +A connection was forcibly closed by a peer. +This normally results from a loss of the connection on the remote socket due to a timeout or a reboot. .It Er 55 ENOBUFS Em "\&No buffer space available" . @@ -353,11 +354,13 @@ A or .Xr send 2 request failed because the connected party did not -properly respond after a period of time. (The timeout +properly respond after a period of time. +(The timeout period is dependent on the communication protocol.) .It Er 61 ECONNREFUSED Em "Connection refused" . No connection could be made because the target machine actively -refused it. This usually results from trying to connect +refused it. +This usually results from trying to connect to a service that is inactive on the foreign host. .It Er 62 ELOOP Em "Too many levels of symbolic links" . A path name lookup involved more than 32 @@ -462,7 +465,8 @@ at run-time. .Bl -tag -width Ds .It Process ID . Each active process in the system is uniquely identified by a non-negative -integer called a process ID. The range of this ID is from 0 to 99999. +integer called a process ID. +The range of this ID is from 0 to 99999. .It Parent process ID A new process is created by a currently active process; (see .Xr fork 2 ) . @@ -472,8 +476,10 @@ the parent process ID of each child is set to the ID of a system process, .Xr init 8 . .It Process Group Each active process is a member of a process group that is identified by -a non-negative integer called the process group ID. This is the process -ID of the group leader. This grouping permits the signaling of related +a non-negative integer called the process group ID. +This is the process +ID of the group leader. +This grouping permits the signaling of related processes (see .Xr termios 4 ) and the job control mechanisms of @@ -527,7 +533,8 @@ termed the real user ID. .Pp Each user is also a member of one or more groups. One of these groups is distinguished from others and -used in implementing accounting facilities. The positive +used in implementing accounting facilities. +The positive integer corresponding to this distinguished group is termed the real group ID. .Pp @@ -544,7 +551,8 @@ group IDs, and it is unspecified whether the effective group ID is a member of the list.) .Pp The effective user ID and effective group ID are initially the -process's real user ID and real group ID respectively. Either +process's real user ID and real group ID respectively. +Either may be modified through execution of a set-user-ID or set-group-ID file (possibly by one its ancestors) (see .Xr execve 2 ) . @@ -553,7 +561,8 @@ list) is duplicated, so that the execution of a set-group-ID program does not result in the loss of the original (real) group ID. .Pp The group access list is a set of group IDs -used only in determining resource accessibility. Access checks +used only in determining resource accessibility. +Access checks are performed as described below in ``File Access Permissions''. .It "Saved Set User ID and Saved Set Group ID" When a process executes a new file, the effective user ID is set @@ -625,12 +634,14 @@ If a path name begins with a slash, the path search begins at the .Em root directory. Otherwise, the search begins from the current working directory. -A slash by itself names the root directory. An empty +A slash by itself names the root directory. +An empty pathname refers to the current directory. .It Directory A directory is a special type of file that contains entries that are references to other files. -Directory entries are called links. By convention, a directory +Directory entries are called links. +By convention, a directory contains at least two links, .Ql .\& and @@ -639,32 +650,38 @@ referred to as .Em dot and .Em dot-dot -respectively. Dot refers to the directory itself and +respectively. +Dot refers to the directory itself and dot-dot refers to its parent directory. .It "Root Directory and Current Working Directory" Each process has associated with it a concept of a root directory and a current working directory for the purpose of resolving path -name searches. A process's root directory need not be the root +name searches. +A process's root directory need not be the root directory of the root file system. .It File Access Permissions Every file in the file system has a set of access permissions. These permissions are used in determining whether a process may perform a requested operation on the file (such as opening -a file for writing). Access permissions are established at the -time a file is created. They may be changed at some later time +a file for writing). +Access permissions are established at the +time a file is created. +They may be changed at some later time through the .Xr chmod 2 call. .Pp File access is broken down according to whether a file may be: read, -written, or executed. Directory files use the execute +written, or executed. +Directory files use the execute permission to control if the directory may be searched. .Pp File access permissions are interpreted by the system as they apply to three different classes of users: the owner of the file, those users in the file's group, anyone else. Every file has an independent set of access permissions for -each of these classes. When an access check is made, the system +each of these classes. +When an access check is made, the system decides if permission should be granted by checking the access information applicable to the caller. .Pp @@ -707,9 +724,12 @@ for more information about the types available and their properties. .Pp Each instance of the system supports some number of sets of -communications protocols. Each protocol set supports addresses -of a certain format. An Address Family is the set of addresses -for a specific group of protocols. Each socket has an address +communications protocols. +Each protocol set supports addresses +of a certain format. +An Address Family is the set of addresses +for a specific group of protocols. +Each socket has an address chosen from the address family in which the socket was created. .El .Sh SEE ALSO diff --git a/lib/libc/sys/ioctl.2 b/lib/libc/sys/ioctl.2 index b6de37e..e5a902f 100644 --- a/lib/libc/sys/ioctl.2 +++ b/lib/libc/sys/ioctl.2 @@ -50,7 +50,7 @@ The .Fn ioctl system call manipulates the underlying device parameters of special files. In particular, many operating -characteristics of character special files (e.g. terminals) +characteristics of character special files (e.g.\& terminals) may be controlled with .Fn ioctl requests. diff --git a/lib/libc/sys/issetugid.2 b/lib/libc/sys/issetugid.2 index 5b0e6e7..a9b234b 100644 --- a/lib/libc/sys/issetugid.2 +++ b/lib/libc/sys/issetugid.2 @@ -75,7 +75,8 @@ system call (or other library code that calls fork, such as It is assumed that a program that clears all privileges as it prepares to execute another will also reset the environment, hence the .Dq tainted -status will not be passed on. This is important for programs such as +status will not be passed on. +This is important for programs such as .Xr su 1 which begin setuid but need to be able to create an untainted process. .Sh ERRORS diff --git a/lib/libc/sys/kldnext.2 b/lib/libc/sys/kldnext.2 index 4cf443c..9588647c 100644 --- a/lib/libc/sys/kldnext.2 +++ b/lib/libc/sys/kldnext.2 @@ -51,7 +51,8 @@ is the last file loaded. The .Fn kldnext system call -returns the fileid of the next kld file (see DESCRIPTION) or 0. If an error +returns the fileid of the next kld file (see DESCRIPTION) or 0. +If an error occurs, .Va errno is set to indicate the error. diff --git a/lib/libc/sys/kldstat.2 b/lib/libc/sys/kldstat.2 index 5f91520..946417a 100644 --- a/lib/libc/sys/kldstat.2 +++ b/lib/libc/sys/kldstat.2 @@ -92,7 +92,8 @@ The file was not found (probably not loaded). .It Bq Er EINVAL The version specified in the .Fa version -field of stat is not the proper version. You would need to rebuild world, the +field of stat is not the proper version. +You would need to rebuild world, the kernel, or your application, if this error occurs, given that you did properly fill in the .Fa version diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2 index 4baaf69..5e84e8a 100644 --- a/lib/libc/sys/kqueue.2 +++ b/lib/libc/sys/kqueue.2 @@ -124,15 +124,18 @@ specified unlike If .Fa timeout is a non-NULL pointer, it specifies a maximum interval to wait -for an event, which will be interpreted as a struct timespec. If +for an event, which will be interpreted as a struct timespec. +If .Fa timeout is a NULL pointer, .Fn kevent -waits indefinitely. To effect a poll, the +waits indefinitely. +To effect a poll, the .Fa timeout argument should be non-NULL, pointing to a zero-valued .Va timespec -structure. The same array may be used for the +structure. +The same array may be used for the .Fa changelist and .Fa eventlist . @@ -165,7 +168,8 @@ Value used to identify this event. The exact interpretation is determined by the attached filter, but often is a file descriptor. .It filter -Identifies the kernel filter used to process this event. The pre-defined +Identifies the kernel filter used to process this event. +The pre-defined system filters are described below. .It flags Actions to perform on the event. @@ -182,9 +186,11 @@ The field can contain the following values: .Bl -tag -width XXXEV_ONESHOT .It EV_ADD -Adds the event to the kqueue. Re-adding an existing event +Adds the event to the kqueue. +Re-adding an existing event will modify the parameters of the original event, and not result -in a duplicate entry. Adding an event automatically enables it, +in a duplicate entry. +Adding an event automatically enables it, unless overridden by the EV_DISABLE flag. .It EV_ENABLE Permit @@ -193,19 +199,23 @@ to return the event if it is triggered. .It EV_DISABLE Disable the event so .Fn kevent -will not return it. The filter itself is not disabled. +will not return it. +The filter itself is not disabled. .It EV_DELETE -Removes the event from the kqueue. Events which are attached to +Removes the event from the kqueue. +Events which are attached to file descriptors are automatically deleted on the last close of the descriptor. .It EV_ONESHOT Causes the event to return only the first occurrence of the filter -being triggered. After the user retrieves the event from the kqueue, +being triggered. +After the user retrieves the event from the kqueue, it is deleted. .It EV_CLEAR After the event is retrieved by the user, its state is reset. This is useful for filters which report state transitions -instead of the current state. Note that some filters may automatically +instead of the current state. +Note that some filters may automatically set this flag internally. .It EV_EOF Filters may set this flag to indicate filter-specific EOF condition. @@ -283,7 +293,8 @@ contains the number of bytes available. .El .It EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever -it is possible to write to the descriptor. For sockets, pipes +it is possible to write to the descriptor. +For sockets, pipes and fifos, .Va data will contain the amount of space remaining in the write buffer. @@ -319,7 +330,8 @@ Alternatively, a kevent structure may be initialized, with containing the descriptor of the kqueue, and the address of the kevent structure placed in the .Va aio_lio_opcode -field of the AIO request. However, this approach will not work on +field of the AIO request. +However, this approach will not work on architectures with 64-bit pointers, and should be considered deprecated. .It EVFILT_VNODE Takes a file descriptor as the identifier and the events to watch for in @@ -371,7 +383,8 @@ or similar call. .It NOTE_TRACK Follow a process across .Fn fork -calls. The parent process will return with NOTE_TRACK set in the +calls. +The parent process will return with NOTE_TRACK set in the .Va fflags field, while the child process will return with NOTE_CHILD set in .Va fflags @@ -392,9 +405,11 @@ This coexists with the .Fn signal and .Fn sigaction -facilities, and has a lower precedence. The filter will record +facilities, and has a lower precedence. +The filter will record all attempts to deliver a signal to a process, even if the signal has -been marked as SIG_IGN. Event notification happens after normal +been marked as SIG_IGN. +Event notification happens after normal signal delivery processing. .Va data returns the number of times the signal has occurred since the last call to diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 index 9c064b4..f39768a 100644 --- a/lib/libc/sys/link.2 +++ b/lib/libc/sys/link.2 @@ -170,5 +170,6 @@ function appeared in The .Fn link system call traditionally allows the super-user to link directories which -corrupts the file system coherency. This implementation no longer permits +corrupts the file system coherency. +This implementation no longer permits it. diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 index 30cf1e0..13bcf21 100644 --- a/lib/libc/sys/lseek.2 +++ b/lib/libc/sys/lseek.2 @@ -101,7 +101,8 @@ If data is later written at this point, subsequent reads of the data in the gap return bytes of zeros (until data is actually written into the gap). .Pp -Some devices are incapable of seeking. The value of the pointer +Some devices are incapable of seeking. +The value of the pointer associated with such a device is undefined. .Sh RETURN VALUES Upon successful completion, diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2 index 25cb5c7..ea7e8ef 100644 --- a/lib/libc/sys/madvise.2 +++ b/lib/libc/sys/madvise.2 @@ -70,23 +70,28 @@ pages immediately preceding a given page when it is faulted in. .It Dv MADV_WILLNEED Causes pages that are in a given virtual address range to temporarily have higher priority, and if they are in -memory, decrease the likelihood of them being freed. Additionally, +memory, decrease the likelihood of them being freed. +Additionally, the pages that are already in memory will be immediately mapped into the process, thereby eliminating unnecessary overhead of going through -the entire process of faulting the pages in. This WILL NOT fault +the entire process of faulting the pages in. +This WILL NOT fault pages in from backing store, but quickly map the pages already in memory into the calling process. .It Dv MADV_DONTNEED Allows the VM system to decrease the in-memory priority -of pages in the specified range. Additionally future references to +of pages in the specified range. +Additionally future references to this address range will incur a page fault. .It Dv MADV_FREE Gives the VM system the freedom to free pages, and tells the system that information in the specified page range -is no longer important. This is an efficient way of allowing +is no longer important. +This is an efficient way of allowing .Xr malloc 3 to free pages anywhere in the address space, while keeping the address space -valid. The next time that the page is referenced, the page might be demand +valid. +The next time that the page is referenced, the page might be demand zeroed, or might contain the data that was there before the .Dv MADV_FREE call. @@ -95,9 +100,11 @@ page the information back in from backing store until the page is modified again. .It Dv MADV_NOSYNC Request that the system not flush the data associated with this map to -physical backing store unless it needs to. Typically this prevents the +physical backing store unless it needs to. +Typically this prevents the file system update daemon from gratuitously writing pages dirtied -by the VM system to physical disk. Note that VM/file system coherency is +by the VM system to physical disk. +Note that VM/file system coherency is always maintained, this feature simply ensures that the mapped data is only flush when it needs to be, usually by the system pager. .Pp @@ -106,14 +113,17 @@ memory area to communicate between processes (IPC) and do not particularly need the data being stored in that area to be physically written to disk. With this feature you get the equivalent performance with mmap that you would expect to get with SysV shared memory calls, but in a more controllable -and less restrictive manner. However, note that this feature is not portable +and less restrictive manner. +However, note that this feature is not portable across UNIX platforms (though some may do the right thing by default). For more information see the MAP_NOSYNC section of .Xr mmap 2 .It Dv MADV_AUTOSYNC Undoes the effects of MADV_NOSYNC for any future pages dirtied within the -address range. The effect on pages already dirtied is indeterminate - they -may or may not be reverted. You can guarantee reversion by using the +address range. +The effect on pages already dirtied is indeterminate - they +may or may not be reverted. +You can guarantee reversion by using the .Xr msync 2 or .Xr fsync 2 diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 index 8d6cfd7..798396e 100644 --- a/lib/libc/sys/mmap.2 +++ b/lib/libc/sys/mmap.2 @@ -181,7 +181,7 @@ it. You can test file fragmentation by observing the KB/t (kilobytes per transfer) results from an .Dq Li iostat 1 -while reading a large file sequentially, e.g. using +while reading a large file sequentially, e.g.\& using .Dq Li dd if=filename of=/dev/null bs=32k . .Pp The diff --git a/lib/libc/sys/modnext.2 b/lib/libc/sys/modnext.2 index b512b7b..3a6f69b 100644 --- a/lib/libc/sys/modnext.2 +++ b/lib/libc/sys/modnext.2 @@ -65,7 +65,8 @@ The system call returns the modid of the next module (see .Sx DESCRIPTION ) -or 0. If an error +or 0. +If an error occurs, .Va errno is set to indicate the error. diff --git a/lib/libc/sys/modstat.2 b/lib/libc/sys/modstat.2 index 21673f5..9356232 100644 --- a/lib/libc/sys/modstat.2 +++ b/lib/libc/sys/modstat.2 @@ -95,7 +95,8 @@ The module was not found (probably not loaded). .It Bq Er EINVAL The version specified in the .Fa version -field of stat is not the proper version. You would need to rebuild world, the +field of stat is not the proper version. +You would need to rebuild world, the kernel, or your application, if this error occurs, given that you did properly fill in the .Fa version diff --git a/lib/libc/sys/nanosleep.2 b/lib/libc/sys/nanosleep.2 index 2d03ee5..f086305 100644 --- a/lib/libc/sys/nanosleep.2 +++ b/lib/libc/sys/nanosleep.2 @@ -51,7 +51,8 @@ The .Fn nanosleep system call -causes the process to sleep for the specified time. An unmasked signal will +causes the process to sleep for the specified time. +An unmasked signal will cause it to terminate the sleep early, regardless of the .Dv SA_RESTART value on the interrupting signal. diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 index 8048ee5..14d8722 100644 --- a/lib/libc/sys/open.2 +++ b/lib/libc/sys/open.2 @@ -247,7 +247,7 @@ or is specified but the underlying file system does not support locking. .It Bq Er EOPNOTSUPP The named file is a special file mounted through a file system that -does not support access to it (e.g. NFS). +does not support access to it (e.g.\& NFS). .It Bq Er EWOULDBLOCK .Dv O_NONBLOCK and one of diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 index 3456350..28c426e 100644 --- a/lib/libc/sys/poll.2 +++ b/lib/libc/sys/poll.2 @@ -50,7 +50,8 @@ The .Fa fds argument is a pointer to an array of pollfd structures as defined in .In poll.h -(shown below). The +(shown below). +The .Fa nfds argument determines the size of the .Fa fds @@ -68,13 +69,16 @@ The fields of are as follows: .Bl -tag -width XXXrevents .It fd -File descriptor to poll. If fd is equal to -1 then +File descriptor to poll. +If fd is equal to -1 then .Fa revents is cleared (set to zero), and that pollfd is not checked. .It events -Events to poll for. (See below.) +Events to poll for. +(See below.) .It revents -Events which may occur. (See below.) +Events which may occur. +(See below.) .El .Pp The event bitmasks in @@ -97,15 +101,18 @@ Normal data may be written without blocking. .It POLLWRBAND Data with a non-zero priority may be written without blocking. .It POLLERR -An exceptional condition has occurred on the device or socket. This +An exceptional condition has occurred on the device or socket. +This flag is always checked, even if not present in the .Fa events bitmask. .It POLLHUP -The device or socket has been disconnected. This flag is always +The device or socket has been disconnected. +This flag is always checked, even if not present in the .Fa events -bitmask. Note that +bitmask. +Note that POLLHUP and POLLOUT @@ -113,7 +120,8 @@ should never be present in the .Fa revents bitmask at the same time. .It POLLNVAL -The file descriptor is not open. This flag is always checked, even +The file descriptor is not open. +This flag is always checked, even if not present in the .Fa events bitmask. @@ -122,9 +130,11 @@ bitmask. If .Fa timeout is neither zero nor INFTIM (-1), it specifies a maximum interval to -wait for any file descriptor to become ready, in milliseconds. If +wait for any file descriptor to become ready, in milliseconds. +If .Fa timeout -is INFTIM (-1), the poll blocks indefinitely. If +is INFTIM (-1), the poll blocks indefinitely. +If .Fa timeout is zero, then .Fn poll @@ -134,7 +144,8 @@ The .Fn poll system call returns the number of descriptors that are ready for I/O, or -1 if an -error occurred. If the time limit expires, +error occurred. +If the time limit expires, .Fn poll returns 0. If @@ -148,15 +159,18 @@ array will be unmodified. This implementation differs from the historical one in that a given file descriptor may not cause .Fn poll -to return with an error. In cases where this would have happened in -the historical implementation (e.g. trying to poll a +to return with an error. +In cases where this would have happened in +the historical implementation (e.g.\& trying to poll a .Xr revoke 2 Ns ed descriptor), this implementation instead copies the .Fa events bitmask to the .Fa revents -bitmask. Attempting to perform I/O on this descriptor will then -return an error. This behaviour is believed to be more useful. +bitmask. +Attempting to perform I/O on this descriptor will then +return an error. +This behaviour is believed to be more useful. .Sh ERRORS An error return from .Fn poll @@ -187,7 +201,8 @@ The distinction between some of the fields in the .Fa events and .Fa revents -bitmasks is really not useful without STREAMS. The fields are +bitmasks is really not useful without STREAMS. +The fields are defined for compatibility with existing software. .Sh HISTORY The diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 index 8e38652..1e98f3a 100644 --- a/lib/libc/sys/read.2 +++ b/lib/libc/sys/read.2 @@ -112,7 +112,8 @@ Upon return from the pointer is incremented by the number of bytes actually read. .Pp Objects that are not capable of seeking always read from the current -position. The value of the pointer associated with such an +position. +The value of the pointer associated with such an object is undefined. .Pp Upon successful completion, @@ -166,7 +167,7 @@ and no data were ready to be read. .It Bq Er EISDIR The file descriptor is associated with a directory residing on a file system that does not allow regular read operations on -directories (e.g. NFS). +directories (e.g.\& NFS). .It Bq Er EOPNOTSUPP The file descriptor is associated with a file system and file type that do not allow regular read operations on it. diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 index 6a9be42..0080f40 100644 --- a/lib/libc/sys/rename.2 +++ b/lib/libc/sys/rename.2 @@ -168,7 +168,8 @@ The link named by .Fa to and the file named by .Fa from -are on different logical devices (file systems). Note that this error +are on different logical devices (file systems). +Note that this error code will not be returned if the implementation permits cross-device links. .It Bq Er ENOSPC diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 index 7f160ec..d6c69dc 100644 --- a/lib/libc/sys/rfork.2 +++ b/lib/libc/sys/rfork.2 @@ -59,7 +59,8 @@ If set, the kernel will force sharing of the entire address space, typically by sharing the hardware page table directly. The child will thus inherit and share all the segments the parent process owns, -whether they are normally shareable or not. The stack segment is +whether they are normally shareable or not. +The stack segment is not split (both the parent and child return on the same stack) and thus .Fn rfork with the RFMEM flag may not generally be called directly from high level @@ -67,7 +68,8 @@ languages including C. May be set only with .Dv RFPROC . A helper function is provided to assist with this problem and will cause -the new process to run on the provided stack. See +the new process to run on the provided stack. +See .Xr rfork_thread 3 for information. .It Dv RFSIGSHARE @@ -75,7 +77,8 @@ If set, the kernel will force sharing the sigacts structure between the child and the parent. .It Dv RFLINUXTHPN If set, the kernel will return SIGUSR1 instead of SIGCHILD upon thread -exit for the child. This is intended to mimic certain Linux clone behaviour. +exit for the child. +This is intended to mimic certain Linux clone behaviour. .El .Pp File descriptors in a shared file descriptor table are kept @@ -110,7 +113,8 @@ Upon successful completion, .Fn rfork returns a value of 0 to the child process and returns the process ID of the child -process to the parent process. Otherwise, a value of -1 is returned +process to the parent process. +Otherwise, a value of -1 is returned to the parent process, no child process is created, and the global variable .Va errno @@ -166,7 +170,8 @@ does not yet implement a native .Fn clone library call, and the current pthreads implementation does not use .Fn rfork -with RFMEM. A native port of the linux threads library, +with RFMEM. +A native port of the linux threads library, .Pa /usr/ports/devel/linuxthreads , contains a working .Fn clone diff --git a/lib/libc/sys/sched_get_priority_max.2 b/lib/libc/sys/sched_get_priority_max.2 index 9f8104a..88d1d6d 100644 --- a/lib/libc/sys/sched_get_priority_max.2 +++ b/lib/libc/sys/sched_get_priority_max.2 @@ -82,7 +82,8 @@ If successful, the and .Fn sched_get_priority_min system calls shall return the appropriate maximum or minimum values, -respectively. If unsuccessful, they shall return a value of -1 and set +respectively. +If unsuccessful, they shall return a value of -1 and set .Fa errno to indicate the error. .Pp diff --git a/lib/libc/sys/sched_setparam.2 b/lib/libc/sys/sched_setparam.2 index bfd9115..dfc2ac0 100644 --- a/lib/libc/sys/sched_setparam.2 +++ b/lib/libc/sys/sched_setparam.2 @@ -85,12 +85,14 @@ argument is set higher than that of the lowest priority running process and if the specified process is ready to run, the process specified by the .Fa pid -argument will preempt a lowest priority running process. Similarly, if +argument will preempt a lowest priority running process. +Similarly, if the process calling .Fn sched_setparam sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority -list will also preempt the calling process. Thus, in either case, the +list will also preempt the calling process. +Thus, in either case, the originating process might not receive notification of the completion of the requested priority change until the higher priority process has executed. @@ -128,7 +130,8 @@ as a read-style operation. If .Fa pid is zero, the scheduling parameters for the calling process will be -returned. In this implementation, the +returned. +In this implementation, the .Fa sched_getparam system call will fail if .Fa pid diff --git a/lib/libc/sys/sched_setscheduler.2 b/lib/libc/sys/sched_setscheduler.2 index 15a1ab7..21b34e0 100644 --- a/lib/libc/sys/sched_setscheduler.2 +++ b/lib/libc/sys/sched_setscheduler.2 @@ -123,7 +123,8 @@ as a read-style operation. If .Fa pid is zero, the scheduling parameters for the calling process will be -returned. In this implementation, the +returned. +In this implementation, the .Fa sched_getscheduler system call will fail if .Fa pid diff --git a/lib/libc/sys/sched_yield.2 b/lib/libc/sys/sched_yield.2 index c8a60a0..9db8942 100644 --- a/lib/libc/sys/sched_yield.2 +++ b/lib/libc/sys/sched_yield.2 @@ -39,7 +39,8 @@ The .Fn sched_yield system call forces the running process to relinquish the processor until it -again becomes the head of its process list. It takes no arguments. +again becomes the head of its process list. +It takes no arguments. .Sh RETURN VALUES .Rv -std sched_yield .Sh ERRORS diff --git a/lib/libc/sys/select.2 b/lib/libc/sys/select.2 index 823eeaa..bacd76e 100644 --- a/lib/libc/sys/select.2 +++ b/lib/libc/sys/select.2 @@ -109,7 +109,8 @@ to the maximum number of descriptors supported by the system. If .Fa timeout is a non-nil pointer, it specifies the maximum interval to wait for the -selection to complete. System activity can lengthen the interval by +selection to complete. +System activity can lengthen the interval by an indeterminate amount. .Pp If @@ -158,7 +159,8 @@ points to an invalid address. A signal was delivered before the time limit expired and before any of the selected events occurred. .It Bq Er EINVAL -The specified time limit is invalid. One of its components is +The specified time limit is invalid. +One of its components is negative or too large. .It Bq Er EINVAL The @@ -195,7 +197,8 @@ If .Fa nfds is greater than the number of open files, .Fn select -is not guaranteed to examine the unused file descriptors. For historical +is not guaranteed to examine the unused file descriptors. +For historical reasons, .Fn select will always examine the first 256 descriptors. diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 index b69b8fb..0971949 100644 --- a/lib/libc/sys/semctl.2 +++ b/lib/libc/sys/semctl.2 @@ -95,7 +95,8 @@ or .Fa sem_perm.cuid , or it must have superuser privileges. .It IPC_RMID -Immediately removes the semaphore set from the system. The calling +Immediately removes the semaphore set from the system. +The calling process's effective uid must equal the semaphore set's .Fa sem_perm.uid or diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 index f493281..18c083b 100644 --- a/lib/libc/sys/semget.2 +++ b/lib/libc/sys/semget.2 @@ -53,13 +53,15 @@ set of semaphores. .\" The key is analogous to a filename: it provides a handle that names an -IPC object. There are three ways to specify a key: +IPC object. +There are three ways to specify a key: .Bl -bullet .It IPC_PRIVATE may be specified, in which case a new IPC object will be created. .It -An integer constant may be specified. If no IPC object corresponding +An integer constant may be specified. +If no IPC object corresponding to .Fa key is specified and the IPC_CREAT bit is set in diff --git a/lib/libc/sys/send.2 b/lib/libc/sys/send.2 index 38c8f80..f5fae6f 100644 --- a/lib/libc/sys/send.2 +++ b/lib/libc/sys/send.2 @@ -183,7 +183,8 @@ but may be caused by transient congestion. The remote host was unreachable. .It Bq Er ECONNREFUSED The socket received an ICMP destination unreachable message -from the last message sent. This typically means that the +from the last message sent. +This typically means that the receiver is not listening on the remote port. .It Bq Er EHOSTDOWN The remote host was down. @@ -214,7 +215,8 @@ domain socket then .Fn close it before it has actually been sent, the result being that the receiver -gets a closed file descriptor. It is left to the application to +gets a closed file descriptor. +It is left to the application to implement an acknowledgment mechanism to prevent this from happening. .Sh SEE ALSO .Xr fcntl 2 , diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2 index 0619133..ac4c110 100644 --- a/lib/libc/sys/shm_open.2 +++ b/lib/libc/sys/shm_open.2 @@ -150,7 +150,8 @@ functions can fail with any error defined for .Fn open and .Fn unlink , -respectively. In addition, the following errors are defined for +respectively. +In addition, the following errors are defined for .Fn shm_open : .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 index b992d41..8fe340c 100644 --- a/lib/libc/sys/shmat.2 +++ b/lib/libc/sys/shmat.2 @@ -49,7 +49,8 @@ The system call attaches the shared memory segment identified by .Fa shmid -to the calling process's address space. The address where the segment +to the calling process's address space. +The address where the segment is attached is determined as follows: .\" .\" These are cribbed almost exactly from Stevens, _Advanced Programming in diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 index ea7eaa7..d73c516 100644 --- a/lib/libc/sys/shmctl.2 +++ b/lib/libc/sys/shmctl.2 @@ -71,10 +71,12 @@ or .Fa shm_perm.cuid , or it must have superuser privileges. .It Dv IPC_RMID -Removes the segment from the system. The removal will not take +Removes the segment from the system. +The removal will not take effect until all processes having attached the segment have exited; however, once the IPC_RMID operation has taken place, no further -processes will be allowed to attach the segment. For the operation +processes will be allowed to attach the segment. +For the operation to succeed, the calling process's effective uid must match .Fa shm_perm.uid or diff --git a/lib/libc/sys/shmget.2 b/lib/libc/sys/shmget.2 index 5d8bc5a..e7fd6d1 100644 --- a/lib/libc/sys/shmget.2 +++ b/lib/libc/sys/shmget.2 @@ -54,13 +54,15 @@ memory segment. .\" The key is analogous to a filename: it provides a handle that names an -IPC object. There are three ways to specify a key: +IPC object. +There are three ways to specify a key: .Bl -bullet .It IPC_PRIVATE may be specified, in which case a new IPC object will be created. .It -An integer constant may be specified. If no IPC object corresponding +An integer constant may be specified. +If no IPC object corresponding to .Fa key is specified and the IPC_CREAT bit is set in @@ -100,7 +102,8 @@ Write access for other. .Pp When creating a new shared memory segment, .Fa size -indicates the desired size of the new segment in bytes. The size +indicates the desired size of the new segment in bytes. +The size of the segment may be rounded up to a multiple convenient to the kernel (i.e., the page size). .Sh RETURN VALUES diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 index 69f60e4..cd4eb89 100644 --- a/lib/libc/sys/sigaction.2 +++ b/lib/libc/sys/sigaction.2 @@ -559,7 +559,7 @@ cause of the signal, usually one of the .Dv SI_... values from .In sys/signal.h -or codes specific to a signal, i.e. one of the +or codes specific to a signal, i.e., one of the .Dv FPE_... values for .Dv SIGFPE . diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 index dab67b2..dadd683 100644 --- a/lib/libc/sys/socket.2 +++ b/lib/libc/sys/socket.2 @@ -81,7 +81,8 @@ PF_NETGRAPH Netgraph sockets .Pp The socket has the indicated .Fa type , -which specifies the semantics of communication. Currently +which specifies the semantics of communication. +Currently defined types are: .Pp .Bd -literal -offset indent -compact @@ -123,9 +124,11 @@ The argument 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. However, it is possible +socket type within a given protocol family. +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 +must be specified in this manner. +The protocol number to use is particular to the .Dq "communication domain" in which communication @@ -135,10 +138,12 @@ is to take place; see Sockets of type .Dv SOCK_STREAM are full-duplex byte streams, similar -to pipes. A stream socket must be in a +to pipes. +A stream socket must be in a .Em connected state before any data may be sent or received -on it. A connection to another socket is created with a +on it. +A connection to another socket is created with a .Xr connect 2 system call. Once connected, data may be transferred using @@ -168,7 +173,8 @@ and received as described in The communications protocols used to implement a .Dv SOCK_STREAM insure that data -is not lost or duplicated. If a piece of data for which the +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 broken and calls @@ -184,7 +190,7 @@ by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise -idle connection for an extended period (e.g. 5 minutes). +idle connection for an extended period (e.g.\& 5 minutes). A .Dv SIGPIPE signal is raised if a process sends @@ -195,7 +201,8 @@ which do not handle the signal, to exit. sockets employ the same system calls as .Dv SOCK_STREAM -sockets. The only difference +sockets. +The only difference is that .Xr read 2 calls will return only the amount of data requested, @@ -207,7 +214,8 @@ and sockets allow sending of datagrams to correspondents named in .Xr send 2 -calls. Datagrams are generally received with +calls. +Datagrams are generally received with .Xr recvfrom 2 , which returns the next datagram with its return address. .Pp diff --git a/lib/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 index 6aaf4f2..29e9da5 100644 --- a/lib/libc/sys/swapon.2 +++ b/lib/libc/sys/swapon.2 @@ -53,9 +53,11 @@ system call makes the block device .Fa special available to the system for -allocation for paging and swapping. The names of potentially +allocation for paging and swapping. +The names of potentially available devices are known to the system and defined at system -configuration time. The size of the swap area on +configuration time. +The size of the swap area on .Fa special is calculated at the time the device is first made available for swapping. diff --git a/lib/libc/sys/sysarch.2 b/lib/libc/sys/sysarch.2 index 0b3e8ae..9d8f050 100644 --- a/lib/libc/sys/sysarch.2 +++ b/lib/libc/sys/sysarch.2 @@ -69,7 +69,8 @@ functions can be found in the header file The .Fn sysarch system call should never be called directly by -user programs. Instead, they should access +user programs. +Instead, they should access its functions using the architecture-dependent library. .Sh RETURN VALUES diff --git a/lib/libc/sys/truncate.2 b/lib/libc/sys/truncate.2 index 29892ac..5966f5f 100644 --- a/lib/libc/sys/truncate.2 +++ b/lib/libc/sys/truncate.2 @@ -57,7 +57,8 @@ or referenced by .Fa fd to be truncated or extended to .Fa length -bytes in size. If the file +bytes in size. +If the file was larger than this size, the extra data is lost. If the file was smaller than this size, diff --git a/lib/libc/sys/umask.2 b/lib/libc/sys/umask.2 index 9226071..00ff4e7 100644 --- a/lib/libc/sys/umask.2 +++ b/lib/libc/sys/umask.2 @@ -49,7 +49,8 @@ The .Fn umask routine sets the process's file mode creation mask to .Fa numask -and returns the previous value of the mask. The 9 low-order +and returns the previous value of the mask. +The 9 low-order access permission bits of .Fa numask diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2 index 6050b39..3326134 100644 --- a/lib/libc/sys/unlink.2 +++ b/lib/libc/sys/unlink.2 @@ -118,5 +118,6 @@ function appeared in The .Fn unlink system call traditionally allows the super-user to unlink directories which -can damage the file system integrity. This implementation no longer permits +can damage the file system integrity. +This implementation no longer permits it. diff --git a/lib/libc/sys/vfork.2 b/lib/libc/sys/vfork.2 index cf57134..b299923 100644 --- a/lib/libc/sys/vfork.2 +++ b/lib/libc/sys/vfork.2 @@ -50,7 +50,8 @@ The system call can be used to create new processes without fully copying the address space of the old process, which is horrendously inefficient in a paged -environment. It is useful when the purpose of +environment. +It is useful when the purpose of .Xr fork 2 would have been to create a new system context for an .Xr execve 2 . diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2 index 4f6df2d..35a2818 100644 --- a/lib/libc/sys/wait.2 +++ b/lib/libc/sys/wait.2 @@ -102,7 +102,8 @@ equals the absolute value of .Pp The .Fa status -argument is defined below. The +argument is defined below. +The .Fa options argument contains the bitwise OR of any of the following options. The @@ -237,7 +238,8 @@ If .Fn wait returns due to a stopped or terminated child process, the process ID of the child -is returned to the calling process. Otherwise, a value of -1 +is returned to the calling process. +Otherwise, a value of -1 is returned and .Va errno is set to indicate the error. diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 index 2064769..4687e3b 100644 --- a/lib/libc/sys/write.2 +++ b/lib/libc/sys/write.2 @@ -112,7 +112,8 @@ Upon return from the pointer is incremented by the number of bytes which were written. .Pp Objects that are not capable of seeking always write from the current -position. The value of the pointer associated with such an object +position. +The value of the pointer associated with such an object is undefined. .Pp If the real user is not the super-user, then @@ -134,7 +135,8 @@ the return value must be noted, and the remainder of the operation should be retried when possible. .Sh RETURN VALUES Upon successful completion the number of bytes which were written -is returned. Otherwise a -1 is returned and the global variable +is returned. +Otherwise a -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS |
