diff options
Diffstat (limited to 'usr/src/man/man3c')
32 files changed, 331 insertions, 245 deletions
diff --git a/usr/src/man/man3c/aligned_alloc.3c b/usr/src/man/man3c/aligned_alloc.3c index d3c6f43c32..ccfc200bcf 100644 --- a/usr/src/man/man3c/aligned_alloc.3c +++ b/usr/src/man/man3c/aligned_alloc.3c @@ -40,7 +40,8 @@ Upon successful completion, the .Fn aligned_alloc function returns a pointer to suitably aligned memory at least .Fa size -bytes large. Otherwise, a +bytes large. +Otherwise, a .Sy NULL pointer is returned and .Sy errno @@ -61,7 +62,8 @@ bytes of memory; but the application could try again later. .It Er EINVAL An invalid value for .Fa alignment -was passed in. It is not a power of two multiple of the word size. +was passed in. +It is not a power of two multiple of the word size. .El .Sh INTERFACE STABILITY .Sy STANDARD diff --git a/usr/src/man/man3c/call_once.3c b/usr/src/man/man3c/call_once.3c index 5cc1ba56a9..80cf0860e2 100644 --- a/usr/src/man/man3c/call_once.3c +++ b/usr/src/man/man3c/call_once.3c @@ -29,7 +29,8 @@ The .Fn call_once function is used to ensure that an operation occurs only once, even -across multiple threads. Each instance of a properly initialized +across multiple threads. +Each instance of a properly initialized .Ft once_flag can be pased to the .Ft call_once @@ -38,10 +39,11 @@ specified function, .Fa func . This ensures that the argument .Fa func -is called only once. Note, the argument +is called only once. +Note, the argument .Fa once -is the only thing used as a point of synchronization. If multiple -callers use the same pointer for +is the only thing used as a point of synchronization. +If multiple callers use the same pointer for .Fa once , but use different values for .Fa func , @@ -73,7 +75,8 @@ had not completed successfully. .Sh RETURN VALUES The .Fn call_once -function does not return any values. Upon its completion, it is guaranteed that +function does not return any values. +Upon its completion, it is guaranteed that .Fa func will have been called at most once across the liftime of the .Fa once diff --git a/usr/src/man/man3c/clearenv.3c b/usr/src/man/man3c/clearenv.3c index aa32c3f7a9..16bd532489 100644 --- a/usr/src/man/man3c/clearenv.3c +++ b/usr/src/man/man3c/clearenv.3c @@ -26,10 +26,12 @@ .Sh DESCRIPTION The .Fn clearenv -function clears the contents of the environment. All environment variables in -the calling process are removed as though the function +function clears the contents of the environment. +All environment variables in the calling process are removed as though the +function .Xr unsetenv 3C -had been called on every environment variable. Until subsequent calls to +had been called on every environment variable. +Until subsequent calls to .Xr putenv 3C or .Xr setenv 3C @@ -44,10 +46,11 @@ returns .Sy 0 . Otherwise, it returns a non-zero value and sets .Sy errno -to indicate the error. At this time, no errors are defined for +to indicate the error. +At this time, no errors are defined for .Fn clearenv , -it will always succeed. Portable applications should always check the return -value of +it will always succeed. +Portable applications should always check the return value of .Fn clearenv . .Sh ERRORS No errors are defined. diff --git a/usr/src/man/man3c/cnd.3c b/usr/src/man/man3c/cnd.3c index 7e2ce29d66..e2bd8041cc 100644 --- a/usr/src/man/man3c/cnd.3c +++ b/usr/src/man/man3c/cnd.3c @@ -15,7 +15,7 @@ .Dt CND 3C .Os .Sh NAME -.Nm cnd +.Nm cnd , .Nm cnd_broadcast , .Nm cnd_destroy , .Nm cnd_init , @@ -57,9 +57,10 @@ The .Sy cnd family of functions implement condition variables which allow threads within a process to wait until a condition occurs and be signaled when -it does. These functions behave similar to both the POSIX threads and -illumos threads; however, they have slightly different call signatures -and return values. For more information, see +it does. +These functions behave similar to both the POSIX threads and illumos threads; +however, they have slightly different call signatures and return values. +For more information, see .Xr threads 5 . Importantly, they do not allow for inter-process synchronization. .Ss Creating and Destroy Condition Variables @@ -67,8 +68,9 @@ The function .Fn cnd_init initializes the condition variable referred to by .Fa cnd . -The condition variable is suitable for intra-process use. Initializing -an already initialized condition variable results in undefined behavior. +The condition variable is suitable for intra-process use. +Initializing an already initialized condition variable results in undefined +behavior. .Pp The function .Fn cnd_destroy @@ -77,9 +79,9 @@ to use it, though it may be initialized again. .Ss Condition Waiting The function .Fn cond_wait -can be used to wait on a condition variable. A thread that waits on a -condition variable blocks until another thread signals that the -condition has changed, generally after making the condition that was +can be used to wait on a condition variable. +A thread that waits on a condition variable blocks until another thread signals +that the condition has changed, generally after making the condition that was false, true. .Pp The function @@ -90,10 +92,11 @@ and blocks on the condition variable .Fa cond . When the thread returns, it will once again be holding .Fa mtx -and must check the current state of the condition. There is no -guarantee that another thread has not gotten in and changed the value -before being woken. In addition, a thread blocking on a condition -variable, may be woken spuriously, such as when a signal is received or +and must check the current state of the condition. +There is no guarantee that another thread has not gotten in and changed the +value before being woken. +In addition, a thread blocking on a condition variable, may be woken spuriously, +such as when a signal is received or .Fn fork is called . .Pp @@ -104,8 +107,8 @@ allows a thread to block in a similar fashion to except that when the absolute time specified in seconds since the epoch (based on .Sy CLOCK_REALTIME ) -in UTC, expires, then the thread will be woken up. The timeout is -specified in +in UTC, expires, then the thread will be woken up. +The timeout is specified in .Fa abstime . .Ss Conditional Signaling The @@ -114,7 +117,8 @@ and .Fn cnd_broadcast functions can be used to signal threads waiting on the condition variable .Fa cnd -that they should be woken up and check the variable again. The +that they should be woken up and check the variable again. +The .Fn cnd_signal function will only wake a single thread that is blocked on the condition variable diff --git a/usr/src/man/man3c/endian.3c b/usr/src/man/man3c/endian.3c index 5161af8fbd..719dae8e28 100644 --- a/usr/src/man/man3c/endian.3c +++ b/usr/src/man/man3c/endian.3c @@ -113,10 +113,10 @@ The .Nm family of functions convert 16, 32, and 64-bit values between the host's -native byte order and big- or little-endian. All of the functions in -this family simply return their input when the host's native byte order -is the same as the desired order. For more information on -endianness, see +native byte order and big- or little-endian. +All of the functions in this family simply return their input when the host's +native byte order is the same as the desired order. +For more information on endianness, see .Xr byteorder 5 . .Pp The @@ -169,13 +169,14 @@ are the same as .Fn letoh32 , and .Fn letoh64 -respectively. Historically, different platforms have diverged on the -naming of these functions. To better support extant software, both are -provided. +respectively. +Historically, different platforms have diverged on the naming of these +functions. +To better support extant software, both are provided. .Pp While these functions are common across multiple platforms, they have -not been standardized. Portable applications should instead use the -functions defined in +not been standardized. +Portable applications should instead use the functions defined in .Xr byteorder 3C . .Sh RETURN VALUES The functions always succeed and return a value that has been properly diff --git a/usr/src/man/man3c/eventfd.3c b/usr/src/man/man3c/eventfd.3c index b0c74e1d51..a1b44439df 100644 --- a/usr/src/man/man3c/eventfd.3c +++ b/usr/src/man/man3c/eventfd.3c @@ -29,8 +29,8 @@ The .Fn eventfd function creates an .Xr eventfd 5 -instance that has an associated 64-bit unsigned counter. It returns a file -descriptor that can be operated upon via +instance that has an associated 64-bit unsigned counter. +It returns a file descriptor that can be operated upon via .Xr read 2 , .Xr write 2 and the facilities that notify of file descriptor activity (e.g., @@ -44,8 +44,9 @@ should be called on the file descriptor. The .Fa initval argument specifies the initial value of the 64-bit counter associated with the -instance. (Note that this limits the initial value to be a 32-bit quantity -despite the fact that the underlying counter is 64-bit.) +instance. +(Note that this limits the initial value to be a 32-bit quantity despite the +fact that the underlying counter is 64-bit.) .Pp The \fIflags\fR argument specifies additional parameters for the instance, and can have any of the following values: @@ -61,7 +62,8 @@ description of .Ed .It Sy EFD_NONBLOCK .Bd -filled -compact -Instance will be set to be non-blocking. A +Instance will be set to be non-blocking. +A .Xr read 2 on an .Sy eventfd @@ -76,7 +78,8 @@ in lieu of blocking if the count associated with the instance is zero. Provide counting semaphore semantics whereby a .Xr read 2 will atomically decrement rather than atomically clear the count when it -becomes non-zero. See below for details on +becomes non-zero. +See below for details on .Xr read 2 semantics. .Ed @@ -89,8 +92,8 @@ instance: .It Sy read(2) .Bd -filled -compact Atomically reads and modifies the value of the 64-bit counter associated -with the instance. The precise semantics -of +with the instance. +The precise semantics of .Xr read 2 depend on the disposition of .Sy EFD_SEMAPHORE @@ -110,7 +113,8 @@ will .Em atomically clear the counter if (and when) it is non-zero, copying the former value of the counter to the eight byte buffer passed to the -system call. In either case, +system call. +In either case, .Xr read 2 will block if the counter is zero (or return @@ -127,8 +131,8 @@ will be returned. .It Sy write(2) .Bd -filled -compact Atomically adds the 64-bit value pointed to by the buffer to the 64-bit -counter associated with the instance. If the resulting value would overflow, -the +counter associated with the instance. +If the resulting value would overflow, the .Xr write 2 will block until the value would not overflow (or return @@ -159,8 +163,10 @@ will be set. .El .Sh RETURN VALUES Upon successful completion, a file descriptor associated with the instance -is returned. Otherwise, -.Sy -1 is returned and +is returned. +Otherwise, +.Sy -1 +is returned and .Sy errno is set to indicate the error. .Sh ERRORS diff --git a/usr/src/man/man3c/fcloseall.3c b/usr/src/man/man3c/fcloseall.3c index c1a9f49847..4b47ca92e8 100644 --- a/usr/src/man/man3c/fcloseall.3c +++ b/usr/src/man/man3c/fcloseall.3c @@ -26,11 +26,13 @@ .Sh DESCRIPTION The .Fn fcloseall -function closes all open standard I/O streams. The equivalent of +function closes all open standard I/O streams. +The equivalent of .Xr fflush 3C is called on each stream before closing, thus any buffered or pending input is discarded while any buffered or pending output is written out -to the underlying file. This includes the standard streams, +to the underlying file. +This includes the standard streams, .Vt stdin , .Vt stdout , and diff --git a/usr/src/man/man3c/get_nprocs.3c b/usr/src/man/man3c/get_nprocs.3c index 4d73833b56..9b5df526df 100644 --- a/usr/src/man/man3c/get_nprocs.3c +++ b/usr/src/man/man3c/get_nprocs.3c @@ -42,7 +42,8 @@ respectively. .Sh RETURN VALUES The .Fn get_nprocs -function returns the number of processors that are currently online. The +function returns the number of processors that are currently online. +The .Fn get_nprocs_conf function returns the number of processors that the operating system has configured. diff --git a/usr/src/man/man3c/getprogname.3c b/usr/src/man/man3c/getprogname.3c index 5bc48e6d69..3825dd91d9 100644 --- a/usr/src/man/man3c/getprogname.3c +++ b/usr/src/man/man3c/getprogname.3c @@ -31,27 +31,27 @@ .Sh DESCRIPTION The .Fn getprogname -function is used to obtain the program name. The program name is set at -program start-up, before +function is used to obtain the program name. +The program name is set at program start-up, before .Fn main -is called. Note, other operating systems, do not guarantee that a -program name has been set at start up time and therefore may return a -null pointer if +is called. +Note, other operating systems, do not guarantee that a program name has been set +at start up time and therefore may return a null pointer if .Fn setprogname has not been called. .Lp The .Fn setprogname -function is used to change the program name to another value. The -argument +function is used to change the program name to another value. +The argument .Fa progname must contain a null terminatd character string, whose last component which will become the new program name. .Sh RETURN VALUES The .Fn getprogname -function always returns the current program name. The program name is -always set, it will not return a null pointer. +function always returns the current program name. +The program name is always set, it will not return a null pointer. .Sh INTERFACE STABILITY .Sy Committed .Sh MT-LEVEL diff --git a/usr/src/man/man3c/getwd.3c b/usr/src/man/man3c/getwd.3c index 2e936e1668..9eec7b54f5 100644 --- a/usr/src/man/man3c/getwd.3c +++ b/usr/src/man/man3c/getwd.3c @@ -33,7 +33,8 @@ including the null byte, fails and returns a null pointer. .Sh RETURN VALUES Upon successful completion, a pointer to the string containing the absolute -pathname of the current working directory is returned. Otherwise, +pathname of the current working directory is returned. +Otherwise, .Fn getwd returns a null pointer and the contents of the array pointed to by .Fa path_name @@ -43,7 +44,8 @@ No errors are defined. .Sh USAGE The .Fn getwd -function is supplied for backwards compatibility. The +function is supplied for backwards compatibility. +The .Xr getcwd 3C should be used instead. .Sh INTERFACE STABILITY @@ -54,7 +56,8 @@ should be used instead. .Sh STANDARDS The .Fn getwd -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3c/mtx.3c b/usr/src/man/man3c/mtx.3c index 8283161d61..677bee08e0 100644 --- a/usr/src/man/man3c/mtx.3c +++ b/usr/src/man/man3c/mtx.3c @@ -56,8 +56,8 @@ The .Sy mtx family of functions implement mutual exclusion locks (mutexes) and behave similarly to both POSIX threads and illumos threads; however, they have -slightly different call signatures and return values. For more -information, see +slightly different call signatures and return values. +For more information, see .Xr threads 5 . Importantly, they do not allow for inter-process synchronization. .Ss Creating and Destroying Mutexes @@ -75,11 +75,12 @@ A simple, intra-process mutex. A simple, intra-process mutex, which allows timed locking operations. .It Sy mtx_plain | mtx_recursive An intra-process mutex that may be acquired recursively by the same -thread. It must be unlocked an equal number of times that it is locked. +thread. +It must be unlocked an equal number of times that it is locked. .It Sy mtx_timed | mtx_recursive An intra-process mutex that supports timed locking operations and may be -acquired recursively by the same thread. It must be unlocked an equal -number of times that it is locked. +acquired recursively by the same thread. +It must be unlocked an equal number of times that it is locked. .El For more information on the different kind of mutexes, see .Xr mutex_init 3C . @@ -101,8 +102,8 @@ function attempts to lock the mutex When the function returns, it will be the sole owner of the mutex and must call .Fn mtx_unlock -when it is done, or risk inducing a deadlock in the process. Other -threads that make calls to +when it is done, or risk inducing a deadlock in the process. +Other threads that make calls to .Fn mtx_lock after another thread has successfully completed its call to .Fn mtx_lock @@ -116,8 +117,9 @@ was created, a thread calling .Fn mtx_lock when it already holds .Fa mtx -will cause the thread to deadlock. Othewrise, the lock will be -successfully taken again. However, a thread must call +will cause the thread to deadlock. +Othewrise, the lock will be successfully taken again. +However, a thread must call .Fn mtx_unlock for each time that it has acquried .Fa mtx . @@ -154,9 +156,10 @@ The .Fn mtx_unlock function unlocks the mutex pointed to by .Fa mtx , -which allows another thread the opportunity to obtain it. If any threads -are actively blocking on the mutex, one of them will obtain it and be -woken up. It is an error to call +which allows another thread the opportunity to obtain it. +If any threads are actively blocking on the mutex, one of them will obtain it +and be woken up. +It is an error to call .Fn mtx_unlock on a mutex which the calling thread does not currently own. .Sh RETURN VALUES diff --git a/usr/src/man/man3c/pthread_attr_get_np.3c b/usr/src/man/man3c/pthread_attr_get_np.3c index 8ffb28c0fc..d6f4571d0d 100644 --- a/usr/src/man/man3c/pthread_attr_get_np.3c +++ b/usr/src/man/man3c/pthread_attr_get_np.3c @@ -29,17 +29,19 @@ The .Fn pthread_attr_get_np function provides a way to get the attributes of the thread .Fa thread -after it has been created. This function is most commonly used to obtain -the actual location and size of a thread's stack. +after it has been created. +This function is most commonly used to obtain the actual location and size of a +thread's stack. .Pp The attributes pointer, .Fa attr , -will be filled in with the current attributes for the thread. The -attributes should be allocated by a call to +will be filled in with the current attributes for the thread. +The attributes should be allocated by a call to .Xr pthread_attr_init 3C prior to calling the .Fn pthrad_attr_get_np -function. When +function. +When .Fa attr is done being used, it should be destroyed through a call to .Xr pthread_attr_destroy 3C . @@ -82,7 +84,8 @@ and it is the preferred interface for obtaining that information. The scheduling policy attribute of .Fa attr will be updated with the current scheduling policy being applied to the -thread. This may have changed, for example, due to a call to +thread. +This may have changed, for example, due to a call to .Xr pthread_setschedparam 3C . As with the thread's scheduling parameter, the preferred interface for obtaining this information is by using diff --git a/usr/src/man/man3c/pthread_mutex_consistent.3c b/usr/src/man/man3c/pthread_mutex_consistent.3c index cb45730cc4..e9e4e33d59 100644 --- a/usr/src/man/man3c/pthread_mutex_consistent.3c +++ b/usr/src/man/man3c/pthread_mutex_consistent.3c @@ -34,13 +34,14 @@ holding a robust lock exits, such as by calling .Xr exit 2 or .Xr thr_exit 3C , -or crashes without unlocking the lock. At that point, if another process -or thread is currently in a call, or calls +or crashes without unlocking the lock. +At that point, if another process or thread is currently in a call, or calls .Xr pthread_mutex_lock 3C , it will obtain the lock; however, the error code .Er EOWNERDEAD -will be returned. In such cases, that thread will own the lock and must -check and clean up any inconsistent state that is protected by the lock. +will be returned. +In such cases, that thread will own the lock and must check and clean up any +inconsistent state that is protected by the lock. When finished, it must call .Fn pthread_mutex_consistent to indicate that it is in a consistent state again. @@ -55,13 +56,14 @@ Upon successful completion, the .Fn pthread_mutex_consistent returns zero and marks .Va mutex -as consistent. Callers of +as consistent. +Callers of .Fn pthread_mutex_lock will not have .Er EOWNERDEAD -returned until another process or thread exits without unlocking. Upon -failure, an error will be returned which corresponds to one of the -errors listed below. +returned until another process or thread exits without unlocking. +Upon failure, an error will be returned which corresponds to one of the errors +listed below. .Sh ERRORS The .Fn pthread_mutex_consistent diff --git a/usr/src/man/man3c/pthread_mutexattr_getrobust.3c b/usr/src/man/man3c/pthread_mutexattr_getrobust.3c index cefcc73042..85b2b335c9 100644 --- a/usr/src/man/man3c/pthread_mutexattr_getrobust.3c +++ b/usr/src/man/man3c/pthread_mutexattr_getrobust.3c @@ -46,23 +46,24 @@ include: .It Sy PTHREAD_MUTEX_STALLED The mutex referred to by .Va attr -is a traditional mutex. When a thread holding an intra-process lock or a -process holding an inter-process lock crashes or terminates without -unlocking the mutex, then the lock will be +is a traditional mutex. +When a thread holding an intra-process lock or a process holding an +inter-process lock crashes or terminates without unlocking the mutex, then the +lock will be .Sy stalled . For another thread or process to obtain the lock, something else must unlock it. .It Sy PTHREAD_MUTEX_ROBUST The mutex referred to by .Va attr -is considered a robust mutex. When a process holding an inter-process -lock crashes or terminates without unlocking the mutex, the attempt to -lock it will return +is considered a robust mutex. +When a process holding an inter-process lock crashes or terminates without +unlocking the mutex, the attempt to lock it will return .Er EOWNERDEAD . This allows the new owner the chance to fix the internal state and call .Xr pthread_mutex_consistent 3C -prior to unlocking the lock, allowing normal operation to proceed. Any -crashes while in this state cause the next owner to obtain +prior to unlocking the lock, allowing normal operation to proceed. +Any crashes while in this state cause the next owner to obtain .Er EOWNERDEAD . .El .Sh RETURN VALUES @@ -72,8 +73,8 @@ function will return .Sy 0 and update .Fa robust -with the current value of the robust attribute. Upon successful -completion, the +with the current value of the robust attribute. +Upon successful completion, the .Fn pthread_mutexattr_setrobust function will return .Sy 0 @@ -82,7 +83,8 @@ and update the robust property of the attributes pointed to by to .Va robust . If either function fails, an error code will be returned to indicate the -error. Valid errors are defined below. +error. +Valid errors are defined below. .Sh ERRORS The .Fn pthread_mutexattr_getrobust diff --git a/usr/src/man/man3c/quick_exit.3c b/usr/src/man/man3c/quick_exit.3c index e3e17603b4..bcdb855854 100644 --- a/usr/src/man/man3c/quick_exit.3c +++ b/usr/src/man/man3c/quick_exit.3c @@ -51,7 +51,8 @@ will be called in reverse order upon calling .Fn quick_exit . Functions registered with .Fn at_quick_exit -will not be called at any other time. Functions that are registered with +will not be called at any other time. +Functions that are registered with .Fn at_quick_exit should not make use of .Xr longjump 3C @@ -70,8 +71,8 @@ The .Fn at_quick_exit function returns .Sy 0 -on success. Otherwise, a non-zero error value is returned to indicate -failure. +on success. +Otherwise, a non-zero error value is returned to indicate failure. .Sh ERRORS The .Fn at_quick_exit diff --git a/usr/src/man/man3c/select.3c b/usr/src/man/man3c/select.3c index 2cf0538f82..1752625126 100644 --- a/usr/src/man/man3c/select.3c +++ b/usr/src/man/man3c/select.3c @@ -125,7 +125,8 @@ The .Fn select function has no .Fa sigmask -argument. It behaves as +argument. +It behaves as .Fn pselect does when .Fa sigmask @@ -142,9 +143,9 @@ The .Fn select and .Fn pselect -functions support regular files, -terminal and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and -sockets. The behavior of +functions support regular files, terminal and pseudo-terminal devices, +STREAMS-based files, FIFOs, pipes, and sockets. +The behavior of .Fn select and .Fn pselect @@ -192,13 +193,13 @@ Upon successful completion, the objects pointed to by the .Fa writefs , and .Fa errorfds -arguments are modified to indicate which file -descriptors are ready for reading, ready for writing, or have an error -condition pending, respectively, and return the total number of ready -descriptors in all the output sets. For each file descriptor less than +arguments are modified to indicate which file descriptors are ready for reading, +ready for writing, or have an error condition pending, respectively, and return +the total number of ready descriptors in all the output sets. +For each file descriptor less than .Fa nfds , -the corresponding bit will be set on successful completion if it -was set on input and the associated condition is true for that file descriptor. +the corresponding bit will be set on successful completion if it was set on +input and the associated condition is true for that file descriptor. .Pp If none of the selected descriptors are ready for the requested operation, the .Fn select @@ -206,24 +207,29 @@ or .Fn pselect function blocks until at least one of the requested operations becomes ready, until the timeout occurs, or until -interrupted by a signal. The +interrupted by a signal. +The .Fa timeout parameter controls how long the .Fn select or .Fn pselect -function takes before timing out. If the +function takes before timing out. +If the .Fa timeout parameter is not a null pointer, it specifies a maximum interval -to wait for the selection to complete. If the specified time interval expires -without any requested operation becoming ready, the function returns. If the +to wait for the selection to complete. +If the specified time interval expires without any requested operation becoming +ready, the function returns. +If the .Fa timeout parameter is a null pointer, then the call to .Fn select or .Fn pselect blocks indefinitely until at least one descriptor meets the -specified criteria. To effect a poll, the +specified criteria. +To effect a poll, the .Fa timeout parameter should not be a null pointer, and should point to a zero-valued .Vt timespec @@ -251,9 +257,10 @@ A descriptor is considered ready for reading when a call to an input function with .Dv O_NONBLOCK clear would not block, whether or not the function would -transfer data successfully. (The function might return data, an end-of-file -indication, or an error other than one indicating that it is blocked, and in -each of these cases the descriptor will be considered ready for reading.) +transfer data successfully. +(The function might return data, an end-of-file indication, or an error other +than one indicating that it is blocked, and in each of these cases the +descriptor will be considered ready for reading.) .Pp A descriptor is considered ready for writing when a call to an output function with @@ -262,10 +269,12 @@ clear would not block, whether or not the function would transfer data successfully. .Pp If a socket has a pending error, it is considered to have an exceptional -condition pending. Otherwise, what constitutes an exceptional condition is file -type-specific. For a file descriptor for use with a socket, it is -protocol-specific except as noted below. For other file types, if the operation -is meaningless for a particular file type, +condition pending. +Otherwise, what constitutes an exceptional condition is file type-specific. +For a file descriptor for use with a socket, it is protocol-specific except as +noted below. +For other file types, if the operation is meaningless for a particular file +type, .Fn select or .Fn pselect @@ -276,39 +285,41 @@ If a descriptor refers to a socket, the implied input function is the .Xr recvmsg 3XNET function with parameters requesting normal and ancillary data, such that the presence of either type causes the socket to be marked as -readable. The presence of out-of-band data is checked if the socket option +readable. +The presence of out-of-band data is checked if the socket option .Dv SO_OOBINLINE has been enabled, as out-of-band data is enqueued with -normal data. If the socket is currently listening, then it is marked as -readable if an incoming connection request has been received, and a call to the -accept function completes without blocking. +normal data. +If the socket is currently listening, then it is marked as readable if an +incoming connection request has been received, and a call to the accept function +completes without blocking. .Pp If a descriptor refers to a socket, the implied output function is the .Xr sendmsg 3XNET function supplying an amount of normal data equal to the current value of the .Dv SO_SNDLOWAT -option for the socket. If a non-blocking -call to the connect function has been made for a socket, and the connection -attempt has either succeeded or failed leaving a pending error, the socket is -marked as writable. +option for the socket. +If a non-blocking call to the connect function has been made for a socket, and +the connection attempt has either succeeded or failed leaving a pending error, +the socket is marked as writable. .Pp A socket is considered to have an exceptional condition pending if a receive operation with .Dv O_NONBLOCK clear for the open file description and with the .Dv MSG_OOB -flag set would return out-of-band data without blocking. (It -is protocol-specific whether the +flag set would return out-of-band data without blocking. +(It is protocol-specific whether the .Dv MSG_OOB -flag would be used to read out-of-band data.) A socket will also be considered -to have an exceptional condition pending if an out-of-band data mark is -present in the receive queue. +flag would be used to read out-of-band data.) +A socket will also be considered to have an exceptional condition pending if an +out-of-band data mark is present in the receive queue. .Pp A file descriptor for a socket that is listening for connections will indicate -that it is ready for reading, when connections are available. A file -descriptor for a socket that is connecting asynchronously will indicate that it -is ready for writing, when a connection has been established. +that it is ready for reading, when connections are available. +A file descriptor for a socket that is connecting asynchronously will indicate +that it is ready for writing, when a connection has been established. .Pp Selecting true for reading on a socket descriptor upon which a .Xr listen 3XNET @@ -321,8 +332,10 @@ If the argument is not a null pointer, it points to an object of type .Vt struct timeval that specifies a maximum interval to wait for the -selection to complete. If the \fItimeout\fR argument points to an object of -type +selection to complete. +If the +.Fa timeout +argument points to an object of type .Vt struct timeval whose members are 0, .Fn select @@ -332,8 +345,9 @@ If the argument is a null pointer, .Fn select blocks until an event causes one of the masks to be returned with a valid -(non-zero) value. If the time limit expires before any event occurs that -would cause one of the masks to be set to a non-zero value, +(non-zero) value. +If the time limit expires before any event occurs that would cause one of the +masks to be set to a non-zero value, .Fn select completes successfully and returns 0. .Pp @@ -349,7 +363,8 @@ argument is not a null pointer, or .Fn pselect blocks for the time specified, or until interrupted by a -signal. If the +signal. +If the .Fa readfds , .Fa writefds , and @@ -368,9 +383,9 @@ On failure, the objects pointed to by the .Fa writefds , and .Fa errorfds -arguments are not modified. If the timeout interval expires -without the specified condition being true for any of the specified file -descriptors, the objects pointed to by the +arguments are not modified. +If the timeout interval expires without the specified condition being true for +any of the specified file descriptors, the objects pointed to by the .Fa readfds , .Fa writefds , and @@ -422,7 +437,8 @@ On successful completion, and .Fn pselect return the total -number of bits set in the bit masks. Otherwise, +number of bits set in the bit masks. +Otherwise, .Sy 1 is returned and .Dv errno diff --git a/usr/src/man/man3c/signalfd.3c b/usr/src/man/man3c/signalfd.3c index fecd46e124..070bafc854 100644 --- a/usr/src/man/man3c/signalfd.3c +++ b/usr/src/man/man3c/signalfd.3c @@ -30,14 +30,15 @@ The .Fn signalfd function returns a file descriptor that can be used -for synchronous consumption of signals. The file descriptor can be operated -upon via +for synchronous consumption of signals. +The file descriptor can be operated upon via .Xr read 2 and the facilities that notify of file descriptor activity (e.g. .Xr poll 2 , .Xr port_get 3C , .Xr epoll_wait 3C -). To dispose of the instance +). +To dispose of the instance .Xr close 2 should be called on the file descriptor. .Pp @@ -72,7 +73,8 @@ see description for in .Xr open 2 . .It Sy SFD_NONBLOCK -Instance will be set to be non-blocking. A +Instance will be set to be non-blocking. +A .Xr read 2 on a signalfd instance that has been initialized with .Fa SFD_NONBLOCK , @@ -85,10 +87,10 @@ that are pending. .Pp As with .Xr sigwait 2 , -reading a signal from the file descriptor will consume the signal. The signals -used with signalfd file descriptors are normally first blocked so that their -handler does not run when a signal arrives. If the signal is not blocked the -behavior matches that of +reading a signal from the file descriptor will consume the signal. +The signals used with signalfd file descriptors are normally first blocked so +that their handler does not run when a signal arrives. +If the signal is not blocked the behavior matches that of .Xr sigwait 2 ; if a .Xr read 2 @@ -154,19 +156,21 @@ typedef struct signalfd_siginfo { File descriptor duplication during fork presents a challenge to the .Sy signalfd facility since signal data and events are dependent on the process from which -they are queried. Its use with caching event systems such as +they are queried. +Its use with caching event systems such as .Xr epoll 5 , -.Sy /dev/poll , +.Pa /dev/poll , or .Xr port_create 3C can result in undefined behavior if signalfd and polling descriptors are used -together after being shared across a fork. Such restrictions do not apply if -the child only calls +together after being shared across a fork. +Such restrictions do not apply if the child only calls .Xr close 2 on the descriptors. .Sh RETURN VALUES Upon successful completion, a file descriptor associated with the instance -is returned. Otherwise, -1 is returned and errno is set to indicate the error. +is returned. +Otherwise, -1 is returned and errno is set to indicate the error. When .Va fd is not -1 and there is no error, the value of diff --git a/usr/src/man/man3c/smt_pause.3c b/usr/src/man/man3c/smt_pause.3c index 495d3b78d1..815a21f40e 100644 --- a/usr/src/man/man3c/smt_pause.3c +++ b/usr/src/man/man3c/smt_pause.3c @@ -26,10 +26,10 @@ .Sh DESCRIPTION The .Fn smt_pause -function performs a busy-wait for an implementation defined period of -time. On hardware platforms that support it, it notifies the hardware -that this is occurring in an effort to minimize resource usage. This is -commonly used in the implementation of spin loops. +function performs a busy-wait for an implementation defined period of time. +On hardware platforms that support it, it notifies the hardware that this is +occurring in an effort to minimize resource usage. +This is commonly used in the implementation of spin loops. .Sh INTERFACE STABILITY .Sy Committed .Sh MT-LEVEL diff --git a/usr/src/man/man3c/thrd_create.3c b/usr/src/man/man3c/thrd_create.3c index ffaf9bf11c..fd31e740b7 100644 --- a/usr/src/man/man3c/thrd_create.3c +++ b/usr/src/man/man3c/thrd_create.3c @@ -39,11 +39,11 @@ When a thread is created, it begins its execution at the function with the argument .Fa arg . A created thread has access to all global data within a process; -however, it has its own private stack. Currently 32-bit processes have a -default stack of 1 megabyte, while 64-bit systems have a default stack -size of 2 megabytes. In addition, newly created threads inherit the -signal mask of the thread which created them; however, they do not -inherit any pending signals. +however, it has its own private stack. +Currently 32-bit processes have a default stack of 1 megabyte, while 64-bit +systems have a default stack size of 2 megabytes. +In addition, newly created threads inherit the signal mask of the thread which +created them; however, they do not inherit any pending signals. .Pp Once created, a thread will continue to execute until either, it returns from its initial function, the thread explicitly calls @@ -51,9 +51,9 @@ from its initial function, the thread explicitly calls or the process itself terminates, such as with a call to .Xr exit 2 . When the initial function returns, it behaves as though a call to -.Xr thrd_exit +.Xr thrd_exit 3C was made, and, if the thread has not been detached with a call to -.Xr thrd_detach, +.Xr thrd_detach 3C , the exit status remains available and the corresponding thread ID will not be reused until a process calls .Xr thrd_join 3C . @@ -74,7 +74,8 @@ function returns .Sy thrd_success . If insufficient memory was available, then .Sy thrd_nomem -is returned. Otherwise, +is returned. +Otherwise, .Sy thrd_error is returned, indicating that a non-memory related error. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3c/thrd_current.3c b/usr/src/man/man3c/thrd_current.3c index 9cc41795ab..6b4fc3e53d 100644 --- a/usr/src/man/man3c/thrd_current.3c +++ b/usr/src/man/man3c/thrd_current.3c @@ -26,8 +26,8 @@ .Sh DESCRIPTION The .Fn thrd_current -function returns the thread ID of the current calling thread. Note, this -ID may be different from the thread ID returned when using +function returns the thread ID of the current calling thread. +Note, this ID may be different from the thread ID returned when using .Xr thr_self 3C or .Xr pthread_self 3C ; diff --git a/usr/src/man/man3c/thrd_detach.3c b/usr/src/man/man3c/thrd_detach.3c index 8749b53c1b..4f19042c2c 100644 --- a/usr/src/man/man3c/thrd_detach.3c +++ b/usr/src/man/man3c/thrd_detach.3c @@ -28,17 +28,19 @@ The .Fn thrd_detach function causes a thread to be considered detached from the rest of the -execution environment. While detached threads are still fully -observable, they cannot be joined with, calls to +execution environment. +While detached threads are still fully observable, they cannot be joined with, +calls to .Fn thrd_join -will fail. In addition, if all non-detached -threads have terminated, the program will terminate; detached threads -cannot keep a program running. The act of calling +will fail. +In addition, if all non-detached threads have terminated, the program will +terminate; detached threads cannot keep a program running. +The act of calling .Fn thrd_detach on a thread does not cause it to terminate. .Sh RETURN VALUES Upon successful completion, the -.Xr thrd_detach +.Xr thrd_detach 3C function returns .Sy thrd_success . Otherwise, it returns diff --git a/usr/src/man/man3c/thrd_equal.3c b/usr/src/man/man3c/thrd_equal.3c index 6c77a72138..0ceec884b8 100644 --- a/usr/src/man/man3c/thrd_equal.3c +++ b/usr/src/man/man3c/thrd_equal.3c @@ -41,8 +41,8 @@ if .Fa thrd0 and .Fa thrd1 -refer to the same thread. Otherwise, a non-zero value is returned, -indicating that +refer to the same thread. +Otherwise, a non-zero value is returned, indicating that .Fa thrd0 and .Fa thrd1 diff --git a/usr/src/man/man3c/thrd_exit.3c b/usr/src/man/man3c/thrd_exit.3c index 3dcf682cd9..58a91a6475 100644 --- a/usr/src/man/man3c/thrd_exit.3c +++ b/usr/src/man/man3c/thrd_exit.3c @@ -28,8 +28,9 @@ The .Fn thrd_exit function terminates the calling thread, in a similar way that .Xr exit 3C -terminates the calling process. If the calling thread has not been -detached, then the exit status information provided in +terminates the calling process. +If the calling thread has not been detached, then the exit status information +provided in .Fa res is saved and can be retrieved by the use of the .Xr thrd_join 3C diff --git a/usr/src/man/man3c/thrd_join.3c b/usr/src/man/man3c/thrd_join.3c index d2cb8c83ea..52a7d8bd33 100644 --- a/usr/src/man/man3c/thrd_join.3c +++ b/usr/src/man/man3c/thrd_join.3c @@ -36,10 +36,12 @@ for that thread in .Fa res , if .Fa res -is non-null. The +is non-null. +The .Fa thrd argument must be a member of the current process and it cannot be -detached. If +detached. +If .Fa thrd has already terminated and another caller has not called .Fn thrd_join @@ -65,7 +67,7 @@ function returns and if .Fa res is a non-null pointer, it will be filled in with the exit status of -.Xr thrd . +.Xr thrd 3C . If an error occurs, .Sy thrd_error will be returned. diff --git a/usr/src/man/man3c/timerfd_create.3c b/usr/src/man/man3c/timerfd_create.3c index 432717f6e9..5f2bdcd2c2 100644 --- a/usr/src/man/man3c/timerfd_create.3c +++ b/usr/src/man/man3c/timerfd_create.3c @@ -80,7 +80,8 @@ description of .Ed .It Sy TFD_NONBLOCK .Bd -filled -compact -Instance will be set to be non-blocking. A +Instance will be set to be non-blocking. +A .Xr read 2 on a .Sy timerfd @@ -109,8 +110,8 @@ or .Fn timerfd_settime . Upon success, the number of expirations will be copied into the eight byte buffer -passed to the system call. If there have been no expirations of the -timer since the last successful +passed to the system call. +If there have been no expirations of the timer since the last successful .Xr read 2 or .Fn timerfd_sttime , @@ -165,7 +166,8 @@ same functional signature and semantics as .El .Sh RETURN VALUES Upon successful completion, a file descriptor associated with the instance -is returned. Otherwise, +is returned. +Otherwise, .Sy -1 is returned and errno is set to indicate the error. .Sh ERRORS diff --git a/usr/src/man/man3c/timespec_get.3c b/usr/src/man/man3c/timespec_get.3c index 7ae55f7b55..532af5ce3c 100644 --- a/usr/src/man/man3c/timespec_get.3c +++ b/usr/src/man/man3c/timespec_get.3c @@ -27,15 +27,16 @@ .Sh DESCRIPTION The .Fn timespec_get -function provides access nanosecond resolution time. The -meaning and source of time is defined by the +function provides access nanosecond resolution time. +The meaning and source of time is defined by the .Fa base -argument. The following values are defined for +argument. +The following values are defined for .Fa base : .Bl -tag -width Ds .It Sy TIME_UTC -Obtain the current time of day from the realtime clock on the system. It -represents the amount of time in second and nanoseconds since the Epoch. +Obtain the current time of day from the realtime clock on the system. +It represents the amount of time in second and nanoseconds since the Epoch. This is logically equivalent to calling .Xr clock_gettime 3C with diff --git a/usr/src/man/man3c/tss.3c b/usr/src/man/man3c/tss.3c index 6e4b696339..9f8fde3912 100644 --- a/usr/src/man/man3c/tss.3c +++ b/usr/src/man/man3c/tss.3c @@ -50,20 +50,21 @@ storage. .Ss Creating and Destorying Thread-Specific Storage The .Fn tss_create -function creates a new thread-specific data key. The key space is opaque -and global to all threads in the process. Each thread has its own -value-space which can be manipulated with the +function creates a new thread-specific data key. +The key space is opaque and global to all threads in the process. +Each thread has its own value-space which can be manipulated with the .Fn tss_get and .Fn tss_set -functions. A given key persists until +functions. +A given key persists until .Fn tss_destroy is called. .Pp When a key is created, the value .Dv NULL -is associated with all current threads. When a thread is created, the -value +is associated with all current threads. +When a thread is created, the value .Dv NULL is assigned as the value for the entire key-space. .Pp @@ -75,20 +76,22 @@ will run when the thread exits (see .Xr thrd_exit 3C ) if the value for the key is not .Dv NULL . -The key space's destructors may be run in any order. When the destructor -is run due to a thread exiting, all signals will be blocked. +The key space's destructors may be run in any order. +When the destructor is run due to a thread exiting, all signals will be blocked. .Pp The .Fn tss_delete function deletes the key identify by .Fa key -from the global name-space. When a key is deleted, no registered -destructor is called, it is up to the calling program to free any -storage that was associated with +from the global name-space. +When a key is deleted, no registered destructor is called, it is up to the +calling program to free any storage that was associated with .Fa key -across all threads. Because of this propety, it is legal to call +across all threads. +Because of this propety, it is legal to call .Fn tss_delete -from inside a destructor. Any destructors that had been assocaited with +from inside a destructor. +Any destructors that had been assocaited with .Fa key will no longer be called when a thread terminates. .Ss Obtaining Values @@ -96,8 +99,9 @@ The .Fn tss_get function may be used to obtain the value associated with .Fa key -for the calling thread. Note that if the calling thread has never set a -value, then it will receive the default value, +for the calling thread. +Note that if the calling thread has never set a value, then it will receive the +default value, .Dv NULL . .Fn tss_get may be called from a tss destructor. @@ -116,7 +120,8 @@ in as .Fa value . Changing the value of a key with .Fn tss_set -does not cause any destructors to be invoked. This means that +does not cause any destructors to be invoked. +This means that .Fn tss_set may be used in the context of a destructor, but special care must be taken to avoid leaking storage or causing an infinite loop. diff --git a/usr/src/man/man3c/ualarm.3c b/usr/src/man/man3c/ualarm.3c index 269d5ebe8f..87273ae88a 100644 --- a/usr/src/man/man3c/ualarm.3c +++ b/usr/src/man/man3c/ualarm.3c @@ -23,11 +23,15 @@ function causes the signal to be generated for the calling process after the number of real-time microseconds specified by the .Fa useconds -argument has elapsed. When the +argument has elapsed. +When the .Fa interval argument is non-zero, repeated timeout notification occurs with a period in microseconds -specified by the \fIinterval\fR argument. If the notification signal, +specified by the +.Fa interval +argument. +If the notification signal, .Dv SIGALRM , is not caught or ignored, the calling process is terminated. .Lp @@ -47,7 +51,8 @@ The function returns the number of microseconds remaining from the previous .Fn ualarm -call. If no timeouts are pending or if +call. +If no timeouts are pending or if .Fn ualarm has not previously been called, .Fn ualarm @@ -61,7 +66,8 @@ function is a simplified interface to .Xr setitimer 2 , and uses the .Dv ITIMER_REAL -interval timer. It's use has been deprecated in favor of the +interval timer. +It's use has been deprecated in favor of the .Xr timer_create 3C family of functions. .Sh INTERFACE STABILITY @@ -79,7 +85,8 @@ family of functions. .Sh STANDARDS The .Fn ualarm -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3c/usleep.3c b/usr/src/man/man3c/usleep.3c index bde0508ec2..e26f1a534c 100644 --- a/usr/src/man/man3c/usleep.3c +++ b/usr/src/man/man3c/usleep.3c @@ -22,12 +22,13 @@ The function suspends the caller from execution for the number of microseconds specified by the .Fa useconds -argument. The actual suspension -time might be less than requested because any caught signal will terminate +argument. +The actual suspension time might be less than requested because any caught +signal will terminate .Fn usleep -following execution of that signal's catching routine. The -suspension time might be longer than requested by an arbitrary amount because -of the scheduling of other activity in the system. +following execution of that signal's catching routine. +The suspension time might be longer than requested by an arbitrary amount +because of the scheduling of other activity in the system. .Lp If the value of .Fa useconds @@ -36,18 +37,21 @@ is 0, then the call has no effect. The use of the usleep function has no effect on the action or blockage -of any signal. In a multithreaded process, only the invoking thread is -suspended from execution. +of any signal. +In a multithreaded process, only the invoking thread is suspended from +execution. .Sh RETURN VALUES On completion, .Fn usleep -returns 0. There are no error returns. +returns 0. +There are no error returns. .Sh ERRORS No errors are returned. .Sh USAGE The .Fn usleep -function is included for its historical usage and is Obsolete. The +function is included for its historical usage and is Obsolete. +The .Xr nanosleep 3C function is preferred over this function. .Sh INTERFACE STABILITY @@ -62,7 +66,8 @@ function is preferred over this function. .Sh STANDARDS The .Fn usleep -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3c/wcpcpy.3c b/usr/src/man/man3c/wcpcpy.3c index b4a5ecad8e..203164992f 100644 --- a/usr/src/man/man3c/wcpcpy.3c +++ b/usr/src/man/man3c/wcpcpy.3c @@ -48,7 +48,8 @@ of .Fn wcpncpy , after .Fa n -wide-characters have been copied. If +wide-characters have been copied. +If .Fa ws2 contains fewer than .Fa n @@ -89,8 +90,8 @@ The .Fn wcpcpy and .Fn wcpncpy -functions return a pointer to the last wide-character written. In the -case of +functions return a pointer to the last wide-character written. +In the case of .Fn wcpncpy this will always be equal to .Po Fa ws1 Li + Fa n Li \(mi 1 Pc . diff --git a/usr/src/man/man3c/wcscasecmp.3c b/usr/src/man/man3c/wcscasecmp.3c index d8af330cf7..f55d18dfd0 100644 --- a/usr/src/man/man3c/wcscasecmp.3c +++ b/usr/src/man/man3c/wcscasecmp.3c @@ -60,10 +60,10 @@ Pairs of wide-characters from each of .Fa ws1 and .Fa ws2 -are compared consecutively, ignoring differences in case (if the -.\"POSIX\." locale upper case characters are treated as lower case). If -the two values are different, the comparison stops and either -a negative value is returned if the character from +are compared consecutively, ignoring differences in case (if the "POSIX" locale +upper case characters are treated as lower case). +If the two values are different, the comparison stops and either a negative +value is returned if the character from .Fa ws1 is less than that from .Fa ws2 , @@ -78,8 +78,8 @@ and .Fn wcsncasecmp_l , after .Fa n -comparisons have been made without finding a difference. In either of -these two cases, 0 is returned. +comparisons have been made without finding a difference. +In either of these two cases, 0 is returned. .Lp The .Fn wcscasecmp @@ -87,7 +87,8 @@ and .Fn wcsncasecmp functions use the .Dv LC_CTYPE -category of the current locale to determine case. The +category of the current locale to determine case. +The .Fn wcscasecmp_l and .Fn wcsncasecmp_l diff --git a/usr/src/man/man3c/wcsdup.3c b/usr/src/man/man3c/wcsdup.3c index 80113744a9..f9692ca5b5 100644 --- a/usr/src/man/man3c/wcsdup.3c +++ b/usr/src/man/man3c/wcsdup.3c @@ -33,9 +33,11 @@ function duplicates a wide-character allocating sufficient memory to store the copy, and then copying from .Fa string . -The resulting copy is returned. It may be deallocated with +The resulting copy is returned. +It may be deallocated with .Xr free 3C -when it is no longer needed. The +when it is no longer needed. +The .Fn wcsdup function is the wide-character equivalent of .Xr strdup 3C . |