diff options
author | sheldonh <sheldonh@FreeBSD.org> | 2000-03-02 09:14:21 +0000 |
---|---|---|
committer | sheldonh <sheldonh@FreeBSD.org> | 2000-03-02 09:14:21 +0000 |
commit | 329223e6f229a55ee8fed800f358f30e994ed749 (patch) | |
tree | 5d5e6c715ccfb778a29f10e1ea16f06731edbda8 /lib/libc | |
parent | 05f0a865546b5e0b902987be72a75a7b0ef85d09 (diff) | |
download | FreeBSD-src-329223e6f229a55ee8fed800f358f30e994ed749.zip FreeBSD-src-329223e6f229a55ee8fed800f358f30e994ed749.tar.gz |
Remove single-space hard sentence breaks. These degrade the quality
of the typeset output, tend to make diffs harder to read and provide
bad examples for new-comers to mdoc.
Diffstat (limited to 'lib/libc')
47 files changed, 294 insertions, 147 deletions
diff --git a/lib/libc/gen/arc4random.3 b/lib/libc/gen/arc4random.3 index 334bb7b..e83bb47 100644 --- a/lib/libc/gen/arc4random.3 +++ b/lib/libc/gen/arc4random.3 @@ -50,7 +50,8 @@ The .Fn arc4random function uses the key stream generator employed by the -arc4 cipher, which uses 8*8 8 bit S-Boxes. The S-Boxes +arc4 cipher, which uses 8*8 8 bit S-Boxes. +The S-Boxes can be in about .if t 2\u\s71700\s10\d .if n (2**1700) @@ -76,9 +77,11 @@ automatically initializes itself. .Xr srandomdev 3 .Sh HISTORY .Pa RC4 -has been designed by RSA Data Security, Inc. It was posted anonymously +has been designed by RSA Data Security, Inc. +It was posted anonymously to the USENET and was confirmed to be equivalent by several sources who -had access to the original cipher. Since +had access to the original cipher. +Since .Pa RC4 used to be a trade secret, the cipher is now referred to as .Pa ARC4 . diff --git a/lib/libc/gen/getgrent.3 b/lib/libc/gen/getgrent.3 index bb3cfb5..ffac782 100644 --- a/lib/libc/gen/getgrent.3 +++ b/lib/libc/gen/getgrent.3 @@ -200,6 +200,7 @@ The functions and .Fn setgrent leave their results in an internal static object and return -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to the same function will modify the same object. diff --git a/lib/libc/gen/getmntinfo.3 b/lib/libc/gen/getmntinfo.3 index d20fc5b..f1a7fa5 100644 --- a/lib/libc/gen/getmntinfo.3 +++ b/lib/libc/gen/getmntinfo.3 @@ -99,7 +99,8 @@ The .Fn getmntinfo function writes the array of structures to an internal static object and returns -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to .Fn getmntinfo will modify the same object. .Pp diff --git a/lib/libc/gen/getpwent.3 b/lib/libc/gen/getpwent.3 index 57803da..d925055 100644 --- a/lib/libc/gen/getpwent.3 +++ b/lib/libc/gen/getpwent.3 @@ -214,6 +214,7 @@ The functions and .Fn getpwuid , leave their results in an internal static object and return -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to the same function will modify the same object. diff --git a/lib/libc/gen/getusershell.3 b/lib/libc/gen/getusershell.3 index 62eaafa..8541762 100644 --- a/lib/libc/gen/getusershell.3 +++ b/lib/libc/gen/getusershell.3 @@ -94,6 +94,7 @@ function appeared in The .Fn getusershell function leaves its result in an internal static object and returns -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to .Fn getusershell will modify the same object. diff --git a/lib/libc/gen/lockf.3 b/lib/libc/gen/lockf.3 index 1cfc40a..fe877bd 100644 --- a/lib/libc/gen/lockf.3 +++ b/lib/libc/gen/lockf.3 @@ -96,7 +96,8 @@ detects if a lock by another process is present on the specified section. The .Fa size argument is the number of contiguous bytes to be locked or -unlocked. The section to be locked or unlocked starts at the current +unlocked. +The section to be locked or unlocked starts at the current offset in the file and extends forward for a positive size or backward for a negative size (the preceding bytes up to but not including the current offset). However, it is not permitted to lock a section that @@ -112,9 +113,11 @@ The sections locked with or .Dv F_TLOCK may, in whole or in part, contain or be contained by a previously -locked section for the same process. When this occurs, or if adjacent +locked section for the same process. +When this occurs, or if adjacent locked sections would occur, the sections are combined into a single -locked section. If the request would cause the number of locks to +locked section. +If the request would cause the number of locks to exceed a system-imposed limit, the request will fail. .Pp .Dv F_LOCK @@ -133,15 +136,18 @@ file descriptor for the file. .Pp .Dv F_ULOCK requests release (wholly or in part) one or more locked sections -controlled by the process. Locked sections will be unlocked starting +controlled by the process. +Locked sections will be unlocked starting at the current file offset through .Fa size bytes or to the end of file if size is 0. When all of a locked section is not released (that is, when the beginning or end of the area to be unlocked falls within a locked section), the remaining portions of -that section are still locked by the process. Releasing the center +that section are still locked by the process. +Releasing the center portion of a locked section will cause the remaining locked beginning -and end portions to become two separate locked sections. If the +and end portions to become two separate locked sections. +If the request would cause the number of locks in the system to exceed a system-imposed limit, the request will fail. .Pp diff --git a/lib/libc/gen/msgctl.3 b/lib/libc/gen/msgctl.3 index 326e8a5..e95284c 100644 --- a/lib/libc/gen/msgctl.3 +++ b/lib/libc/gen/msgctl.3 @@ -131,7 +131,8 @@ or in the data structure associated with the message queue. The value of .Va msg_qbytes -can only be increased by the super-user. Values for +can only be increased by the super-user. +Values for .Va msg_qbytes that exceed the system limit (MSGMNB from .Aq Pa sys/msg.h ) @@ -140,7 +141,8 @@ are silently truncated to that limit. .It Dv IPC_RMID Remove the message queue specified by .Fa msqid -and destroy the data associated with it. Only the super-user or a process +and destroy the data associated with it. +Only the super-user or a process with an effective uid equal to the .Va msg_perm.cuid or @@ -167,7 +169,8 @@ effective gid can match either or .Va msg_perm.gid . .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, -1 is +Upon successful completion, a value of 0 is returned. +Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. diff --git a/lib/libc/gen/msgrcv.3 b/lib/libc/gen/msgrcv.3 index e4aa45d..846ac6f 100644 --- a/lib/libc/gen/msgrcv.3 +++ b/lib/libc/gen/msgrcv.3 @@ -83,7 +83,8 @@ will be received. .El .Pp .Fa msgsz -specifies the maximum length of the requested message. If the received +specifies the maximum length of the requested message. +If the received message has a length greater than .Fa msgsz it will be silently truncated if the @@ -100,7 +101,8 @@ depends on whether the .Dv IPC_NOWAIT flag is set in .Fa msgflg -or not. If +or not. +If .Dv IPC_NOWAIT is set, .Fn msgrcv diff --git a/lib/libc/gen/msgsnd.3 b/lib/libc/gen/msgsnd.3 index d6812e2..2ede183 100644 --- a/lib/libc/gen/msgsnd.3 +++ b/lib/libc/gen/msgsnd.3 @@ -49,7 +49,8 @@ The function sends a message to the message queue specified in .Fa msqid . .Fa msgp -points to a structure containing the message. This structure should +points to a structure containing the message. +This structure should consist of the following members: .Bd -literal long mtype; /* message type */ @@ -78,7 +79,8 @@ If .Fa msgflg has .Dv IPC_NOWAIT -mask set in it, the call will return immediately. If +mask set in it, the call will return immediately. +If .Fa msgflg does not have .Dv IPC_NOWAIT @@ -93,7 +95,8 @@ The message queue is removed, in which case -1 will be returned, and is set to .Er EINVAL . .It -The caller catches a signal. The call returns with +The caller catches a signal. +The call returns with .Va errno set to .Er EINTR . @@ -116,7 +119,8 @@ is set to the pid of the calling process. is set to the current time. .El .Sh RETURN VALUES -Upon successful completion, 0 is returned. Otherwise, -1 is returned and +Upon successful completion, 0 is returned. +Otherwise, -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/gen/rand48.3 b/lib/libc/gen/rand48.3 index 86e7a2f..ac7e33e 100644 --- a/lib/libc/gen/rand48.3 +++ b/lib/libc/gen/rand48.3 @@ -50,7 +50,8 @@ The .Fn rand48 family of functions generates pseudo-random numbers using a linear -congruential algorithm working on integers 48 bits in size. The +congruential algorithm working on integers 48 bits in size. +The particular formula employed is r(n+1) = (a * r(n) + c) mod m where the default values are @@ -64,7 +65,8 @@ computational step is to perform a single iteration of the algorithm. .Fn drand48 and .Fn erand48 -return values of type double. The full 48 bits of r(n+1) are +return values of type double. +The full 48 bits of r(n+1) are loaded into the mantissa of the returned value, with the exponent set such that the values produced lie in the interval [0.0, 1.0). .Pp @@ -119,7 +121,8 @@ also initializes the internal buffer r(n) of and .Fn mrand48 , but here all 48 bits of the seed can be specified in an array of 3 shorts, -where the zeroth member specifies the lowest bits. Again, +where the zeroth member specifies the lowest bits. +Again, the constant multiplicand and addend of the algorithm are reset to the default values given above. .Fn seed48 diff --git a/lib/libc/gen/signal.3 b/lib/libc/gen/signal.3 index 3da89d8..589331f 100644 --- a/lib/libc/gen/signal.3 +++ b/lib/libc/gen/signal.3 @@ -147,7 +147,8 @@ To ignore the signal should be .Dv SIG_IGN . This will cause subsequent instances of the signal to be ignored -and pending instances to be discarded. If +and pending instances to be discarded. +If .Dv SIG_IGN is not used, further occurrences of the signal are diff --git a/lib/libc/gen/ttyname.3 b/lib/libc/gen/ttyname.3 index 719b9fb..5e7bb4e 100644 --- a/lib/libc/gen/ttyname.3 +++ b/lib/libc/gen/ttyname.3 @@ -50,7 +50,8 @@ .Fn ttyslot void .Sh DESCRIPTION These functions operate on the system file descriptors for terminal -type devices. These descriptors are not related to the standard +type devices. +These descriptors are not related to the standard .Tn I/O .Dv FILE typedef, but refer to the special device files found in @@ -122,6 +123,7 @@ appeared in The .Fn ttyname function leaves its result in an internal static object and returns -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to .Fn ttyname will modify the same object. diff --git a/lib/libc/net/ethers.3 b/lib/libc/net/ethers.3 index 41376c9..72b7488 100644 --- a/lib/libc/net/ethers.3 +++ b/lib/libc/net/ethers.3 @@ -86,7 +86,8 @@ format and sets .Ar e to the ethernet address specified in the string and .Ar h -to the hostname. This function is used to parse lines from +to the hostname. +This function is used to parse lines from .Pa /etc/ethers into their component parts. .Pp @@ -96,7 +97,8 @@ function converts an .Tn ASCII representation of an ethernet address into an .Ar ether_addr -structure. Likewise, +structure. +Likewise, .Fn ether_ntoa converts an ethernet address specified as an .Ar ether_addr @@ -132,12 +134,14 @@ On success, .Fn ether_ntoa returns a pointer to a string containing an .Tn ASCII -representation of an ethernet address. If it is unable to convert +representation of an ethernet address. +If it is unable to convert the supplied .Ar ether_addr structure, it returns a .Dv NULL -pointer. Likewise, +pointer. +Likewise, .Fn ether_aton returns a pointer to an .Ar ether_addr diff --git a/lib/libc/net/getnetent.3 b/lib/libc/net/getnetent.3 index 58bb7a2..1bf3664 100644 --- a/lib/libc/net/getnetent.3 +++ b/lib/libc/net/getnetent.3 @@ -120,7 +120,8 @@ net name or net address and type is found, or until .Dv EOF -is encountered. The +is encountered. +The .Fa type must be .Dv AF_INET . diff --git a/lib/libc/nls/catopen.3 b/lib/libc/nls/catopen.3 index 3130616..53b4ee8 100644 --- a/lib/libc/nls/catopen.3 +++ b/lib/libc/nls/catopen.3 @@ -67,7 +67,8 @@ locale category used to open the message catalog; using .Dv NL_CAT_LOCALE conforms to the .St -xpg4 -standard. You can specify 0 for compatibility with +standard. +You can specify 0 for compatibility with .St -xpg3 ; when .Fa oflag diff --git a/lib/libc/rpc/des_crypt.3 b/lib/libc/rpc/des_crypt.3 index 00ddda9..e8651fe 100644 --- a/lib/libc/rpc/des_crypt.3 +++ b/lib/libc/rpc/des_crypt.3 @@ -54,7 +54,8 @@ mode, which chains together successive blocks. .SM CBC mode protects against insertions, deletions and -substitutions of blocks. Also, regularities in the clear text will +substitutions of blocks. +Also, regularities in the clear text will not appear in the cipher text. .LP Here is how to use these routines. The first parameter, @@ -66,7 +67,8 @@ is in the low bit of each byte, use .IR des_setparity . The second parameter, .IR data , -contains the data to be encrypted or decrypted. The +contains the data to be encrypted or decrypted. +The third parameter, .IR datalen , is the length in bytes of diff --git a/lib/libc/rpc/publickey.3 b/lib/libc/rpc/publickey.3 index 7f32e49..79608d6 100644 --- a/lib/libc/rpc/publickey.3 +++ b/lib/libc/rpc/publickey.3 @@ -31,7 +31,8 @@ which is used to decrypt the encrypted secret key stored in the database. Both routines return 1 if they are successful in finding the key, 0 otherwise. The keys are returned as .SM NULL\s0-terminated, -hexadecimal strings. If the password supplied to +hexadecimal strings. +If the password supplied to .B getsecretkey(\|) fails to decrypt the secret key, the routine will return 1 but the .I secretkey diff --git a/lib/libc/rpc/publickey.5 b/lib/libc/rpc/publickey.5 index 806028f..b289933 100644 --- a/lib/libc/rpc/publickey.5 +++ b/lib/libc/rpc/publickey.5 @@ -9,7 +9,8 @@ publickey \- public key database .LP .B /etc/publickey is the public key database used for secure -networking. Each entry in +networking. +Each entry in the database consists of a network user name (which may either refer to a user or a hostname), followed by the user's diff --git a/lib/libc/rpc/rpc.3 b/lib/libc/rpc/rpc.3 index 92b0d98..89d8942 100644 --- a/lib/libc/rpc/rpc.3 +++ b/lib/libc/rpc/rpc.3 @@ -39,7 +39,8 @@ auth_destroy(auth) A macro that destroys the authentication information associated with .IR auth . Destruction usually involves deallocation of private data -structures. The use of +structures. +The use of .I auth is undefined after calling .BR auth_destroy(\|) . @@ -57,7 +58,8 @@ authnone_create(\|) Create and returns an .SM RPC authentication handle that passes nonusable authentication -information with each remote procedure call. This is the +information with each remote procedure call. +This is the default authentication used by .SM RPC. .if t .ne 10 @@ -169,7 +171,8 @@ resultproc_t eachresult; Like .BR callrpc(\|) , except the call message is broadcast to all locally -connected broadcast nets. Each time it receives a +connected broadcast nets. +Each time it receives a response, this routine calls .BR eachresult(\|) , whose form is: @@ -201,7 +204,8 @@ waits for more replies; otherwise it returns with appropriate status. .IP Warning: broadcast sockets are limited in size to the -maximum transfer unit of the data link. For ethernet, +maximum transfer unit of the data link. +For ethernet, this value is 1500 bytes. .br .if t .ne 13 @@ -252,7 +256,8 @@ clnt_destroy(clnt) .IP A macro that destroys the client's .SM RPC -handle. Destruction usually involves deallocation +handle. +Destruction usually involves deallocation of private data structures, including .I clnt itself. Use of @@ -282,7 +287,8 @@ Generic client creation routine. identifies the name of the remote host where the server is located. .I proto -indicates which kind of transport protocol to use. The +indicates which kind of transport protocol to use. +The currently supported values for this field are \(lqudp\(rq and \(lqtcp\(rq. Default timeouts are set, but can be modified using @@ -315,7 +321,8 @@ about a client object. .I req indicates the type of operation, and .I info -is a pointer to the information. For both +is a pointer to the information. +For both .SM UDP and .SM TCP\s0, @@ -573,7 +580,8 @@ This allows simulation of and acquisition of .SM RPC overheads, such as round trip times, without any -kernel interference. This routine returns +kernel interference. +This routine returns .SM NULL if it fails. .br @@ -599,7 +607,8 @@ version .IR versnum ; the client uses .SM TCP/IP -as a transport. The remote program is located at Internet +as a transport. +The remote program is located at Internet address .IR *addr . If @@ -651,7 +660,8 @@ version .IR versnum ; the client uses .SM UDP/IP -as a transport. The remote program is located at Internet +as a transport. +The remote program is located at Internet address .IR addr . If @@ -705,7 +715,8 @@ on .IR versnum ; the client uses .SM UDP/IP -as a transport. The remote program is located at Internet +as a transport. +The remote program is located at Internet address .IR addr . If @@ -851,7 +862,8 @@ The parameter .I *portp will be modified to the program's port number if the procedure -succeeds. The definitions of other parameters are discussed +succeeds. +The definitions of other parameters are discussed in .B callrpc(\|) and @@ -880,7 +892,8 @@ and .I port on the machine's .B portmap -service. The value of +service. +The value of .I protocol is most likely .B @@ -909,7 +922,8 @@ and .B ports on the machine's .B portmap -service. This routine returns one if it succeeds, zero +service. +This routine returns one if it succeeds, zero otherwise. .br .if t .ne 15 @@ -1004,7 +1018,8 @@ service side's read file descriptor bit mask; it is suitable as a template parameter to the .B select -system call. This is only of interest +system call. +This is only of interest if a service implementor does not call .BR svc_run(\|) , but rather does his own asynchronous event processing. @@ -1032,7 +1047,8 @@ int svc_fds; .IP Similar to .BR svc_fedset(\|) , -but limited to 32 descriptors. This +but limited to 32 descriptors. +This interface is obsoleted by .BR svc_fdset(\|) . .br @@ -1143,7 +1159,8 @@ int rdfds; .IP Similar to .BR svc_getreqset(\|) , -but limited to 32 descriptors. This interface is obsoleted by +but limited to 32 descriptors. +This interface is obsoleted by .BR svc_getreqset(\|) . .br .if t .ne 17 @@ -1212,12 +1229,14 @@ svc_run(\|) .fi .ft R .IP -This routine never returns. It waits for +This routine never returns. +It waits for .SM RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq(\|) -when one arrives. This procedure is usually waiting for a +when one arrives. +This procedure is usually waiting for a .B select(\|) system call to return. .br @@ -1291,7 +1310,8 @@ svcerr_decode(xprt) .ft R .IP Called by a service dispatch routine that cannot successfully -decode its parameters. See also +decode its parameters. +See also .BR svc_getargs(\|) . .br .if t .ne 7 @@ -1321,7 +1341,8 @@ svcerr_noprog(xprt) .IP Called when the desired program is not registered with the .SM RPC -package. Service implementors usually do not need this routine. +package. +Service implementors usually do not need this routine. .br .if t .ne 7 .LP @@ -1337,7 +1358,8 @@ svcerr_progvers(xprt) Called when the desired version of a program is not registered with the .SM RPC -package. Service implementors usually do not need this routine. +package. +Service implementors usually do not need this routine. .br .if t .ne 7 .LP @@ -1434,7 +1456,8 @@ is the transport's socket descriptor, and is the transport's port number. This routine returns .SM NULL -if it fails. Since +if it fails. +Since .SM TCP\s0-based .SM RPC uses buffered @@ -1455,7 +1478,8 @@ u_int recvsize; .fi .ft R .IP -Create a service on top of any open descriptor. Typically, +Create a service on top of any open descriptor. +Typically, this descriptor is a connected socket for a stream protocol such as @@ -1488,7 +1512,8 @@ which may be in which case a new socket is created. If the socket is not bound to a local .SM UDP -port, then this routine binds it to an arbitrary port. Upon +port, then this routine binds it to an arbitrary port. +Upon completion, \fB\%xprt\->xp_sock\fR is the transport's socket descriptor, and @@ -1516,7 +1541,8 @@ struct accepted_reply *ar; .IP Used for encoding .SM RPC -reply messages. This routine is useful for users who +reply messages. +This routine is useful for users who wish to generate \s-1RPC\s0-style messages without using the @@ -1536,7 +1562,8 @@ struct authunix_parms *aupp; .IP Used for describing .SM UNIX -credentials. This routine is useful for users +credentials. +This routine is useful for users who wish to generate these credentials without using the .SM RPC authentication package. diff --git a/lib/libc/rpc/rpc_secure.3 b/lib/libc/rpc/rpc_secure.3 index 23f1a7e..f3e57cc 100644 --- a/lib/libc/rpc/rpc_secure.3 +++ b/lib/libc/rpc/rpc_secure.3 @@ -69,7 +69,8 @@ The first parameter .Fa name is the network name, or .Fa netname , -of the owner of the server process. This field usually +of the owner of the server process. +This field usually represents a .Fa hostname derived from the utility routine @@ -80,21 +81,25 @@ The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of -resynchronizations because of clock drift. The third +resynchronizations because of clock drift. +The third parameter .Fa addr is optional. If it is .Dv NULL , then the authentication system will assume that the local clock is always in sync with the server's -clock, and will not attempt resynchronizations. If an address +clock, and will not attempt resynchronizations. +If an address is supplied, however, then the system will use the address for consulting the remote time service whenever resynchronization -is required. This parameter is usually the +is required. +This parameter is usually the address of the .Tn RPC -server itself. The final parameter +server itself. +The final parameter .Fa ckey is also optional. If it is .Dv NULL , @@ -113,7 +118,8 @@ is used on the server side for converting a credential, which is operating system independent, into a .Ux -credential. This routine differs from utility routine +credential. +This routine differs from utility routine .Fn netname2user in that .Fn authdes_getucred @@ -133,11 +139,13 @@ if it fails. .Pp .Fn Host2netname converts from a domain-specific hostname to an -operating-system independent netname. Returns +operating-system independent netname. +Returns .Dv TRUE if it succeeds and .Dv FALSE -if it fails. Inverse of +if it fails. +Inverse of .Fn netname2host . .Pp .Fn Key_decryptsession @@ -168,7 +176,8 @@ is the inverse of .Fn key_encryptsession . .Pp .Fn Key_encryptsession -is a keyserver interface routine. It +is a keyserver interface routine. +It takes a server netname and a des key, and encrypts it using the public key of the the server and the secret key associated with the effective uid of the calling process. It @@ -176,7 +185,8 @@ is the inverse of .Fn key_decryptsession . .Pp .Fn Key_gendes -is a keyserver interface routine. It +is a keyserver interface routine. +It is used to ask the keyserver for a secure conversation key. Choosing one .Qq random @@ -186,14 +196,16 @@ the common ways of choosing random numbers, such as using the current time, are very easy to guess. .Pp .Fn Key_setsecret -is a keyserver interface routine. It is used to set the key for +is a keyserver interface routine. +It is used to set the key for the effective .Fa uid of the calling process. .Pp .Fn Netname2host converts from an operating-system independent netname to a -domain-specific hostname. Returns +domain-specific hostname. +Returns .Dv TRUE if it succeeds and .Dv FALSE @@ -207,16 +219,19 @@ Returns .Dv TRUE if it succeeds and .Dv FALSE -if it fails. Inverse of +if it fails. +Inverse of .Fn user2netname . .Pp .Fn User2netname converts from a domain-specific username to an operating-system -independent netname. Returns +independent netname. +Returns .Dv TRUE if it succeeds and .Dv FALSE -if it fails. Inverse of +if it fails. +Inverse of .Fn netname2user . .Sh SEE ALSO .Xr rpc 3 , diff --git a/lib/libc/rpc/rtime.3 b/lib/libc/rpc/rtime.3 index de19866..6847e15 100644 --- a/lib/libc/rpc/rtime.3 +++ b/lib/libc/rpc/rtime.3 @@ -25,7 +25,8 @@ struct pointed to by .IR timep . Normally, the .SM UDP -protocol is used when consulting the Time Server. The +protocol is used when consulting the Time Server. +The .I timeout parameter specifies how long the routine should wait before giving @@ -37,7 +38,8 @@ however, the routine will instead use .SM TCP and block until a reply is received from the time server. .LP -The routine returns 0 if it is successful. Otherwise, +The routine returns 0 if it is successful. +Otherwise, it returns \-1 and .B errno is set to reflect the cause of the error. diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index 6e1b0c8..f18f658 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -544,7 +544,8 @@ No argument is converted. .It Cm % A .Ql % -is written. No argument is converted. The complete conversion specification +is written. No argument is converted. +The complete conversion specification is .Ql %% . .El diff --git a/lib/libc/stdio/putc.3 b/lib/libc/stdio/putc.3 index d251174..6de85c1 100644 --- a/lib/libc/stdio/putc.3 +++ b/lib/libc/stdio/putc.3 @@ -69,7 +69,8 @@ The .Fn putc macro acts essentially identically to .Fn fputc , -but is a macro that expands in-line. It may evaluate +but is a macro that expands in-line. +It may evaluate .Fa stream more than once, so arguments given to .Fn putc diff --git a/lib/libc/stdio/scanf.3 b/lib/libc/stdio/scanf.3 index 1144f5a..f6be018 100644 --- a/lib/libc/stdio/scanf.3 +++ b/lib/libc/stdio/scanf.3 @@ -397,7 +397,8 @@ conversion. The value .Dv EOF is returned if an input failure occurs before any conversion such as an -end-of-file occurs. If an error or end-of-file occurs after conversion +end-of-file occurs. +If an error or end-of-file occurs after conversion has begun, the number of conversions which were successfully completed is returned. .Sh SEE ALSO diff --git a/lib/libc/stdio/stdio.3 b/lib/libc/stdio/stdio.3 index 9648414..345a083 100644 --- a/lib/libc/stdio/stdio.3 +++ b/lib/libc/stdio/stdio.3 @@ -52,22 +52,26 @@ interface. Input and output is mapped into logical data streams and the physical .Tn I/O -characteristics are concealed. The functions and macros are listed +characteristics are concealed. +The functions and macros are listed below; more information is available from the individual man pages. .Pp A stream is associated with an external file (which may be a physical device) by .Em opening -a file, which may involve creating a new file. Creating an +a file, which may involve creating a new file. +Creating an existing file causes its former contents to be discarded. If a file can support positioning requests (such as a disk file, as opposed to a terminal) then a .Em file position indicator associated with the stream is positioned at the start of the file (byte -zero), unless the file is opened with append mode. If append mode +zero), unless the file is opened with append mode. +If append mode is used, the position indicator will be placed at the end-of-file. The position indicator is maintained by subsequent reads, writes -and positioning requests. All input occurs as if the characters +and positioning requests. +All input occurs as if the characters were read by successive calls to the .Xr fgetc 3 function; all output takes place as if all characters were diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index ae5c6a1..c8796b8 100644 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -322,7 +322,8 @@ and the .Fn \&_r variants of the other functions, these functions leaves their result in an internal static object and return -a pointer to that object. Subsequent calls to these +a pointer to that object. +Subsequent calls to these function will modify the same object. .Pp The C Standard provides no mechanism for a program to modify its current diff --git a/lib/libc/string/strxfrm.3 b/lib/libc/string/strxfrm.3 index 81b07f6..4c7e2fa 100644 --- a/lib/libc/string/strxfrm.3 +++ b/lib/libc/string/strxfrm.3 @@ -79,7 +79,8 @@ two original strings with Upon successful completion, .Fn strxfrm returns the length of the transformed string not including -the terminating null character. If this value is +the terminating null character. +If this value is .Fa n or more, the contents of .Fa dst diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 index 384823e..e716261 100644 --- a/lib/libc/sys/accept.2 +++ b/lib/libc/sys/accept.2 @@ -150,7 +150,8 @@ for read and write, then calls .Fn _thread_sys_accept . If the call to .Fn _thread_sys_accept -would block, a context switch is performed. Before returning, +would block, a context switch is performed. +Before returning, .Fn accept unlocks .Va s . diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 index 87e171f..87e0098 100644 --- a/lib/libc/sys/chmod.2 +++ b/lib/libc/sys/chmod.2 @@ -116,7 +116,8 @@ If mode .Dv ISVTX (the `sticky bit') is set on a directory, an unprivileged user may not delete or rename -files of other users in that directory. The sticky bit may be +files of other users in that directory. +The sticky bit may be set by any user on a directory which the user owns or has appropriate permissions. For more details of the properties of the sticky bit, see @@ -129,15 +130,19 @@ created within this directory are set to be the same as the owner of that directory. If this function is enabled, new directories will inherit the bit from their parents. Execute bits are removed from -the file, and it will not be given to root. This behavior does not change the +the file, and it will not be given to root. +This behavior does not change the requirements for the user to be allowed to write the file, but only the eventual -owner after it has been created. Group inheritance is not effected. +owner after it has been created. +Group inheritance is not effected. .Pp This feature is designed for use on fileservers serving PC users via -ftp, SAMBA, or netatalk. It provides security holes for shell users and as +ftp, SAMBA, or netatalk. +It provides security holes for shell users and as such should not be used on shell machines, especially on home directories. This option requires the SUIDDIR -option in the kernel to work. Only UFS filesystems support this option. +option in the kernel to work. +Only UFS filesystems support this option. For more details of the suiddir mount option, see .Xr mount 8 . .Pp diff --git a/lib/libc/sys/connect.2 b/lib/libc/sys/connect.2 index aef52f1..8885e72 100644 --- a/lib/libc/sys/connect.2 +++ b/lib/libc/sys/connect.2 @@ -89,7 +89,8 @@ for read and write, then calls .Fn _thread_sys_connect . If the call to .Fn _thread_sys_connect -would block, a context switch is performed. Before returning, +would block, a context switch is performed. +Before returning, .Fn connect unlocks .Va s . diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 index 2adc7c9..3e35f42 100644 --- a/lib/libc/sys/execve.2 +++ b/lib/libc/sys/execve.2 @@ -117,7 +117,8 @@ Descriptors that remain open are unaffected by .Pp Signals set to be ignored in the calling process are set to be ignored in the -new process. Signals which are set to be caught in the calling process image +new process. +Signals which are set to be caught in the calling process image are set to default action in the new process image. Blocked signals remain blocked regardless of changes to the signal action. The signal stack is reset to be undefined (see diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 index 97236fe..ee38c33 100644 --- a/lib/libc/sys/fcntl.2 +++ b/lib/libc/sys/fcntl.2 @@ -263,7 +263,8 @@ but may not start or extend before the beginning of the file. A lock is set to extend to the largest possible value of the file offset for that file if .Fa l_len -is set to zero. If +is set to zero. +If .Fa l_whence and .Fa l_start diff --git a/lib/libc/sys/fhopen.2 b/lib/libc/sys/fhopen.2 index 6265771..d82e26f 100644 --- a/lib/libc/sys/fhopen.2 +++ b/lib/libc/sys/fhopen.2 @@ -61,13 +61,15 @@ opens the file referenced by .Fa fhp for reading and/or writing as specified by the argument .Fa flags -and returns the file descriptor to the calling process. The +and returns the file descriptor to the calling process. +The .Fa flags are specified by .Em or Ns 'ing together the flags used for the .Xr open 2 -call. All said flags are valid except for +call. +All said flags are valid except for .Dv O_CREAT . .Pp .Fn fhstat diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 index fd978ca..b43b9c8 100644 --- a/lib/libc/sys/intro.2 +++ b/lib/libc/sys/intro.2 @@ -49,7 +49,8 @@ their error returns, and other common definitions and concepts. .\"<more later...> .Sh RETURN VALUES Nearly all of the system calls provide an error number referenced via -the external identifier errno. This identifier is defined in +the external identifier errno. +This identifier is defined in .Aq Pa sys/errno.h as .Pp @@ -59,7 +60,8 @@ as The .Va __error() function returns a pointer to a field in the thread specific structure for -threads other than the initial thread. For the initial thread and +threads other than the initial thread. +For the initial thread and non-threaded processes, .Va __error() returns a pointer to a global @@ -104,7 +106,8 @@ An asynchronous signal (such as or .Dv SIGQUIT ) was caught by the process during the execution of an interruptible -function. If the signal handler performs a normal return, the +function. +If the signal handler performs a normal return, the interrupted function call will seem to have returned the error condition. .It Er 5 EIO Em "Input/output error" . Some physical input or output error occurred. @@ -264,7 +267,8 @@ A message sent on a socket was larger than the internal message buffer or some other network limit. .It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" . A protocol was specified that does not support the semantics of the -socket type requested. For example, you cannot use the +socket type requested. +For example, you cannot use the .Tn ARPA Internet .Tn UDP diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 index aaccac7..83ed0cd 100644 --- a/lib/libc/sys/lseek.2 +++ b/lib/libc/sys/lseek.2 @@ -92,7 +92,8 @@ bytes. The .Fn lseek function allows the file offset to be set beyond the end -of the existing end-of-file of the file. If data is later written +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 bytes of zeros (until data is actually written into the gap). .Pp diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 index 185b7b8..cffccf8 100644 --- a/lib/libc/sys/mmap.2 +++ b/lib/libc/sys/mmap.2 @@ -133,9 +133,12 @@ Modifications are private. Modifications are shared. .It Dv MAP_STACK This option is only available if your system has been compiled with -VM_STACK defined when compiling the kernel. This is the default for -i386 only. Consider adding -DVM_STACK to COPTFLAGS in your /etc/make.conf -to enable this option for other architechures. MAP_STACK implies +VM_STACK defined when compiling the kernel. +This is the default for +i386 only. +Consider adding -DVM_STACK to COPTFLAGS in your /etc/make.conf +to enable this option for other architechures. +MAP_STACK implies MAP_ANON, and .Fa offset of 0. @@ -274,16 +277,19 @@ is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but it is possible to map a window of size (filesize % 2GB) for file sizes of slightly less than 2G, 4GB, 6GB and 8GB. .Pp -The limit is imposed for a variety of reasons. Most of them have to do +The limit is imposed for a variety of reasons. +Most of them have to do with .Tn FreeBSD not wanting to use 64 bit offsets in the VM system due to -the extreme performance penalty. So +the extreme performance penalty. +So .Tn FreeBSD uses 32bit page indexes and this gives .Tn FreeBSD -a maximum of 8TB filesizes. It's actually bugs in +a maximum of 8TB filesizes. +It's actually bugs in the filesystem code that causes the limit to be further restricted to 1TB (loss of precision when doing blockno calculations). .Pp diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2 index 24e33e8..d0b5345 100644 --- a/lib/libc/sys/msync.2 +++ b/lib/libc/sys/msync.2 @@ -71,7 +71,8 @@ MS_INVALIDATE Invalidate all cached data .Ed .Sh RETURN VALUES If any errors occur, -1 is returned and errno is set to indicate the -error. Otherwise, a 0 value is returned. +error. +Otherwise, a 0 value is returned. .Sh ERRORS .Fn msync will fail if: @@ -84,7 +85,8 @@ is not a multiple of the hardware page size. is too large or negative. .It Bq Er EINVAL .Fa flags -was both MS_ASYNC and MS_INVALIDATE. Only one of these flags is allowed. +was both MS_ASYNC and MS_INVALIDATE. +Only one of these flags is allowed. .It Bq Er EIO An I/O error occurred while writing to the file system. .Sh SEE ALSO diff --git a/lib/libc/sys/pipe.2 b/lib/libc/sys/pipe.2 index 1151505..98f53aa 100644 --- a/lib/libc/sys/pipe.2 +++ b/lib/libc/sys/pipe.2 @@ -86,7 +86,8 @@ portable to older systems, so it is recommended to use the convention for using the endpoints in the traditional manner when using a pipe in one direction. .Sh RETURN VALUES -On successful creation of the pipe, zero is returned. Otherwise, +On successful creation of the pipe, zero is returned. +Otherwise, a value of -1 is returned and the variable .Va errno set to indicate the diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 index b8c451d..16fe7284 100644 --- a/lib/libc/sys/read.2 +++ b/lib/libc/sys/read.2 @@ -135,7 +135,8 @@ for read, then calls .Fn _thread_sys_read . If the call to .Fn _thread_sys_read -would block, a context switch is performed. Before returning, +would block, a context switch is performed. +Before returning, .Fn read unlocks .Va d . @@ -158,13 +159,15 @@ for read, then calls .Fn _thread_sys_readv . If the call to .Fn _thread_sys_readv -would block, a context switch is performed. Before returning, +would block, a context switch is performed. +Before returning, .Fn readv unlocks .Va d . .Sh RETURN VALUES If successful, the -number of bytes actually read is returned. Upon reading end-of-file, +number of bytes actually read is returned. +Upon reading end-of-file, zero is returned. Otherwise, a -1 is returned and the global variable .Va errno diff --git a/lib/libc/sys/reboot.2 b/lib/libc/sys/reboot.2 index 00d750c..85a6717 100644 --- a/lib/libc/sys/reboot.2 +++ b/lib/libc/sys/reboot.2 @@ -84,7 +84,8 @@ the processor is simply halted; no reboot takes place. This option should be used with caution. .It Dv RB_POWEROFF After halting, the shutdown code will do what it can to turn -of the power. This requires hardware support. +of the power. +This requires hardware support. .It Dv RB_INITNAME An option allowing the specification of an init program (see .Xr init 8 ) diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 index c5825cb..b9b5aa7 100644 --- a/lib/libc/sys/rfork.2 +++ b/lib/libc/sys/rfork.2 @@ -37,7 +37,8 @@ If set a new process is created; otherwise changes affect the current process. The current implementation requires this flag to always be set. .It RFNOWAIT -If set, the child process will be dissociated from the parent. Upon +If set, the child process will be dissociated from the parent. +Upon exit the child will not leave a status for the parent to collect. See .Xr wait 2 . @@ -53,7 +54,8 @@ Is mutually exclusive with .It RFMEM If set, the kernel will force sharing of the entire address space. The child -will then inherit all the shared segments the parent process owns. Other segment +will then inherit all the shared segments the parent process owns. +Other segment types will be unaffected. Subsequent forks by the parent will then propagate the shared data and bss between children. The stack segment is always split. May be set only with diff --git a/lib/libc/sys/rtprio.2 b/lib/libc/sys/rtprio.2 index 579ed1b..3ee2a91 100644 --- a/lib/libc/sys/rtprio.2 +++ b/lib/libc/sys/rtprio.2 @@ -44,7 +44,8 @@ is used to lookup or change the realtime or idle priority of a process. .Fa function -specifies the operation to be performed. RTP_LOOKUP to lookup the current priority, +specifies the operation to be performed. +RTP_LOOKUP to lookup the current priority, and RTP_SET to set the priority. .Fa pid specifies the process to be used, 0 for the current process. @@ -73,11 +74,14 @@ Realtime and idle priority is inherited through fork() and exec(). A realtime process can only be preempted by a process of equal or higher priority, or by an interrupt; idle priority processes will run only -when no other real/normal priority process is runnable. Higher real/idle priority processes -preempt lower real/idle priority processes. Processes of equal real/idle priority are run round-robin. +when no other real/normal priority process is runnable. +Higher real/idle priority processes +preempt lower real/idle priority processes. +Processes of equal real/idle priority are run round-robin. .Sh RETURN VALUES .Fn rtprio -will return 0 for success and -1 for all errors. The global variable +will return 0 for success and -1 for all errors. +The global variable .Va errno will be set to indicate the error. .Sh ERRORS @@ -89,7 +93,8 @@ The specified .Fa prio was out of range. .It Bq Er EPERM -The calling process is not allowed to set the realtime priority. Only +The calling process is not allowed to set the realtime priority. +Only root is allowed to change the realtime priority of any process, and non-root may only change the idle priority of the current process. .It Bq Er ESRCH diff --git a/lib/libc/sys/sendfile.2 b/lib/libc/sys/sendfile.2 index 87b9bac..254f1630 100644 --- a/lib/libc/sys/sendfile.2 +++ b/lib/libc/sys/sendfile.2 @@ -46,7 +46,8 @@ out a stream socket specified by descriptor .Pp The .Fa offset -argument specifies where to begin in the file. The +argument specifies where to begin in the file. +The .Fa nbytes argument specifies how many bytes of the file should be sent, with 0 having the special meaning of send until the end of file has been reached. @@ -67,9 +68,11 @@ The .Fa headers and .Fa tailers -pointers, if non-NULL, point to arrays of struct iovec structures. See the +pointers, if non-NULL, point to arrays of struct iovec structures. +See the .Fn writev -system call for information on the iovec structure. The number of iovecs in these +system call for information on the iovec structure. +The number of iovecs in these arrays is specified by .Fa hdr_cnt and @@ -85,7 +88,8 @@ argument is currently undefined and should be specified as 0. .Pp When using a socket marked for non-blocking I/O, .Fn sendfile -may send fewer bytes than requested. In this case, the number of bytes successfully +may send fewer bytes than requested. +In this case, the number of bytes successfully written is returned in .Fa *sbytes (if specified), diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 index c3c41f7..efddfc5 100644 --- a/lib/libc/sys/sigaction.2 +++ b/lib/libc/sys/sigaction.2 @@ -320,7 +320,8 @@ or Any attempt to do so will be silently ignored. .Pp The following functions are either reentrant or not interruptible -by signals and are async-signal safe. Therefore applications may +by signals and are async-signal safe. +Therefore applications may invoke them, without restriction, from signal-catching functions: .Pp Base Interfaces: diff --git a/lib/libc/sys/sync.2 b/lib/libc/sys/sync.2 index a989e8d5..68acbb9 100644 --- a/lib/libc/sys/sync.2 +++ b/lib/libc/sys/sync.2 @@ -47,7 +47,8 @@ The .Fn sync function forces a write of dirty (modified) buffers in the block buffer cache out -to disk. The kernel keeps this information in core to reduce +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 .Fn sync diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 index ab5d236..0f4693f 100644 --- a/lib/libc/sys/write.2 +++ b/lib/libc/sys/write.2 @@ -142,7 +142,8 @@ for read and write, then calls .Fn _thread_sys_write . If the call to .Fn _thread_sys_write -would block, a context switch is performed. Before returning, +would block, a context switch is performed. +Before returning, .Fn write unlocks .Va d . @@ -165,7 +166,8 @@ for read and write, then calls .Fn _thread_sys_writev . If the call to .Fn _thread_sys_writev -would block, a context switch is performed. Before returning, +would block, a context switch is performed. +Before returning, .Fn writev unlocks .Va d . diff --git a/lib/libc/xdr/xdr.3 b/lib/libc/xdr/xdr.3 index 979b54e..cbe5892 100644 --- a/lib/libc/xdr/xdr.3 +++ b/lib/libc/xdr/xdr.3 @@ -24,7 +24,8 @@ xdrproc_t elproc; .IP A filter primitive that translates between variable-length arrays -and their corresponding external representations. The +and their corresponding external representations. +The parameter .I arrp is the address of the pointer to the array, while @@ -58,7 +59,8 @@ bool_t *bp; .IP A filter primitive that translates between booleans (C integers) -and their external representations. When encoding data, this +and their external representations. +When encoding data, this filter produces values of either one or zero. This routine returns one if it succeeds, zero otherwise. .br @@ -78,7 +80,8 @@ A filter primitive that translates between counted byte strings and their external representations. The parameter .I sp -is the address of the string pointer. The length of the +is the address of the string pointer. +The length of the string is located at address .IR sizep ; strings cannot be longer than @@ -100,7 +103,8 @@ A filter primitive that translates between C characters and their external representations. This routine returns one if it succeeds, zero otherwise. Note: encoded characters are not packed, and occupy 4 bytes -each. For arrays of characters, it is worthwhile to +each. +For arrays of characters, it is worthwhile to consider .BR xdr_bytes(\|) , .B xdr_opaque(\|) @@ -189,10 +193,13 @@ char *objp; .fi .ft R .IP -Generic freeing routine. The first argument is the +Generic freeing routine. +The first argument is the .SM XDR -routine for the object being freed. The second argument -is a pointer to the object itself. Note: the pointer passed +routine for the object being freed. +The second argument +is a pointer to the object itself. +Note: the pointer passed to this routine is .I not freed, but what it points to @@ -392,7 +399,8 @@ stream object pointed to by The stream's data is written to a buffer of size .IR sendsize ; a value of zero indicates the system should use a suitable -default. The stream's data is read from a buffer of size +default. +The stream's data is read from a buffer of size .IR recvsize ; it too can be set to a suitable default by passing a zero value. @@ -439,7 +447,8 @@ The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow -is non-zero. This routine returns one if it succeeds, zero +is non-zero. +This routine returns one if it succeeds, zero otherwise. .br .if t .ne 8 @@ -511,7 +520,8 @@ This routine returns one if it succeeds, zero otherwise. .IP Warning: this routine does not understand .SM NULL -pointers. Use +pointers. +Use .B xdr_pointer(\|) instead. .br @@ -706,7 +716,8 @@ bool_t (*defaultarm) (\|); /* may equal \s-1NULL\s0 */ .IP A filter primitive that translates between a discriminated C .B union -and its corresponding external representation. It first +and its corresponding external representation. +It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an @@ -717,7 +728,8 @@ is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim(\|) -structures. Each structure contains an ordered pair of +structures. +Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to the associated .IR value , |