From 33992dc0ed9323e5ba9d2d4a5b8dec5401a9c4e2 Mon Sep 17 00:00:00 2001 From: Ruslan Ermilov Date: Wed, 30 Jun 2004 20:09:10 +0000 Subject: [PATCH] Markup, grammar, and spelling fixes. --- lib/libc/gen/vis.3 | 10 +++++-- lib/libc/locale/ctype.3 | 2 +- lib/libc/locale/multibyte.3 | 44 +++++++++++++++--------------- lib/libc/net/getipnodebyname.3 | 2 +- lib/libc/net/inet.3 | 6 +++- lib/libc/net/resolver.3 | 2 +- lib/libc/posix1e/mac_get.3 | 6 ++-- lib/libc/posix1e/mac_text.3 | 2 +- lib/libc/stdio/printf.3 | 7 ++--- lib/libc/string/ffs.3 | 2 +- lib/libc/sys/kqueue.2 | 6 ++-- lib/libc/sys/mount.2 | 12 ++++---- lib/libc/sys/msync.2 | 17 ++++++++---- lib/libc/sys/open.2 | 2 +- lib/libc/sys/poll.2 | 2 +- lib/libc/sys/ptrace.2 | 5 ++-- lib/libc/sys/read.2 | 8 +++--- lib/libc/sys/send.2 | 12 +++++--- lib/libc/sys/sendfile.2 | 50 +++++++++++++++++++++++----------- lib/libc/sys/statfs.2 | 6 ++-- 20 files changed, 121 insertions(+), 82 deletions(-) diff --git a/lib/libc/gen/vis.3 b/lib/libc/gen/vis.3 index 5b75041008a2..3d094eb9945c 100644 --- a/lib/libc/gen/vis.3 +++ b/lib/libc/gen/vis.3 @@ -138,8 +138,14 @@ The following flags alter this: .Bl -tag -width VIS_WHITEX .It Dv VIS_GLOB -Also encode magic characters ('*', '?', '[' and '#') recognized by -.Xr glob 3 +Also encode magic characters +.Ql ( * , +.Ql \&? , +.Ql \&[ +and +.Ql # ) +recognized by +.Xr glob 3 . .It Dv VIS_SP Also encode space. .It Dv VIS_TAB diff --git a/lib/libc/locale/ctype.3 b/lib/libc/locale/ctype.3 index db2cdadcda53..44aeac7f3bdb 100644 --- a/lib/libc/locale/ctype.3 +++ b/lib/libc/locale/ctype.3 @@ -126,10 +126,10 @@ See the specific manual pages for more information. .Xr isgraph 3 , .Xr isideogram 3 , .Xr islower 3 , -.Xr isrune 3 , .Xr isphonogram 3 , .Xr isprint 3 , .Xr ispunct 3 , +.Xr isrune 3 , .Xr isspace 3 , .Xr isspecial 3 , .Xr isupper 3 , diff --git a/lib/libc/locale/multibyte.3 b/lib/libc/locale/multibyte.3 index db003c51e083..604711385615 100644 --- a/lib/libc/locale/multibyte.3 +++ b/lib/libc/locale/multibyte.3 @@ -51,7 +51,7 @@ .Sh DESCRIPTION The basic elements of some written natural languages, such as Chinese, cannot be represented uniquely with single C -.Va char Ns s . +.Vt char Ns s . The C standard supports two different ways of dealing with extended natural language encodings: wide characters and @@ -59,10 +59,10 @@ multibyte characters. Wide characters are an internal representation which allows each basic element to map to a single object of type -.Va wchar_t . +.Vt wchar_t . Multibyte characters are used for input and output and code each basic element as a sequence of C -.Va char Ns s . +.Vt char Ns s . Individual basic elements may map into one or more (up to .Dv MB_LEN_MAX ) @@ -75,7 +75,7 @@ The locale category .Dv LC_CTYPE specifically controls this interpretation. The -.Va wchar_t +.Vt wchar_t type is wide enough to hold the largest value in the wide character representations for all locales. .Pp @@ -89,17 +89,17 @@ but are lumped with a neighboring character. There is always a distinguished .Sq initial shift state. -Some functions (e.g. -.Fn mblen , -.Fn mbtowc +Some functions (e.g., +.Xr mblen 3 , +.Xr mbtowc 3 and -.Fn wctomb ) +.Xr wctomb 3 ) maintain static shift state internally, whereas -others store in an +others store it in an .Vt mbstate_t object passed by the caller. Shift states are undefined after a call to -.Fn setlocale +.Xr setlocale 3 with the .Dv LC_CTYPE or @@ -118,22 +118,22 @@ Null bytes are not permitted within multibyte characters. The C library provides the following functions for dealing with multibyte characters: .Bl -column "Description" -.It Sy "Function Description" -.It "mblen get number of bytes in a character" -.It "mbrlen get number of bytes in a character (restartable)" -.It "mbrtowc convert a character to a wide-character code (restartable)" -.It "mbsrtowcs convert a character string to a wide-character string (restartable)" -.It "mbstowcs convert a character string to a wide-character string" -.It "mbtowc convert a character to a wide-character code" -.It "wcrtomb convert a wide-character code to a character (restartable)" -.It "wcstombs convert a wide-character string to a character string" -.It "wcsrtombs convert a wide-character string to a character string (restartable)" -.It "wctomb convert a wide-character code to a character" +.It Sy "Function Description" +.It Xr mblen 3 Ta "get number of bytes in a character" +.It Xr mbrlen 3 Ta "get number of bytes in a character (restartable)" +.It Xr mbrtowc 3 Ta "convert a character to a wide-character code (restartable)" +.It Xr mbsrtowcs 3 Ta "convert a character string to a wide-character string (restartable)" +.It Xr mbstowcs 3 Ta "convert a character string to a wide-character string" +.It Xr mbtowc 3 Ta "convert a character to a wide-character code" +.It Xr wcrtomb 3 Ta "convert a wide-character code to a character (restartable)" +.It Xr wcstombs 3 Ta "convert a wide-character string to a character string" +.It Xr wcsrtombs 3 Ta "convert a wide-character string to a character string (restartable)" +.It Xr wctomb 3 Ta "convert a wide-character code to a character" .El .Sh SEE ALSO .Xr mklocale 1 , -.Xr stdio 3 , .Xr setlocale 3 , +.Xr stdio 3 , .Xr big5 5 , .Xr euc 5 , .Xr gb18030 5 , diff --git a/lib/libc/net/getipnodebyname.3 b/lib/libc/net/getipnodebyname.3 index 1ade42d2cee8..c5e65a326766 100644 --- a/lib/libc/net/getipnodebyname.3 +++ b/lib/libc/net/getipnodebyname.3 @@ -458,7 +458,7 @@ are documented in Although the current implementation is otherwise thread-safe, using it in conjunction with .Fn gethostby* -(see +(see .Xr gethostbyname 3 ) or .Xr yp 8 diff --git a/lib/libc/net/inet.3 b/lib/libc/net/inet.3 index 2c27bde399ba..39b60be9f1d8 100644 --- a/lib/libc/net/inet.3 +++ b/lib/libc/net/inet.3 @@ -243,7 +243,11 @@ call fails if: was not large enough to store the presentation form of the address. .It Bq Er EAFNOSUPPORT .Fa *src -was not an AF_INET or AF_INET6 family address. +was not an +.Dv AF_INET +or +.Dv AF_INET6 +family address. .El .Sh SEE ALSO .Xr addr2ascii 3 , diff --git a/lib/libc/net/resolver.3 b/lib/libc/net/resolver.3 index 68d80d8eeb8a..235898c61415 100644 --- a/lib/libc/net/resolver.3 +++ b/lib/libc/net/resolver.3 @@ -399,7 +399,7 @@ to a buffer pointed to by .Sh RETURN VALUES The .Fn res_init -function will return 0 on success, or -1 in a threaded program if +function will return 0 on success, or \-1 in a threaded program if per-thread storage could not be allocated. .Sh IMPLEMENTATION NOTES This implementation of the resolver is thread-safe, but it will not diff --git a/lib/libc/posix1e/mac_get.3 b/lib/libc/posix1e/mac_get.3 index 96e068802266..cd498d0e4e7d 100644 --- a/lib/libc/posix1e/mac_get.3 +++ b/lib/libc/posix1e/mac_get.3 @@ -37,6 +37,8 @@ .Nm mac_get_file , .Nm mac_get_link , .Nm mac_get_fd , +.Nm mac_get_peer , +.Nm mac_get_pid , .Nm mac_get_proc .Nd get the label of a file, socket, socket peer or process .Sh LIBRARY @@ -61,7 +63,7 @@ The system call returns the label associated with a file specified by pathname. The -.Fn mac_get_link +.Fn mac_get_link function is the same as .Fn mac_get_file , except that it does not follow symlinks. @@ -86,7 +88,7 @@ The and .Fn mac_get_proc system calls return the process label associated with an arbitrary -process id, or the current process. +process ID, or the current process. .Pp Label storage for use with these calls must first be allocated and prepared using the diff --git a/lib/libc/posix1e/mac_text.3 b/lib/libc/posix1e/mac_text.3 index f6a04af031fa..068533a215a6 100644 --- a/lib/libc/posix1e/mac_text.3 +++ b/lib/libc/posix1e/mac_text.3 @@ -84,7 +84,7 @@ implementation, they must be freed using as .Xr mac_free 3 is used only to free memory used for type -.Dv mac_t . +.Vt mac_t . .Sh ERRORS .Bl -tag -width Er .It Bq Er ENOMEM diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index 55a60c3230ce..4196cccf893a 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -549,10 +549,9 @@ to represent the hex digits, and the letter to separate the mantissa and exponent. .Pp Note that there may be multiple valid ways to represent floating-point -numbers in this hexadecimal format. For example, -.Li 0x3.24p+0 -and -.Li 0x6.48p-1 +numbers in this hexadecimal format. +For example, +.Li 0x3.24p+0 , 0x6.48p-1 and .Li 0xc.9p-2 are all equivalent. diff --git a/lib/libc/string/ffs.3 b/lib/libc/string/ffs.3 index cb9c6cc3931f..7199bf5c9c26 100644 --- a/lib/libc/string/ffs.3 +++ b/lib/libc/string/ffs.3 @@ -34,7 +34,7 @@ .\" @(#)ffs.3 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" -.Dd April 19, 1994 +.Dd January 13, 2004 .Dt FFS 3 .Os .Sh NAME diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2 index 14e8b327392c..4baaf69eac12 100644 --- a/lib/libc/sys/kqueue.2 +++ b/lib/libc/sys/kqueue.2 @@ -120,7 +120,7 @@ is zero, will return immediately even if there is a .Fa timeout specified unlike -.Xr select 2 . +.Xr select 2 . If .Fa timeout is a non-NULL pointer, it specifies a maximum interval to wait @@ -345,7 +345,7 @@ The file referenced by the descriptor was renamed. .It NOTE_REVOKE Access to the file was revoked via .Xr revoke 2 -or the underlying filesystem was unmounted. +or the underlying file system was unmounted. .El .Pp On return, @@ -530,7 +530,7 @@ It is currently not possible to watch a that resides on anything but a UFS file system. .Pp -The +The .Dv EVFILT_NETDEV filter is currently only implemented for devices that use the .Xr miibus 4 diff --git a/lib/libc/sys/mount.2 b/lib/libc/sys/mount.2 index 42a5bb15de1e..f6d6200bddbc 100644 --- a/lib/libc/sys/mount.2 +++ b/lib/libc/sys/mount.2 @@ -82,24 +82,24 @@ The .Fn nmount system call behaves similarly to .Fn mount , -except that the mount options (filesystem type name, device to mount, +except that the mount options (file system type name, device to mount, mount-point name, etc.) are passed as an array of name-value pairs in the array .Fa iov , containing .Fa niov elements. -The following options are required by all filesystems: +The following options are required by all file systems: .Bl -item -offset indent -compact .It -.Li fstype Ta filesystem type name (e.g. Dq Li procfs ) +.Li fstype Ta file system type name (e.g., Dq Li procfs ) .It -.Li fspath Ta mount point pathname (e.g. Dq Li /proc ) +.Li fspath Ta mount point pathname (e.g., Dq Li /proc ) .El .Pp -Depending on the filesystem type, other options may be +Depending on the file system type, other options may be recognized or required; -for example, most disk-based filesystems require a +for example, most disk-based file systems require a .Dq Li from option containing the pathname of a special device in addition to the options listed above. diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2 index a692d748f5c5..28aa1a7a38f0 100644 --- a/lib/libc/sys/msync.2 +++ b/lib/libc/sys/msync.2 @@ -65,11 +65,15 @@ succeeding locations will be examined. The .Fa flags argument may be specified as follows: -.Bd -literal -MS_ASYNC Return immediately -MS_SYNC Perform synchronous writes -MS_INVALIDATE Invalidate all cached data -.Ed +.Pp +.Bl -tag -width ".Dv MS_INVALIDATE" -compact +.It Dv MS_ASYNC +Return immediately +.It Dv MS_SYNC +Perform synchronous writes +.It Dv MS_INVALIDATE +Invalidate all cached data +.El .Sh RETURN VALUES .Rv -std msync .Sh ERRORS @@ -80,7 +84,8 @@ will fail if: .Bl -tag -width Er .It Bq Er EBUSY Some or all of the pages in the specified region are locked and -MS_INVALIDATE is specified. +.Dv MS_INVALIDATE +is specified. .It Bq Er EINVAL The .Fa addr diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 index 1fb294543e99..8048ee55c6df 100644 --- a/lib/libc/sys/open.2 +++ b/lib/libc/sys/open.2 @@ -246,7 +246,7 @@ or .Dv O_EXLOCK is specified but the underlying file system does not support locking. .It Bq Er EOPNOTSUPP -The named file is a special file mounted through a filesystem that +The named file is a special file mounted through a file system that does not support access to it (e.g. NFS). .It Bq Er EWOULDBLOCK .Dv O_NONBLOCK diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 index 252678d2e8b4..3456350bc3c7 100644 --- a/lib/libc/sys/poll.2 +++ b/lib/libc/sys/poll.2 @@ -176,7 +176,7 @@ The specified time limit is negative. .Sh SEE ALSO .Xr accept 2 , .Xr connect 2 , -.Xr kqueue 2 , +.Xr kqueue 2 , .Xr read 2 , .Xr recv 2 , .Xr select 2 , diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 index 8b61df3a2571..18683faf89aa 100644 --- a/lib/libc/sys/ptrace.2 +++ b/lib/libc/sys/ptrace.2 @@ -34,7 +34,8 @@ issue a series of system calls to control the execution of the process, as well as access process memory and register state. For the duration of the tracing session, the traced process will be -"re-parented", with its parent process id (and resulting behavior) +.Dq re-parented , +with its parent process ID (and resulting behavior) changed to the tracing process. It is permissible for a tracing process to attach to more than one other process at a time. @@ -61,7 +62,7 @@ as a result of attaching, system calls, or stepping by the tracing process. The tracing process may choose to intercept the signal, using it to observe process behavior (such as -.Dv SIGTRAP ), +.Dv SIGTRAP ) , or forward the signal to the process if appropriate. The .Fn ptrace diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 index b73e11ada233..8e3865217a79 100644 --- a/lib/libc/sys/read.2 +++ b/lib/libc/sys/read.2 @@ -165,10 +165,10 @@ The file was marked for non-blocking I/O, and no data were ready to be read. .It Bq Er EISDIR The file descriptor is associated with a directory residing -on a filesystem that does not allow regular read operations on +on a file system that does not allow regular read operations on directories (e.g. NFS). .It Bq Er EOPNOTSUPP -The file descriptor is associated with a filesystem and file type that +The file descriptor is associated with a file system and file type that do not allow regular read operations on it. .It Bq Er EOVERFLOW The file descriptor is associated with a regular file, @@ -178,7 +178,7 @@ is greater than 0, is before the end-of-file, and .Fa offset is greater than or equal to the offset maximum established -for this filesystem. +for this file system. .El .Pp In addition, @@ -190,7 +190,7 @@ The .Fa iovcnt argument was less than or equal to 0, or greater than -.Li IOV_MAX . +.Dv IOV_MAX . .It Bq Er EINVAL One of the .Fa iov_len diff --git a/lib/libc/sys/send.2 b/lib/libc/sys/send.2 index c1c033b7b979..38c8f80c66a0 100644 --- a/lib/libc/sys/send.2 +++ b/lib/libc/sys/send.2 @@ -190,12 +190,16 @@ The remote host was down. .It Bq Er ENETDOWN The remote network was down. .It Bq Er EPERM -The process using a SOCK_RAW socket was jailed and the source -address specified in the IP header did not match the IP +The process using a +.Dv SOCK_RAW +socket was jailed and the source +address specified in the IP header did not match the IP address bound to the prison. .It Bq Er EPIPE -The socket is unable to send anymore data (SBS_CANTSENDMORE has -been set on the socket). This typically means that the socket +The socket is unable to send anymore data +.Dv ( SBS_CANTSENDMORE +has been set on the socket). +This typically means that the socket is not connected. .El .Sh BUGS diff --git a/lib/libc/sys/sendfile.2 b/lib/libc/sys/sendfile.2 index dc6c062b23db..3f2b3d3cbb17 100644 --- a/lib/libc/sys/sendfile.2 +++ b/lib/libc/sys/sendfile.2 @@ -89,9 +89,13 @@ variable pointed to by The .Fa flags argument has one possible value: -.Fa SF_NODISKIO . -This flag causes any sendfile call which would block on disk I/O to instead -return EBUSY. Busy servers may benefit by transferring requests that would +.Dv SF_NODISKIO . +This flag causes any +.Fn sendfile +call which would block on disk I/O to instead +return +.Er EBUSY . +Busy servers may benefit by transferring requests that would block to a separate I/O worker thread. .Pp When using a socket marked for non-blocking I/O, @@ -112,27 +116,30 @@ implementation of is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. .Sh TUNING Internally, this system call uses a special -.Xr sendfile 2 +.Fn sendfile buffer .Pq Vt "struct sf_buf" to handle sending file data to the client. If the sending socket is -blocking, and there are not enough sendfile buffers available, -.Xr sendfile 2 +blocking, and there are not enough +.Fn sendfile +buffers available, +.Fn sendfile will block and report a state of .Dq Li sfbufa . If the sending socket is non-blocking and there are not enough -sendfile buffers available, the call will block and wait for the +.Fn sendfile +buffers available, the call will block and wait for the necessary buffers to become available before finishing the call. .Pp The number of .Vt sf_buf Ns 's allocated should be proportional to the number of nmbclusters used to send data to a client via -.Xr sendfile 2 . +.Fn sendfile . Tune accordingly to avoid blocking! Busy installations that make extensive use of -.Xr sendfile 2 +.Fn sendfile may want to increase these values to be inline with their .Va kern.ipc.nmbclusters (see @@ -140,20 +147,25 @@ may want to increase these values to be inline with their for details). .Pp The number of -.Xr sendfile 2 +.Fn sendfile buffers available is determined at boot time by either the .Va kern.ipc.nsfbufs .Xr loader.conf 5 variable or the .Dv NSFBUFS kernel configuration tunable. -The number of sendfile buffers scales with +The number of +.Fn sendfile +buffers scales with .Va kern.maxusers . +The .Va kern.ipc.nsfbufsused and .Va kern.ipc.nsfbufspeak -read-only sysctl variables show current and peak -.Xr sendfile 2 +read-only +.Xr sysctl 8 +variables show current and peak +.Fn sendfile buffers usage respectively. These values may also be viewed through .Nm netstat Fl m . @@ -173,8 +185,11 @@ argument is not a valid socket descriptor. .It Bq Er EBUSY Completing the entire transfer would have required disk I/O, so -it was aborted. Partial data may have been sent. -(This error can only occur when SF_NODISKIO is specified.) +it was aborted. +Partial data may have been sent. +(This error can only occur when +.Dv SF_NODISKIO +is specified.) .It Bq Er ENOTSOCK The .Fa s @@ -208,7 +223,10 @@ An error occurred while reading from .It Bq Er EFAULT An invalid address was specified for an argument. .It Bq Er EINTR -A signal interrupted sendfile before it could be completed. If specified, the number +A signal interrupted +.Fn sendfile +before it could be completed. +If specified, the number of bytes successfully sent will be returned in .Fa *sbytes . .It Bq Er EAGAIN diff --git a/lib/libc/sys/statfs.2 b/lib/libc/sys/statfs.2 index 75908b2a90ce..0a98ba788908 100644 --- a/lib/libc/sys/statfs.2 +++ b/lib/libc/sys/statfs.2 @@ -116,11 +116,11 @@ All I/O to the file system is done synchronously. No file system I/O is done synchronously. .It Dv MNT_SOFTDEP Soft updates being done (see -.Xr ffs 7). +.Xr ffs 7 ) . .It Dv MNT_SUIDDIR Special handling of SUID bit on directories. .It Dv MNT_UNION -Union with underlying filesystem. +Union with underlying file system. .It Dv MNT_NOSYMFOLLOW Symbolic links are not followed. .It Dv MNT_NOCLUSTERR @@ -132,7 +132,7 @@ Write clustering is disabled. .It Dv MNT_MULTILABEL Mandatory Access Control (MAC) support for individual objects (see -.Xr mac 4). +.Xr mac 4 ) . .It Dv MNT_ACLS Access Control List (ACL) support enabled. .It Dv MNT_LOCAL