diff options
| author | ru <ru@FreeBSD.org> | 2002-12-18 09:22:32 +0000 |
|---|---|---|
| committer | ru <ru@FreeBSD.org> | 2002-12-18 09:22:32 +0000 |
| commit | a4b155d7a2170a500eb79b46959eef4018441062 (patch) | |
| tree | cb18f664ed0ee63bee30f6af9b148510b6e9663b /lib | |
| parent | e7e659d1cc574138f455ed70d58a07294211ff5a (diff) | |
| download | FreeBSD-src-a4b155d7a2170a500eb79b46959eef4018441062.zip FreeBSD-src-a4b155d7a2170a500eb79b46959eef4018441062.tar.gz | |
mdoc(7) police: Tidy up the syscall language.
Stop calling system calls "function calls".
Use "The .Fn system call" a-la "The .Nm utility".
When referring to a non-BSD implementation in
the HISTORY section, call syscall a function,
to be safe.
Diffstat (limited to 'lib')
147 files changed, 1011 insertions, 668 deletions
diff --git a/lib/libc/sys/_exit.2 b/lib/libc/sys/_exit.2 index 0793374..e864a78 100644 --- a/lib/libc/sys/_exit.2 +++ b/lib/libc/sys/_exit.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn _exit -function +system call terminates a process with the following consequences: .Bl -bullet .It @@ -103,7 +103,9 @@ before calling .Fn _exit . .Sh RETURN VALUES +The .Fn _exit +system call can never return. .Sh SEE ALSO .Xr fork 2 , @@ -113,10 +115,10 @@ can never return. .Sh STANDARDS The .Fn _exit -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -An +The .Fn _exit -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 index 93e2ab4..b0adcbd 100644 --- a/lib/libc/sys/accept.2 +++ b/lib/libc/sys/accept.2 @@ -56,7 +56,7 @@ and is listening for connections after a .Xr listen 2 . The .Fn accept -call +system call extracts the first connection request on the queue of pending connections, creates a new socket with the same properties as @@ -125,7 +125,7 @@ integer that is a descriptor for the accepted socket. .Sh ERRORS The .Fn accept -will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The descriptor is invalid. @@ -165,5 +165,5 @@ on the listen queue. .Sh HISTORY The .Fn accept -function appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2 index 5d912b8..0d3611a 100644 --- a/lib/libc/sys/access.2 +++ b/lib/libc/sys/access.2 @@ -51,7 +51,7 @@ The .Fn access and .Fn eaccess -functions check the accessibility of the +system calls check the accessibility of the file named by the .Fa path @@ -80,12 +80,12 @@ section of .Pp The .Fn eaccess -call uses +system call uses the effective user ID and the group access list to authorize the request; the .Fn access -call uses +system call uses the real user ID in place of the effective user ID, the real group ID in place of the effective group ID, and the rest of the group access list. @@ -130,7 +130,7 @@ An I/O error occurred while reading from or writing to the file system. .Sh SECURITY CONSIDERATIONS The .Fn access -call +system call is a potential security hole due to race conditions and should never be used. Set-user-ID and set-group-ID applications should restore the @@ -140,7 +140,7 @@ and perform actions directly rather than use to simulate access checks for the real user or group ID. The .Fn eaccess -call +system call likewise may be subject to races if used inappropriately. .Sh SEE ALSO .Xr chmod 2 , @@ -149,10 +149,10 @@ likewise may be subject to races if used inappropriately. .Sh STANDARDS The .Fn access -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -An +The .Fn access -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/acct.2 b/lib/libc/sys/acct.2 index 0095dc4..7db84c8 100644 --- a/lib/libc/sys/acct.2 +++ b/lib/libc/sys/acct.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn acct -call enables or disables the collection of system accounting +system call enables or disables the collection of system accounting records. If the argument .Fa file @@ -84,7 +84,7 @@ The file must exist and the call may be exercised only by the super-user. .Sh ERRORS The .Fn acct -function will fail if one of the following is true: +system call will fail if one of the following is true: .Bl -tag -width Er .It Bq Er EPERM The caller is not the super-user. @@ -112,7 +112,7 @@ An I/O error occurred while reading from or writing to the file system. .Xr acct 5 , .Xr sa 8 .Sh HISTORY -An +The .Fn acct -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/adjtime.2 b/lib/libc/sys/adjtime.2 index a090ed4..373c46e 100644 --- a/lib/libc/sys/adjtime.2 +++ b/lib/libc/sys/adjtime.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn adjtime -function +system call makes small adjustments to the system time, as returned by .Xr gettimeofday 2 , advancing or retarding it @@ -82,15 +82,16 @@ of computers in a local area network. Such time servers would slow down the clocks of some machines and speed up the clocks of others to bring them to the average network time. .Pp -The call +The .Fn adjtime +system call is restricted to the super-user. .Sh RETURN VALUES .Rv -std adjtime .Sh ERRORS The .Fn adjtime -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EFAULT An argument points outside the process's allocated address space. @@ -110,5 +111,5 @@ The process's effective user ID is not that of the super-user. .Sh HISTORY The .Fn adjtime -function call appeared in +system call appeared in .Bx 4.3 . diff --git a/lib/libc/sys/aio_cancel.2 b/lib/libc/sys/aio_cancel.2 index 30eecb5..7f2399b 100644 --- a/lib/libc/sys/aio_cancel.2 +++ b/lib/libc/sys/aio_cancel.2 @@ -39,7 +39,7 @@ .Sh DESCRIPTION The .Fn aio_cancel -function cancels the outstanding asynchronous +system call cancels the outstanding asynchronous I/O request for the file descriptor specified in .Fa fildes . If @@ -52,16 +52,16 @@ Requests complete with an error result of .Sh RESTRICTIONS The .Fn aio_cancel -function does not cancel asynchronous I/O requests for raw disk devices. +system call does not cancel asynchronous I/O requests for raw disk devices. The .Fn aio_cancel -function will always return +system call will always return .Dv AIO_NOTCANCELED for file descriptors associated with raw disk devices. .Sh RETURN VALUES The .Fn aio_cancel -function returns -1 to indicate an error, or one of the following: +system call returns -1 to indicate an error, or one of the following: .Bl -tag -width Dv .It Bq Dv AIO_CANCELED All outstanding requests meeting the criteria specified were cancelled. @@ -91,13 +91,13 @@ is an invalid file descriptor. .Sh STANDARDS The .Fn aio_cancel -function is expected to conform to the +system call is expected to conform to the .St -p1003.2 standard. .Sh HISTORY The .Fn aio_cancel -function first appeared in +system call first appeared in .Fx 3.0 . The first functional implementation of .Fn aio_cancel diff --git a/lib/libc/sys/aio_error.2 b/lib/libc/sys/aio_error.2 index 08f3d9f..444e281 100644 --- a/lib/libc/sys/aio_error.2 +++ b/lib/libc/sys/aio_error.2 @@ -39,7 +39,7 @@ .Sh DESCRIPTION The .Fn aio_error -function returns the error status of the asynchronous I/O request +system call returns the error status of the asynchronous I/O request associated with the structure pointed to by .Fa iocb . .Sh RETURN VALUES @@ -64,7 +64,7 @@ to indicate the error condition. .Sh ERRORS The .Fn aio_error -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL .Fa iocb @@ -81,14 +81,16 @@ does not reference an outstanding asynchronous I/O request. .Xr write 2 , .Xr aio 4 .Sh STANDARDS +The .Fn aio_error +system call is expected to conform to the .St -p1003.2 standard. .Sh HISTORY The -.Nm -function first appeared in +.Fn aio_error +system call first appeared in .Fx 3.0 . .Sh AUTHORS This diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 index e1256ce..8090963 100644 --- a/lib/libc/sys/aio_read.2 +++ b/lib/libc/sys/aio_read.2 @@ -40,7 +40,7 @@ .Sh DESCRIPTION The .Fn aio_read -function allows the calling process to read +system call allows the calling process to read .Fa iocb->aio_nbytes from the descriptor .Fa iocb->aio_fildes @@ -61,7 +61,7 @@ The .Fa iocb->aio_lio_opcode is ignored by the .Fn aio_read -call. +system call. .Pp The .Fa iocb @@ -110,26 +110,26 @@ None. .Sh ERRORS The .Fn aio_read -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN The request was not queued because of system resource limitations. .It Bq Er ENOSYS The .Fn aio_read -call is not supported. +system call is not supported. .El .Pp The following conditions may be synchronously detected when the .Fn aio_read -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 .Va errno appropriately; otherwise the .Fn aio_return -function must be called, and will return -1, and +system call must be called, and will return -1, and .Fn aio_error must be called to determine the actual calue that would have been returned in @@ -160,13 +160,13 @@ offset maximum. If the request is successfully enqueued, but subsequently cancelled or an error occurs, the value returned by the .Fn aio_return -function is per the +system call is per the .Xr read 2 -call, and the value returned by the +system call, and the value returned by the .Fn aio_error -function is either one of the error returns from the +system call is either one of the error returns from the .Xr read 2 -call, or one of: +system call, or one of: .Bl -tag -width Er .It Bq Er EBADF .Fa iocb->aio_fildes @@ -190,13 +190,13 @@ would be invalid. .Sh STANDARDS The .Fn aio_read -call is expected to conform to the +system call is expected to conform to the .St -p1003.2 standard. .Sh HISTORY The -.Nm -function first appeared in +.Fn aio_read +system call first appeared in .Fx 3.0 . .Sh AUTHORS This diff --git a/lib/libc/sys/aio_return.2 b/lib/libc/sys/aio_return.2 index 5f7e682..b12b787 100644 --- a/lib/libc/sys/aio_return.2 +++ b/lib/libc/sys/aio_return.2 @@ -39,11 +39,13 @@ .Sh DESCRIPTION The .Fn aio_return -function returns the final status of the asynchronous I/O request +system call returns the final status of the asynchronous I/O request associated with the structure pointed to by .Fa iocb . .Pp +The .Fn aio_return +system call should only be called once, to obtain the final status of an asynchronous I/O operation once .Xr aio_error 2 @@ -66,7 +68,7 @@ to indicate the error condition. .Sh ERRORS The .Fn aio_return -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL .Fa iocb @@ -83,14 +85,16 @@ does not reference an outstanding asynchronous I/O request. .Xr write 2 , .Xr aio 4 .Sh STANDARDS +The .Fn aio_return +system call is expected to conform to the .St -p1003.2 standard. .Sh HISTORY The -.Nm -function first appeared in +.Fn aio_return +system call first appeared in .Fx 3.0 . .Sh AUTHORS This diff --git a/lib/libc/sys/aio_suspend.2 b/lib/libc/sys/aio_suspend.2 index f03d6eb..7c88bf8 100644 --- a/lib/libc/sys/aio_suspend.2 +++ b/lib/libc/sys/aio_suspend.2 @@ -39,7 +39,7 @@ .Sh DESCRIPTION The .Fn aio_suspend -function suspends the calling process until at least one of the +system call suspends the calling process until at least one of the specified asynchronous I/O requests have completed, a signal is delivered, or the .Fa timeout @@ -70,7 +70,7 @@ to indicate the error, as enumerated below. .Sh ERRORS The .Fn aio_suspend -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN the @@ -93,14 +93,16 @@ the suspend was interrupted by a signal. .Xr aio_write 2 , .Xr aio 4 .Sh STANDARDS +The .Fn aio_suspend +system call is expected to conform to the .St -p1003.2 standard. .Sh HISTORY The -.Nm -function first appeared in +.Fn aio_suspend +system call first appeared in .Fx 3.0 . .Sh AUTHORS This diff --git a/lib/libc/sys/aio_waitcomplete.2 b/lib/libc/sys/aio_waitcomplete.2 index 573f002..5145f78 100644 --- a/lib/libc/sys/aio_waitcomplete.2 +++ b/lib/libc/sys/aio_waitcomplete.2 @@ -39,7 +39,7 @@ .Sh DESCRIPTION The .Fn aio_waitcomplete -function waits for completion of an asynchronous I/O request. +system call waits for completion of an asynchronous I/O request. Upon completion, .Fn aio_waitcomplete returns the result of the function and sets @@ -64,7 +64,7 @@ argument should be non-NULL, pointing to a zero-valued timeval structure. .Pp The .Fn aio_waitcomplete -function also serves the function of +system call also serves the function of .Fn aio_return , thus .Fn aio_return @@ -91,7 +91,7 @@ to indicate the error condition. .Sh ERRORS The .Fn aio_waitcomplete -function fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EINVAL The specified time limit is invalid. @@ -122,16 +122,16 @@ completed. .Sh STANDARDS The .Fn aio_waitcomplete -function is a +system call is a .Fx Ns -specific extension. .Sh HISTORY The .Fn aio_waitcomplete -function first appeared in +system call first appeared in .Fx 4.0 . .Sh AUTHORS The .Fn aio_waitcomplete -function and this manual page were written by +system call and this manual page were written by .An Christopher M Sedore Aq cmsedore@maxwell.syr.edu . diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2 index fae6fc6..9858ea9 100644 --- a/lib/libc/sys/aio_write.2 +++ b/lib/libc/sys/aio_write.2 @@ -39,7 +39,7 @@ .Sh DESCRIPTION The .Fn aio_write -function allows the calling process to write +system call allows the calling process to write .Fa iocb->aio_nbytes from the buffer pointed to by .Fa iocb->aio_buf @@ -96,7 +96,7 @@ The asynchronous I/O control buffer .Fa iocb should be zeroed before the .Fn aio_write -call to avoid passing bogus context information to the kernel. +system call to avoid passing bogus context information to the kernel. .Pp Modifications of the Asynchronous I/O Control Block structure or the buffer contents after the request has been enqueued, but before the @@ -112,26 +112,26 @@ no I/O will occur. .Sh ERRORS The .Fn aio_write -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN The request was not queued because of system resource limitations. .It Bq Er ENOSYS The .Fn aio_write -call is not supported. +system call is not supported. .El .Pp The following conditions may be synchronously detected when the .Fn aio_write -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 .Va errno appropriately; otherwise the .Fn aio_return -function must be called, and will return -1, and +system call must be called, and will return -1, and .Fn aio_error must be called to determine the actual value that would have been returned in @@ -154,13 +154,13 @@ is not valid. If the request is successfully enqueued, but subsequently canceled or an error occurs, the value returned by the .Fn aio_return -function is per the +system call is per the .Xr write 2 -call, and the value returned by the +system call, and the value returned by the .Fn aio_error -function is either one of the error returns from the +system call is either one of the error returns from the .Xr write 2 -call, or one of: +system call, or one of: .Bl -tag -width Er .It Bq Er EBADF .Fa iocb->aio_fildes @@ -181,14 +181,16 @@ would be invalid. .Xr aio_waitcomplete 2 , .Xr aio 4 .Sh STANDARDS +The .Fn aio_write +system call is expected to conform to the .St -p1003.2 standard. .Sh HISTORY The -.Nm -Function first appeared in +.Fn aio_write +system call first appeared in .Fx 3.0 . .Sh AUTHORS This manual page was written by diff --git a/lib/libc/sys/bind.2 b/lib/libc/sys/bind.2 index c0afbd7..33e228c 100644 --- a/lib/libc/sys/bind.2 +++ b/lib/libc/sys/bind.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn bind -function +system call assigns the local protocol address to a socket. When a socket is created with @@ -56,7 +56,7 @@ with it exists in an address family space but has no protocol address assigned. The .Fn bind -function requests that +system call requests that .Fa addr be assigned to the socket. .Sh NOTES @@ -76,7 +76,7 @@ before populating it and passing it to .Sh ERRORS The .Fn bind -call will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN Kernel resources to complete the request are @@ -127,5 +127,5 @@ An empty pathname was specified. .Sh HISTORY The .Fn bind -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/brk.2 b/lib/libc/sys/brk.2 index 2683fb4..e1053f3 100644 --- a/lib/libc/sys/brk.2 +++ b/lib/libc/sys/brk.2 @@ -128,9 +128,11 @@ is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS +The .Fn brk -or +and .Fn sbrk +functions will fail if: .Bl -tag -width Er .It Bq Er EINVAL @@ -167,7 +169,7 @@ from a failure caused by exceeding the maximum size of the data segment without consulting .Xr getrlimit 2 . .Sh HISTORY -A +The .Fn brk -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/chdir.2 b/lib/libc/sys/chdir.2 index bb7a0c8..373892b 100644 --- a/lib/libc/sys/chdir.2 +++ b/lib/libc/sys/chdir.2 @@ -53,7 +53,7 @@ The argument points to the pathname of a directory. The .Fn chdir -function +system call causes the named directory to become the current working directory, that is, the starting point for path searches of pathnames not beginning with @@ -62,7 +62,7 @@ a slash, .Pp The .Fn fchdir -function +system call causes the directory referenced by .Fa fd to become the current working directory, @@ -77,7 +77,7 @@ a process must have execute (search) access to the directory. .Sh ERRORS The .Fn chdir -function +system call will fail and the current working directory will be unchanged if one or more of the following are true: .Bl -tag -width Er @@ -102,7 +102,7 @@ An I/O error occurred while reading from or writing to the file system. .Pp The .Fn fchdir -function +system call will fail and the current working directory will be unchanged if one or more of the following are true: .Bl -tag -width Er @@ -121,15 +121,14 @@ is not a valid file descriptor. .Sh STANDARDS The .Fn chdir -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn chdir -function call appeared in +system call appeared in .At v7 . The .Fn fchdir -function call -appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2 index 00dd0f8..70e3d89 100644 --- a/lib/libc/sys/chflags.2 +++ b/lib/libc/sys/chflags.2 @@ -123,7 +123,7 @@ for details.) .Sh ERRORS The .Fn chflags -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. @@ -154,7 +154,7 @@ The underlying file system does not support file flags. .Pp The .Fn fchflags -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The descriptor is not valid. @@ -181,8 +181,8 @@ The underlying file system does not support file flags. .Xr mount_unionfs 8 .Sh HISTORY The -.Nm chflags +.Fn chflags and -.Nm fchflags -functions first appeared in +.Fn fchflags +system calls first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 index 7854c36..8c92be2 100644 --- a/lib/libc/sys/chmod.2 +++ b/lib/libc/sys/chmod.2 @@ -59,7 +59,7 @@ are changed to .Fa mode . The .Fn chmod -function verifies that the process owner (user) either owns +system call verifies that the process owner (user) either owns the file specified by .Fa path (or @@ -68,12 +68,12 @@ or is the super-user. The .Fn chmod -function follows symbolic links to operate on the target of the link +system call follows symbolic links to operate on the target of the link rather than the link itself. .Pp The -.Fa lchmod -function is similar to +.Fn lchmod +system call is similar to .Fn chmod but does not follow symbolic links. .Pp @@ -161,7 +161,7 @@ at the expense of a degree of compatibility. .Sh ERRORS The .Fn chmod -function +system call will fail and the file mode will be unchanged if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -191,7 +191,7 @@ An attempt was made to set the sticky bit upon an executable. .Pp The .Fn fchmod -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The descriptor is not valid. @@ -212,23 +212,22 @@ An I/O error occurred while reading from or writing to the file system. .Sh STANDARDS The .Fn chmod -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 , except for the return of .Er EFTYPE and the use of .Dv S_ISTXT . .Sh HISTORY -A +The .Fn chmod -function call appeared in +function appeared in .At v7 . The .Fn fchmod -function call -appeared in +system call appeared in .Bx 4.2 . The .Fn lchmod -function call appeared in +system call appeared in .Fx 3.0 . diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2 index 7ea3449..d663776 100644 --- a/lib/libc/sys/chown.2 +++ b/lib/libc/sys/chown.2 @@ -70,26 +70,28 @@ capability is restricted to the super-user. .Pp The .Fn chown -function +system call clears the set-user-id and set-group-id bits on the file to prevent accidental or mischievous creation of set-user-id and set-group-id programs if not executed by the super-user. +The .Fn chown +system call follows symbolic links to operate on the target of the link rather than the link itself. .Pp The .Fn fchown -function +system call is particularly useful when used in conjunction with the file locking primitives (see .Xr flock 2 ) . .Pp The .Fn lchown -function is similar to +system call is similar to .Fn chown but does not follow symbolic links. .Pp @@ -128,7 +130,7 @@ An I/O error occurred while reading from or writing to the file system. .Pp The .Fn fchown -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF .Fa fd @@ -151,25 +153,24 @@ An I/O error occurred while reading from or writing to the file system. .Sh STANDARDS The .Fn chown -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn chown -function call appeared in +function appeared in .At v7 . The .Fn fchown -function call -appeared in +system call appeared in .Bx 4.2 . .Pp The .Fn chown -function was changed to follow symbolic links in +system call was changed to follow symbolic links in .Bx 4.4 . The .Fn lchown -function was added in +system call was added in .Fx 3.0 to compensate for the loss of functionality. diff --git a/lib/libc/sys/chroot.2 b/lib/libc/sys/chroot.2 index 8c750c4..78bdfb6 100644 --- a/lib/libc/sys/chroot.2 +++ b/lib/libc/sys/chroot.2 @@ -49,7 +49,7 @@ is the address of the pathname of a directory, terminated by an ASCII NUL. The .Fn chroot -function causes +system call causes .Fa dirname to become the root directory, that is, the starting point for path searches of pathnames @@ -87,9 +87,9 @@ is set to one (the default), will fail with .Er EPERM if there are any directories open and the -process is already subject to a +process is already subject to the .Fn chroot -call. +system call. .Pp Any other value for .Ql kern.chroot_allow_open_directories @@ -102,7 +102,7 @@ is set to indicate an error. .Sh ERRORS The .Fn chroot -function +system call will fail and the root directory will be unchanged if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -131,5 +131,5 @@ An I/O error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn chroot -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/clock_gettime.2 b/lib/libc/sys/clock_gettime.2 index 31f6a4e..0e41168 100644 --- a/lib/libc/sys/clock_gettime.2 +++ b/lib/libc/sys/clock_gettime.2 @@ -1,5 +1,4 @@ .\" $OpenBSD: clock_gettime.2,v 1.4 1997/05/08 20:21:16 kstailey Exp $ -.\" $FreeBSD$ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -32,6 +31,8 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" +.\" $FreeBSD$ +.\" .Dd May 8, 1997 .Dt CLOCK_GETTIME 2 .Os @@ -91,7 +92,7 @@ system call even when the system is secure. .Pp The resolution (granularity) of a clock is returned by the .Fn clock_getres -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 @@ -118,6 +119,8 @@ A user other than the super-user attempted to set the time. .Sh STANDARDS The .Fn clock_gettime , -etc.\& -functions conform to +.Fn clock_settime , +and +.Fn clock_getres +system calls conform to .St -p1003.1b-93 . diff --git a/lib/libc/sys/close.2 b/lib/libc/sys/close.2 index 9e9471b..16abee5 100644 --- a/lib/libc/sys/close.2 +++ b/lib/libc/sys/close.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn close -call deletes a descriptor from the per-process object +system call deletes a descriptor from the per-process object reference table. If this is the last reference to the underlying object, the object will be deactivated. @@ -74,7 +74,7 @@ When a process exits, all associated file descriptors are freed, but since there is a limit on active descriptors per processes, the .Fn close -function call +system call is useful when a large quantity of file descriptors are being handled. .Pp When a process forks (see @@ -106,7 +106,7 @@ which is to not close the descriptor. .Sh ERRORS The .Fn close -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF .Fa D @@ -126,10 +126,10 @@ An interrupt was received. .Sh STANDARDS The .Fn close -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn close -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/connect.2 b/lib/libc/sys/connect.2 index c80f03d..79ab4f9 100644 --- a/lib/libc/sys/connect.2 +++ b/lib/libc/sys/connect.2 @@ -76,7 +76,7 @@ by connecting to an invalid address, such as a null address. .Sh ERRORS The .Fn connect -call fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EBADF .Fa s @@ -142,5 +142,5 @@ Too many symbolic links were encountered in translating the pathname. .Sh HISTORY The .Fn connect -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/dup.2 b/lib/libc/sys/dup.2 index c93ece0..10cbc79 100644 --- a/lib/libc/sys/dup.2 +++ b/lib/libc/sys/dup.2 @@ -50,7 +50,7 @@ .Sh DESCRIPTION The .Fn dup -function +system call duplicates an existing object descriptor and returns its value to the calling process .Fa ( newd @@ -89,7 +89,7 @@ If a separate pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional .Xr open 2 -call. +system call. The close-on-exec flag on the new file descriptor is unset. .Pp In @@ -100,9 +100,9 @@ is specified. If this descriptor is already in use and .Fa oldd \*(Ne .Fa newd , -the descriptor is first deallocated as if a +the descriptor is first deallocated as if the .Xr close 2 -call had been used. +system call had been used. If .Fa oldd is not a valid descriptor, then @@ -127,7 +127,7 @@ The .Fn dup and .Fn dup2 -functions fail if: +system calls fail if: .Bl -tag -width Er .It Bq Er EBADF .Fa Oldd @@ -151,12 +151,12 @@ The .Fn dup and .Fn dup2 -function calls are expected to conform to +system calls are expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn dup -and a +and .Fn dup2 -function call appeared in +functions appeared in .At v7 . diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 index 4cfabef..7e54ac3 100644 --- a/lib/libc/sys/execve.2 +++ b/lib/libc/sys/execve.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn execve -function +system call transforms the calling process into a new process. The new process is constructed from an ordinary file, whose name is pointed to by @@ -183,7 +183,7 @@ the calling process: .Pp When a program is executed as a result of an .Fn execve -call, it is entered as follows: +system call, it is entered as follows: .Bd -literal -offset indent main(argc, argv, envp) int argc; @@ -202,7 +202,7 @@ to the arguments themselves. .Sh RETURN VALUES As the .Fn execve -function overlays the current process image +system call overlays the current process image with a new process image the successful call has no process to return to. If @@ -214,7 +214,7 @@ is set to indicate the error. .Sh ERRORS The .Fn execve -function +system call will fail and return to the calling process if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -289,7 +289,7 @@ of a super-user as well. .Sh STANDARDS The .Fn execve -function conforms to +system call conforms to .St -p1003.1-2001 , with the exception of reopening descriptors 0, 1, and/or 2 in certain circumstances. @@ -300,5 +300,5 @@ The support for executing interpreted programs is an extension. .Sh HISTORY The .Fn execve -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/extattr_get_file.2 b/lib/libc/sys/extattr_get_file.2 index 42625b8..5716cc2 100644 --- a/lib/libc/sys/extattr_get_file.2 +++ b/lib/libc/sys/extattr_get_file.2 @@ -71,19 +71,19 @@ They exist as pairs within a set of namespaces. The .Fn extattr_get_file -call retrieves the value of the specified extended attribute into +system call retrieves the value of the specified extended attribute into a buffer pointed to by .Fa data of size .Fa nbytes . The .Fn extattr_set_file -call sets the value of the specified extended attribute to the data +system call sets the value of the specified extended attribute to the data described by .Fa data . The .Fn extattr_delete_file -call deletes the extended attribute specified. +system call deletes the extended attribute specified. The .Fn extattr_get_file and @@ -111,11 +111,11 @@ The .Fn extattr_get_link , and .Fn extattr_set_link -functions behave in the same way as their _file counterparts, except that +system calls behave in the same way as their _file counterparts, except that they do not follow symlinks. .Pp The -.Fn extatttr_get_fd , +.Fn extattr_get_fd , .Fn extattr_set_fd , and .Fn extattr_delete_fd @@ -195,7 +195,7 @@ The .Fn extattr_set_fd , and .Fn extattr_delete_fd -functions may also fail if: +system calls may also fail if: .Bl -tag -width Er .It Bq Er EBADF The file descriptor referenced by diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 index 6635e31..5d5a252 100644 --- a/lib/libc/sys/fcntl.2 +++ b/lib/libc/sys/fcntl.2 @@ -47,14 +47,14 @@ .Sh DESCRIPTION The .Fn fcntl -function provides for control over descriptors. +system call provides for control over descriptors. The argument .Fa fd is a descriptor to be operated on by .Fa cmd as described below. Depending on the value of .Fa cmd , -.Nm +.Fn fcntl can take an additional third argument .Fa "int arg" . .Bl -tag -width F_GETOWNX @@ -145,7 +145,7 @@ flags are as follows: .It Dv O_NONBLOCK Non-blocking I/O; if no data is available to a .Xr read 2 -call, or if a +system call, or if a .Xr write 2 operation would block, the read or write call returns -1 with the error @@ -195,7 +195,7 @@ in the .Fa flock structure. If no lock is found that would prevent this lock from being created, -the structure is left unchanged by this function call except for the +the structure is left unchanged by this system call except for the lock type which is set to .Dv F_UNLCK . .It Dv F_SETLK @@ -331,7 +331,7 @@ requested a lock on the database. Another minor semantic problem with this interface is that locks are not inherited by a child process created using the .Xr fork 2 -function. +system call. The .Xr flock 2 interface has much more rational last close semantics and @@ -390,7 +390,7 @@ is set to indicate the error. .Sh ERRORS The .Fn fcntl -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN The argument @@ -450,7 +450,7 @@ The argument .Fa cmd is .Dv F_SETLKW , -and the function was interrupted by a signal. +and the system call was interrupted by a signal. .It Bq Er EINVAL .Fa Cmd is @@ -554,5 +554,5 @@ for the reasons as stated in .Sh HISTORY The .Fn fcntl -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/fhopen.2 b/lib/libc/sys/fhopen.2 index 0dd736b..a48f9d0 100644 --- a/lib/libc/sys/fhopen.2 +++ b/lib/libc/sys/fhopen.2 @@ -1,5 +1,4 @@ .\" $NetBSD: fhopen.2,v 1.1 1999/06/30 01:32:15 wrstuden Exp $ -.\" $FreeBSD$ .\" .\" Copyright (c) 1999 National Aeronautics & Space Administration .\" All rights reserved. @@ -31,7 +30,9 @@ .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. -.\"/ +.\" +.\" $FreeBSD$ +.\" .Dd June 29, 1999 .Dt FHOPEN 2 .Os @@ -53,12 +54,14 @@ .Ft int .Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf" .Sh DESCRIPTION -These functions provide a means to access a file given the file handle +These system calls provide a means to access a file given the file handle .Fa fhp . As this method bypasses directory access restrictions, these calls are restricted to the superuser. .Pp +The .Fn fhopen +system call opens the file referenced by .Fa fhp for reading and/or writing as specified by the argument @@ -70,13 +73,15 @@ are specified by .Em or Ns 'ing together the flags used for the .Xr open 2 -call. +system call. All said flags are valid except for .Dv O_CREAT . .Pp +The .Fn fhstat and .Fn fhstatfs +system calls provide the functionality of the .Xr fstat 2 and @@ -128,11 +133,12 @@ The .Fn fhstat , and .Fn fhstatfs -functions first appeared in +system calls first appeared in .Nx 1.5 and were adapted to .Fx 4.0 -by Alfred Perlstein. +by +.An Alfred Perlstein . .Sh AUTHORS This man page was written by .An William Studenmund diff --git a/lib/libc/sys/flock.2 b/lib/libc/sys/flock.2 index fc3e15c..40f071d 100644 --- a/lib/libc/sys/flock.2 +++ b/lib/libc/sys/flock.2 @@ -51,7 +51,7 @@ .Sh DESCRIPTION The .Fn flock -function applies or removes an +system call applies or removes an .Em advisory lock on the file associated with the file descriptor .Fa fd . @@ -118,7 +118,7 @@ Processes blocked awaiting a lock may be awakened by signals. .Sh ERRORS The .Fn flock -call fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EWOULDBLOCK The file is locked and the @@ -146,5 +146,5 @@ refers to an object that does not support file locking. .Sh HISTORY The .Fn flock -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 index 82f6629..1c699bb 100644 --- a/lib/libc/sys/fork.2 +++ b/lib/libc/sys/fork.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn fork -function causes creation of a new process. +system call causes creation of a new process. The new process (child process) is an exact copy of the calling process (parent process) except for the following: .Bl -bullet -offset indent @@ -92,7 +92,7 @@ is set to indicate the error. .Sh ERRORS The .Fn fork -function will fail and no child process will be created if: +system call will fail and no child process will be created if: .Bl -tag -width Er .It Bq Er EAGAIN The system-imposed limit on the total @@ -129,7 +129,7 @@ There is insufficient swap space for the new process. .Xr vfork 2 , .Xr wait 2 .Sh HISTORY -A +The .Fn fork -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/sys/fsync.2 b/lib/libc/sys/fsync.2 index 821b096..883177e 100644 --- a/lib/libc/sys/fsync.2 +++ b/lib/libc/sys/fsync.2 @@ -45,14 +45,18 @@ .Ft int .Fn fsync "int fd" .Sh DESCRIPTION -.Fn Fsync +The +.Fn fsync +system call causes all modified data and attributes of .Fa fd to be moved to a permanent storage device. This normally results in all in-core modified copies of buffers for the associated file to be written to a disk. .Pp -.Fn Fsync +The +.Fn fsync +system call should be used by programs that require a file to be in a known state, for example, in building a simple transaction facility. @@ -79,5 +83,5 @@ An I/O error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn fsync -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getdirentries.2 b/lib/libc/sys/getdirentries.2 index 4efd448..0a286124 100644 --- a/lib/libc/sys/getdirentries.2 +++ b/lib/libc/sys/getdirentries.2 @@ -53,7 +53,7 @@ The .Fn getdirentries and .Fn getdents -functions read directory entries from the directory +system calls read directory entries from the directory referenced by the file descriptor .Fa fd into the buffer pointed to by @@ -68,7 +68,7 @@ argument must be greater than or equal to the block size associated with the file, see .Xr stat 2 . -Some file systems may not support these functions +Some file systems may not support these system calls with buffers smaller than this size. .Pp The data in the buffer is a series of @@ -130,7 +130,7 @@ the end of the directory has been reached. .Pp The .Fn getdirentries -function writes the position of the block read into the location pointed to by +system call writes the position of the block read into the location pointed to by .Fa basep . Alternatively, the current position pointer may be set and retrieved by .Xr lseek 2 . @@ -138,7 +138,7 @@ The current position pointer should only be set to a value returned by .Xr lseek 2 , a value returned in the location pointed to by .Fa basep -.Pf ( Fn getdirentries +.Fn ( getdirentries only) or zero. .Sh RETURN VALUES @@ -147,7 +147,9 @@ Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS -.Fn Getdirentries +The +.Fn getdirentries +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF @@ -177,9 +179,9 @@ error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn getdirentries -function first appeared in +system call first appeared in .Bx 4.4 . The .Fn getdents -function first appeared in +system call first appeared in .Fx 3.0 . diff --git a/lib/libc/sys/getdtablesize.2 b/lib/libc/sys/getdtablesize.2 index a5ed3dc..cda45fa 100644 --- a/lib/libc/sys/getdtablesize.2 +++ b/lib/libc/sys/getdtablesize.2 @@ -48,9 +48,9 @@ Each process has a fixed size descriptor table, which is guaranteed to have at least 20 slots. The entries in the descriptor table are numbered with small integers starting at 0. -The call +The .Fn getdtablesize -returns the size of this table. +system call returns the size of this table. .Sh SEE ALSO .Xr close 2 , .Xr dup 2 , @@ -59,5 +59,5 @@ returns the size of this table. .Sh HISTORY The .Fn getdtablesize -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getfh.2 b/lib/libc/sys/getfh.2 index fcaff6c..c61a8c5 100644 --- a/lib/libc/sys/getfh.2 +++ b/lib/libc/sys/getfh.2 @@ -46,7 +46,9 @@ .Ft int .Fn getfh "const char *path" "fhandle_t *fhp" .Sh DESCRIPTION -.Fn Getfh +The +.Fn getfh +system call returns a file handle for the specified file or directory in the file handle pointed to by .Fa fhp . @@ -54,7 +56,9 @@ This system call is restricted to the superuser. .Sh RETURN VALUES .Rv -std getfh .Sh ERRORS -.Fn Getfh +The +.Fn getfh +system call fails if one or more of the following are true: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -89,6 +93,5 @@ error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn getfh -function -first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/getfsstat.2 b/lib/libc/sys/getfsstat.2 index d25610b..c9bd8dc 100644 --- a/lib/libc/sys/getfsstat.2 +++ b/lib/libc/sys/getfsstat.2 @@ -47,7 +47,9 @@ .Ft int .Fn getfsstat "struct statfs *buf" "long bufsize" "int flags" .Sh DESCRIPTION -.Fn Getfsstat +The +.Fn getfsstat +system call returns information about all mounted file systems. .Fa Buf is a pointer to @@ -152,7 +154,9 @@ Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS -.Fn Getfsstat +The +.Fn getfsstat +system call fails if one or more of the following are true: .Bl -tag -width Er .It Bq Er EFAULT @@ -170,5 +174,5 @@ error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn getfsstat -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/getgid.2 b/lib/libc/sys/getgid.2 index 3bc8658..00c64ea 100644 --- a/lib/libc/sys/getgid.2 +++ b/lib/libc/sys/getgid.2 @@ -51,7 +51,7 @@ .Sh DESCRIPTION The .Fn getgid -function returns the real group ID of the calling process, +system call returns the real group ID of the calling process, .Fn getegid returns the effective group ID of the calling process. .Pp @@ -69,7 +69,7 @@ The .Fn getgid and .Fn getegid -functions are always successful, and no return value is reserved to +system calls are always successful, and no return value is reserved to indicate an error. .Sh SEE ALSO .Xr getuid 2 , @@ -81,5 +81,5 @@ The .Fn getgid and .Fn getegid -function calls are expected to conform to +system calls are expected to conform to .St -p1003.1-90 . diff --git a/lib/libc/sys/getgroups.2 b/lib/libc/sys/getgroups.2 index 3538b38..bdff4fb 100644 --- a/lib/libc/sys/getgroups.2 +++ b/lib/libc/sys/getgroups.2 @@ -46,7 +46,9 @@ .Ft int .Fn getgroups "int gidsetlen" "gid_t *gidset" .Sh DESCRIPTION -.Fn Getgroups +The +.Fn getgroups +system call gets the current group access list of the user process and stores it in the array .Fa gidset . @@ -54,7 +56,9 @@ The parameter .Fa gidsetlen indicates the number of entries that may be placed in .Fa gidset . -.Fn Getgroups +The +.Fn getgroups +system call returns the actual number of groups returned in .Fa gidset . No more than @@ -94,5 +98,5 @@ an invalid address. .Sh HISTORY The .Fn getgroups -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getitimer.2 b/lib/libc/sys/getitimer.2 index 5e3eda7..ef175d2 100644 --- a/lib/libc/sys/getitimer.2 +++ b/lib/libc/sys/getitimer.2 @@ -56,13 +56,13 @@ defined in .Ao Pa sys/time.h Ac . The .Fn getitimer -call returns the current value for the timer specified in +system call returns the current value for the timer specified in .Fa which in the structure at .Fa value . The .Fn setitimer -call sets a timer to the specified +system call sets a timer to the specified .Fa value (returning the previous value of the timer if .Fa ovalue @@ -149,9 +149,11 @@ compares two time values. .Sh RETURN VALUES .Rv -std .Sh ERRORS -.Fn Getitimer +The +.Fn getitimer and .Fn setitimer +system calls will fail if: .Bl -tag -width Er .It Bq Er EFAULT @@ -172,5 +174,5 @@ to be handled. .Sh HISTORY The .Fn getitimer -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getlogin.2 b/lib/libc/sys/getlogin.2 index dca0f60..7f7ba9b 100644 --- a/lib/libc/sys/getlogin.2 +++ b/lib/libc/sys/getlogin.2 @@ -66,7 +66,9 @@ for example when .Xr su 1 is used). .Pp +The .Fn getlogin_r +function provides the same service as .Fn getlogin except the caller must provide the buffer @@ -78,10 +80,12 @@ to hold the result. The buffer should be at least .Dv MAXLOGNAME bytes in length. .Pp +The .Fn setlogin +system call sets the login name of the user associated with the current session to .Fa name . -This call is restricted to the super-user, and +This system call is restricted to the super-user, and is normally used only when a new session is being created on behalf of the named user (for example, at login time, or when a remote shell is invoked). @@ -100,8 +104,8 @@ Making a system call is the .Em ONLY way to do this. The -.Fn daemon -library call calls +.Xr daemon 3 +function calls .Fn setsid which is an ideal way of detaching from a controlling terminal and forking into the background. @@ -116,7 +120,7 @@ sufficient. .Pp Once a parent process does a .Fn setsid -call, it is acceptable for some child of that process to then do a +system call, it is acceptable for some child of that process to then do a .Fn setlogin even though it is not the session leader, but beware that ALL processes in the session will change their login name at the same time, even the @@ -136,7 +140,9 @@ succeeds, it returns a pointer to a null-terminated string in a static buffer, or .Dv NULL if the name has not been set. +The .Fn getlogin_r +function returns zero if successful, or the error number upon failure. .Pp .Rv -std setlogin @@ -180,7 +186,7 @@ Portable programs should probably still make this check. .Sh HISTORY The .Fn getlogin -function first appeared in +system call first appeared in .Bx 4.4 . The return value of .Fn getlogin_r @@ -189,8 +195,12 @@ was changed from earlier versions of to be conformant with .St -p1003.1-96 . .Sh STANDARDS +The .Fn getlogin +system call and +the .Fn getlogin_r +function conform to .St -p1003.1-96 . diff --git a/lib/libc/sys/getpeername.2 b/lib/libc/sys/getpeername.2 index 7454550..627770a 100644 --- a/lib/libc/sys/getpeername.2 +++ b/lib/libc/sys/getpeername.2 @@ -46,7 +46,9 @@ .Ft int .Fn getpeername "int s" "struct sockaddr *name" "socklen_t *namelen" .Sh DESCRIPTION -.Fn Getpeername +The +.Fn getpeername +system call returns the name of the peer connected to socket .Fa s . @@ -92,5 +94,5 @@ process address space. .Sh HISTORY The .Fn getpeername -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getpgrp.2 b/lib/libc/sys/getpgrp.2 index a35f1ed..e96ba84 100644 --- a/lib/libc/sys/getpgrp.2 +++ b/lib/libc/sys/getpgrp.2 @@ -65,7 +65,7 @@ that have the same process group as the terminal are foreground and may read, while others will block with a signal if they attempt to read. .Pp -This call is thus used by programs such as +This system call is thus used by programs such as .Xr csh 1 to create process groups @@ -79,15 +79,17 @@ are used to get/set the process group of the control terminal. .Sh RETURN VALUES The .Fn getpgrp -call always succeeds. +system call always succeeds. Upon successful completion, the .Fn getpgid -call returns the process group of the specified process; +system call returns the process group of the specified process; otherwise, it returns a value of \-1 and sets .Va errno to indicate the error. .Sh ERRORS +The .Fn getpgid +system call will succeed unless: .Bl -tag -width Er .It Bq Er ESRCH @@ -101,15 +103,16 @@ there is no process whose process ID equals .Sh HISTORY The .Fn getpgrp -function call appeared in +system call appeared in .Bx 4.0 . The .Fn getpgid -function call is derived from its usage in System V Release 4. +system call is derived from its usage in +.At V.4 . .Sh STANDARDS The .Fn getpgrp -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh COMPATIBILITY This version of @@ -127,7 +130,7 @@ Rationale: .Bx 4.3 provides a .Fn getpgrp -function that returns the process group ID for a specified process. +system call that returns the process group ID for a specified process. Although this function is used to support job control, all known job-control shells always specify the calling process with this function. @@ -140,4 +143,4 @@ suffices, and the added complexity of the has been omitted from POSIX.1. The old functionality is available from the .Fn getpgid -function. +system call. diff --git a/lib/libc/sys/getpid.2 b/lib/libc/sys/getpid.2 index 4c9889c..20e3319 100644 --- a/lib/libc/sys/getpid.2 +++ b/lib/libc/sys/getpid.2 @@ -49,7 +49,9 @@ .Ft pid_t .Fn getppid void .Sh DESCRIPTION -.Fn Getpid +The +.Fn getpid +system call returns the process ID of the calling process. @@ -60,7 +62,9 @@ security reasons; see .Xr mkstemp 3 instead. .Pp -.Fn Getppid +The +.Fn getppid +system call returns the process ID of the parent of the calling process. .Sh ERRORS @@ -68,7 +72,7 @@ The .Fn getpid and .Fn getppid -functions are always successful, and no return value is reserved to +system calls are always successful, and no return value is reserved to indicate an error. .Sh SEE ALSO .Xr gethostid 3 @@ -77,10 +81,10 @@ The .Fn getpid and .Fn getppid -function calls are expected to conform to +system calls are expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn getpid -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/getpriority.2 b/lib/libc/sys/getpriority.2 index ef45d13b..9466435 100644 --- a/lib/libc/sys/getpriority.2 +++ b/lib/libc/sys/getpriority.2 @@ -56,9 +56,9 @@ and .Fa who is obtained with the .Fn getpriority -call and set with the +system call and set with the .Fn setpriority -call. +system call. .Fa Which is one of .Dv PRIO_PROCESS , @@ -85,10 +85,10 @@ lower priorities cause more favorable scheduling. .Pp The .Fn getpriority -call returns the highest priority (lowest numerical value) +system call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The .Fn setpriority -call sets the priorities of all of the specified processes +system call sets the priorities of all of the specified processes to the specified value. Only the super-user may lower priorities. .Sh RETURN VALUES Since @@ -102,9 +102,11 @@ if a -1 is an error or a legitimate value. .Pp .Rv -std setpriority .Sh ERRORS -.Fn Getpriority +The +.Fn getpriority and .Fn setpriority +system calls will fail if: .Bl -tag -width Er .It Bq Er ESRCH @@ -139,5 +141,5 @@ A non super-user attempted to lower a process priority. .Sh HISTORY The .Fn getpriority -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getrlimit.2 b/lib/libc/sys/getrlimit.2 index a4f144a..4ca298a 100644 --- a/lib/libc/sys/getrlimit.2 +++ b/lib/libc/sys/getrlimit.2 @@ -53,9 +53,9 @@ Limits on the consumption of system resources by the current process and each process it creates may be obtained with the .Fn getrlimit -call, and set with the +system call, and set with the .Fn setrlimit -call. +system call. .Pp The .Fa resource @@ -72,14 +72,14 @@ each process. The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the .Xr sbrk 2 -system call. +function. .It Li RLIMIT_FSIZE The largest size (in bytes) file that may be created. .It Li RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into memory using the .Xr mlock 2 -function. +system call. .It Li RLIMIT_NOFILE The maximum number of open files for this process. .It Li RLIMIT_NPROC @@ -137,7 +137,7 @@ is thus a built-in command to The system refuses to extend the data or stack space when the limits would be exceeded in the normal way: a .Xr brk 2 -call fails if the data space limit is reached. +function fails if the data space limit is reached. When the stack limit is reached, the process receives a segmentation fault .Pq Dv SIGSEGV ; @@ -157,9 +157,11 @@ offending process. .Sh RETURN VALUES .Rv -std .Sh ERRORS -.Fn Getrlimit +The +.Fn getrlimit and .Fn setrlimit +system calls will fail if: .Bl -tag -width Er .It Bq Er EFAULT @@ -183,5 +185,5 @@ raised the maximum limit value, and the caller is not the super-user. .Sh HISTORY The .Fn getrlimit -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getrusage.2 b/lib/libc/sys/getrusage.2 index 599bebc..2efa819 100644 --- a/lib/libc/sys/getrusage.2 +++ b/lib/libc/sys/getrusage.2 @@ -49,7 +49,9 @@ .Ft int .Fn getrusage "int who" "struct rusage *rusage" .Sh DESCRIPTION -.Fn Getrusage +The +.Fn getrusage +system call returns information describing the resources utilized by the current process, or all its terminated child processes. The @@ -156,7 +158,7 @@ to the first process to read or write the data. .Sh ERRORS The .Fn getrusage -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL The @@ -177,5 +179,5 @@ that has not yet terminated. .Sh HISTORY The .Fn getrusage -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getsid.2 b/lib/libc/sys/getsid.2 index 2800248..8d31074 100644 --- a/lib/libc/sys/getsid.2 +++ b/lib/libc/sys/getsid.2 @@ -46,13 +46,16 @@ is zero, .Fn getsid returns the session ID of the current process. .Sh RETURN VALUES -Upon successful completion, the function +Upon successful completion, the .Fn getsid +system call returns the session ID of the specified process; otherwise, it returns a value of -1 and sets errno to indicate an error. .Sh ERRORS +The .Fn getsid +system call will succeed unless: .Bl -tag -width Er .It Bq Er ESRCH @@ -60,7 +63,7 @@ if there is no process with a process ID equal to .Fa pid . .El .Pp -Note that an implementation may restrict this function call to +Note that an implementation may restrict this system call to processes within the same session ID as the calling process. .Sh SEE ALSO .Xr getpgid 2 , @@ -71,9 +74,9 @@ processes within the same session ID as the calling process. .Sh HISTORY The .Fn getsid -function call appeared in +system call appeared in .Fx 3.0 . The .Fn getsid -function call is derived from its usage in +system call is derived from its usage in .At V . diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2 index f4b3060..9f9005f 100644 --- a/lib/libc/sys/getsockname.2 +++ b/lib/libc/sys/getsockname.2 @@ -46,7 +46,9 @@ .Ft int .Fn getsockname "int s" "struct sockaddr *name" "socklen_t *namelen" .Sh DESCRIPTION -.Fn Getsockname +The +.Fn getsockname +system call returns the current .Fa name for the specified socket. The @@ -91,5 +93,5 @@ returns a zero length name. .Sh HISTORY The .Fn getsockname -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getsockopt.2 b/lib/libc/sys/getsockopt.2 index 8505f49..a6ef175 100644 --- a/lib/libc/sys/getsockopt.2 +++ b/lib/libc/sys/getsockopt.2 @@ -49,9 +49,11 @@ .Ft int .Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen" .Sh DESCRIPTION -.Fn Getsockopt +The +.Fn getsockopt and .Fn setsockopt +system calls manipulate the .Em options associated with a socket. Options may exist at multiple @@ -164,7 +166,7 @@ enables debugging in the underlying protocol modules. indicates that the rules used in validating addresses supplied in a .Xr bind 2 -call should allow reuse of local addresses. +system call should allow reuse of local addresses. .Dv SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set @@ -199,7 +201,7 @@ attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in seconds in the .Fn setsockopt -call when +system call when .Dv SO_LINGER is requested). If @@ -315,7 +317,7 @@ must be called on the socket before trying to install the filter on it, or else the .Fn setsockopt -call will fail. +system call will fail. .Bd -literal struct accept_filter_arg { char af_name[16]; diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 index b7bfca1..397388d 100644 --- a/lib/libc/sys/gettimeofday.2 +++ b/lib/libc/sys/gettimeofday.2 @@ -56,9 +56,9 @@ the kernel. The system's notion of the current Greenwich time and the current time zone is obtained with the .Fn gettimeofday -call, and set with the +system call, and set with the .Fn settimeofday -call. The time is expressed in seconds and microseconds +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 @@ -128,5 +128,5 @@ A user other than the super-user attempted to set the time. .Sh HISTORY The .Fn gettimeofday -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/getuid.2 b/lib/libc/sys/getuid.2 index e352adf..3e32fb0 100644 --- a/lib/libc/sys/getuid.2 +++ b/lib/libc/sys/getuid.2 @@ -51,10 +51,10 @@ .Sh DESCRIPTION The .Fn getuid -function returns the real user ID of the calling process. +system call returns the real user ID of the calling process. The .Fn geteuid -function +system call returns the effective user ID of the calling process. .Pp The real user ID is that of the user who has invoked the program. @@ -70,7 +70,7 @@ The .Fn getuid and .Fn geteuid -functions are always successful, and no return value is reserved to +system calls are always successful, and no return value is reserved to indicate an error. .Sh SEE ALSO .Xr getgid 2 , @@ -83,12 +83,12 @@ The .Fn geteuid and .Fn getuid -function calls are expected to conform to +system calls are expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn getuid -and a +and .Fn geteuid -function call appeared in +functions appeared in .At v7 . diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 index 3b4ef29..7b772e2 100644 --- a/lib/libc/sys/intro.2 +++ b/lib/libc/sys/intro.2 @@ -102,7 +102,7 @@ pathname was an empty string. .It Er 3 ESRCH Em "No such process" . No process could be found corresponding to that specified by the given process ID. -.It Er 4 EINTR Em "Interrupted function call" . +.It Er 4 EINTR Em "Interrupted system call" . An asynchronous signal (such as .Dv SIGINT or @@ -110,7 +110,7 @@ or was caught by the process during the execution of an interruptible function. If the signal handler performs a normal return, the -interrupted function call will seem to have returned the error condition. +interrupted system call will seem to have returned the error condition. .It Er 5 EIO Em "Input/output error" . Some physical input or output error occurred. This error will not be reported until a subsequent operation on the same file @@ -126,7 +126,7 @@ loaded on a drive. The number of bytes used for the argument and environment list of the new process exceeded the current limit of 65536 bytes -.Pf ( Dv NCARGS +.Dv ( NCARGS in .Aq Pa sys/param.h ) . .It Er 8 ENOEXEC Em "Exec format error" . @@ -170,7 +170,7 @@ in a manner which would have conflicted with the request. An existing file was mentioned in an inappropriate context, for instance, as the new link name in a .Xr link 2 -function. +system call. .It Er 18 EXDEV Em "Improper link" . A hard link to a file on another file system was attempted. @@ -189,9 +189,10 @@ Some invalid argument was supplied. (For example, specifying an undefined signal to a .Xr signal 3 -or +function +or a .Xr kill 2 -function). +system call). .It Er 23 ENFILE Em "Too many open files in system" . Maximum number of file descriptors allowable on the system has been reached and a requests for an open cannot be satisfied @@ -201,7 +202,7 @@ until at least one has been closed. open files per process is 64.> The .Xr getdtablesize 2 -function will obtain the current limit. +system call will obtain the current limit. .It Er 25 ENOTTY Em "Inappropriate ioctl for device" . A control function (see .Xr ioctl 2 ) @@ -230,7 +231,7 @@ on the file system. .It Er 29 ESPIPE Em "Illegal seek" . An .Xr lseek 2 -function was issued on a socket, pipe or +system call was issued on a socket, pipe or .Tn FIFO . .It Er 30 EROFS Em "Read-only file system" . An attempt was made to modify a file or directory diff --git a/lib/libc/sys/ioctl.2 b/lib/libc/sys/ioctl.2 index e779b9f..516bca7 100644 --- a/lib/libc/sys/ioctl.2 +++ b/lib/libc/sys/ioctl.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn ioctl -function manipulates the underlying device parameters of special files. +system call manipulates the underlying device parameters of special files. In particular, many operating characteristics of character special files (e.g. terminals) may be controlled with @@ -59,11 +59,11 @@ The argument must be an open file descriptor. .Pp The third argument to -.Nm +.Fn ioctl is traditionally named .Ar "char *argp" . Most uses of -.Nm +.Fn ioctl in .Fx 3.0 however, require the third argument to be a @@ -91,7 +91,9 @@ If an error has occurred, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS +The .Fn ioctl +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF @@ -121,7 +123,7 @@ points outside the process's allocated address space. .Xr intro 4 , .Xr tty 4 .Sh HISTORY -An +The .Fn ioctl -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/issetugid.2 b/lib/libc/sys/issetugid.2 index 10aa6df..5b0e6e7 100644 --- a/lib/libc/sys/issetugid.2 +++ b/lib/libc/sys/issetugid.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn issetugid -function returns 1 if the process environment or memory address space +system call returns 1 if the process environment or memory address space is considered .Dq tainted , and returns 0 otherwise. @@ -81,7 +81,7 @@ which begin setuid but need to be able to create an untainted process. .Sh ERRORS The .Fn issetugid -function is always successful, and no return value is reserved to +system call is always successful, and no return value is reserved to indicate an error. .Sh SEE ALSO .Xr execve 2 , @@ -93,9 +93,9 @@ indicate an error. .Xr setreuid 2 , .Xr setuid 2 .Sh HISTORY -A +The .Fn issetugid -function call first appeared in +system call first appeared in .Ox 2.0 and was also implemented in .Fx 3.0 . diff --git a/lib/libc/sys/jail.2 b/lib/libc/sys/jail.2 index 65b5c88..4656438 100644 --- a/lib/libc/sys/jail.2 +++ b/lib/libc/sys/jail.2 @@ -23,7 +23,7 @@ .Fn jail "struct jail *jail" .Sh DESCRIPTION The -.Nm +.Fn jail system call sets up a jail and locks the current process in it. .Pp The argument is a pointer to a structure describing the prison: @@ -75,7 +75,9 @@ it will show a field near the end of the line, either as a single hyphen for a process at large, or the hostname currently set for the prison for jailed processes. .Sh ERRORS +The .Fn jail +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL @@ -96,7 +98,7 @@ manual page for details. .Sh HISTORY The .Fn jail -function call appeared in +system call appeared in .Fx 4.0 . .Sh AUTHORS The jail feature was written by diff --git a/lib/libc/sys/kenv.2 b/lib/libc/sys/kenv.2 index 9d8bd32..2ca1c99 100644 --- a/lib/libc/sys/kenv.2 +++ b/lib/libc/sys/kenv.2 @@ -41,7 +41,7 @@ .Sh DESCRIPTION The .Fn kenv -function manipulates kernel environment variables. +system call manipulates kernel environment variables. It supports the well known userland actions of getting, setting and unsetting environment variables, as well as the ability to dump all of the entries in the kernel environment. @@ -119,7 +119,7 @@ points to. .Sh RETURN VALUES The .Fn kenv -function returns 0 if successful in the case of +system call returns 0 if successful in the case of .Dv KENV_SET and .Dv KENV_UNSET , @@ -134,7 +134,9 @@ the global variable .Va errno is set to indicate the error. .Sh ERRORS +The .Fn kenv +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/kill.2 b/lib/libc/sys/kill.2 index a04f46f..7cbe63d 100644 --- a/lib/libc/sys/kill.2 +++ b/lib/libc/sys/kill.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn kill -function sends the signal given by +system call sends the signal given by .Fa sig to .Fa pid , @@ -108,7 +108,9 @@ This is a variant of .Sh RETURN VALUES .Rv -std kill .Sh ERRORS -.Fn Kill +The +.Fn kill +system call will fail and no signal will be sent if: .Bl -tag -width Er .It Bq Er EINVAL @@ -136,10 +138,10 @@ of the group could not be signaled. .Sh STANDARDS The .Fn kill -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn kill -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/kldfind.2 b/lib/libc/sys/kldfind.2 index b7be17a..a8892ed 100644 --- a/lib/libc/sys/kldfind.2 +++ b/lib/libc/sys/kldfind.2 @@ -39,12 +39,15 @@ .Ft int .Fn kldfind "const char *file" .Sh DESCRIPTION -The function +The .Fn kldfind +system call returns the fileid of the kld file referenced by .Fa file . .Sh RETURN VALUES +The .Fn kldfind +system call returns the fileid of the kld file referenced by .Fa file . Upon error, diff --git a/lib/libc/sys/kldfirstmod.2 b/lib/libc/sys/kldfirstmod.2 index 8b51be0..d9967cc 100644 --- a/lib/libc/sys/kldfirstmod.2 +++ b/lib/libc/sys/kldfirstmod.2 @@ -41,7 +41,7 @@ .Sh DESCRIPTION The .Fn kldfirstmod -function returns the module id pertaining to the first module referenced by +system call returns the module id pertaining to the first module referenced by .Fa fileid . .Sh RETURN VALUES The diff --git a/lib/libc/sys/kldload.2 b/lib/libc/sys/kldload.2 index e289a5e..60db2ec 100644 --- a/lib/libc/sys/kldload.2 +++ b/lib/libc/sys/kldload.2 @@ -39,12 +39,14 @@ .Ft int .Fn kldload "const char *file" .Sh DESCRIPTION -The function +The .Fn kldload +system call loads a kld file into the kernel using the kernel linker. .Sh RETURN VALUES -The function +The .Fn kldload +system call returns the fileid of the kld file which was loaded into the kernel. If an error occurs, .Fn kldload @@ -58,7 +60,7 @@ The named file is loaded unless: You do not have access to read the file or link it with the kernel. You should be the root user to be able to use the .Nm kld -functions. +system calls. .It Bq Er EFAULT Bad address encountered when adding kld info into the kernel space. .It Bq Er ENOMEM diff --git a/lib/libc/sys/kldnext.2 b/lib/libc/sys/kldnext.2 index bf56ad0..4cf443c 100644 --- a/lib/libc/sys/kldnext.2 +++ b/lib/libc/sys/kldnext.2 @@ -39,15 +39,18 @@ .Ft int .Fn kldnext "int fileid" .Sh DESCRIPTION -The function +The .Fn kldnext +system call returns the fileid of the next kld file (that is, the one after .Va fileid ) or 0 if .Va fileid is the last file loaded. .Sh RETURN VALUES +The .Fn kldnext +system call returns the fileid of the next kld file (see DESCRIPTION) or 0. If an error occurs, .Va errno diff --git a/lib/libc/sys/kldstat.2 b/lib/libc/sys/kldstat.2 index 99b06f7..5f91520 100644 --- a/lib/libc/sys/kldstat.2 +++ b/lib/libc/sys/kldstat.2 @@ -41,7 +41,7 @@ .Sh DESCRIPTION The .Fn kldstat -function writes the info for the file referred to by +system call writes the info for the file referred to by .Fa fileid into .Fa stat . @@ -101,7 +101,7 @@ field. There was a problem copying one, some, or all of the fields into .Fa stat in the -.Fn copyout +.Xr copyout 9 function. .El .Sh SEE ALSO diff --git a/lib/libc/sys/kldsym.2 b/lib/libc/sys/kldsym.2 index 127b2ed..3a2f32d 100644 --- a/lib/libc/sys/kldsym.2 +++ b/lib/libc/sys/kldsym.2 @@ -40,7 +40,7 @@ .Sh DESCRIPTION The .Fn kldsym -function returns the address of the symbol specified in +system call returns the address of the symbol specified in .Fa data in the module specified by .Fa fileid . @@ -91,7 +91,7 @@ and the size of the data it points to, respectively. .Sh ERRORS The .Fn kldsym -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL Invalid value in @@ -116,5 +116,5 @@ or the specified symbol could not be found. .Sh HISTORY The .Fn kldsym -function first appeared in +system call first appeared in .Fx 3.0 . diff --git a/lib/libc/sys/kldunload.2 b/lib/libc/sys/kldunload.2 index 7cbd528..aa042d2 100644 --- a/lib/libc/sys/kldunload.2 +++ b/lib/libc/sys/kldunload.2 @@ -39,8 +39,9 @@ .Ft int .Fn kldunload "int fileid" .Sh DESCRIPTION -The function +The .Fn kldunload +system call unloads a kld file from the kernel that was previously linked via .Xr kldload 2 . .Sh RETURN VALUES diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2 index 0dae6b1..2d65591 100644 --- a/lib/libc/sys/kqueue.2 +++ b/lib/libc/sys/kqueue.2 @@ -43,7 +43,9 @@ .Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout" .Fn EV_SET "&kev" ident filter flags fflags data udata .Sh DESCRIPTION +The .Fn kqueue +system call provides a generic method of notifying the user when an event happens or a condition holds, based on the results of small pieces of kernel code termed filters. @@ -69,7 +71,9 @@ Calling .Fn close on a file descriptor will remove any kevents that reference the descriptor. .Pp +The .Fn kqueue +system call creates a new kernel event queue and returns a descriptor. The queue is not inherited by a child created with .Xr fork 2 . @@ -80,7 +84,9 @@ is called without the flag, then the descriptor table is shared, which will allow sharing of the kqueue between two processes. .Pp +The .Fn kevent +system call is used to register events with the queue, and return any pending events to the user. .Fa changelist @@ -115,8 +121,9 @@ structure. The same array may be used for the and .Fa eventlist . .Pp +The .Fn EV_SET -is a macro which is provided for ease of initializing a +macro is provided for ease of initializing a kevent structure. .Pp The @@ -272,12 +279,16 @@ be attached to, containing the udata value, and .Va sigev_notify set to SIGEV_KEVENT. -When the aio_* function is called, the event will be registered +When the +.Fn aio_* +system call is made, the event will be registered with the specified kqueue, and the .Va ident argument set to the .Fa struct aiocb -returned by the aio_* function. +returned by the +.Fn aio_* +system call. The filter returns under the same conditions as aio_error. .Pp Alternatively, a kevent structure may be initialized, with @@ -294,7 +305,9 @@ and returns when one or more of the requested events occurs on the descriptor. The events to monitor are: .Bl -tag -width XXNOTE_RENAME .It NOTE_DELETE +The .Fn unlink +system call was called on the file referenced by the descriptor. .It NOTE_WRITE A write occurred on the file referenced by the descriptor. @@ -378,12 +391,16 @@ contains the number of times the timeout has expired since the last call to This filter automatically sets the EV_CLEAR flag internally. .El .Sh RETURN VALUES +The .Fn kqueue +system call creates a new kernel event queue and returns a file descriptor. If there was an error creating the kernel event queue, a value of -1 is returned and errno set. .Pp +The .Fn kevent +system call returns the number of events placed in the .Fa eventlist , up to the value given by @@ -411,7 +428,7 @@ returns 0. .Sh ERRORS The .Fn kqueue -function fails if: +system call fails if: .Bl -tag -width Er .It Bq Er ENOMEM The kernel failed to allocate enough memory for the kernel queue. @@ -423,7 +440,7 @@ The system file table is full. .Pp The .Fn kevent -function fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EACCES The process does not have permission to register a filter. @@ -460,7 +477,7 @@ The .Fn kqueue and .Fn kevent -functions first appeared in +system calls first appeared in .Fx 4.1 . .Sh AUTHORS The diff --git a/lib/libc/sys/kse.2 b/lib/libc/sys/kse.2 index 0497bc2..4222c05 100644 --- a/lib/libc/sys/kse.2 +++ b/lib/libc/sys/kse.2 @@ -57,7 +57,7 @@ .Ft int .Fn kse_thr_interrupt "struct kse_thr_mailbox *tmbx" .Sh DESCRIPTION -These functions implement kernel support for multi-threaded processes. +These system calls implement kernel support for multi-threaded processes. .\" .Ss Overview .\" @@ -210,7 +210,9 @@ received). .\" To become multi-threaded, a process must first invoke .Fn kse_create . +The .Fn kse_create +system call creates a new KSE (except for the very first invocation; see below). The KSE will be associated with the mailbox pointed to by .Fa mbx . @@ -248,20 +250,24 @@ There may however be arbitrarily many user threads, and it is up to the user thread scheduler to handle mapping the application's user threads onto the available KSEs. .Pp +The .Fn kse_exit +system call causes the KSE assigned to the currently running thread to be destroyed. If this KSE is the last one in the KSE group, there must be no remaining threads associated with the KSE group blocked in the kernel. -This function does not return. +This system call does not return. .Pp As a special case, if the last remaining KSE in the last remaining KSE group -invokes this function, then the KSE is not destroyed; +invokes this system call, then the KSE is not destroyed; instead, the KSE just looses the association with its mailbox and .Fn kse_exit returns normally. This returns the process to its original, unthreaded state. .Pp +The .Fn kse_release +system call is used to .Dq park the KSE assigned to the currently running thread when it is not needed, @@ -272,13 +278,15 @@ If successful, .Fn kse_release does not return. .Pp +The .Fn kse_wakeup +system call is the opposite of .Fn kse_release . It causes the KSE associated with the mailbox pointed to by .Fa mbx to be woken up, causing it to upcall. -If the KSE has already woken up for another reason, this function has no +If the KSE has already woken up for another reason, this system call has no effect. The .Fa mbx @@ -287,7 +295,9 @@ may be to specify .Dq "any KSE in the current KSE group" . .Pp +The .Fn kse_thr_interrupt +system call is used to interrupt a currently blocked thread. The thread must either be blocked in the kernel or assigned to a KSE (i.e., executing). @@ -488,22 +498,28 @@ may contain any of the following bits OR'ed together: (No flags are defined yet.) .El .Sh RETURN VALUES +The .Fn kse_create , kse_wakeup , and .Fn kse_thr_interrupt +system calls return zero if successful. +The .Fn kse_exit and .Fn kse_release +system calls do not return if successful. .Pp -All of these functions return a non-zero error code in case of an error. +All of these system calls return a non-zero error code in case of an error. .Pp .Em Note : error codes are returned directly rather than via .Va errno . .Sh ERRORS +The .Fn kse_create +system call will fail if: .Bl -tag -width Er .It Bq Er ENXIO @@ -535,7 +551,9 @@ would be exceeded (see points to an address which is not a valid part of the process address space. .El .Pp +The .Fn kse_exit +system call will fail if: .Bl -tag -width Er .It Bq Er EDEADLK @@ -548,7 +566,9 @@ in traditional, unthreaded mode (in this case use to exit the process). .El .Pp +The .Fn kse_release +system call will fail if: .Bl -tag -width Er .It Bq Er ESRCH @@ -556,7 +576,9 @@ The current KSE has no associated mailbox, i.e., the process is operating is traditional, unthreaded mode. .El .Pp +The .Fn kse_wakeup +system call will fail if: .Bl -tag -width Er .It Bq Er ESRCH @@ -574,7 +596,9 @@ and the current KSE has no associated mailbox, i.e., the process is operating in traditional, unthreaded mode. .El .Pp +The .Fn kse_thr_interrupt +system call will fail if: .Bl -tag -width Er .It Bq Er ESRCH @@ -601,7 +625,7 @@ kernel. .%T "Scheduler activations: effective kernel support for the user-level management of parallelism" .Re .Sh HISTORY -The KSE function calls first appeared in +The KSE system calls first appeared in .Fx 5.0 . .Sh AUTHORS KSE was originally implemented by diff --git a/lib/libc/sys/ktrace.2 b/lib/libc/sys/ktrace.2 index 6060e3f..41761a0 100644 --- a/lib/libc/sys/ktrace.2 +++ b/lib/libc/sys/ktrace.2 @@ -50,7 +50,7 @@ .Sh DESCRIPTION The .Fn ktrace -function enables or disables tracing of one or more processes. +system call enables or disables tracing of one or more processes. Users may only trace their own processes. Only the super-user can trace setuid or setgid programs. .Pp @@ -137,7 +137,9 @@ include file. .Sh RETURN VALUES .Rv -std ktrace .Sh ERRORS -.Fn Ktrace +The +.Fn ktrace +system call will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -162,7 +164,7 @@ support. .Xr kdump 1 , .Xr ktrace 1 .Sh HISTORY -A +The .Fn ktrace -function call first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 index 5d44d2d..dbf2682 100644 --- a/lib/libc/sys/link.2 +++ b/lib/libc/sys/link.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn link -function call +system call atomically creates the specified directory entry (hard link) .Fa name2 with the attributes of the underlying object pointed at by @@ -82,7 +82,9 @@ may not be a directory. .Sh RETURN VALUES .Rv -std link .Sh ERRORS -.Fn Link +The +.Fn link +system call will fail and no link will be created if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -153,12 +155,12 @@ is outside the process's allocated address space. .Sh STANDARDS The .Fn link -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn link -function call appeared in +function appeared in .At v7 . .Pp The diff --git a/lib/libc/sys/listen.2 b/lib/libc/sys/listen.2 index 6423850..c7a9bdb 100644 --- a/lib/libc/sys/listen.2 +++ b/lib/libc/sys/listen.2 @@ -57,7 +57,7 @@ accepted with .Xr accept 2 . The .Fn listen -call applies only to sockets of type +system call applies only to sockets of type .Dv SOCK_STREAM or .Dv SOCK_SEQPACKET . @@ -120,7 +120,9 @@ parameter. .Sh RETURN VALUES .Rv -std listen .Sh ERRORS -.Fn Listen +The +.Fn listen +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF @@ -145,7 +147,7 @@ The socket is not of a type that supports the operation .Sh HISTORY The .Fn listen -function call appeared in +system call appeared in .Bx 4.2 . The ability to configure the maximum .Fa backlog diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 index 988b52b..c2a04de 100644 --- a/lib/libc/sys/lseek.2 +++ b/lib/libc/sys/lseek.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn lseek -function repositions the offset of the file descriptor +system call repositions the offset of the file descriptor .Fa fildes to the argument @@ -58,7 +58,9 @@ The argument .Fa fildes must be an open file descriptor. -.Fn Lseek +The +.Fn lseek +system call repositions the file position pointer associated with the file descriptor .Fa fildes @@ -93,7 +95,7 @@ bytes. .Pp The .Fn lseek -function allows the file offset to be set beyond the end +system call allows the file offset to be set beyond the end of the existing end-of-file of the file. If data is later written at this point, subsequent reads of the data in the gap return @@ -112,7 +114,9 @@ a value of -1 is returned and is set to indicate the error. .Sh ERRORS -.Fn Lseek +The +.Fn lseek +system call will fail and the file position pointer will remain unchanged if: .Bl -tag -width Er .It Bq Er EBADF @@ -141,10 +145,10 @@ is incorrect English, but is maintained for historical reasons. .Sh STANDARDS The .Fn lseek -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn lseek -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2 index 2260a7d..8b6ed9d 100644 --- a/lib/libc/sys/madvise.2 +++ b/lib/libc/sys/madvise.2 @@ -136,7 +136,7 @@ Include region in a core file. .Sh ERRORS The .Fn madvise -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL The virtual address range specified by the @@ -153,5 +153,5 @@ arguments is not valid. .Sh HISTORY The .Fn madvise -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/mincore.2 b/lib/libc/sys/mincore.2 index 914153d..2c70dbb 100644 --- a/lib/libc/sys/mincore.2 +++ b/lib/libc/sys/mincore.2 @@ -81,5 +81,5 @@ The vector description is wrong. .Sh HISTORY The .Fn mincore -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/minherit.2 b/lib/libc/sys/minherit.2 index cb9d1e0..b19e36d 100644 --- a/lib/libc/sys/minherit.2 +++ b/lib/libc/sys/minherit.2 @@ -61,7 +61,7 @@ Inheritance only effects children created by It has no effect on .Fn exec . exec'd processes replace their address space entirely. -This function also +This system call also has no effect on the parent's address space (other than to potentially share the address space with its children). .Pp @@ -101,7 +101,7 @@ space in the parent. .Sh ERRORS The .Fn minherit -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL The virtual address range specified by the @@ -137,5 +137,5 @@ short of unmapping and remapping the area. .Sh HISTORY The .Fn minherit -function first appeared in +system call first appeared in .Ox . diff --git a/lib/libc/sys/mkdir.2 b/lib/libc/sys/mkdir.2 index cc5cd8c..8ef3f18 100644 --- a/lib/libc/sys/mkdir.2 +++ b/lib/libc/sys/mkdir.2 @@ -60,7 +60,9 @@ which it is created. .Sh RETURN VALUES .Rv -std mkdir .Sh ERRORS -.Fn Mkdir +The +.Fn mkdir +system call will fail and no directory will be created if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -108,5 +110,5 @@ points outside the process's allocated address space. .Sh STANDARDS The .Fn mkdir -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . diff --git a/lib/libc/sys/mkfifo.2 b/lib/libc/sys/mkfifo.2 index b85c021..19461be 100644 --- a/lib/libc/sys/mkfifo.2 +++ b/lib/libc/sys/mkfifo.2 @@ -46,7 +46,9 @@ .Ft int .Fn mkfifo "const char *path" "mode_t mode" .Sh DESCRIPTION -.Fn Mkfifo +The +.Fn mkfifo +system call creates a new fifo file with name .Fa path . The access permissions are @@ -62,7 +64,9 @@ which it is created. .Sh RETURN VALUES .Rv -std mkfifo .Sh ERRORS -.Fn Mkfifo +The +.Fn mkfifo +system call will fail and no fifo will be created if: .Bl -tag -width Er .It Bq Er ENOTSUP @@ -117,5 +121,5 @@ points outside the process's allocated address space. .Sh STANDARDS The .Fn mkfifo -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . diff --git a/lib/libc/sys/mknod.2 b/lib/libc/sys/mknod.2 index f23bce2..849e17a 100644 --- a/lib/libc/sys/mknod.2 +++ b/lib/libc/sys/mknod.2 @@ -61,12 +61,16 @@ Otherwise, .Fa dev is ignored. .Pp -.Fn Mknod +The +.Fn mknod +system call requires super-user privileges. .Sh RETURN VALUES .Rv -std mknod .Sh ERRORS -.Fn Mknod +The +.Fn mknod +system call will fail and the file will be not created if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -118,7 +122,7 @@ is not supported. .Xr stat 2 , .Xr umask 2 .Sh HISTORY -A +The .Fn mknod -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/sys/mlock.2 b/lib/libc/sys/mlock.2 index c6f168b..c4839c0 100644 --- a/lib/libc/sys/mlock.2 +++ b/lib/libc/sys/mlock.2 @@ -59,7 +59,7 @@ for bytes. The .Fn munlock -call unlocks pages previously locked by one or more +system call unlocks pages previously locked by one or more .Fn mlock calls. For both, the @@ -73,7 +73,7 @@ The entire range must be allocated. .Pp After an .Fn mlock -call, the indicated pages will cause neither a non-resident page +system call, the indicated pages will cause neither a non-resident page nor address-translation fault until they are unlocked. They may still cause protection-violation faults or TLB-miss faults on architectures with software-managed TLBs. @@ -110,7 +110,9 @@ These calls are only available to the super-user. If the call succeeds, all pages in the range become locked (unlocked); otherwise the locked status of all pages in the range remains unchanged. .Sh ERRORS -.Fn Mlock +The +.Fn mlock +system call will fail if: .Bl -tag -width Er .It Bq Er EPERM @@ -124,7 +126,9 @@ limit for locked memory. Some portion of the indicated address range is not allocated. There was an error faulting/mapping a page. .El -.Fn Munlock +The +.Fn munlock +system call will fail if: .Bl -tag -width Er .It Bq Er EPERM @@ -167,5 +171,5 @@ The .Fn mlock and .Fn munlock -functions first appeared in +system calls first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 index f336df5..05f5b4f 100644 --- a/lib/libc/sys/mmap.2 +++ b/lib/libc/sys/mmap.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn mmap -function causes the pages starting at +system call causes the pages starting at .Fa addr and continuing for at most .Fa len @@ -186,7 +186,7 @@ while reading a large file sequentially, e.g. using .Pp The .Xr fsync 2 -function will flush all dirty data and metadata associated with a file, +system call will flush all dirty data and metadata associated with a file, including dirty NOSYNC VM data, to physical media. The .Xr sync 8 @@ -233,7 +233,7 @@ address returned by the call. .Pp The .Xr close 2 -function does not unmap pages, see +system call does not unmap pages, see .Xr munmap 2 for further information. .Pp @@ -254,7 +254,9 @@ is returned and .Va errno is set to indicate the error. .Sh ERRORS -.Fn Mmap +The +.Fn mmap +system call will fail if: .Bl -tag -width Er .It Bq Er EACCES diff --git a/lib/libc/sys/modfind.2 b/lib/libc/sys/modfind.2 index 35fa7c9..3f48579 100644 --- a/lib/libc/sys/modfind.2 +++ b/lib/libc/sys/modfind.2 @@ -39,12 +39,15 @@ .Ft int .Fn modfind "const char *modname" .Sh DESCRIPTION -The function +The .Fn modfind +system call returns the modid of the kernel module referenced by .Fa modname . .Sh RETURN VALUES +The .Fn modfind +system call returns the modid of the kernel module referenced by .Fa file . Upon error, diff --git a/lib/libc/sys/modnext.2 b/lib/libc/sys/modnext.2 index dc578ad..b512b7b 100644 --- a/lib/libc/sys/modnext.2 +++ b/lib/libc/sys/modnext.2 @@ -41,8 +41,9 @@ .Ft int .Fn modfnext "int modid" .Sh DESCRIPTION -The function +The .Fn modnext +system call returns the modid of the next kernel module (that is, the one after .Va modid ) or 0 if @@ -54,11 +55,17 @@ If the value is 0, then .Fn modnext will return the modid of the first module. +The .Fn modfnext +system call must always be given a valid modid. .Sh RETURN VALUES +The .Fn modnext -returns the modid of the next module (see DESCRIPTION) or 0. If an error +system call +returns the modid of the next module (see +.Sx DESCRIPTION ) +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 d19f469..21673f5 100644 --- a/lib/libc/sys/modstat.2 +++ b/lib/libc/sys/modstat.2 @@ -41,7 +41,7 @@ .Sh DESCRIPTION The .Fn modstat -function writes the info for the kernel module referred to by +system call writes the info for the kernel module referred to by .Fa modid into .Fa stat . @@ -104,7 +104,7 @@ field. There was a problem copying one, some, or all of the fields into .Fa stat in the -.Fn copyout +.Xr copyout 9 function. .El .Sh SEE ALSO diff --git a/lib/libc/sys/mount.2 b/lib/libc/sys/mount.2 index b5f92f2..7922158 100644 --- a/lib/libc/sys/mount.2 +++ b/lib/libc/sys/mount.2 @@ -51,7 +51,7 @@ .Sh DESCRIPTION The .Fn mount -function grafts +system call grafts a file system object onto the system file tree at the point .Ar dir . @@ -137,14 +137,14 @@ By convention file system manual pages are named by prefixing ``mount_'' to the name of the file system as returned by .Xr lsvfs 1 . Thus the -.Nm NFS +.Tn NFS file system is described by the .Xr mount_nfs 8 manual page. .Pp The .Fn unmount -function call disassociates the file system from the specified +system call disassociates the file system from the specified mount point .Fa dir . .Pp @@ -173,7 +173,7 @@ pages for more information. .Sh ERRORS The .Fn mount -function will fail when one of the following occurs: +system call will fail when one of the following occurs: .Bl -tag -width Er .It Bq Er EPERM The caller is not the super-user. @@ -250,7 +250,7 @@ points outside the process's allocated address space. .Pp The .Fn unmount -function may fail with one of the following errors: +system call may fail with one of the following errors: .Bl -tag -width Er .It Bq Er EPERM The caller is not the super-user. @@ -284,8 +284,9 @@ mounted. .Sh BUGS Some of the error codes need translation to more obvious messages. .Sh HISTORY -.Fn Mount +The +.Fn mount and .Fn unmount -function calls appeared in +functions appeared in .At v6 . diff --git a/lib/libc/sys/mprotect.2 b/lib/libc/sys/mprotect.2 index 99894a4..6dd28da 100644 --- a/lib/libc/sys/mprotect.2 +++ b/lib/libc/sys/mprotect.2 @@ -57,7 +57,7 @@ the granularity of protection changes may be as large as an entire region. .Sh ERRORS The .Fn mprotect -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL The virtual address range specified by the @@ -80,5 +80,5 @@ argument. .Sh HISTORY The .Fn mprotect -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2 index 6960c98..254ed12 100644 --- a/lib/libc/sys/msync.2 +++ b/lib/libc/sys/msync.2 @@ -73,7 +73,9 @@ MS_INVALIDATE Invalidate all cached data .Sh RETURN VALUES .Rv -std msync .Sh ERRORS +The .Fn msync +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL @@ -97,5 +99,5 @@ An I/O error occurred while writing to the file system. .Sh HISTORY The .Fn msync -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/munmap.2 b/lib/libc/sys/munmap.2 index 47e0128..f6acf79 100644 --- a/lib/libc/sys/munmap.2 +++ b/lib/libc/sys/munmap.2 @@ -54,7 +54,9 @@ to generate invalid memory references. .Sh RETURN VALUES .Rv -std munmap .Sh ERRORS -.Fn Munmap +The +.Fn munmap +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL @@ -76,5 +78,5 @@ valid address range for a process. .Sh HISTORY The .Fn munmap -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/nanosleep.2 b/lib/libc/sys/nanosleep.2 index 5a39a44..b628131 100644 --- a/lib/libc/sys/nanosleep.2 +++ b/lib/libc/sys/nanosleep.2 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .\" $OpenBSD: nanosleep.2,v 1.1 1997/04/20 20:56:20 tholo Exp $ .\" $NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $ .\" @@ -34,6 +33,7 @@ .\" SUCH DAMAGE. .\" .\" @(#)sleep.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ .\" .Dd April 17, 1997 .Dt NANOSLEEP 2 @@ -48,7 +48,9 @@ .Ft int .Fn nanosleep "const struct timespec *rqtp" "struct timespec *rmtp" .Sh DESCRIPTION -.Fn Nanosleep +The +.Fn nanosleep +system call 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 @@ -56,25 +58,25 @@ value on the interrupting signal. .Sh RETURN VALUES If the .Fn nanosleep -function returns because the requested time has elapsed, the value +system call returns because the requested time has elapsed, the value returned will be zero. .Pp If the .Fn nanosleep -function returns due to the delivery of a signal, the value returned +system call returns due to the delivery of a signal, the value returned will be the -1, and the global variable .Va errno will be set to indicate the interruption. If .Fa rmtp is -.Pf non- Dv NULL , +.No non- Ns Dv NULL , the timespec structure it references is updated to contain the unslept amount (the request time minus the time actually slept). .Sh ERRORS The .Fn nanosleep -call fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EFAULT Either @@ -84,14 +86,18 @@ or points to memory that is not a valid part of the process address space. .It Bq Er EINTR +The .Fn nanosleep +system call was interrupted by the delivery of a signal. .It Bq Er EINVAL .Fa rqtp specified a nanosecond value less than zero or greater than or equal to 1000 million. .It Bq Er ENOSYS +The .Fn nanosleep +system call is not supported by this implementation. .El .Sh SEE ALSO @@ -100,5 +106,5 @@ is not supported by this implementation. .Sh STANDARDS The .Fn nanosleep -function conforms to +system call conforms to .St -p1003.1b-93 . diff --git a/lib/libc/sys/nfssvc.2 b/lib/libc/sys/nfssvc.2 index 1c24040..25f2773 100644 --- a/lib/libc/sys/nfssvc.2 +++ b/lib/libc/sys/nfssvc.2 @@ -52,7 +52,7 @@ .Sh DESCRIPTION The .Fn nfssvc -function is used by the NFS daemons to pass information into and out +system call is used by the NFS daemons to pass information into and out of the kernel and also to enter the kernel as a server daemon. The .Fa flags @@ -76,7 +76,7 @@ set to .Dv NULL to enter the kernel as a block I/O server daemon. For -.Nm NQNFS , +.Tn NQNFS , .Xr mount_nfs 8 calls .Fn nfssvc @@ -243,7 +243,7 @@ The caller is not the super-user. .Sh HISTORY The .Fn nfssvc -function first appeared in +system call first appeared in .Bx 4.4 . .Sh BUGS The diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 index f9d3dac..8775f0e 100644 --- a/lib/libc/sys/open.2 +++ b/lib/libc/sys/open.2 @@ -59,7 +59,7 @@ created if it does not exist (by specifying the .Dv O_CREAT flag). In this case -.Nm +.Fn open requires a third argument .Fa "mode_t mode" , and the file is created with mode @@ -118,7 +118,7 @@ If the .Dv O_NONBLOCK flag is specified and the .Fn open -call would result +system call would result in the process being blocked for some reason (e.g., waiting for carrier on a dialup line), .Fn open @@ -286,7 +286,7 @@ allocating the inode for The file is a pure procedure (shared text) file that is being executed and the .Fn open -call requests write access. +system call requests write access. .It Bq Er EFAULT .Fa Path points outside the process's allocated address space. @@ -315,7 +315,7 @@ and .Xr umask 2 , .Xr write 2 .Sh HISTORY -An +The .Fn open -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/sys/pathconf.2 b/lib/libc/sys/pathconf.2 index fbf54cc..de521bb 100644 --- a/lib/libc/sys/pathconf.2 +++ b/lib/libc/sys/pathconf.2 @@ -52,7 +52,7 @@ The .Fn pathconf and .Fn fpathconf -functions provides a method for applications to determine the current +system calls provide a method for applications to determine the current value of a configurable system limit or option variable associated with a pathname or file descriptor. .Pp @@ -155,7 +155,7 @@ If any of the following conditions occur, the .Fn pathconf and .Fn fpathconf -functions shall return -1 and set +system calls shall return -1 and set .Va errno to the corresponding value. .Bl -tag -width Er @@ -168,7 +168,9 @@ The implementation does not support an association of the variable name with the associated file. .El .Pp -.Fn Pathconf +The +.Fn pathconf +system call will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -187,7 +189,9 @@ An I/O error occurred while reading from or writing to the file system. .El .Pp .Bl -tag -width Er -.Fn Fpathconf +The +.Fn fpathconf +system call will fail if: .It Bq Er EBADF .Fa fd @@ -202,5 +206,5 @@ The .Fn pathconf and .Fn fpathconf -functions first appeared in +system calls first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/pipe.2 b/lib/libc/sys/pipe.2 index 8372978..10c33b8 100644 --- a/lib/libc/sys/pipe.2 +++ b/lib/libc/sys/pipe.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn pipe -function +system call creates a .Em pipe , which is an object allowing @@ -92,7 +92,7 @@ pipe in one direction. .Sh ERRORS The .Fn pipe -call will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EMFILE Too many descriptors are active. @@ -111,9 +111,9 @@ space. .Xr socketpair 2 , .Xr write 2 .Sh HISTORY -A +The .Fn pipe -function call appeared in +function appeared in .At v3 . .Pp Bidirectional pipes were first used on diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 index df306e7..1026811 100644 --- a/lib/libc/sys/poll.2 +++ b/lib/libc/sys/poll.2 @@ -41,7 +41,9 @@ .Ft int .Fn poll "struct pollfd fds[]" "nfds_t nfds" "int timeout" .Sh DESCRIPTION -.Fn Poll +The +.Fn poll +system call examines a set of file descriptors to see if some of them are ready for I/O. The @@ -128,7 +130,9 @@ is zero, then .Fn poll will return without blocking. .Sh RETURN VALUES -.Fn Poll +The +.Fn poll +system call returns the number of descriptors that are ready for I/O, or -1 if an error occured. If the time limit expires, .Fn poll @@ -136,7 +140,7 @@ returns 0. If .Fn poll returns with an error, -including one due to an interrupted call, +including one due to an interrupted system call, the .Fa fds array will be unmodified. @@ -185,7 +189,7 @@ defined for compatibility with existing software. .Sh HISTORY The .Fn poll -function call appeared in +function appeared in .At V . This manual page and the core of the implementation was taken from .Nx . diff --git a/lib/libc/sys/profil.2 b/lib/libc/sys/profil.2 index 7437ef7..640cfda 100644 --- a/lib/libc/sys/profil.2 +++ b/lib/libc/sys/profil.2 @@ -50,7 +50,7 @@ .Sh DESCRIPTION The .Fn profil -function enables or disables +system call enables or disables program counter profiling of the current process. If profiling is enabled, then at every profiling clock tick, @@ -110,9 +110,9 @@ contains an invalid address. .Sh SEE ALSO .Xr gprof 1 .Sh HISTORY -A +The .Fn profil -function call appeared in +function appeared in .At v7 . .Sh BUGS This routine should be named diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 index 7b08791..298de96 100644 --- a/lib/libc/sys/ptrace.2 +++ b/lib/libc/sys/ptrace.2 @@ -16,7 +16,9 @@ .Ft int .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" .Sh DESCRIPTION +The .Fn ptrace +system call provides tracing and debugging facilities. It allows one process (the @@ -37,7 +39,9 @@ or the delivery of a .Dv SIGCHLD signal, examine the state of the stopped process, and cause it to terminate or continue as appropriate. +The .Fn ptrace +system call is the mechanism by which all this happens. .Pp The @@ -252,7 +256,7 @@ can be set to 0 before the call and checked afterwards. .Sh ERRORS The .Fn ptrace -function may fail if: +system call may fail if: .Bl -tag -width Er .It Bq Er ESRCH .Bl -bullet -compact @@ -324,7 +328,7 @@ above. .Xr i386_clr_watch 3 , .Xr i386_set_watch 3 .Sh HISTORY -A +The .Fn ptrace -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/quotactl.2 b/lib/libc/sys/quotactl.2 index 44d74b2..5276133 100644 --- a/lib/libc/sys/quotactl.2 +++ b/lib/libc/sys/quotactl.2 @@ -51,7 +51,7 @@ .Sh DESCRIPTION The .Fn quotactl -call enables, disables and +system call enables, disables and manipulates file system quotas. A quota control command given by @@ -129,7 +129,7 @@ structure (defined in The usage fields of the .Fa dqblk structure are ignored. -This call is restricted to the super-user. +This system call is restricted to the super-user. .It Dv Q_SETUSE Set disk usage limits for the user or group (as determined by the command type) with identifier @@ -140,7 +140,7 @@ is a pointer to a structure (defined in .Ao Pa ufs/ufs/quota.h Ac ) . Only the usage fields are used. -This call is restricted to the super-user. +This system call is restricted to the super-user. .It Dv Q_SYNC Update the on-disk copy of quota usages. The command type specifies which type of quotas are to be updated. @@ -153,9 +153,9 @@ parameters are ignored. .Sh RETURN VALUES .Rv -std quotactl .Sh ERRORS -A +The .Fn quotactl -call will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EOPNOTSUPP The kernel has not been compiled with the @@ -222,5 +222,5 @@ and .Sh HISTORY The .Fn quotactl -function call appeared in +system call appeared in .Bx 4.3 Reno . diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 index 42d04ce..fc7d002 100644 --- a/lib/libc/sys/read.2 +++ b/lib/libc/sys/read.2 @@ -53,21 +53,27 @@ .Ft ssize_t .Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" .Sh DESCRIPTION -.Fn Read +The +.Fn read +system call attempts to read .Fa nbytes of data from the object referenced by the descriptor .Fa d into the buffer pointed to by .Fa buf . -.Fn Readv +The +.Fn readv +system call performs the same action, but scatters the input data into the .Fa iovcnt buffers specified by the members of the .Fa iov array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. -.Fn Pread +The +.Fn pread +system call performs the same function, but reads from the specified position in the file without modifying the file pointer. .Pp @@ -88,7 +94,9 @@ Each .Fa iovec entry specifies the base address and length of an area in memory where data should be placed. -.Fn Readv +The +.Fn readv +system call will always fill an area completely before proceeding to the next. .Pp @@ -125,10 +133,12 @@ Otherwise, a -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS -.Fn Read , +The +.Fn read , .Fn readv , and .Fn pread +system calls will succeed unless: .Bl -tag -width Er .It Bq Er EBADF @@ -178,7 +188,7 @@ points outside the process's allocated address space. .Pp The .Fn pread -call may also return the following errors: +system call may also return the following errors: .Bl -tag -width Er .It Bq Er EINVAL The specified file offset is invalid. @@ -196,26 +206,24 @@ The file descriptor is associated with a pipe, socket, or FIFO. .Sh STANDARDS The .Fn read -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . The .Fn readv and .Fn pread -functions are expected to conform to +system calls are expected to conform to .St -xpg4.2 . .Sh HISTORY The .Fn pread -function call -appeared in +function appeared in .At V.4 . The .Fn readv -function call -appeared in +system call appeared in .Bx 4.2 . -A +The .Fn read -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/sys/readlink.2 b/lib/libc/sys/readlink.2 index fd97e1d..57ed4e6 100644 --- a/lib/libc/sys/readlink.2 +++ b/lib/libc/sys/readlink.2 @@ -45,7 +45,9 @@ .Ft int .Fn readlink "const char *path" "char *buf" "int bufsiz" .Sh DESCRIPTION -.Fn Readlink +The +.Fn readlink +system call places the contents of the symbolic link .Fa path in the buffer @@ -54,7 +56,7 @@ which has size .Fa bufsiz . The .Fn readlink -function does not append a +system call does not append a .Dv NUL character to .Fa buf . @@ -64,7 +66,9 @@ if it succeeds, or a -1 if an error occurs, placing the error code in the global variable .Va errno . .Sh ERRORS -.Fn Readlink +The +.Fn readlink +system call will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -94,5 +98,5 @@ extends outside the process's allocated address space. .Sh HISTORY The .Fn readlink -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/reboot.2 b/lib/libc/sys/reboot.2 index 8e3a19a..66339d4 100644 --- a/lib/libc/sys/reboot.2 +++ b/lib/libc/sys/reboot.2 @@ -46,7 +46,9 @@ .Ft int .Fn reboot "int howto" .Sh DESCRIPTION -.Fn Reboot +The +.Fn reboot +system call reboots the system. Only the super-user may reboot a machine on demand. However, a reboot is invoked @@ -103,7 +105,7 @@ Several other options have different meaning if combined with this option, although their use may not be possible via the .Fn reboot -call. +system call. See .Xr ddb 4 for more information. @@ -162,5 +164,5 @@ nor .Sh HISTORY The .Fn reboot -function call appeared in +system call appeared in .Bx 4.0 . diff --git a/lib/libc/sys/recv.2 b/lib/libc/sys/recv.2 index 3acd694..9d85d2b 100644 --- a/lib/libc/sys/recv.2 +++ b/lib/libc/sys/recv.2 @@ -52,9 +52,11 @@ .Ft ssize_t .Fn recvmsg "int s" "struct msghdr *msg" "int flags" .Sh DESCRIPTION -.Fn Recvfrom +The +.Fn recvfrom and .Fn recvmsg +system calls are used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented. @@ -72,7 +74,7 @@ address stored there. .Pp The .Fn recv -call is normally used only on a +function is normally used only on a .Em connected socket (see .Xr connect 2 ) @@ -111,11 +113,13 @@ described in .Pp The .Xr select 2 -call may be used to determine when more data arrive. +system call may be used to determine when more data arrive. .Pp The .Fa flags -argument to a recv call is formed by +argument to a +.Fn recv +function is formed by .Em or Ap ing one or more of the values: .Bl -column MSG_WAITALL -offset indent @@ -142,7 +146,7 @@ or the next data to be received is of a different type than that returned. .Pp The .Fn recvmsg -call uses a +system call uses a .Fa msghdr structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in @@ -192,7 +196,7 @@ As an example, one could use this to learn of changes in the data-stream in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting a recvmsg with no data buffer provided immediately after an .Fn accept -call. +system call. .Pp Open file descriptors are now passed as ancillary data for .Dv AF_UNIX @@ -291,5 +295,5 @@ address space. .Sh HISTORY The .Fn recv -function call appeared in +function appeared in .Bx 4.2 . diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 index 2046861..1409c84 100644 --- a/lib/libc/sys/rename.2 +++ b/lib/libc/sys/rename.2 @@ -45,7 +45,9 @@ .Ft int .Fn rename "const char *from" "const char *to" .Sh DESCRIPTION -.Fn Rename +The +.Fn rename +system call causes the link named .Fa from to be renamed as @@ -60,7 +62,9 @@ and must be of the same type (that is, both directories or both non-directories), and must reside on the same file system. .Pp -.Fn Rename +The +.Fn rename +system call guarantees that if .Fa to already exists, an instance of @@ -102,7 +106,9 @@ not the file or directory to which it points. .Sh RETURN VALUES .Rv -std rename .Sh ERRORS -.Fn Rename +The +.Fn rename +system call will fail and neither of the argument files will be affected if: .Bl -tag -width Er @@ -195,5 +201,5 @@ is a directory and is not empty. .Sh STANDARDS The .Fn rename -function call is expected to conform to +system call is expected to conform to .St -p1003.1-96 . diff --git a/lib/libc/sys/revoke.2 b/lib/libc/sys/revoke.2 index 687a317..f420db9 100644 --- a/lib/libc/sys/revoke.2 +++ b/lib/libc/sys/revoke.2 @@ -50,7 +50,7 @@ .Sh DESCRIPTION The .Fn revoke -function invalidates all current open file descriptors in the system +system call invalidates all current open file descriptors in the system for the file named by .Fa path . Subsequent operations on any such descriptors @@ -60,7 +60,7 @@ from a character device file which has been revoked returns a count of zero (end of file), and a .Fn close -call will succeed. +system call will succeed. If the file is a special file for a device which is open, the device close function is called as if all open references to the file had been closed. @@ -68,7 +68,7 @@ is called as if all open references to the file had been closed. Access to a file may be revoked only by its owner or the super user. The .Fn revoke -function is currently supported only for block and character special +system call is currently supported only for block and character special device files. It is normally used to prepare a terminal device for a new login session, preventing any access by a previous user of the terminal. @@ -103,5 +103,5 @@ The caller is neither the owner of the file nor the super user. .Sh HISTORY The .Fn revoke -function was introduced in +system call first appeared in .Bx 4.3 Reno . diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 index 60eb9b3..d4d4e20 100644 --- a/lib/libc/sys/rfork.2 +++ b/lib/libc/sys/rfork.2 @@ -67,7 +67,7 @@ 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 -.Fn rfork_thread 3 +.Xr rfork_thread 3 for information. .It RFSIGSHARE If set, the kernel will force sharing the sigacts structure between the @@ -93,10 +93,14 @@ the return value is zero. Process id's range from 1 to the maximum integer .Ft ( int ) value. -.Fn Rfork +The +.Fn rfork +system call will sleep, if necessary, until required process resources are available. .Pp -.Fn Fork +The +.Fn fork +system call can be implemented as a call to .Fn rfork "RFFDG | RFPROC" but isn't for backwards compatibility. @@ -111,7 +115,9 @@ variable .Va errno is set to indicate the error. .Sh ERRORS -.Fn Rfork +The +.Fn rfork +system call will fail and no child process will be created if: .Bl -tag -width Er .It Bq Er EAGAIN @@ -165,10 +171,10 @@ contains a working .Fn clone call that utilizes RFMEM. The -.Fn rfork_thread -library call can often be used instead of +.Xr rfork_thread 3 +function can often be used instead of .Fn clone . .Sh HISTORY The .Fn rfork -function call first appeared in Plan9. +function first appeared in Plan9. diff --git a/lib/libc/sys/rmdir.2 b/lib/libc/sys/rmdir.2 index d6e052f..54b9b25 100644 --- a/lib/libc/sys/rmdir.2 +++ b/lib/libc/sys/rmdir.2 @@ -45,7 +45,9 @@ .Ft int .Fn rmdir "const char *path" .Sh DESCRIPTION -.Fn Rmdir +The +.Fn rmdir +system call removes a directory file whose name is given by .Fa path . @@ -101,5 +103,5 @@ points outside the process's allocated address space. .Sh HISTORY The .Fn rmdir -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/rtprio.2 b/lib/libc/sys/rtprio.2 index 47e0af8..a935404 100644 --- a/lib/libc/sys/rtprio.2 +++ b/lib/libc/sys/rtprio.2 @@ -43,7 +43,9 @@ .Ft int .Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp" .Sh DESCRIPTION +The .Fn rtprio +system call is used to lookup or change the realtime or idle priority of a process. .Pp .Fa function @@ -64,11 +66,11 @@ struct rtprio { .Ed .Pp The value of the -.Nm type +.Va type field may be RTP_PRIO_REALTIME for realtime priorities, RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. The priority specified by the -.Nm prio +.Va prio field ranges between 0 and .Dv RTP_PRIO_MAX (usually 31) . 0 is the highest possible priority. @@ -84,7 +86,9 @@ Processes of equal real/idle priority are run round-robin. .Sh RETURN VALUES .Rv -std rtprio .Sh ERRORS +The .Fn rtprio +system call will fail if .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/sched_get_priority_max.2 b/lib/libc/sys/sched_get_priority_max.2 index eba278d..e54228f 100644 --- a/lib/libc/sys/sched_get_priority_max.2 +++ b/lib/libc/sys/sched_get_priority_max.2 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .\" Copyright (c) 1998 HD Associates, Inc. .\" All rights reserved. .\" @@ -23,6 +22,8 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" +.\" $FreeBSD$ +.\" .Dd March 12, 1998 .Dt SCHED_GET_PRIORITY_MAX 2 .Os @@ -46,12 +47,12 @@ The .Fn sched_get_priority_max and .Fn sched_get_priority_min -functions return the appropriate maximum or minimum, respectively, +system calls return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .Fa policy . The .Fn sched_rr_get_interval -function updates the +system call updates the .Fa timespec structure referenced by the .Fa interval @@ -80,7 +81,7 @@ If successful, the .Fn sched_get_priority_max and .Fn sched_get_priority_min -functions shall return the appropriate maximum or minimum values, +system calls shall return the appropriate maximum or minimum values, respectively. If unsuccessful, they shall return a value of -1 and set .Fa errno to indicate the error. @@ -101,7 +102,7 @@ The .Fn sched_get_priority_min , and .Fn sched_rr_get_interval -functions are not supported by the implementation. +system calls are not supported by the implementation. .It Bq Er ESRCH No process can be found corresponding to that specified by .Fa pid . @@ -117,5 +118,5 @@ The .Fn sched_get_priority_min , and .Fn sched_rr_get_interval -functions conform to +system calls conform to .St -p1003.1b-93 . diff --git a/lib/libc/sys/sched_setparam.2 b/lib/libc/sys/sched_setparam.2 index 136e70d..7f3dfbb 100644 --- a/lib/libc/sys/sched_setparam.2 +++ b/lib/libc/sys/sched_setparam.2 @@ -41,7 +41,7 @@ .Sh DESCRIPTION The .Fn sched_setparam -function sets the scheduling parameters of the process specified by +system call sets the scheduling parameters of the process specified by .Fa pid to the values specified by the .Fa sched_param @@ -58,7 +58,7 @@ Higher numerical values for the priority represent higher priorities. .Pp In this implementation, if the value of .Fa pid -is negative the function will fail. +is negative the system call will fail. .Pp If a process specified by .Fa pid @@ -105,7 +105,7 @@ lower than any actual realtime priority. .Pp The .Fn sched_getparam -function will return the scheduling parameters of a process specified +system call will return the scheduling parameters of a process specified by .Fa pid in the @@ -130,7 +130,7 @@ If is zero, the scheduling parameters for the calling process will be returned. In this implementation, the .Fa sched_getparam -function will fail if +system call will fail if .Fa pid is negative. .Sh RETURN VALUES @@ -167,5 +167,5 @@ The .Fn sched_setparam and .Fn sched_getparam -functions conform to +system calls conform to .St -p1003.1b-93 . diff --git a/lib/libc/sys/sched_setscheduler.2 b/lib/libc/sys/sched_setscheduler.2 index 35c8627..7043649 100644 --- a/lib/libc/sys/sched_setscheduler.2 +++ b/lib/libc/sys/sched_setscheduler.2 @@ -41,7 +41,7 @@ .Sh DESCRIPTION The .Fn sched_setscheduler -function sets the scheduling policy and scheduling parameters +system call sets the scheduling policy and scheduling parameters of the process specified by .Fa pid to @@ -61,7 +61,7 @@ the scheduling policy specified by .Pp In this implementation, if the value of .Fa pid -is negative the function will fail. +is negative the system call will fail. .Pp If a process specified by .Fa pid @@ -104,7 +104,7 @@ struct sched_param { .Pp The .Fn sched_getscheduler -function returns the scheduling policy of the process specified +system call returns the scheduling policy of the process specified by .Fa pid . .Pp @@ -125,7 +125,7 @@ If is zero, the scheduling parameters for the calling process will be returned. In this implementation, the .Fa sched_getscheduler -function will fail if +system call will fail if .Fa pid is negative. .Sh RETURN VALUES @@ -162,5 +162,5 @@ The .Fn sched_setscheduler and .Fn sched_getscheduler -functions conform to +system calls conform to .St -p1003.1b-93 . diff --git a/lib/libc/sys/sched_yield.2 b/lib/libc/sys/sched_yield.2 index 3457a35..c8a60a0 100644 --- a/lib/libc/sys/sched_yield.2 +++ b/lib/libc/sys/sched_yield.2 @@ -38,7 +38,7 @@ .Sh DESCRIPTION The .Fn sched_yield -function forces the running process to relinquish the processor until it +system call forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .Sh RETURN VALUES .Rv -std sched_yield @@ -53,5 +53,5 @@ The system is not configured to support this functionality. .Sh STANDARDS The .Fn sched_yield -function conforms to +system call conforms to .St -p1003.1b-93 . diff --git a/lib/libc/sys/select.2 b/lib/libc/sys/select.2 index b3addb7..871d68d 100644 --- a/lib/libc/sys/select.2 +++ b/lib/libc/sys/select.2 @@ -49,7 +49,9 @@ .Fn FD_ISSET fd &fdset .Fn FD_ZERO &fdset .Sh DESCRIPTION -.Fn Select +The +.Fn select +system call examines the I/O descriptor sets whose addresses are passed in .Fa readfds , .Fa writefds , @@ -71,7 +73,9 @@ On return, replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. -.Fn Select +The +.Fn select +system call returns the total number of ready descriptors in all the sets. .Pp The descriptor sets are stored as bit fields in arrays of integers. @@ -123,7 +127,9 @@ and .Fa exceptfds may be given as nil pointers if no descriptors are of interest. .Sh RETURN VALUES -.Fn Select +The +.Fn select +system call returns the number of ready descriptors that are contained in the descriptor sets, or -1 if an error occurred. @@ -133,7 +139,7 @@ returns 0. If .Fn select returns with an error, -including one due to an interrupted call, +including one due to an interrupted system call, the descriptor sets will be unmodified. .Sh ERRORS An error return from @@ -189,11 +195,11 @@ allows systems to modify the original timeout in place. Thus, it is unwise to assume that the timeout value will be unmodified by the .Fn select -call. +system call. .Sh STANDARDS The .Fn select -function and +system call and .Fn FD_CLR , .Fn FD_ISSET , .Fn FD_SET , @@ -204,5 +210,5 @@ macros conform with .Sh HISTORY The .Fn select -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 index ea96a38..b5a33ba 100644 --- a/lib/libc/sys/semctl.2 +++ b/lib/libc/sys/semctl.2 @@ -40,7 +40,9 @@ .Ft int .Fn semctl "int semid" "int semnum" "int cmd" ... .Sh DESCRIPTION -.Fn Semctl +The +.Fn semctl +system call performs the operation indicated by .Fa cmd on the semaphore set indicated by @@ -166,7 +168,9 @@ On failure, -1 is returned, and .Va errno is set to indicate the error. .Sh ERRORS -.Fn Semctl +The +.Fn semctl +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 index b9fad0d..f45e92b 100644 --- a/lib/libc/sys/semget.2 +++ b/lib/libc/sys/semget.2 @@ -66,9 +66,10 @@ is specified and the IPC_CREAT bit is set in .Fa flag , a new one will be created. .It -.Fn ftok -may be used to generate a key from a pathname. See -.Xr ftok 3 . +The +.Xr ftok 3 +function +may be used to generate a key from a pathname. .El .\" .\" Likewise for this section, except SHM_* becomes SEM_*. @@ -101,13 +102,17 @@ Otherwise, .Fa nsems may be specified as 0. .Sh RETURN VALUES -.Fn Semget +The +.Fn semget +system call returns the id of a semaphore set if successful; otherwise, -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS -.Fn Semget +The +.Fn semget +system call will fail if: .Bl -tag -width Er .\" ipcperm could fail (we're opening to read and write, as it were) diff --git a/lib/libc/sys/semop.2 b/lib/libc/sys/semop.2 index efcb6a0..174cee2 100644 --- a/lib/libc/sys/semop.2 +++ b/lib/libc/sys/semop.2 @@ -42,7 +42,7 @@ .Sh DESCRIPTION The .Fn semop -call +system call atomically performs the array of operations indicated by .Fa array on the semaphore set indicated by @@ -229,7 +229,7 @@ unexpectedly. .Sh ERRORS The .Fn semop -call will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL No semaphore set corresponds to @@ -261,7 +261,7 @@ The semaphore set was removed from the system. .It Bq Er EINTR The .Fn semop -call was interrupted by a signal. +system call was interrupted by a signal. .It Bq Er ENOSPC The system .Dv SEM_UNDO @@ -283,7 +283,7 @@ to exceed the system-imposed limits. .Sh BUGS The .Fn semop -call +system call may block waiting for memory even if .Dv IPC_NOWAIT was specified. diff --git a/lib/libc/sys/send.2 b/lib/libc/sys/send.2 index 885b59a..ac64f3f 100644 --- a/lib/libc/sys/send.2 +++ b/lib/libc/sys/send.2 @@ -52,12 +52,18 @@ .Ft ssize_t .Fn sendmsg "int s" "const struct msghdr *msg" "int flags" .Sh DESCRIPTION -.Fn Send , -.Fn sendto , +The +.Fn send +function, +and +.Fn sendto and .Fn sendmsg +system calls are used to transmit a message to another socket. -.Fn Send +The +.Fn send +function may be used only when the socket is in a .Em connected state, while @@ -90,7 +96,7 @@ normally blocks, unless the socket has been placed in non-blocking I/O mode. The .Xr select 2 -call may be used to determine when it is possible to +system call may be used to determine when it is possible to send more data. .Pp The @@ -139,10 +145,13 @@ structure. The call returns the number of characters sent, or -1 if an error occurred. .Sh ERRORS -.Fn Send , -.Fn sendto , +The +.Fn send +function and +.Fn sendto and .Fn sendmsg +system calls fail if: .Bl -tag -width Er .It Bq Er EBADF @@ -205,5 +214,5 @@ implement an acknowlegment mechanism to prevent this from happening. .Sh HISTORY The .Fn send -function call appeared in +function appeared in .Bx 4.2 . diff --git a/lib/libc/sys/sendfile.2 b/lib/libc/sys/sendfile.2 index c2ca529..09e8dac 100644 --- a/lib/libc/sys/sendfile.2 +++ b/lib/libc/sys/sendfile.2 @@ -40,7 +40,9 @@ .Ft int .Fn sendfile "int fd" "int s" "off_t offset" "size_t nbytes" "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" .Sh DESCRIPTION -.Fn Sendfile +The +.Fn sendfile +system call sends a regular file specified by descriptor .Fa fd out a stream socket specified by descriptor @@ -147,12 +149,16 @@ If specified, the number of bytes successfully sent will be returned in .Xr socket 2 , .Xr writev 2 .Sh HISTORY +The .Fn sendfile +system call first appeared in .Fx 3.0 . This manual page first appeared in .Fx 3.1 . .Sh AUTHORS +The .Fn sendfile +system call and this manual page were written by .An David Greenman Aq dg@root.com . diff --git a/lib/libc/sys/setgroups.2 b/lib/libc/sys/setgroups.2 index 355298e..79f60ac 100644 --- a/lib/libc/sys/setgroups.2 +++ b/lib/libc/sys/setgroups.2 @@ -46,7 +46,9 @@ .Ft int .Fn setgroups "int ngroups" "const gid_t *gidset" .Sh DESCRIPTION -.Fn Setgroups +The +.Fn setgroups +system call sets the group access list of the current user process according to the array .Fa gidset . @@ -64,7 +66,7 @@ Only the super-user may set new groups. .Sh ERRORS The .Fn setgroups -call will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EPERM The caller is not the super-user. @@ -80,5 +82,5 @@ address space. .Sh HISTORY The .Fn setgroups -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/setpgid.2 b/lib/libc/sys/setpgid.2 index 14186ea..37c1d98 100644 --- a/lib/libc/sys/setpgid.2 +++ b/lib/libc/sys/setpgid.2 @@ -48,7 +48,9 @@ .Ft int .Fn setpgrp "pid_t pid" "pid_t pgrp" .Sh DESCRIPTION -.Fn Setpgid +The +.Fn setpgid +system call sets the process group of the specified process .Fa pid to the specified @@ -63,7 +65,9 @@ of the invoking process. .Sh RETURN VALUES .Rv -std setpgid .Sh ERRORS -.Fn Setpgid +The +.Fn setpgid +system call will fail and the process group will not be altered if: .Bl -tag -width Er .It Bq Er ESRCH @@ -78,10 +82,12 @@ of the calling process. .Sh STANDARDS The .Fn setpgid -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh COMPATIBILITY -.Fn Setpgrp +The +.Fn setpgrp +system call is identical to .Fn setpgid , and is retained for calling convention compatibility with historical diff --git a/lib/libc/sys/setregid.2 b/lib/libc/sys/setregid.2 index d23e48a..0ea6acf 100644 --- a/lib/libc/sys/setregid.2 +++ b/lib/libc/sys/setregid.2 @@ -60,19 +60,18 @@ ID in place of the -1 parameter. .Pp The .Fn setregid -function was intended to allow swapping +system call was intended to allow swapping the real and effective group IDs in set-group-ID programs to temporarily relinquish the set-group-ID value. -This function did not work correctly, +This system call did not work correctly, and its purpose is now better served by the use of the -.Fn setegid -function (see -.Xr setuid 2 ) . +.Xr setegid 2 +system call. .Pp When setting the real and effective group IDs to the same value, the standard .Fn setgid -function is preferred. +system call is preferred. .Sh RETURN VALUES .Rv -std setregid .Sh ERRORS diff --git a/lib/libc/sys/setresuid.2 b/lib/libc/sys/setresuid.2 index 7030586..08d07f3 100644 --- a/lib/libc/sys/setresuid.2 +++ b/lib/libc/sys/setresuid.2 @@ -96,4 +96,4 @@ They exist in .Fx to support Linux binaries linked against GNU libc2. .Sh HISTORY -These system calls first appeared in HP-UX. +These functions first appeared in HP-UX. diff --git a/lib/libc/sys/setreuid.2 b/lib/libc/sys/setreuid.2 index fd5d636..cd8b718 100644 --- a/lib/libc/sys/setreuid.2 +++ b/lib/libc/sys/setreuid.2 @@ -63,17 +63,16 @@ the real user ID, then the saved user ID will be set to the effective user ID. .Pp The .Fn setreuid -function has been used to swap the real and effective user IDs +system call has been used to swap the real and effective user IDs in set-user-ID programs to temporarily relinquish the set-user-ID value. This purpose is now better served by the use of the -.Fn seteuid -function (see -.Xr setuid 2 ) . +.Xr seteuid 2 +system call. .Pp When setting the real and effective user IDs to the same value, the standard .Fn setuid -function is preferred. +system call is preferred. .Sh RETURN VALUES .Rv -std setreuid .Sh ERRORS diff --git a/lib/libc/sys/setsid.2 b/lib/libc/sys/setsid.2 index 0dc1cef..56506a6 100644 --- a/lib/libc/sys/setsid.2 +++ b/lib/libc/sys/setsid.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn setsid -function creates a new session. +system call creates a new session. The calling process is the session leader of the new session, is the process group leader of a new process group and has no controlling terminal. @@ -56,7 +56,7 @@ process group. .Sh RETURN VALUES Upon successful completion, the .Fn setsid -function returns the value of the process group ID of the new process +system call returns the value of the process group ID of the new process group, which is the same as the process ID of the calling process. If an error occurs, .Fn setsid @@ -66,7 +66,7 @@ is set to indicate the error. .Sh ERRORS The .Fn setsid -function will fail if: +system call will fail if: .Bl -tag -width Er .It Bq Er EPERM The calling process is already a process group leader, or the process @@ -80,6 +80,6 @@ ID of the calling process. .Sh STANDARDS The .Fn setsid -function is expected to be compliant with the +system call is expected to be compliant with the .St -p1003.1-90 specification. diff --git a/lib/libc/sys/setuid.2 b/lib/libc/sys/setuid.2 index aaa7ebb..0296f57 100644 --- a/lib/libc/sys/setuid.2 +++ b/lib/libc/sys/setuid.2 @@ -57,7 +57,7 @@ .Sh DESCRIPTION The .Fn setuid -function +system call sets the real and effective user IDs and the saved set-user-ID of the current process to the specified value. @@ -66,13 +66,13 @@ to the specified value. .\" effective user ID is that of the super user. .\" I.e. .\" .Fn setuid -.\" function is equal to +.\" system call is equal to .\" .Fn seteuid -.\" function if the effective user ID is not that of the super user. +.\" system call if the effective user ID is not that of the super user. .\" End of block The .Fn setuid -function is permitted if the specified ID is equal to the real user ID +system call is permitted if the specified ID is equal to the real user ID .\" Comment out next line for !_POSIX_SAVED_IDS .\" or the saved set-user-ID .\" Next line is for Appendix B.4.2.2 case. @@ -81,7 +81,7 @@ of the process, or if the effective user ID is that of the super user. .Pp The .Fn setgid -function +system call sets the real and effective group IDs and the saved set-group-ID of the current process to the specified value. @@ -90,13 +90,13 @@ to the specified value. .\" effective user ID is that of the super user. .\" I.e. .\" .Fn setgid -.\" function is equal to +.\" system call is equal to .\" .Fn setegid -.\" function if the effective user ID is not that of the super user. +.\" system call if the effective user ID is not that of the super user. .\" End of block The .Fn setgid -function is permitted if the specified ID is equal to the real group ID +system call is permitted if the specified ID is equal to the real group ID .\" Comment out next line for !_POSIX_SAVED_IDS .\" or the saved set-group-ID .\" Next line is for Appendix B.4.2.2 case. @@ -105,7 +105,7 @@ of the process, or if the effective user ID is that of the super user. .Pp The .Fn seteuid -function +system call .Pq Fn setegid sets the effective user ID (group ID) of the current process. @@ -122,7 +122,7 @@ of the real group ID or the saved set-user-ID. .Sh RETURN VALUES .Rv -std .Sh ERRORS -The functions will fail if: +The system calls will fail if: .Bl -tag -width Er .It Bq Er EPERM The user is not the super user and the ID @@ -172,7 +172,7 @@ The .Fn setuid and .Fn setgid -functions are compliant with the +system calls are compliant with the .St -p1003.1-90 specification with .Li _POSIX_SAVED_IDS @@ -183,15 +183,15 @@ The .Fn seteuid and .Fn setegid -functions are extensions based on the +system calls are extensions based on the .Tn POSIX concept of .Li _POSIX_SAVED_IDS , and have been proposed for a future revision of the standard. .Sh HISTORY -A +The .Fn setuid -and a +and .Fn setgid -function calls appeared in +functions appeared in .At v7 . diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 index 429d0c8..e4c9eee 100644 --- a/lib/libc/sys/shmat.2 +++ b/lib/libc/sys/shmat.2 @@ -44,7 +44,9 @@ .Ft int .Fn shmdt "void *addr" .Sh DESCRIPTION -.Fn Shmat +The +.Fn shmat +system call attaches the shared memory segment identified by .Fa shmid to the calling process's address space. The address where the segment @@ -73,7 +75,9 @@ is specified and SHM_RND is specified, is rounded down to the nearest multiple of SHMLBA. .El .Pp -.Fn Shmdt +The +.Fn shmdt +system call detaches the shared memory segment at the address specified by .Fa addr from the calling process's address space. @@ -87,7 +91,9 @@ is set to indicate the error. .Pp .Rv -std shmdt .Sh ERRORS -.Fn Shmat +The +.Fn shmat +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL @@ -98,7 +104,9 @@ No shared memory segment was found corresponding to was not an acceptable address. .El .Pp -.Fn Shmdt +The +.Fn shmdt +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 index c321e5b..5b27ff5 100644 --- a/lib/libc/sys/shmctl.2 +++ b/lib/libc/sys/shmctl.2 @@ -111,7 +111,9 @@ struct shmid_ds { .Sh RETURN VALUES .Rv -std shmctl .Sh ERRORS -.Fn Shmctl +The +.Fn shmctl +system call will fail if: .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/shmget.2 b/lib/libc/sys/shmget.2 index 281cc66..bf54fb2 100644 --- a/lib/libc/sys/shmget.2 +++ b/lib/libc/sys/shmget.2 @@ -67,9 +67,9 @@ is specified and the IPC_CREAT bit is set in .Fa flag , a new one will be created. .It -.Fn ftok -may be used to generate a key from a pathname. See -.Xr ftok 3 . +The +.Xr ftok 3 +may be used to generate a key from a pathname. .El .Pp The mode of a newly created IPC object is determined by @@ -111,7 +111,9 @@ Otherwise, -1 is returned and .Va errno set to indicate the error. .Sh ERRORS -.Fn Shmget +The +.Fn shmget +system call will fail if: .Bl -tag -width Er .\" diff --git a/lib/libc/sys/shutdown.2 b/lib/libc/sys/shutdown.2 index ed61ecc..3d258cb 100644 --- a/lib/libc/sys/shutdown.2 +++ b/lib/libc/sys/shutdown.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn shutdown -call causes all or part of a full-duplex connection on +system call causes all or part of a full-duplex connection on the socket associated with the file descriptor .Fa s to be shut down. @@ -69,7 +69,7 @@ further sends and receives will be disallowed. .Sh ERRORS The .Fn shutdown -call fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EBADF The @@ -92,13 +92,13 @@ argument does not refer to a socket. .Sh STANDARDS The .Fn shutdown -function is expected to comply with +system call is expected to comply with .St -p1003.1g-2000 , when finalized. .Sh HISTORY The .Fn shutdown -function call appeared in +system call appeared in .Bx 4.2 . The .Dv SHUT_RD , SHUT_WR , diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 index 898de2b..b084cdd 100644 --- a/lib/libc/sys/sigaction.2 +++ b/lib/libc/sys/sigaction.2 @@ -110,7 +110,7 @@ appearing to interrupt the handlers for the previous signals before their first instructions. The set of pending signals is returned by the .Xr sigpending 2 -function. +system call. When a caught signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), @@ -124,20 +124,22 @@ must arrange to restore the previous context itself. When a signal is delivered to a process a new signal mask is installed for the duration of the process' signal handler (or until a -.Xr sigprocmask -call is made). +.Xr sigprocmask 2 +system call is made). This mask is formed by taking the union of the current signal mask set, the signal to be delivered, and the signal mask associated with the handler to be invoked. .Pp -.Fn Sigaction +The +.Fn sigaction +system call assigns an action for a signal specified by .Fa sig . If .Fa act is non-zero, it specifies an action -.Pf ( Dv SIG_DFL , +.Dv ( SIG_DFL , .Dv SIG_IGN , or a handler routine) and mask to be used when delivering the specified signal. @@ -149,7 +151,7 @@ is returned to the user. Once a signal handler is installed, it normally remains installed until another .Fn sigaction -call is made, or an +system call is made, or an .Xr execve 2 is performed. A signal-specific default action may be reset by @@ -535,7 +537,9 @@ The argument to a POSIX SA_SIGINFO handler points to an instance of ucontext_t. .Sh ERRORS -.Fn Sigaction +The +.Fn sigaction +system call will fail and no new signal handler will be installed if one of the following occurs: .Bl -tag -width Er @@ -558,7 +562,7 @@ or .Sh STANDARDS The .Fn sigaction -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . The .Dv SA_ONSTACK diff --git a/lib/libc/sys/sigaltstack.2 b/lib/libc/sys/sigaltstack.2 index b44db94..fe8fda5 100644 --- a/lib/libc/sys/sigaltstack.2 +++ b/lib/libc/sys/sigaltstack.2 @@ -52,7 +52,9 @@ typedef struct sigaltstack { .Ft int .Fn sigaltstack "const stack_t * restrict ss" "stack_t * restrict oss" .Sh DESCRIPTION -.Fn Sigaltstack +The +.Fn sigaltstack +system call allows users to define an alternate stack on which signals are to be processed. If @@ -66,7 +68,7 @@ on that stack. When a signal's action indicates its handler should execute on the signal stack (specified with a .Xr sigaction 2 -call), the system checks to see +system call), the system checks to see if the process is currently executing on that stack. If the process is not currently executing on the signal stack, the system arranges a switch to the signal stack for the @@ -135,7 +137,9 @@ unpredictable results may occur. .Sh RETURN VALUES .Rv -std sigaltstack .Sh ERRORS -.Fn Sigaltstack +The +.Fn sigaltstack +system call will fail and the signal stack context will remain unchanged if one of the following occurs. .Bl -tag -width Er diff --git a/lib/libc/sys/sigpending.2 b/lib/libc/sys/sigpending.2 index e6635d3..cc5597b 100644 --- a/lib/libc/sys/sigpending.2 +++ b/lib/libc/sys/sigpending.2 @@ -50,7 +50,7 @@ .Sh DESCRIPTION The .Fn sigpending -function returns a mask of the signals pending for delivery +system call returns a mask of the signals pending for delivery to the calling process in the location indicated by .Fa set . Signals may be pending because they are currently masked, @@ -59,7 +59,9 @@ normally detectable). .Sh RETURN VALUES .Rv -std sigpending .Sh ERRORS +The .Fn sigpending +system call will fail if: .Bl -tag -width Er .It Bq Er EFAULT @@ -73,5 +75,5 @@ argument specified an invalid address. .Sh STANDARDS The .Fn sigpending -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . diff --git a/lib/libc/sys/sigprocmask.2 b/lib/libc/sys/sigprocmask.2 index debb2a3..c1af81b 100644 --- a/lib/libc/sys/sigprocmask.2 +++ b/lib/libc/sys/sigprocmask.2 @@ -51,7 +51,7 @@ .Sh DESCRIPTION The .Fn sigprocmask -function examines and/or changes the current signal mask (those signals +system call examines and/or changes the current signal mask (those signals that are blocked from delivery). Signals are blocked if they are members of the current signal mask set. .Pp @@ -104,7 +104,7 @@ to be blocked. .Sh ERRORS The .Fn sigprocmask -call will fail and the signal mask will be unchanged if one +system call will fail and the signal mask will be unchanged if one of the following occurs: .Bl -tag -width Er .It Bq Er EINVAL @@ -120,6 +120,6 @@ has a value other than those listed here. .Sh STANDARDS The .Fn sigprocmask -function call is expected to +system call is expected to conform to .St -p1003.1-90 . diff --git a/lib/libc/sys/sigreturn.2 b/lib/libc/sys/sigreturn.2 index 6c5df09..3aec154 100644 --- a/lib/libc/sys/sigreturn.2 +++ b/lib/libc/sys/sigreturn.2 @@ -45,7 +45,9 @@ .Ft int .Fn sigreturn "ucontext_t *scp" .Sh DESCRIPTION -.Fn Sigreturn +The +.Fn sigreturn +system call allows users to atomically unmask, switch stacks, and return from a signal context. The processes signal mask and stack status are @@ -68,7 +70,9 @@ Otherwise, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS -.Fn Sigreturn +The +.Fn sigreturn +system call will fail and the process context will remain unchanged if one of the following occurs. .Bl -tag -width Er @@ -87,5 +91,5 @@ raise the privilege level of the process. .Sh HISTORY The .Fn sigreturn -function call appeared in +system call appeared in .Bx 4.3 . diff --git a/lib/libc/sys/sigstack.2 b/lib/libc/sys/sigstack.2 index 9f1dfa9..95c0db2 100644 --- a/lib/libc/sys/sigstack.2 +++ b/lib/libc/sys/sigstack.2 @@ -50,5 +50,5 @@ function has been deprecated in favor of the interface described in .Sh HISTORY The .Fn sigstack -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/sigsuspend.2 b/lib/libc/sys/sigsuspend.2 index 1dbfe0b..1b2ec9f 100644 --- a/lib/libc/sys/sigsuspend.2 +++ b/lib/libc/sys/sigsuspend.2 @@ -45,7 +45,9 @@ .Ft int .Fn sigsuspend "const sigset_t *sigmask" .Sh DESCRIPTION -.Fn Sigsuspend +The +.Fn sigsuspend +system call temporarily changes the blocked signal mask to the set to which .Fa sigmask points, @@ -66,7 +68,7 @@ with the previous mask returned by .Sh RETURN VALUES The .Fn sigsuspend -function +system call always terminates by being interrupted, returning -1 with .Va errno set to @@ -77,6 +79,6 @@ set to .Xr sigsetops 3 .Sh STANDARDS The -.Fn sigsupend -function call is expected to conform to +.Fn sigsuspend +system call is expected to conform to .St -p1003.1-90 . diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 index bd1a14c..c3869a7 100644 --- a/lib/libc/sys/socket.2 +++ b/lib/libc/sys/socket.2 @@ -46,7 +46,9 @@ .Ft int .Fn socket "int domain" "int type" "int protocol" .Sh DESCRIPTION -.Fn Socket +The +.Fn socket +system call creates an endpoint for communication and returns a descriptor. .Pp The @@ -156,7 +158,7 @@ to pipes. A stream socket must be in a state before any data may be sent or received on it. A connection to another socket is created with a .Xr connect 2 -call. +system call. Once connected, data may be transferred using .Xr read 2 and @@ -165,14 +167,14 @@ calls or some variant of the .Xr send 2 and .Xr recv 2 -calls. +functions. (Some protocol families, such as the Internet family, support the notion of an .Dq implied connect , which permits data to be sent piggybacked onto a connect operation by using the .Xr sendto 2 -call.) +system call.) When a session has been completed a .Xr close 2 may be performed. @@ -229,7 +231,7 @@ which returns the next datagram with its return address. .Pp An .Xr fcntl 2 -call can be used to specify a process group to receive +system call can be used to specify a process group to receive a .Dv SIGURG signal when the out-of-band data arrives. @@ -252,7 +254,7 @@ value is a descriptor referencing the socket. .Sh ERRORS The .Fn socket -call fails if: +system call fails if: .Bl -tag -width Er .It Bq Er EPROTONOSUPPORT The protocol type or the specified protocol is not supported @@ -300,5 +302,5 @@ The socket cannot be created until sufficient resources are freed. .Sh HISTORY The .Fn socket -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/socketpair.2 b/lib/libc/sys/socketpair.2 index 929b921..2dbc202 100644 --- a/lib/libc/sys/socketpair.2 +++ b/lib/libc/sys/socketpair.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn socketpair -call creates an unnamed pair of connected sockets in +system call creates an unnamed pair of connected sockets in the specified domain .Fa d , of the specified @@ -91,5 +91,5 @@ domain. .Sh HISTORY The .Fn socketpair -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 index 590525c..49d24f7 100644 --- a/lib/libc/sys/stat.2 +++ b/lib/libc/sys/stat.2 @@ -54,7 +54,7 @@ .Sh DESCRIPTION The .Fn stat -function obtains information about the file pointed to by +system call obtains information about the file pointed to by .Fa path . Read, write or execute permission of the named file is not required, but all directories @@ -62,7 +62,7 @@ listed in the path name leading to the file must be searchable. .Pp The .Fn lstat -function is like +system call is like .Fn stat except in the case where the named file is a symbolic link, in which case @@ -74,7 +74,7 @@ returns information about the file the link references. .Pp The .Fn fstat -function obtains the same information about an open file +system call obtains the same information about an open file known by the file descriptor .Fa fd . .Pp @@ -218,7 +218,7 @@ The .Fn stat and .Fn lstat -functions will fail if: +system calls will fail if: .Bl -tag -width Er .It Bq Er EACCES Search permission is denied for a component of the path prefix. @@ -247,7 +247,7 @@ represented correctly in the structure pointed to by .Bl -tag -width Er The .Fn fstat -function will fail if: +system call will fail if: .It Bq Er EBADF .Fa fd is not a valid open file descriptor. @@ -279,16 +279,16 @@ The .Fn stat and .Fn fstat -function calls are expected to conform to +system calls are expected to conform to .St -p1003.1-90 . .Sh HISTORY -A +The .Fn stat -and a +and .Fn fstat -function call appeared in +system calls appeared in .At v7 . -A +The .Fn lstat -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/statfs.2 b/lib/libc/sys/statfs.2 index fb48f98..6cdc692 100644 --- a/lib/libc/sys/statfs.2 +++ b/lib/libc/sys/statfs.2 @@ -48,7 +48,9 @@ .Ft int .Fn fstatfs "int fd" "struct statfs *buf" .Sh DESCRIPTION -.Fn Statfs +The +.Fn statfs +system call returns information about a mounted file system. .Fa Path is the path name of any file within the mounted file system. @@ -121,13 +123,17 @@ The file system is exported with Kerberos uid mapping. .El .Pp Fields that are undefined for a particular file system are set to -1. -.Fn Fstatfs +The +.Fn fstatfs +system call returns the same information about an open file referenced by descriptor .Fa fd . .Sh RETURN VALUES .Rv -std .Sh ERRORS -.Fn Statfs +The +.Fn statfs +system call fails if one or more of the following are true: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -162,7 +168,9 @@ An error occurred while reading from or writing to the file system. .El .Pp -.Fn Fstatfs +The +.Fn fstatfs +system call fails if one or more of the following are true: .Bl -tag -width Er .It Bq Er EBADF @@ -179,5 +187,5 @@ error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn statfs -function first appeared in +system call first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 index f4f9092..1feb7c0 100644 --- a/lib/libc/sys/swapon.2 +++ b/lib/libc/sys/swapon.2 @@ -47,7 +47,9 @@ .Ft int .Fn swapoff "const char *special" .Sh DESCRIPTION -.Fn Swapon +The +.Fn swapon +system call makes the block device .Fa special available to the system for @@ -135,8 +137,9 @@ paging and swapping to the given device. .Sh HISTORY The .Fn swapon -function call appeared in +system call appeared in .Bx 4.0 . -.Fn Swapoff -appeared in +The +.Fn swapoff +system call appeared in .Fx 5.0 . diff --git a/lib/libc/sys/symlink.2 b/lib/libc/sys/symlink.2 index 1fa0666..8d25e33 100644 --- a/lib/libc/sys/symlink.2 +++ b/lib/libc/sys/symlink.2 @@ -49,7 +49,7 @@ A symbolic link .Fa name2 is created to .Fa name1 -.Pf ( Fa name2 +.Fa ( name2 is the name of the file created, .Fa name1 @@ -132,5 +132,5 @@ points outside the process's allocated address space. .Sh HISTORY The .Fn symlink -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/sync.2 b/lib/libc/sys/sync.2 index 6b16b1f..89c2583 100644 --- a/lib/libc/sys/sync.2 +++ b/lib/libc/sys/sync.2 @@ -47,21 +47,22 @@ .Sh DESCRIPTION The .Fn sync -function forces a write of dirty (modified) buffers +system call forces a write of dirty (modified) buffers in the block buffer cache out to disk. The kernel keeps this information in core to reduce the number of disk I/O transfers required by the system. -As information in the cache is lost after a system crash a +As information in the cache is lost after a system crash, a .Fn sync -call is issued +system call is issued frequently by the user process .Xr syncer 4 (about every 30 seconds). .Pp -The function +The .Xr fsync 2 +system call may be used to synchronize individual file descriptor attributes. .Sh SEE ALSO @@ -69,10 +70,12 @@ attributes. .Xr syncer 4 , .Xr sync 8 .Sh BUGS -.Fn Sync +The +.Fn sync +system call may return before the buffers are completely flushed. .Sh HISTORY -A +The .Fn sync -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/sys/sysarch.2 b/lib/libc/sys/sysarch.2 index 5439747..2685a37 100644 --- a/lib/libc/sys/sysarch.2 +++ b/lib/libc/sys/sysarch.2 @@ -47,7 +47,9 @@ .Ft int .Fn sysarch "int number" "void *args" .Sh DESCRIPTION -.Fn Sysarch +The +.Fn sysarch +system call performs the architecture-dependent function specified by .Fa number @@ -69,7 +71,7 @@ user programs. Instead, they should access its functions using the architecture-dependent library. .Sh RETURN VALUES -See the manual pages for specific architecture-dependent function calls +See the manual pages for specific architecture-dependent system calls for information about their return values. .Sh SEE ALSO .Xr i386_get_ioperm 2 , diff --git a/lib/libc/sys/syscall.2 b/lib/libc/sys/syscall.2 index 5ecbf8b..10109ce 100644 --- a/lib/libc/sys/syscall.2 +++ b/lib/libc/sys/syscall.2 @@ -49,7 +49,9 @@ .Ft off_t .Fn __syscall "quad_t number" ... .Sh DESCRIPTION -.Fn Syscall +The +.Fn syscall +function performs the system call whose assembly language interface has the specified .Fa number @@ -75,5 +77,5 @@ such as .Sh HISTORY The .Fn syscall -function call appeared in +function appeared in .Bx 4.0 . diff --git a/lib/libc/sys/truncate.2 b/lib/libc/sys/truncate.2 index 6e3a07e..32e487e 100644 --- a/lib/libc/sys/truncate.2 +++ b/lib/libc/sys/truncate.2 @@ -48,7 +48,9 @@ .Ft int .Fn ftruncate "int fd" "off_t length" .Sh DESCRIPTION -.Fn Truncate +The +.Fn truncate +system call causes the file named by .Fa path or referenced by @@ -67,7 +69,9 @@ the file must be open for writing. .Sh RETURN VALUES .Rv -std .Sh ERRORS -.Fn Truncate +The +.Fn truncate +system call succeeds unless: .Bl -tag -width Er .It Bq Er ENOTDIR @@ -96,7 +100,9 @@ An I/O error occurred updating the inode. points outside the process's allocated address space. .El .Pp -.Fn Ftruncate +The +.Fn ftruncate +system call succeeds unless: .Bl -tag -width Er .It Bq Er EBADF @@ -124,5 +130,5 @@ to extend a file is not portable. .Sh HISTORY The .Fn truncate -function call appeared in +system call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/umask.2 b/lib/libc/sys/umask.2 index c747a63..9226071 100644 --- a/lib/libc/sys/umask.2 +++ b/lib/libc/sys/umask.2 @@ -73,7 +73,7 @@ The previous value of the file mode mask is returned by the call. .Sh ERRORS The .Fn umask -function is always successful. +system call is always successful. .Sh SEE ALSO .Xr chmod 2 , .Xr mknod 2 , @@ -81,10 +81,10 @@ function is always successful. .Sh STANDARDS The .Fn umask -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . .Sh HISTORY -An +The .Fn umask -function call appeared in +function appeared in .At v7 . diff --git a/lib/libc/sys/undelete.2 b/lib/libc/sys/undelete.2 index 12cc6f0..fba16f8 100644 --- a/lib/libc/sys/undelete.2 +++ b/lib/libc/sys/undelete.2 @@ -48,7 +48,7 @@ .Sh DESCRIPTION The .Fn undelete -function attempts to recover the deleted file named by +system call attempts to recover the deleted file named by .Fa path . Currently, this works only when the named object is a whiteout in a union file system. @@ -98,7 +98,7 @@ points outside the process's allocated address space. .Xr unlink 2 , .Xr mount_unionfs 8 .Sh HISTORY -An +The .Fn undelete -function call first appeared in +system call first appeared in .Bx 4.4 Lite . diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2 index 72c716d..61a2de1 100644 --- a/lib/libc/sys/unlink.2 +++ b/lib/libc/sys/unlink.2 @@ -47,7 +47,7 @@ .Sh DESCRIPTION The .Fn unlink -function +system call removes the link named by .Fa path from its directory and decrements the link count of the @@ -106,9 +106,9 @@ points outside the process's allocated address space. .Xr rmdir 2 , .Xr symlink 7 .Sh HISTORY -An +The .Fn unlink -function call appeared in +function appeared in .At v6 . .Pp The diff --git a/lib/libc/sys/utimes.2 b/lib/libc/sys/utimes.2 index 6ca9e38..dd03e90 100644 --- a/lib/libc/sys/utimes.2 +++ b/lib/libc/sys/utimes.2 @@ -71,7 +71,7 @@ write the file, or be the super-user. If .Fa times is -.Pf non- Dv NULL , +.No non- Ns Dv NULL , it is assumed to point to an array of two timeval structures. The access time is set to the value of the first element, and the modification time is set to the value of the second element. @@ -89,7 +89,9 @@ The caller must be the owner of the file or be the super-user. In either case, the inode-change-time of the file is set to the current time. .Pp +The .Fn lutimes +system call is like .Fn utimes except in the case where the named file is a symbolic link, @@ -102,9 +104,11 @@ changes the times of the file the link references. .Sh RETURN VALUES .Rv -std .Sh ERRORS +The .Fn utimes and .Fn lutimes +system calls will fail if: .Bl -tag -width Er .It Bq Er EACCES @@ -146,7 +150,9 @@ does not match the owner of the file and is not the super-user. The file system containing the file is mounted read-only. .El .Pp +The .Fn futimes +system call will fail if: .Bl -tag -width Er .It Bq Er EBADF @@ -154,7 +160,7 @@ will fail if: does not refer to a valid descriptor. .El .Pp -All of the functions will fail if: +All of the system calls will fail if: .Bl -tag -width Er .It Bq Er EACCES The @@ -185,11 +191,11 @@ The file system containing the file is mounted read-only. .Sh HISTORY The .Fn utimes -function call appeared in +system call appeared in .Bx 4.2 . The .Fn futimes and .Fn lutimes -function calls first appeared in +system calls first appeared in .Fx 3.0 . diff --git a/lib/libc/sys/uuidgen.2 b/lib/libc/sys/uuidgen.2 index d2881cc..6aa09a8 100644 --- a/lib/libc/sys/uuidgen.2 +++ b/lib/libc/sys/uuidgen.2 @@ -38,7 +38,7 @@ .Fn uuidgen "struct uuid *store" "int count" .Sh DESCRIPTION The -.Nm +.Fn uuidgen system call generates .Fa count universally unique identifiers (UUIDs) and writes them to the buffer @@ -55,7 +55,7 @@ force a new random clock sequence, thereby increasing the likelyhood for the identifier to be unique. .Pp When multiple identifiers are to be generated, the -.Nm +.Fn uuidgen system call will generate a set of identifiers that is dense in such a way that there is no identifier that is larger than the smallest identifier in the set and smaller than the largest identifier in the set and that is not already @@ -94,7 +94,7 @@ The most significant 6 bits of a 14-bit sequence number multiplexed with a 2-bit variant value. Note that the width of the variant value is determined by the variant itself. Identifiers generated by the -.Nm +.Fn uuidgen system call have variant value 10b. the variant value is stored in the most significant bits of the field. .It Va clock_seq_low @@ -114,7 +114,7 @@ terms and is otherwise beyond the scope of this system call. .Rv -std .Sh ERRORS The -.Nm +.Fn uuidgen system call can fail with: .Bl -tag -width Er .It Bq Er EFAULT @@ -133,10 +133,10 @@ parameter is less than 1 or larger than the hard upper limit of 2048. The identifiers are represented and generated in conformance with the DCE 1.1 RPC specification. The -.Nm +.Fn uuidgen system call is itself not part of the specification. .Sh HISTORY The -.Nm +.Fn uuidgen system call first appeared in .Fx 5.0 . diff --git a/lib/libc/sys/vfork.2 b/lib/libc/sys/vfork.2 index 680b67d..113dff9 100644 --- a/lib/libc/sys/vfork.2 +++ b/lib/libc/sys/vfork.2 @@ -45,14 +45,18 @@ .Ft int .Fn vfork void .Sh DESCRIPTION -.Fn Vfork +The +.Fn vfork +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 .Xr fork 2 would have been to create a new system context for an .Xr execve 2 . -.Fn Vfork +The +.Fn vfork +system call differs from .Xr fork 2 in that the child borrows the parent's memory and thread of @@ -63,11 +67,15 @@ or an exit (either by a call to or abnormally). The parent process is suspended while the child is using its resources. .Pp -.Fn Vfork +The +.Fn vfork +system call returns 0 in the child's context and (later) the pid of the child in the parent's context. .Pp -.Fn Vfork +The +.Fn vfork +system call can normally be used just like .Xr fork 2 . It does not work, however, to return while running in the childs context @@ -128,5 +136,5 @@ and input attempts result in an end-of-file indication. .Sh HISTORY The .Fn vfork -function call appeared in +system call appeared in .Bx 2.9 . diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2 index ece08dd..7f8925a 100644 --- a/lib/libc/sys/wait.2 +++ b/lib/libc/sys/wait.2 @@ -73,7 +73,7 @@ as defined below. .Pp The .Fn wait4 -call provides a more general interface for programs +system call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. @@ -145,7 +145,7 @@ of 0. .Pp The .Fn waitpid -call is identical to +function is identical to .Fn wait4 with an .Fa rusage @@ -266,7 +266,9 @@ is returned and .Va errno is set to indicate the error. .Sh ERRORS -.Fn Wait +The +.Fn wait +function will fail and return immediately if: .Bl -tag -width Er .It Bq Er ECHILD @@ -307,7 +309,7 @@ call are extensions to the POSIX interface. .Xr _exit 2 , .Xr exit 3 .Sh HISTORY -A +The .Fn wait -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 index 729a4d0..0ea137a 100644 --- a/lib/libc/sys/write.2 +++ b/lib/libc/sys/write.2 @@ -53,21 +53,27 @@ .Ft ssize_t .Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset" .Sh DESCRIPTION -.Fn Write +The +.Fn write +system call attempts to write .Fa nbytes of data to the object referenced by the descriptor .Fa d from the buffer pointed to by .Fa buf . -.Fn Writev +The +.Fn writev +system call performs the same action, but gathers the output data from the .Fa iovcnt buffers specified by the members of the .Fa iov array: iov[0], iov[1], ..., iov[iovcnt\|-\|1]. -.Fn Pwrite +The +.Fn pwrite +system call performs the same function, but writes to the specified position in the file without modifying the file pointer. .Pp @@ -88,7 +94,9 @@ Each .Fa iovec entry specifies the base address and length of an area in memory from which data should be written. -.Fn Writev +The +.Fn writev +system call will always write a complete area before proceeding to the next. .Pp @@ -130,10 +138,12 @@ is returned. Otherwise a -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS -.Fn Write , +The +.Fn write , .Fn writev , and .Fn pwrite +system calls will fail and the file pointer will remain unchanged if: .Bl -tag -width Er .It Bq Er EBADF @@ -212,7 +222,7 @@ The mbuf pool has been completely exhausted when writing to a socket. .Pp The .Fn pwrite -call may also return the following errors: +system call may also return the following errors: .Bl -tag -width Er .It Bq Er EINVAL The specified file offset is invalid. @@ -228,26 +238,24 @@ The file descriptor is associated with a pipe, socket, or FIFO. .Sh STANDARDS The .Fn write -function call is expected to conform to +system call is expected to conform to .St -p1003.1-90 . The .Fn writev and .Fn pwrite -functions are expected to conform to +system calls are expected to conform to .St -xpg4.2 . .Sh HISTORY The .Fn pwrite -function call -appeared in +function appeared in .At V.4 . The .Fn writev -function call -appeared in +system call appeared in .Bx 4.2 . -A +The .Fn write -function call appeared in +function appeared in .At v6 . |
