diff options
Diffstat (limited to 'usr/src/man/man3proc')
125 files changed, 871 insertions, 668 deletions
diff --git a/usr/src/man/man3proc/Lfree.3proc b/usr/src/man/man3proc/Lfree.3proc index 07e0f3f6c5..b65a7bedae 100644 --- a/usr/src/man/man3proc/Lfree.3proc +++ b/usr/src/man/man3proc/Lfree.3proc @@ -42,7 +42,8 @@ The state of the thread controlled by is not affected by the call to .Fn Lfree . The thread's state will not transition from running to stopped or -vice-versa. It will retain its state prior to the call to +vice-versa. +It will retain its state prior to the call to .Fn Lfree . .Sh INTERFACE STABILITY .Sy Uncommitted diff --git a/usr/src/man/man3proc/Lgrab.3proc b/usr/src/man/man3proc/Lgrab.3proc index 24ad4a44b5..d5f840304d 100644 --- a/usr/src/man/man3proc/Lgrab.3proc +++ b/usr/src/man/man3proc/Lgrab.3proc @@ -35,7 +35,8 @@ residing under the process .Fa P . This handle is then passed as argument to other .Sy libproc -routines. The +routines. +The .Fa lwpid can be obtained from the .Sy pr_lwpid @@ -48,31 +49,33 @@ The argument must point to a valid pointer that will be used to store an error code in the event that .Fn Lgrab -is unable to successfully obtain a handle to the process. The possible -errors are defined below in the +is unable to successfully obtain a handle to the process. +The possible errors are defined below in the .Sx ERRORS -section. The code may be transformed into a human readable string -through the use of +section. +The code may be transformed into a human readable string through the use of .Xr Lgrab_error 3PROC . .Pp The handle to the thread is valid until the .Xr Lfree 3PROC -function is called, which also releases associated resources from the -handle. Only a single handle to a specific thread may exist at any -time. If the handle already exists and another caller attempts to grab -that thread, it will result in an error. The caller must call +function is called, which also releases associated resources from the handle. +Only a single handle to a specific thread may exist at any time. +If the handle already exists and another caller attempts to grab +that thread, it will result in an error. +The caller must call .Fn Lfree before releasing the handle associated with .Fa P . .Pp Unlike grabbing a process, grabbing a thread does not change the current -state of the thread. If it is running, it will remain running. If it is -stopped, it will remain stopped. +state of the thread. +If it is running, it will remain running. +If it is stopped, it will remain stopped. .Sh RETURN VALUES Upon successful completion, the .Fn Lgrab -function returns a pointer to the control handle for the specified -thread. Otherwise, the +function returns a pointer to the control handle for the specified thread. +Otherwise, the .Dv NULL pointer is returned and .Fa perr @@ -92,10 +95,11 @@ The thread identified by .Fa lwpid does not exist or has already become a zombie. .It Er G_STRANGE -An unanticipated system error occurred while trying to create the -handle. When this occurs, then the value of +An unanticipated system error occurred while trying to create the handle. +When this occurs, then the value of .Sy errno -is meaningful. See +is meaningful. +See .Xr errno 3C for more information and .Xr Intro 2 diff --git a/usr/src/man/man3proc/Lgrab_error.3proc b/usr/src/man/man3proc/Lgrab_error.3proc index cb544f9398..6606ac74c6 100644 --- a/usr/src/man/man3proc/Lgrab_error.3proc +++ b/usr/src/man/man3proc/Lgrab_error.3proc @@ -28,7 +28,8 @@ The .Fn Lgrab_error function returns a pointer to a human-readable character string -describing the error that occurred. The +describing the error that occurred. +The .Fn Lgrab_error function only knows how to translate error codes that were stored in the third argument diff --git a/usr/src/man/man3proc/Lprochandle.3proc b/usr/src/man/man3proc/Lprochandle.3proc index 7472c74b9c..72f1630450 100644 --- a/usr/src/man/man3proc/Lprochandle.3proc +++ b/usr/src/man/man3proc/Lprochandle.3proc @@ -29,10 +29,12 @@ The .Fn Lprochandle function returns the process handle to which the thread handle .Fa L -belongs. This proccess handle may be used with other +belongs. +This proccess handle may be used with other .Xr libproc 3PROC functions just as if -.Xr Pgrab 3PROC was called. The returned handle is valid even if +.Xr Pgrab 3PROC was called. +The returned handle is valid even if .Xr Lfree 3PROC is called on .Fa L . diff --git a/usr/src/man/man3proc/Lpsinfo.3proc b/usr/src/man/man3proc/Lpsinfo.3proc index d9ff12afb1..920c721112 100644 --- a/usr/src/man/man3proc/Lpsinfo.3proc +++ b/usr/src/man/man3proc/Lpsinfo.3proc @@ -30,7 +30,8 @@ The function returns the thread handle .Fa L Ns 's .Xr ps 1 -information. The +information. +The .Sy lwpsinfo_t structure that is returned is defined in .Xr proc 4 @@ -39,7 +40,8 @@ and is valid until a subsequent call to .Sh RETURN VALUES Upon successful completion, the .Fn Lpsinfo -function returns a pointer to the thread's ps information. Otherwise, +function returns a pointer to the thread's ps information. +Otherwise, .Dv NULL is returned to indicate that it could not be found. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Lstatus.3proc b/usr/src/man/man3proc/Lstatus.3proc index b02b63f6db..9efc793656 100644 --- a/usr/src/man/man3proc/Lstatus.3proc +++ b/usr/src/man/man3proc/Lstatus.3proc @@ -38,7 +38,8 @@ of its stack, its user and system time, and more. .Pp The returned pointer is only valid as long as the thread handle .Fa L -is valid. After a call to +is valid. +After a call to .Xr Ltree 3PROC , the returned data pointer is invalid. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Paddr_to_ctf.3proc b/usr/src/man/man3proc/Paddr_to_ctf.3proc index 9e46933478..5eb4183a23 100644 --- a/usr/src/man/man3proc/Paddr_to_ctf.3proc +++ b/usr/src/man/man3proc/Paddr_to_ctf.3proc @@ -53,9 +53,11 @@ shared libraries are searched. .Pp The CTF container returned is valid as long as the process handle .Fa P -is valid. That is, until a call to +is valid. +That is, until a call to .Xr Prelease 3PROC -is made. Further, consumers must not close the CTF container. +is made. +Further, consumers must not close the CTF container. .Pp The .Fn Paddr_to_ctf @@ -63,8 +65,8 @@ function attempts to find the CTF section, if any, that exists for the address .Fa addr . Note, not all addresses correspond to memory regions that have CTF -data. For example, if a user creates a region of anonymous memory -through the +data. +For example, if a user creates a region of anonymous memory through the .Xr mmap 2 function, then it will not have any corresponding CTF information. .Pp @@ -72,8 +74,9 @@ The .Fn Pname_to_ctf function looks up the object named .Fa name -and returns the corresponding CTF section, if any exists. Two special -values may be used for name. The macro +and returns the corresponding CTF section, if any exists. +Two special values may be used for name. +The macro .Dv PR_OBJ_EXEC refers to the executable object itself and the macro .Dv PR_OBJ_LDSO refers to the object ld.so.1 . @@ -86,7 +89,8 @@ It allows the passing of a link-map identifier, .Fa lmid , which constricts the search of the object named with .Fa name -to that link-map. The special value of +to that link-map. +The special value of .Dv PR_LMID_EVERY indicates that every link-map should be searched, which is equivalent in behavior to the diff --git a/usr/src/man/man3proc/Paddr_to_loadobj.3proc b/usr/src/man/man3proc/Paddr_to_loadobj.3proc index 220f17e47c..6430d8eae4 100644 --- a/usr/src/man/man3proc/Paddr_to_loadobj.3proc +++ b/usr/src/man/man3proc/Paddr_to_loadobj.3proc @@ -54,18 +54,19 @@ identifier, the TLS module ID, and the address of various sections. The pointer to the data returned by the library will only be valid for as long as the handle .Fa P -is valid. Any calls to +is valid. +Any calls to .Xr Prelease 3PROC will invalidate the data. .Pp The .Fn Paddr_to_loadobj -function attempts to find the loaded object information, if any, that exists for the -address +function attempts to find the loaded object information, if any, that exists for +the address .Fa addr . Not all address correspond to memory regions that were loaded by the -run-time link-editor. For example, if a user creates a region of -anonymous memory through the +run-time link-editor. +For example, if a user creates a region of anonymous memory through the .Xr mmap 2 function, then it will not have any corresponding loaded module. .Pp @@ -73,8 +74,9 @@ The .Fn Pname_to_loadobj function looks up the object named .Fa name -and returns the corresponding loaded object information. Two special -values may be used for name. The macro +and returns the corresponding loaded object information. +Two special values may be used for name. +The macro .Dv PR_OBJ_EXEC refers to the executable object itself and the macro .Dv PR_OBJ_LDSO refers to the object ld.so.1 . @@ -87,7 +89,8 @@ It allows the use of a link-map identifier, .Fa lmid , which constricts the search of the object named with .Fa name -to that link-map. The special value of +to that link-map. +The special value of .Dv PR_LMID_EVERY may be passed to indicate that every link-map should be searched, which is equivalent in behavior to the diff --git a/usr/src/man/man3proc/Paddr_to_map.3proc b/usr/src/man/man3proc/Paddr_to_map.3proc index eac5dc001d..d49067ee65 100644 --- a/usr/src/man/man3proc/Paddr_to_map.3proc +++ b/usr/src/man/man3proc/Paddr_to_map.3proc @@ -62,7 +62,8 @@ the mapping and is defined in The pointer to the data returned by the library will only be valid for as long as the handle .Fa P -is valid. Any calls to +is valid. +Any calls to .Xr Prelease 3PROC will invalidate the data. .Pp @@ -85,8 +86,9 @@ The .Fn Pname_to_map function looks up the object named .Fa name -and returns the corresponding mapping information. Two special -values may be used for name. The macro +and returns the corresponding mapping information. +Two special values may be used for name. +The macro .Dv PR_OBJ_EXEC refers to the executable object itself and the macro .Dv PR_OBJ_LDSO refers to the object ld.so.1 . @@ -99,7 +101,8 @@ It allows passing a link-map identifier, .Fa lmid , which constricts the search of the object named with .Fa name -to that link-map. The special value of +to that link-map. +The special value of .Dv PR_LMID_EVERY may be passed to indicate that every link-map should be searched, which is equivalent in behavior to the diff --git a/usr/src/man/man3proc/Pasfd.3proc b/usr/src/man/man3proc/Pasfd.3proc index 90c8865b66..a5ae8a9dc4 100644 --- a/usr/src/man/man3proc/Pasfd.3proc +++ b/usr/src/man/man3proc/Pasfd.3proc @@ -31,15 +31,17 @@ funtion returns a file descriptor that allows direct access to the address space of the process handle .Fa P . A defined file descriptor is provided when using the -.Xr Pcreate , +.Xr Pcreate 3PROC , .Xr Pgrab 3PROC , .Xr Pgrab_file 3PROC , and .Xr Pgrab_core 3PROC -functions. Note that the address space may be different in each of these -cases and doesn't necessarily correspond to the /proc +functions. +Note that the address space may be different in each of these cases and doesn't +necessarily correspond to the /proc .Sy as -file, except for live processes. Other means of obtaining a +file, except for live processes. +Other means of obtaining a .Sy libproc process handle may not define a file descriptor that contains the address space. @@ -47,14 +49,15 @@ address space. The returned file descriptor must not be closed and is only valid for as long as the corresponding process handle .Fa P -is valid. After a call to +is valid. +After a call to .Xr Prelease 3PROC the file descriptor is invalidated. .Sh RETURN VALUES Upon successful completion, the .Fn Pasfd -function returns a valid file descriptor. Otherwise, if none exists, -then +function returns a valid file descriptor. +Otherwise, if none exists, then .Sy -1 is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pclearfault.3proc b/usr/src/man/man3proc/Pclearfault.3proc index dba09993df..0c1f7ed862 100644 --- a/usr/src/man/man3proc/Pclearfault.3proc +++ b/usr/src/man/man3proc/Pclearfault.3proc @@ -32,9 +32,9 @@ .Sh DESCRIPTION During normal operation a process may encounter a .Sy fault , -due to a hardware exception, identifying a problem with the running -process. Hardware faults include things like executing illegal -instructions, encountering a breakpoint, and arithmetic exceptions. +due to a hardware exception, identifying a problem with the running process. +Hardware faults include things like executing illegal instructions, encountering +a breakpoint, and arithmetic exceptions. Faults are discussed further in .Xr proc 4 . .Pp @@ -58,8 +58,9 @@ The .Fn Pclearfault and .Fn Lclearfault -functions only have meaning for active processes. They will fail on process -handles corresponding to zombie processes, ELF objects, and cores. +functions only have meaning for active processes. +They will fail on process handles corresponding to zombie processes, ELF +objects, and cores. .Sh RETURN VALUES Upon successful completion, the .Fn Pclearfault diff --git a/usr/src/man/man3proc/Pclearsig.3proc b/usr/src/man/man3proc/Pclearsig.3proc index b96d78b697..577fcf9359 100644 --- a/usr/src/man/man3proc/Pclearsig.3proc +++ b/usr/src/man/man3proc/Pclearsig.3proc @@ -30,8 +30,8 @@ .Fa "struct ps_lwphandle *L" .Fc .Sh DESCRIPTION -During normal operation a process may receive a signal. Signals may -indicate an error, for example referencing unmapped memory, an alarm +During normal operation a process may receive a signal. +Signals may indicate an error, for example referencing unmapped memory, an alarm firing, requests for information, and users requesting an interruption. For more information on the generation and usage of signals, see .Xr signal.h 3HEAD . @@ -54,8 +54,9 @@ representive thread, it instead operates on the thread handle .Pp The .Fn Pclearsig -function only has meaning for active processes. It will fail on process -handles corresponding to core files, zombie processes and ELF objects. +function only has meaning for active processes. +It will fail on process handles corresponding to core files, zombie processes +and ELF objects. .Sh RETURN VALUES Upon successful completion, the .Fn Pclearsig diff --git a/usr/src/man/man3proc/Pcontent.3proc b/usr/src/man/man3proc/Pcontent.3proc index 0f31978cef..27d9d6742a 100644 --- a/usr/src/man/man3proc/Pcontent.3proc +++ b/usr/src/man/man3proc/Pcontent.3proc @@ -31,13 +31,14 @@ function describes information available from the process handle .Fa P . .Pp Different types of process handles have different kinds of content -available to them. For example, handles to active and running processes -have more information available than various core files, as the core -file retains a subset of information available in the running process. +available to them. +For example, handles to active and running processes have more information +available than various core files, as the core file retains a subset of +information available in the running process. Handles that refer to ELF objects, obtained through .Xr Pgrab_file 3PROC , -will not have information such as a stack available. The content of -core files is controlled by +will not have information such as a stack available. +The content of core files is controlled by .Xr coreadm 1M . .Pp The symbols that may be returned are listed in the @@ -49,7 +50,8 @@ section in .Sh RETURN VALUES Upon successful completion, the .Fn Pcontent -function returns the bitwise-inclusive-OR of content types. Otherwise, +function returns the bitwise-inclusive-OR of content types. +Otherwise, .Dv CC_CONTENT_INVALID is returned to indicate an error. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pcreate.3proc b/usr/src/man/man3proc/Pcreate.3proc index 23eb6f9e6a..6185e60d23 100644 --- a/usr/src/man/man3proc/Pcreate.3proc +++ b/usr/src/man/man3proc/Pcreate.3proc @@ -48,7 +48,8 @@ The .Fn Pcreate function creates a process controlled by the .Sy libproc -library. The +library. +The .Fn Pxcreate function does the same while also allowing the replacement of the environment via @@ -71,9 +72,10 @@ The process image will be invoked with the arguments specified by .Fa argv , which should be a .Dv NULL Ns -terminated -array of character strings. Each entry in the array is an individual -argument. The environment of the process image will be inherited from -the running process if the +array of character strings. +Each entry in the array is an individual argument. +The environment of the process image will be inherited from the running process +if the .Fn Pcreate function is called or if the .Fn Pxcreate @@ -97,9 +99,9 @@ process before the call to .Xr exec 2 . The symbol .Sy Pcreate_callback -is a symbol that may be interposed on by consumers. It allows the chance -for the modification of signal dispositions or any other changes that a -caller may wish to make. +is a symbol that may be interposed on by consumers. +It allows the chance for the modification of signal dispositions or any other +changes that a caller may wish to make. .Pp If the caller's real user or group ID is not their effective user or group ID, then the child process's user and group IDs will all be reset @@ -109,7 +111,8 @@ The .Fa perr argument must be a .Pf non- Dv NULL -pointer. If the +pointer. +If the .Fn Pcreate or .Fn Pxcreate @@ -125,7 +128,8 @@ may exist on the .Fa PATH . To determine the full path of the executable pass a non-NULL .Fa path -pointer. Upon successful completion of +pointer. +Upon successful completion of .Fn Pcreate or .Fn Pxcreate @@ -139,22 +143,24 @@ Upon successful completion of the .Fn Pcreate or .Fn Pxcreate -function, a handle to the process is returned. This handle is usable -with other +function, a handle to the process is returned. +This handle is usable with other .Sy libproc routines and will persist until either .Xr Pfree 3PROC or .Xr Prelease 3PROC -is called on the resulting handle. The process created is stopped just -after return from the +is called on the resulting handle. +The process created is stopped just after return from the .Xr exec 2 -family of system calls. The process will not run, unless the caller sets -it running or releases its handle to the process. +family of system calls. +The process will not run, unless the caller sets it running or releases its +handle to the process. .Pp A 32-bit process cannot use this interface to launch or control a -64-bit process. However, a 64-bit process can create and control both -32-bit and 64-bit processes. +64-bit process. +However, a 64-bit process can create and control both 32-bit and 64-bit +processes. .Sh RETURN VALUES Upon successful completion, both the .Fn Pcreate @@ -162,7 +168,8 @@ and .Fn Pxcreate functions create a new process and return a .Sy libproc -handle to it. Otherwise, +handle to it. +Otherwise, .Sy NULL is returned and .Fa perr @@ -202,9 +209,11 @@ or the one found by searching is set-id or unreadable. .It Er C_STRANGE An unanticipated system error occurred while trying to create the -process and its handle. When this occurs, then the value of +process and its handle. +When this occurs, then the value of .Sy errno -is meaningful. See +is meaningful. +See .Xr errno 3C for more information and .Xr Intro 2 diff --git a/usr/src/man/man3proc/Pcreate_agent.3proc b/usr/src/man/man3proc/Pcreate_agent.3proc index 8fcf3e35e4..a421938e06 100644 --- a/usr/src/man/man3proc/Pcreate_agent.3proc +++ b/usr/src/man/man3proc/Pcreate_agent.3proc @@ -30,7 +30,8 @@ The function creates the agent LWP in the process represented by the handle .Fa P . The agent LWP is used as a means to force system calls to be invoked on -the controlled process. For more information on the agent LWP, see +the controlled process. +For more information on the agent LWP, see .Xr proc 4 . .Pp The agent LWP cannot be created for process handles corresponding to @@ -39,8 +40,9 @@ objects. .Pp The .Fn Pcreate_agent -function is reentrant. It may be entered recursively. The act of -creating the agent LWP will cause the process to be stopped. +function is reentrant. +It may be entered recursively. +The act of creating the agent LWP will cause the process to be stopped. For every call to the .Fn Pcreate_agent function, a corresponding call to @@ -51,7 +53,8 @@ Upon successful completion, the .Fn Pcreate_agent function returns .Sy 0 -and creates the agent LWP. Otherwise, +and creates the agent LWP. +Otherwise, .Sy -1 is returned, .Sy errno @@ -67,8 +70,8 @@ The process referred to by is a core file, zombie, ELF object, or has not begun execution. .El .Pp -Note, it is possible for other error numbers to be returned. If they -are, they represent unanticipated failure. +Note, it is possible for other error numbers to be returned. +If they are, they represent unanticipated failure. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Pcreate_error.3proc b/usr/src/man/man3proc/Pcreate_error.3proc index 74d8331630..73a2538ec8 100644 --- a/usr/src/man/man3proc/Pcreate_error.3proc +++ b/usr/src/man/man3proc/Pcreate_error.3proc @@ -28,7 +28,8 @@ The .Fn Pcreate_error function returns a pointer to a human-readable character string -describing the error that occurred. The +describing the error that occurred. +The .Fn Pcreate_error function translates errors produced by the .Xr Pcreate 3PROC diff --git a/usr/src/man/man3proc/Pcred.3proc b/usr/src/man/man3proc/Pcred.3proc index f8376d45e2..bec0030fd4 100644 --- a/usr/src/man/man3proc/Pcred.3proc +++ b/usr/src/man/man3proc/Pcred.3proc @@ -39,8 +39,9 @@ The type is defined in .Xr proc 4 . It contains information about the current effective, saved, and real -user and group IDs. It also allows for supplemental groups to be -obtained. The +user and group IDs. +It also allows for supplemental groups to be obtained. +The .Fn Pcred function will read a number of supplemental groups based on the value of .Fa ngroups . @@ -54,7 +55,7 @@ groups that are desired. .Pp Not all process handles have credential information available to them. For example, the handles that come from -.Xr Pgrab_file +.Xr Pgrab_file 3PROC have no processes associated with them and thus have no credentials associated with them. .Sh RETURN VALUES @@ -64,7 +65,8 @@ function returns .Sy 0 and updates the memory at .Fa pcrp -with the credentials. Otherwise, +with the credentials. +Otherwise, .Sy -1 is returned to indicate an error. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pctlfd.3proc b/usr/src/man/man3proc/Pctlfd.3proc index cf331879ed..00e383c481 100644 --- a/usr/src/man/man3proc/Pctlfd.3proc +++ b/usr/src/man/man3proc/Pctlfd.3proc @@ -36,8 +36,8 @@ however, many interfaces for using it are provided by .Xr libproc 3LIB itself. .Pp -Only live processes have a control file descriptor. Process handles that -correspond to files and cores, created through +Only live processes have a control file descriptor. +Process handles that correspond to files and cores, created through .Xr Prab_file 3PROC and .Xr Pgrab_core 3PROC , @@ -50,8 +50,8 @@ or if control is lost and the handle is reopened. .Sh RETURN VALUES Upon successful completion, the .Fn Pctlfd -function returns a valid file descriptor. Otherwise, if none exists, -then +function returns a valid file descriptor. +Otherwise, if none exists, then .Sy -1 is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pdelbkpt.3proc b/usr/src/man/man3proc/Pdelbkpt.3proc index d999c38426..e00c5f7684 100644 --- a/usr/src/man/man3proc/Pdelbkpt.3proc +++ b/usr/src/man/man3proc/Pdelbkpt.3proc @@ -40,8 +40,8 @@ If the instruction at .Fa address is no longer the architecture-specific breakpoint instruction, then .Fa saved -is not restored, but the function still returns successfully. This -behavior is done due to the presence of setting breakpoints in +is not restored, but the function still returns successfully. +This behavior is done due to the presence of setting breakpoints in self-modifying code, e.g. procedure linkage tables. .Pp The diff --git a/usr/src/man/man3proc/Pdestroy_agent.3proc b/usr/src/man/man3proc/Pdestroy_agent.3proc index 9b379142cc..30c677204e 100644 --- a/usr/src/man/man3proc/Pdestroy_agent.3proc +++ b/usr/src/man/man3proc/Pdestroy_agent.3proc @@ -35,8 +35,8 @@ therefore if .Xr Pcreate_agent 3PROC has been called multiple times, the .Fn Pdestroy_agent -function must be called an equal number of times. Upon the last time, it -will destroy the agent LWP. +function must be called an equal number of times. +Upon the last time, it will destroy the agent LWP. .Pp Destroying the agent LWP does not change the state of the process represented by diff --git a/usr/src/man/man3proc/Penv_iter.3proc b/usr/src/man/man3proc/Penv_iter.3proc index 84fae69969..8dc616ee0f 100644 --- a/usr/src/man/man3proc/Penv_iter.3proc +++ b/usr/src/man/man3proc/Penv_iter.3proc @@ -35,18 +35,18 @@ For each environment variable, .Fa func is passed the caller argument .Fa data -along with the address of the environment variable and the key-value -pair. For the full signature of the +along with the address of the environment variable and the key-value pair. +For the full signature of the .Ft proc_env_f callback, see .Xr libproc 3LIB . .Pp -The callback's return value controls whether or not iteration -proceeds. If +The callback's return value controls whether or not iteration proceeds. +If .Fa func -returns zero, then iteration continues. Otherwise, iteration is -terminated and the value is returned. It is recommended that callback -functions do not return +returns zero, then iteration continues. +Otherwise, iteration is terminated and the value is returned. +It is recommended that callback functions do not return .Sy -1 so as to distinguish between the failure of the .Fn Penv_iter @@ -59,7 +59,8 @@ function returns Otherwise, if there was an internal error, for example due to a corrupted environment, then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Perror_printf.3proc b/usr/src/man/man3proc/Perror_printf.3proc index 4ad0b9de08..a71d6f3336 100644 --- a/usr/src/man/man3proc/Perror_printf.3proc +++ b/usr/src/man/man3proc/Perror_printf.3proc @@ -30,10 +30,12 @@ The function allows for consumers of the .Sy libproc library to obtain additional diagnostic information during various -operations. Consumers must explicitly +operations. +Consumers must explicitly .Em interpose -on this symbol and provide their own definition, if desired. There is no -requirement for such an interposition to be done. When called, +on this symbol and provide their own definition, if desired. +There is no requirement for such an interposition to be done. +When called, .Fa P will be the process handle that the additional diagnostics are being generated for and the diagnostics will be provided in a @@ -49,7 +51,7 @@ the provided diagnostics are and may change at any time. .Sh LOCKING Callers should presume that this function may be called from multiple -threads and always in a context in which taking locks is fine. Callers -should not expect to be called from a signal handler. +threads and always in a context in which taking locks is fine. +Callers should not expect to be called from a signal handler. .Sh SEE ALSO .Xr libproc 3LIB diff --git a/usr/src/man/man3proc/Pexecname.3proc b/usr/src/man/man3proc/Pexecname.3proc index d380333932..f7560c7396 100644 --- a/usr/src/man/man3proc/Pexecname.3proc +++ b/usr/src/man/man3proc/Pexecname.3proc @@ -41,9 +41,9 @@ bytes, including the null terminator. .Pp For a handle grabbed with .Xr Pgrab_file 3PROC , -the executable refers to the path of the file itself. For a core file, -the system attempts to determine the original path of the executable -and return that. +the executable refers to the path of the file itself. +For a core file, the system attempts to determine the original path of the +executable and return that. .Sh RETURN VALUES Upon successful completion, the .Fn Pexecname diff --git a/usr/src/man/man3proc/Pfault.3proc b/usr/src/man/man3proc/Pfault.3proc index 61c6454f02..7c1d8ed99e 100644 --- a/usr/src/man/man3proc/Pfault.3proc +++ b/usr/src/man/man3proc/Pfault.3proc @@ -34,34 +34,37 @@ function controls what the process should do on faults. .Pp A fault is a hardware event that occurs in the context of a running -process and thread. A hardware fault may occur because an illegal -instruction was executed, a breakpoint or watchpoint was encountered, or -an arithmetic exception occurred, among others. The full list of faults -is available in both +process and thread. +A hardware fault may occur because an illegal instruction was executed, +a breakpoint or watchpoint was encountered, or an arithmetic exception occurred, +among others. +The full list of faults is available in both .Xr proc 4 and .In sys/fault.h . .Pp For each hardware fault, a process may be configured to stop the thread -that encountered it when it occurs. The value of the +that encountered it when it occurs. +The value of the .Fa stop parameter controls whether or not the listed fault in .Fa which -will cause the thread to trap. A value of 1 indicates the thread -should stop; a value of 0 indicates it should not. +will cause the thread to trap. +A value of 1 indicates the thread should stop; a value of 0 indicates it should +not. .Pp The value of .Fa which -indicates which hardware fault the change applies to. However, if the -value of +indicates which hardware fault the change applies to. +However, if the value of .Fa which is zero, then it applies to all faults. .Pp The .Fn Pfault -function only applies to actively running processes. It does not -function on handles that refer to core files, zombie processes, or ELF -objects. +function only applies to actively running processes. +It does not function on handles that refer to core files, zombie processes, or +ELF objects. .Sh RETURN VALUES Upon successful completion, the .Fn Pfault @@ -70,7 +73,8 @@ function returns the old disposition of the fault -- if it was not set to stop and .Sy 1 if it was -- -and the fault state is updated. Otherwise, +and the fault state is updated. +Otherwise, .Sy -1 is returned, .Dv errno diff --git a/usr/src/man/man3proc/Pfdinfo_iter.3proc b/usr/src/man/man3proc/Pfdinfo_iter.3proc index 80408130a7..055355e00c 100644 --- a/usr/src/man/man3proc/Pfdinfo_iter.3proc +++ b/usr/src/man/man3proc/Pfdinfo_iter.3proc @@ -47,16 +47,19 @@ see .Pp The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 , -then iteration will continue. However, if +then iteration will continue. +However, if .Fa func instead returns a non-zero value, then iteration will halt and that value will be used as the return value of the .Fn Pfdinfo_iter -function. Because the +function. +Because the .Fn Pfdinfo_iter function returns .Sy -1 @@ -74,7 +77,8 @@ returns .Sy 0 . Otherwise, if there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pgcore.3proc b/usr/src/man/man3proc/Pgcore.3proc index 24f38c3f6d..732331b7ff 100644 --- a/usr/src/man/man3proc/Pgcore.3proc +++ b/usr/src/man/man3proc/Pgcore.3proc @@ -44,7 +44,8 @@ wide variety of tools and libraries including .Xr mdb 1 , .Xr pargs 1 , .Xr pstack 1 , -and more. For details on the core file format, see +and more. +For details on the core file format, see .Xr core 4 . .Pp .Fn Pfgcore @@ -57,8 +58,8 @@ writes the core to the file path .Pp The content of the core is controlled by the .Fa content -argument. It's the inclusive-bitwise-OR of the various content types -listed under the +argument. +It's the inclusive-bitwise-OR of the various content types listed under the .Sy core_content_t heading in the .Sy TYPES @@ -75,7 +76,8 @@ or functions stop the handle .Fa P . It is up to the caller to stop the process; which is recommended for -obtaining a consistent view of the process. See the +obtaining a consistent view of the process. +See the .Xr Pstop 3PROC function for a means to stop a handle. .Sh RETURN VALUES @@ -85,9 +87,11 @@ and .Fn Pgcore functions return .Sy 0 -and write out a core file to specified location. Otherwise, +and write out a core file to specified location. +Otherwise, .Sy -1 -is returned. The +is returned. +The .Fn Pfgcore function will truncate .Fa fd diff --git a/usr/src/man/man3proc/Pgetareg.3proc b/usr/src/man/man3proc/Pgetareg.3proc index 1d8a67ca75..254530b6d6 100644 --- a/usr/src/man/man3proc/Pgetareg.3proc +++ b/usr/src/man/man3proc/Pgetareg.3proc @@ -57,8 +57,8 @@ to by .Fa P . .Pp The getting and setting of registers of the process operates on the -representative thread (LWP). For more information on how the -representative is chosen, see +representative thread (LWP). +For more information on how the representative is chosen, see .Xr proc 4 . To change the registers of a specific thread, use the .Xr Lgetareg 3PROC @@ -66,17 +66,19 @@ and .Xr Lsetareg 3PROC functions. .Pp -The getting and setting of registers only applies to stopped -processes. In addition, one may obtain registers from core files, but -not set them. To stop a process, see the +The getting and setting of registers only applies to stopped processes. +In addition, one may obtain registers from core files, but not set them. +To stop a process, see the .Xr Pstop 3PROC function. .Pp The register to get or set is indicated by the .Fa regno -argument. For a list of registers, see +argument. +For a list of registers, see .In sys/regset.h . -The set of registers is specific to each architecture of the system. The +The set of registers is specific to each architecture of the system. +The .Fn Pgetareg function will fill in the value of .Fa preg @@ -123,7 +125,8 @@ functions will fail if: .It Er EINVAL The value of .Fa regno -is invalid. This means it is less than +is invalid. +This means it is less than .Sy 0 and greater than .Sy NPRGREG . @@ -150,7 +153,8 @@ functions will fail if: .It Er EINVAL The value of .Fa regno -is invalid. This means it is less than +is invalid. +This means it is less than .Sy 0 and greater than .Sy NPRGREG . diff --git a/usr/src/man/man3proc/Pgetauxval.3proc b/usr/src/man/man3proc/Pgetauxval.3proc index 034d68c7f3..2d6122bfe7 100644 --- a/usr/src/man/man3proc/Pgetauxval.3proc +++ b/usr/src/man/man3proc/Pgetauxval.3proc @@ -32,10 +32,11 @@ function looks up the entry .Fa type in the auxiliary vector of the process handle .Fa P -and returns its value. The +and returns its value. +The .Fa type -argument should be the entry of the auxiliary vector. The list of such -types may be found in +argument should be the entry of the auxiliary vector. +The list of such types may be found in .In sys/auxv.h . .Sh RETURN VALUES Upon successful completion, the diff --git a/usr/src/man/man3proc/Pgetauxvec.3proc b/usr/src/man/man3proc/Pgetauxvec.3proc index a940bdfdcf..348e01ea15 100644 --- a/usr/src/man/man3proc/Pgetauxvec.3proc +++ b/usr/src/man/man3proc/Pgetauxvec.3proc @@ -32,7 +32,8 @@ process handle .Fa P . If the process handle does not represent an actively running process or the auxiliary vector could not be found, then it instead returns an -empty auxiliary vector. The definitions of the +empty auxiliary vector. +The definitions of the .Sy auxv_t may be found in .In sys/auxv.h . diff --git a/usr/src/man/man3proc/Pgrab.3proc b/usr/src/man/man3proc/Pgrab.3proc index 3627d1712f..a6df2614e1 100644 --- a/usr/src/man/man3proc/Pgrab.3proc +++ b/usr/src/man/man3proc/Pgrab.3proc @@ -32,8 +32,9 @@ The function attempts to grab the process identified by .Fa pid and returns a handle to it that allows the process to be controlled, -interrogated, and manipulated. This interface only works with processes -that already exist. Use +interrogated, and manipulated. +This interface only works with processes that already exist. +Use .Xr Pgrab_core 3PROC for core files and .Xr Pcreate 3PROC @@ -48,38 +49,41 @@ The process is stopped .It All other tracing flags are cleared .It -The grab is exclusive. If any existing handles to this process exist -or anyone else is using the underlying facilities of the /proc file -system to control this process, it will fail. +The grab is exclusive. +If any existing handles to this process exist or anyone else is using the +underlying facilities of the /proc file system to control this process, +it will fail. .It Unless the process is already stopped, the .Dv PR_RLC -flag is set indicating the process should run-on-last-close. Allowing -the process to resume running if its controlling process dies. +flag is set indicating the process should run-on-last-close. +Allowing the process to resume running if its controlling process dies. .El .Pp Grabbing a process is a .Em destructive -action. Stopping a process stops execution of all its threads. The -impact of stopping a process depends on the purpose of that process. +action. +Stopping a process stops execution of all its threads. +The impact of stopping a process depends on the purpose of that process. For example, if one stops a process that's primarily doing computation, then its computation is delayed the entire time that it -is stopped. However, if instead this is an active TCP server, then the -accept backlog may fill causing connection errors and potentially -connection time out errors. +is stopped. +However, if instead this is an active TCP server, then the accept backlog may +fill causing connection errors and potentially connection time out errors. .Pp Special care must be taken to ensure that a stopped process continues, -even if the controlling process terminates. If the controlling process -disables the +even if the controlling process terminates. +If the controlling process disables the .Dv PR_RLC flag or the process was already stopped, then the process remains -stopped after the controlling process terminates. Exercise caution -when changing this behavior. +stopped after the controlling process terminates. +Exercise caution when changing this behavior. .Pp Many of these default behaviors can be controlled by passing values to the .Fa flags -argument. Values for +argument. +Values for .Fa flags are constructed by a bitwise-inclusive-OR of flags from the following list: @@ -87,17 +91,18 @@ list: .It Dv PGRAB_RETAIN Indicates that any existing tracing flags on .Fa pid -should be retained. If this flag is not specified, they will be cleared -as part of creating the +should be retained. +If this flag is not specified, they will be cleared as part of creating the .Sy libproc handle for this process. .Pp Normally extant tracing flags are cleared when a process is grabbed. .It Dv PGRAB_FORCE -Indicates that the process should not be grabbed exclusively. Care -should be taken with this option. If other consumers are manipulating -the process, then this may result in surprising behavior as the process -is being manipulated from multiple points of control at the same time. +Indicates that the process should not be grabbed exclusively. +Care should be taken with this option. +If other consumers are manipulating the process, then this may result in +surprising behavior as the process is being manipulated from multiple points of +control at the same time. .Pp Normally an attempt will be made to grab the process exclusively and fail if it is already in use. @@ -107,15 +112,15 @@ This implies that both the .Dv PGRAB_RETAIN and .Dv PGRAB_NOSTOP -flags should be set. If a process is opened read-only, then a caller can -only read information about a process and cannot manipulate it, change -its current state, or inject systems calls into it. +flags should be set. +If a process is opened read-only, then a caller can only read information about +a process and cannot manipulate it, change its current state, or inject systems +calls into it. .Pp -Normally when a process is grabbed, it does so for both reading and -writing. +Normally when a process is grabbed, it does so for both reading and writing. .It Dv PGRAB_NOSTOP -Do not stop a process as it is grabbed. Note, any extant tracing flags -on the process will still be cleared unless the +Do not stop a process as it is grabbed. +Note, any extant tracing flags on the process will still be cleared unless the .Dv PGRAB_RETAIN flag has been set. .Pp @@ -128,31 +133,34 @@ argument must be a .Pf non- Dv NULL pointer which will store a more detailed error in the event that the .Fn Pgrab -function fails. A human-readable form of the error can be obtained -with +function fails. +A human-readable form of the error can be obtained with .Xr Pgrab_error 3PROC . .Pp Once a caller is done with the library handle it should call .Xr Prelease 3PROC -to release the grabbed process. Failure to properly release the handle -may leave a process stopped and interfere with the ability of other -software to obtain a handle. +to release the grabbed process. +Failure to properly release the handle may leave a process stopped and interfere +with the ability of other software to obtain a handle. .Ss Permissions Unprivileged users may grab and control their own processes only if both the user and group IDs of the target process match those of the calling -process. In addition, the caller must have a super set of the target's -privileges. Processes with the +process. +In addition, the caller must have a super set of the target's privileges. +Processes with the .Sy PRIV_PROC_OWNER privilege may manipulate any process on the system, as long as it has an -equal privilege set. For more details on the security and programming -considerations, please see the section +equal privilege set. +For more details on the security and programming considerations, please see the +section .Sy PROGRAMMING NOTES in .Xr proc 4 . .Sh RETURN VALUES Upon successful completion, the .Fn Pgrab -function returns a control handle to the process. Otherwise, +function returns a control handle to the process. +Otherwise, .Dv NULL is returned with .Fa perr @@ -174,7 +182,8 @@ The calling process is a 32-bit process and process .Fa pid is 64-bit. .It Er G_NOFD -Too many files are open. This is logically equivalent to receiving +Too many files are open. +This is logically equivalent to receiving .Er EMFILE . .It Er G_NOPROC The process referred to by @@ -182,7 +191,8 @@ The process referred to by does not exist. .It Er G_PERM The calling process has insufficient permissions or privileges to open -the specified process. See +the specified process. +See .Sx Permissions for more information. .It Er G_SYS @@ -194,7 +204,8 @@ The process referred to by .Fa pid is the process ID of the caller and the .Dv PGRAB_RDONLY -was not passed. A process may only grab itself if it's read-only. +was not passed. +A process may only grab itself if it's read-only. .It Er G_STRANGE An unanticipated system error occurred while trying to grab the process file and create the handle. diff --git a/usr/src/man/man3proc/Pgrab_core.3proc b/usr/src/man/man3proc/Pgrab_core.3proc index cf28387c03..2b864bd563 100644 --- a/usr/src/man/man3proc/Pgrab_core.3proc +++ b/usr/src/man/man3proc/Pgrab_core.3proc @@ -39,11 +39,12 @@ The .Fn Pgrab_core and .Fn Pfgrab_core -functions open a core file for introspection. Unlike live processes, -core files cannot have their state modified; however, all of the -functions that iterate or query state will work. These functions work -on all illumos core files and the core files of some other operating -systems. See both +functions open a core file for introspection. +Unlike live processes, core files cannot have their state modified; +however, all of the functions that iterate or query state will work. +These functions work on all illumos core files and the core files of some other +operating systems. +See both .Xr core 4 and the .Em Core Files @@ -58,17 +59,18 @@ function attempts to open the core file specified by The system attempts to determine the path of the original executable. The argument .Fa aout -may either be the path to that file, a path to a directory to -search, or the +may either be the path to that file, a path to a directory to search, or the .Dv NULL -pointer, if neither is known. The system will search for it and will -supplement information in the core file with that. +pointer, if neither is known. +The system will search for it and will supplement information in the core file +with that. .Pp The .Fa gflag argument to the .Fn Pgrab_core -function controls how the file is opened. If the +function controls how the file is opened. +If the .Dv PGRAB_RDONLY flag is specified, then the core file will be opened with the .Xr open 2 @@ -83,16 +85,17 @@ argument must be a .Pf non- Dv NULL pointer which will store a more detailed error in the event that the .Fn Pgrab_core -function fails. A human-readable form of the error can be obtained -through the routine +function fails. +A human-readable form of the error can be obtained through the routine .Xr Pgrab_error 3PROC . .Pp The .Fn Pfgrab_core is similar to the .Fn Pgrab_core -function. Except, instead of operating on a path, it opens a handle to -the core file referenced by +function. +Except, instead of operating on a path, it opens a handle to the core file +referenced by .Fa core_fd . The .Fa aout @@ -114,7 +117,8 @@ and .Fn Pfgrab_core functions return a .Sy libproc -handle to the core file. Otherwise, +handle to the core file. +Otherwise, .Dv NULL is returned and .Fa perr diff --git a/usr/src/man/man3proc/Pgrab_error.3proc b/usr/src/man/man3proc/Pgrab_error.3proc index 30bfa23f32..01be5d1ccf 100644 --- a/usr/src/man/man3proc/Pgrab_error.3proc +++ b/usr/src/man/man3proc/Pgrab_error.3proc @@ -28,8 +28,8 @@ The .Fn Pgrab_error function returns a pointer to a human-readable character string -describing the error that occurred. This function only knows how to -translate errors that are stored in +describing the error that occurred. +This function only knows how to translate errors that are stored in .Fa perr during a failed call to .Xr Pgrab 3PROC , diff --git a/usr/src/man/man3proc/Pgrab_file.3proc b/usr/src/man/man3proc/Pgrab_file.3proc index d12e052697..8c883d9677 100644 --- a/usr/src/man/man3proc/Pgrab_file.3proc +++ b/usr/src/man/man3proc/Pgrab_file.3proc @@ -36,13 +36,13 @@ handle, it allows one to inspect aspects of the ELF contents present in the handle, for example obtaining CTF information and looking up symbols. .Pp -There is no running state associated with this handle nor can -there be. If one intends to control a running process or create a -process, see +There is no running state associated with this handle nor can there be. +If one intends to control a running process or create a process, see .Xr Pgrab 3PROC and .Xr Pcreate 3PROC -respectively. To inspect a core file use +respectively. +To inspect a core file use .Xr Pgrab_core 3PROC . .Pp The @@ -51,7 +51,8 @@ argument must be a .Pf non- Dv NULL pointer which will store a more detailed error in the event that .Fn Pgrab_file -fails. A human-readable form of the error can be obtained with +fails. +A human-readable form of the error can be obtained with .Xr Pgrab_error 3PROC . .Pp When finished with the returned handle, @@ -60,7 +61,8 @@ must be called to clean up resources associated with it. .Sh RETURN VALUES Upon successful completion, the .Fn Pgrab_file -function returns a control handle to the process. Otherwise, +function returns a control handle to the process. +Otherwise, .Dv NULL is returned and .Fa perr diff --git a/usr/src/man/man3proc/Pisprocdir.3proc b/usr/src/man/man3proc/Pisprocdir.3proc index daa3569c8f..18aef39e5a 100644 --- a/usr/src/man/man3proc/Pisprocdir.3proc +++ b/usr/src/man/man3proc/Pisprocdir.3proc @@ -30,8 +30,8 @@ The .Fn Pisprocdir function determines whether or not the directory .Fa dir -is the root of the /proc file-system. This works across loopback file -system (lofs) mounts and chroots. +is the root of the /proc file-system. +This works across loopback file system (lofs) mounts and chroots. .Sh RETURN VALUES Upon successful completion, the .Fn Pisprocdir diff --git a/usr/src/man/man3proc/Pissyscall.3proc b/usr/src/man/man3proc/Pissyscall.3proc index 9ec1ba29d3..58b4d36950 100644 --- a/usr/src/man/man3proc/Pissyscall.3proc +++ b/usr/src/man/man3proc/Pissyscall.3proc @@ -16,7 +16,7 @@ .Os .Sh NAME .Nm Pissyscall , -.Nm Pissyscall_prev , +.Nm Pissyscall_prev .Nd determine if instructions are system call instructions .Sh SYNOPSIS .Lb libproc @@ -47,8 +47,8 @@ function determines whether or not the instruction before .Fa addr in the process handle .Fa P -corresponds to one of the architecture's system call instructions. If it -does, and +corresponds to one of the architecture's system call instructions. +If it does, and .Fa dst is a .Pf non- Dv NULL @@ -62,7 +62,8 @@ function returns .Sy non-zero if .Fa addr -corresponds to a system call instruction. Otherwise, +corresponds to a system call instruction. +Otherwise, .Sy 0 is returned. .Pp @@ -77,7 +78,8 @@ corresponds to a system call instruction and if is .Pf non- Dv NULL , .Fa dst -is updated. Otherwise, +is updated. +Otherwise, .Sy 0 is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pldt.3proc b/usr/src/man/man3proc/Pldt.3proc index f492497ba3..c39a0b6371 100644 --- a/usr/src/man/man3proc/Pldt.3proc +++ b/usr/src/man/man3proc/Pldt.3proc @@ -60,7 +60,8 @@ The buffer .Fa pldt should contain sufficient space for .Fa nldt -entries. For example, callers could allocate space as: +entries. +For example, callers could allocate space as: .Pp .Dl pldt = malloc(sizeof (struct ssd) * nldt); .Pp @@ -91,9 +92,11 @@ is .Dv NULL or .Fa nldt -is zero, then no data will be written. Otherwise, +is zero, then no data will be written. +Otherwise, .Sy -1 -is returned. The +is returned. +The .Fn Pldt function sets .Sy errno diff --git a/usr/src/man/man3proc/Plookup_by_addr.3proc b/usr/src/man/man3proc/Plookup_by_addr.3proc index 6502956de4..5c0d2355c7 100644 --- a/usr/src/man/man3proc/Plookup_by_addr.3proc +++ b/usr/src/man/man3proc/Plookup_by_addr.3proc @@ -78,8 +78,8 @@ functions look up symbol information in the process handle .Fa P and fill in the ELF symbol information in .Fa symp -with the found symbol. Symbols may be looked up both by address and -name. +with the found symbol. +Symbols may be looked up both by address and name. .Pp The .Fn Plookup_by_addr @@ -97,7 +97,8 @@ function is identical to the .Fn Plookup_by_addr function, except that it also fills in the structure .Fa sip -with additional information. The definition of the +with additional information. +The definition of the .Sy prsyminfo_t is found in .Xr libproc 3PROC . @@ -112,16 +113,19 @@ to an absolute path on the file system. .Pp The .Fn Plookup_by_name -function attempts to look up a symbol based on its name. The +function attempts to look up a symbol based on its name. +The .Fa object argument allows the caller to specify a specific object that was mapped in by the run-time link-editor to search for .Fa symbol -in. The system provides three special values which may be passed in for +in. +The system provides three special values which may be passed in for .Fa object . The value .Dv PR_OBJ_EXEC -refers to the executable's object (a.out). The value +refers to the executable's object (a.out). +The value .Dv PR_OBJ_LDSO refers to the object .Sy ld.so.1 . @@ -147,16 +151,18 @@ and symbol named .Fa symbol to the specified link-map. .Pp -There are three special link-map identifiers -that may be passed in. The symbol +There are three special link-map identifiers that may be passed in. +The symbol .Dv PR_LMID_EVERY -indicates that every link-map should be searched. The symbol +indicates that every link-map should be searched. +The symbol .Dv LM_ID_BASE indicates that the base link-map, the one that is used for the -executable should be searched. Finally, the symbol +executable should be searched. +Finally, the symbol .Dv LM_ID_LDSO -refers to the link-map that is used by the run-time link editor, -ld.so.1. The +refers to the link-map that is used by the run-time link editor, ld.so.1. +The .Fn Plookup_by_name function behaves like .Fn Pxlookup_by_name @@ -175,7 +181,8 @@ and .Fn Pxlookup_by_name functions return .Sy 0 -and fill in the symbol information. Otherwise, +and fill in the symbol information. +Otherwise, .Sy -1 is returned to indicate that the symbol could not be found. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Plwp_getasrs.3proc b/usr/src/man/man3proc/Plwp_getasrs.3proc index 7630857461..85fa41e910 100644 --- a/usr/src/man/man3proc/Plwp_getasrs.3proc +++ b/usr/src/man/man3proc/Plwp_getasrs.3proc @@ -46,14 +46,16 @@ in the process handle .Pp The ancillary state registers are only present on 64-bit .Sy SPARCv9 -processes. They contain information that is specific to the platform and -are not included in the information obtained through functions such as +processes. +They contain information that is specific to the platform and are not included +in the information obtained through functions such as .Xr Plwp_getregs 3PROC , .Xr Plwp_getfpregs 3PROC , and .Xr Plwp_getxregs 3PROC . .Pp -The Plwp_getasrs +The +.Fn Plwp_getasrs function reads the ancillary registers into .Fa asrs , while the @@ -62,7 +64,8 @@ sets the thread's ancillary registers to the values provided by .Fa asrs . .Pp Processes should be stopped prior to obtaining the register state of -individual threads. Processes may be stopped with +individual threads. +Processes may be stopped with .Xr Pstop 3PROC . .Pp The @@ -79,7 +82,8 @@ and .Fn Plwp_setasrs functions return .Sy 0 -and get or set the register state. Otherwise, +and get or set the register state. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getgwindows.3proc b/usr/src/man/man3proc/Plwp_getgwindows.3proc index f6a4234d84..173406352b 100644 --- a/usr/src/man/man3proc/Plwp_getgwindows.3proc +++ b/usr/src/man/man3proc/Plwp_getgwindows.3proc @@ -42,7 +42,8 @@ function returns .Sy 0 and .Fa gwins -is filled in with information about the windows. Otherwise, +is filled in with information about the windows. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getpsinfo.3proc b/usr/src/man/man3proc/Plwp_getpsinfo.3proc index c798a1dd91..4d7d64fca7 100644 --- a/usr/src/man/man3proc/Plwp_getpsinfo.3proc +++ b/usr/src/man/man3proc/Plwp_getpsinfo.3proc @@ -60,7 +60,8 @@ and is filled in with the thread-specific .Xr ps 1 -information. Otherwise, +information. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getregs.3proc b/usr/src/man/man3proc/Plwp_getregs.3proc index 70115f4b4b..5d4e7766f7 100644 --- a/usr/src/man/man3proc/Plwp_getregs.3proc +++ b/usr/src/man/man3proc/Plwp_getregs.3proc @@ -92,7 +92,8 @@ to the register state contained in .Fa gregs . .Pp Processes must be stopped before obtaining the register state of -individual threads. Processes may be stopped with +individual threads. +Processes may be stopped with .Xr Pstop 3PROC . The structures used for registers are described in .Xr proc 4 @@ -112,7 +113,8 @@ and .Fn Plwp_setfpregs functions return .Sy 0 -and obtain or set the register state. Otherwise, +and obtain or set the register state. +Otherwise, .Sy -1 is returned, .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getspymaster.3proc b/usr/src/man/man3proc/Plwp_getspymaster.3proc index 67244077d1..7810b402b0 100644 --- a/usr/src/man/man3proc/Plwp_getspymaster.3proc +++ b/usr/src/man/man3proc/Plwp_getspymaster.3proc @@ -35,11 +35,11 @@ the agent LWP for the thread in the process handle .Fa P . .Pp -The agent LWP allows another process to inject actions into the target -process. When an agent LWP is created, it leverages an existing thread -in the process and it also creates a record of whom created the agent, -which is called the spy master. For more information on the agent LWP -and the spy master, see +The agent LWP allows another process to inject actions into the target process. +When an agent LWP is created, it leverages an existing thread in the process and +it also creates a record of whom created the agent, which is called the spy +master. +For more information on the agent LWP and the spy master, see .Xr proc 4 . .Pp If the thread identified @@ -54,8 +54,9 @@ will be filled into Note, process handles that correspond to a file, created by .Xr Pgrab_file 3PROC , cannot have an agent LWP created for them and thus cannot have any spy -master information. In addition, core files from older releases may not -have any data on the spy master. +master information. +In addition, core files from older releases may not have any data on the spy +master. .Sh RETURN VALUES Upon successful completion, the .Fn Plwp_getspymaster diff --git a/usr/src/man/man3proc/Plwp_getxregs.3proc b/usr/src/man/man3proc/Plwp_getxregs.3proc index 0445251578..e1801eedda 100644 --- a/usr/src/man/man3proc/Plwp_getxregs.3proc +++ b/usr/src/man/man3proc/Plwp_getxregs.3proc @@ -43,8 +43,8 @@ functions get and set the extended register state of the thread in the process handle .Fa P . .Pp -The extended register state is defined by the architecture. These -registers may refer to optional registers that have become common on the +The extended register state is defined by the architecture. +These registers may refer to optional registers that have become common on the platform, but are not part of the standard ABI and thus not covered by functions such as .Xr Plwp_getregs 3PROC @@ -63,7 +63,8 @@ for the process handle .Fa P . .Pp Processes must be stopped prior to obtaining the register state of -individual threads. Processes may be stopped with +individual threads. +Processes may be stopped with .Xr Pstop 3PROC . .Pp The @@ -80,7 +81,8 @@ and .Fn Plwp_setxregs functions return .Sy 0 -and get or set the register state. Otherwise, +and get or set the register state. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_iter.3proc b/usr/src/man/man3proc/Plwp_iter.3proc index 3ad0f1219b..15de2f12ea 100644 --- a/usr/src/man/man3proc/Plwp_iter.3proc +++ b/usr/src/man/man3proc/Plwp_iter.3proc @@ -53,7 +53,8 @@ is called with the pointer to the private data argument, .Fa data , and the thread's .Sy lwpstatus_t -structure. In the case of the +structure. +In the case of the .Fn Plwp_iter_all function, the thread's .Sy lwpsinfo_t @@ -61,18 +62,21 @@ is also included. .Pp The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 , -then both functions will continue iteration. However, if +then both functions will continue iteration. +However, if .Fa func returns non-zero, then iteration will halt and that value will be used as the return value of the .Fn Plwp_iter and .Fn Plwp_iter_all -functions. Because both functions return +functions. +Because both functions return .Sy -1 on internal failure, it is recommended that the callback function does not return @@ -92,7 +96,8 @@ functions return .Sy 0 . Otherwise, if there was an internal error or there is no thread data, then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Plwp_stack.3proc b/usr/src/man/man3proc/Plwp_stack.3proc index 1e8c189a9f..2cf3303ed2 100644 --- a/usr/src/man/man3proc/Plwp_stack.3proc +++ b/usr/src/man/man3proc/Plwp_stack.3proc @@ -73,7 +73,8 @@ in the process handle Each thread in a process has its own stack which is used both for maintaining function call sequences and the storing of local variables. A thread may also configure a different stack to handle specific -signals. This stack is often called the +signals. +This stack is often called the .Em alternate stack . Whether or not the alternate stack is used may be controlled through the .Xr sigaction 2 @@ -134,7 +135,8 @@ functions return .Sy 0 and fills in .Fa stkp -with information about the appropriate stack. Otherwise, +with information about the appropriate stack. +Otherwise, .Sy -1 is returned, .Sy errno diff --git a/usr/src/man/man3proc/Pmapping_iter.3proc b/usr/src/man/man3proc/Pmapping_iter.3proc index b60d06ad50..7f2fb46124 100644 --- a/usr/src/man/man3proc/Pmapping_iter.3proc +++ b/usr/src/man/man3proc/Pmapping_iter.3proc @@ -64,16 +64,17 @@ the .Sy prmap_t structure defined from .Xr proc 4 , -and a name of the mapping. The way that the name is obtained varies -based on whether one calls +and a name of the mapping. +The way that the name is obtained varies based on whether one calls .Fn Pmapping_iter or .Fn Pmapping_iter_resolved . In both cases, the dynamic linker is consulted to determine the file -name for the mapping, if it's known. If the name is unknown, for example -an anonymous mapping, then the +name for the mapping, if it's known. +If the name is unknown, for example an anonymous mapping, then the .Dv NULL -pointer is passed in for the name. In the case of the +pointer is passed in for the name. +In the case of the .Fn Pmapping_iter_resolved function the system tries to resolve it to a complete file system path. If that fails, it falls back to the information from the dynamic linker, @@ -88,20 +89,24 @@ see .Pp The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 -then iteration continues. If +then iteration continues. +If .Fa func returns non-zero then iteration will halt and the value will be -returned to the caller. Because +returned to the caller. +Because .Sy -1 -indicates internal failure, it is recommended that the callback -function not return +indicates internal failure, it is recommended that the callback function not +return .Sy -1 -to indicate an error itself. This allows the caller to distinguish -between failure of the callback function versus failure of the +to indicate an error itself. +This allows the caller to distinguish between failure of the callback function +versus failure of the .Fn Pmapping_iter and .Fn Pmapping_iter_resolved @@ -115,13 +120,13 @@ functions are similar to the .Fn Pmapping_iter and .Fn Pmapping_iter_resolved -functions. Except, rather than iterating over every mapping, they -iterate over the objects that the process has loaded by the dynamic -linker. For example, an anonymous mapping will show up when iterating -mappings, but will not show up when iterating objects. Further, while -most dynamic shared objects have multiple mappings for the text and -data sections, there will only be a single object that is iterated -over. +functions. +Except, rather than iterating over every mapping, they iterate over the objects +that the process has loaded by the dynamic linker. +For example, an anonymous mapping will show up when iterating mappings, but will +not show up when iterating objects. +Further, while most dynamic shared objects have multiple mappings for the text +and data sections, there will only be a single object that is iterated over. .Pp The distinction between the .Fn Pobject_iter @@ -143,7 +148,8 @@ functions return .Sy 0. Otherwise, if there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pobjname.3proc b/usr/src/man/man3proc/Pobjname.3proc index cd97e41ce7..4b75abb31a 100644 --- a/usr/src/man/man3proc/Pobjname.3proc +++ b/usr/src/man/man3proc/Pobjname.3proc @@ -16,7 +16,7 @@ .Os .Sh NAME .Nm Pobjname , -.Nm Pobjname_resolved , +.Nm Pobjname_resolved .Nd turn a virtual address into its mapped object .Sh SYNOPSIS .Lb libproc @@ -46,9 +46,9 @@ contains the virtual address in the process handle .Fa P . .Pp -A program consists of multiple memory mappings. Some are provided by the -system, such as the stack and the heap. While others are created through -explicit calls to +A program consists of multiple memory mappings. +Some are provided by the system, such as the stack and the heap. +While others are created through explicit calls to .Xr mmap 2 or brought in by the run-time link-editor due to dependencies specified in binaries and libraries. @@ -62,8 +62,8 @@ of the name of the corresponding object will be written into .Fa buffer . The .Fn Pobjname_resolved -function attempts to resolve the object to a full file system path. If -the full file-system path cannot be determined, then it will fall back +function attempts to resolve the object to a full file system path. +If the full file-system path cannot be determined, then it will fall back to the name that the run-time link-editor has for that mapping, which is the behavior of .Fn Pobjname . diff --git a/usr/src/man/man3proc/Ppltdest.3proc b/usr/src/man/man3proc/Ppltdest.3proc index efdca692dc..56eea82f85 100644 --- a/usr/src/man/man3proc/Ppltdest.3proc +++ b/usr/src/man/man3proc/Ppltdest.3proc @@ -34,8 +34,8 @@ in the process handle .Fa P corresponds to an entry in the procedure linkage table (PLT) and if so, returns a pointer to a null-terminated character string that contains -the symbol's name. The returned pointer is not valid after any other -calls to function in +the symbol's name. +The returned pointer is not valid after any other calls to function in .Xr libproc 3LIB . The .Fn Ppltdest @@ -45,7 +45,8 @@ corresponds to an address in the PLT. .Sh RETURN VALUES Upon successful completion, the .Fn Ppltdest -returns a pointer to a character string with the name. Otherwise, +returns a pointer to a character string with the name. +Otherwise, .Dv NULL is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Ppriv.3proc b/usr/src/man/man3proc/Ppriv.3proc index ae238eae67..f7adf48756 100644 --- a/usr/src/man/man3proc/Ppriv.3proc +++ b/usr/src/man/man3proc/Ppriv.3proc @@ -59,7 +59,8 @@ function returns .Sy 0 and .Fa pprv -is updated with a pointer to the allocated privilege set. Otherwise, +is updated with a pointer to the allocated privilege set. +Otherwise, .Sy -1 is returned and .Fa pprv diff --git a/usr/src/man/man3proc/Ppsinfo.3proc b/usr/src/man/man3proc/Ppsinfo.3proc index f86572f9f6..7032494b06 100644 --- a/usr/src/man/man3proc/Ppsinfo.3proc +++ b/usr/src/man/man3proc/Ppsinfo.3proc @@ -30,7 +30,8 @@ The function returns the process handle .Fa P Ns 's .Xr ps 1 -information. The +information. +The .Sy psinfo_t structure that is returned is defined in .Xr proc 4 @@ -39,7 +40,8 @@ and is valid until a subsequent call to .Sh RETURN VALUES Upon successful completion, the .Fn Ppsinfo -function returns a pointer to the process ps information. Otherwise, +function returns a pointer to the process ps information. +Otherwise, .Dv NULL is returned to indicate that it could not be found. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Prd_agent.3proc b/usr/src/man/man3proc/Prd_agent.3proc index 78438621c5..412ef9b04a 100644 --- a/usr/src/man/man3proc/Prd_agent.3proc +++ b/usr/src/man/man3proc/Prd_agent.3proc @@ -43,8 +43,8 @@ is released through a call to .Sh RETURN VALUES Upon successful completion, the .Fn Prd_agent -function returns a pointer to the librtld_db agent. Otherwise, it -returns +function returns a pointer to the librtld_db agent. +Otherwise, it returns .Dv NULL to indicate failure. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pread.3proc b/usr/src/man/man3proc/Pread.3proc index 8b4eb52da8..5a1e449c31 100644 --- a/usr/src/man/man3proc/Pread.3proc +++ b/usr/src/man/man3proc/Pread.3proc @@ -50,14 +50,15 @@ and is logically analogous to the .Xr pread 2 function. .Pp -For live processes, this function is equivalent to reading from the -/proc file system +For live processes, this function is equivalent to reading from the /proc file +system .Sy as -file for the process. For core files and file handles, it reads and -writes from the logical address space and not the corresponding offset -of the file itself. For example, a core file contains a sparse -representation of the address space of a crashed process and unmapped -regions are not present in the file. However, +file for the process. +For core files and file handles, it reads and writes from the logical address +space and not the corresponding offset of the file itself. +For example, a core file contains a sparse representation of the address space +of a crashed process and unmapped regions are not present in the file. +However, .Fa address still refers to the virtual addresses that were present at run-time and not those in the core file. @@ -73,7 +74,8 @@ into .Fa buf if either .Fa nbytes -has been read or a null terminator is encountered. The resulting data in +has been read or a null terminator is encountered. +The resulting data in .Fa buf will always be null terminated, even if no null terminator was found in the first @@ -85,7 +87,8 @@ Upon successful completion, the and .Fn Pread_string functions return a non-negative integer indicating the number of bytes -actually read. Otherwise, the functions return +actually read. +Otherwise, the functions return .Sy -1 and set .Sy errno diff --git a/usr/src/man/man3proc/Prelease.3proc b/usr/src/man/man3proc/Prelease.3proc index d201d198ac..3d66a0d560 100644 --- a/usr/src/man/man3proc/Prelease.3proc +++ b/usr/src/man/man3proc/Prelease.3proc @@ -35,8 +35,9 @@ The .Fn Prelease function is used to release all of the resources associated with a .Nm libproc -handle. It is suitable for handles to core files, created processes, and -grabbed processes from the +handle. +It is suitable for handles to core files, created processes, and grabbed +processes from the .Xr Pgrab_core 3PROC , .Xr Pcreate 3PROC , .Xr Pgrab 3PROC , @@ -47,7 +48,8 @@ functions. After calling the .Fn Prelease function, all data that was returned via the handle will no longer be -valid. For example, the data from calls to +valid. +For example, the data from calls to .Xr Pctlfd 3PROC , .Xr Pgetauxvec 3PROC , .Xr Pstatus 3PROC , @@ -55,16 +57,16 @@ and others. .Pp The behavior of the released process is controlled by the .Fa flags -argument. By default, if no flags are passed, then the process -represented by +argument. +By default, if no flags are passed, then the process represented by .Fa P will be set running if it was created by -.Xr Pcreate -or if it was not originally stopped or set to stop in /proc. The -following values may be passed in to the +.Xr Pcreate 3PROC +or if it was not originally stopped or set to stop in /proc. +The following values may be passed in to the .Fa flags -argument. Multiple flags should be be combined with a -bitwise-inclusive-OR. +argument. +Multiple flags should be be combined with a bitwise-inclusive-OR. .Bl -tag -width Er -offset indent .It Dv PRELEASE_CLEAR When releasing the process, clear all tracing flags that are set on the @@ -73,14 +75,14 @@ process. When releasing the process, retain all tracing flags that are currently active on the process. .It Dv PRELEASE_HANG -Leave the process stopped. It will not resume execution unless it is -explicitly enabled with +Leave the process stopped. +It will not resume execution unless it is explicitly enabled with .Xr prun 1 or another process explicitly enables it. .It Dv PRELEASE_KILL Release the process and terminate it with -.Dv SIGKILL . This option takes precedence over all other values that may -be passed in to +.Dv SIGKILL . +This option takes precedence over all other values that may be passed in to .Fa flags . .El .Pp @@ -94,7 +96,8 @@ handle however, unlike the .Fn Prelease function, it does not handle any logic to change or set the grabbed processes -state. In general, prefer +state. +In general, prefer .Fn Prelease to .Fn Pfree . diff --git a/usr/src/man/man3proc/Preopen.3proc b/usr/src/man/man3proc/Preopen.3proc index 6343a56f12..088480ab57 100644 --- a/usr/src/man/man3proc/Preopen.3proc +++ b/usr/src/man/man3proc/Preopen.3proc @@ -37,7 +37,8 @@ function returning the value This may occur when the controlled process performs an .Xr exec 2 of a setuid or setgid binary or one where the controlling process cannot -read the object file. For more information on this, see the +read the object file. +For more information on this, see the .Sy PROGRAMMING NOTES section of .Xr proc 4 . diff --git a/usr/src/man/man3proc/Psecflags.3proc b/usr/src/man/man3proc/Psecflags.3proc index 7cedb0f78e..4f4b342146 100644 --- a/usr/src/man/man3proc/Psecflags.3proc +++ b/usr/src/man/man3proc/Psecflags.3proc @@ -59,7 +59,8 @@ function returns .Sy 0 and .Fa psf -is updated with a pointer to the allocated security flags. Otherwise, +is updated with a pointer to the allocated security flags. +Otherwise, .Sy -1 is returned and .Fa psf diff --git a/usr/src/man/man3proc/Psetbkpt.3proc b/usr/src/man/man3proc/Psetbkpt.3proc index 1d0992d298..430063ef1e 100644 --- a/usr/src/man/man3proc/Psetbkpt.3proc +++ b/usr/src/man/man3proc/Psetbkpt.3proc @@ -50,9 +50,9 @@ breakpoint it generates a trap causing the thread to stop. .Pp -Note, breakpoints may only be set in active processes. They may not be -set in process handles that refer to core files, zombie processes, or -files. +Note, breakpoints may only be set in active processes. +They may not be set in process handles that refer to core files, zombie +processes, or files. .Sh RETURN VALUES Upon successful completion, the .Fn Psetbkpt diff --git a/usr/src/man/man3proc/Psetcred.3proc b/usr/src/man/man3proc/Psetcred.3proc index 4cd9e214b5..afc0ce65d6 100644 --- a/usr/src/man/man3proc/Psetcred.3proc +++ b/usr/src/man/man3proc/Psetcred.3proc @@ -33,13 +33,14 @@ function updates the credentials of the process handle to the values set in .Fa credp . .Fa credp -must be fully initialized. The definition of the +must be fully initialized. +The definition of the .Sy prcred_t structure may be found in .Xr proc 4 . .Pp -Note, the credentials may only be updated for an active process. If the -process handle refers to a zombie process, core file, or a file, then +Note, the credentials may only be updated for an active process. +If the process handle refers to a zombie process, core file, or a file, then .Fn Psetcred will fail. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Psetfault.3proc b/usr/src/man/man3proc/Psetfault.3proc index 4a3200762b..7cb467c402 100644 --- a/usr/src/man/man3proc/Psetfault.3proc +++ b/usr/src/man/man3proc/Psetfault.3proc @@ -32,8 +32,8 @@ function sets the fault tracing flags on the process handle .Fa P to .Fa set . -It replaces any existing fault tracing flags on the process. These -flags indicate which faults cause execution of the thread to stop. +It replaces any existing fault tracing flags on the process. +These flags indicate which faults cause execution of the thread to stop. Allowing another tool, such as a debugger, to act upon the process. For more information on faults and the .Sy fltset_t @@ -45,8 +45,8 @@ The current fault set for the process may be obtained through the .Xr Pfault 3PROC function. .Pp -Note, only active processes may have their fault set updated. Process -handles that refer to core files, zombie processes, and files do not +Note, only active processes may have their fault set updated. +Process handles that refer to core files, zombie processes, and files do not have fault tracing flags and this function is a no-op on them. .Sh INTERFACE STABILITY .Sy Uncommitted diff --git a/usr/src/man/man3proc/Psetflags.3proc b/usr/src/man/man3proc/Psetflags.3proc index 8a1783b738..a91126442b 100644 --- a/usr/src/man/man3proc/Psetflags.3proc +++ b/usr/src/man/man3proc/Psetflags.3proc @@ -15,7 +15,7 @@ .Dt PSETFLAGS 3PROC .Os .Sh NAME -.Nm Psetflags +.Nm Psetflags , .Nm Punsetflags .Nd set and unset process flags .Sh SYNOPSIS @@ -39,11 +39,12 @@ and functions manipulate the process flags for the process handle .Fa P . The process flags determine how the process behaves in the face of -various actions. For example, setting the +various actions. +For example, setting the .Sy PR_FORK flag indicates that the tracing flags of the process and the -inherit-on-fork mode should be set on children. A full list of the -process flags is available in the +inherit-on-fork mode should be set on children. +A full list of the process flags is available in the .Sy PCSET section in .Xr proc 4 . @@ -58,7 +59,8 @@ The .Fn Punsetflags function removes the flags specified in .Fa flags -from the tracing flags of the process. Items not listed in +from the tracing flags of the process. +Items not listed in .Fa flags will remain. .Pp @@ -66,14 +68,15 @@ To see the current set of flags active on the process, check the .Sy pr_flags member of the .Sy pstatus_t -for the process. It can be obtained through the +for the process. +It can be obtained through the .Xr Pstatus 3PROC function. .Pp Note, attempting to modify the process flags only works on active -processes. Attempting to call these functions of process handles -corresponding to core files, zombie processes, or files, will result in -an error. +processes. +Attempting to call these functions of process handles corresponding to core +files, zombie processes, or files, will result in an error. .Sh RETURN VALUES Upon successful completion, the .Fn Psetflags diff --git a/usr/src/man/man3proc/Psetpriv.3proc b/usr/src/man/man3proc/Psetpriv.3proc index d2a0dbc08c..4d327280e4 100644 --- a/usr/src/man/man3proc/Psetpriv.3proc +++ b/usr/src/man/man3proc/Psetpriv.3proc @@ -54,7 +54,8 @@ Upon successful completion, the .Fn Psetpriv function returns .Sy 0 -and updates the privilege sets of the process. Otherwise, +and updates the privilege sets of the process. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Psetrun.3proc b/usr/src/man/man3proc/Psetrun.3proc index 6a063d6dd9..68b6f92ebd 100644 --- a/usr/src/man/man3proc/Psetrun.3proc +++ b/usr/src/man/man3proc/Psetrun.3proc @@ -43,14 +43,15 @@ If .Fa sig is non-zero, then the .Fn Psetrun -function causes the signal to be delivered. See +function causes the signal to be delivered. +See .Xr signal.h 3HEAD for a list of valid signal identifiers. .Pp The .Fa flags -member modifies the behavior of the resumed handle. The following values -may be combined by a bitwise-inclusive-OR: +member modifies the behavior of the resumed handle. +The following values may be combined by a bitwise-inclusive-OR: .Bl -tag -width Dv -offset indent .It Dv PRCSIG Clears the current signal, if any. @@ -58,17 +59,18 @@ Clears the current signal, if any. Clears the current fault, if any. .It Dv PRSTEP Indicates that the thread should single-step over the next machine -instruction and upon completion, inject a trap. For the specific -mechanics of single-stepping and what traps or signals will be injected, -see the +instruction and upon completion, inject a trap. +For the specific mechanics of single-stepping and what traps or signals will be +injected, see the .Sy PRSTEP section of .Xr proc 4 . .It Dv PRSABORT Indicates that the thread should abort the system call that it is -currently executing. This is only valid if the thread is stopped because -it is asleep or right before a system call. This will cause the system -call to return +currently executing. +This is only valid if the thread is stopped because it is asleep or right before +a system call. +This will cause the system call to return .Er EINTR . .El .Pp @@ -85,16 +87,17 @@ was passed the argument .Sy 0 . .Pp When the process is resumed all extent tracing flags and register -changes will be synchronized with the process. For more information on -resuming a thread see the +changes will be synchronized with the process. +For more information on resuming a thread see the .Sy PCRUN section in .Xr proc 4 . .Pp Note, the .Fn Psetrun -function is only valid for active processes. It will fail on process -handles that refer to core files, zombie processes, and ELF objects. +function is only valid for active processes. +It will fail on process handles that refer to core files, zombie processes, and +ELF objects. .Pp The .Fn Lsetrun @@ -105,7 +108,8 @@ thread. .Fn Lsetrun causes the specified thread, .Fa L , -to resume execution. Whereas +to resume execution. +Whereas .Fn Psetrun causes all threads in the process to resume. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Psetsignal.3proc b/usr/src/man/man3proc/Psetsignal.3proc index c861788570..58745ffaa7 100644 --- a/usr/src/man/man3proc/Psetsignal.3proc +++ b/usr/src/man/man3proc/Psetsignal.3proc @@ -37,9 +37,9 @@ The call to replaces any existing signal tracing flags entirely with .Fa set . The signal tracing flags determine which signals, when received by a -thread in the process, will cause that thread to stop. For more -information on the behavior of the signal tracing flags, including which -signals may be traced this way, see the +thread in the process, will cause that thread to stop. +For more information on the behavior of the signal tracing flags, including +which signals may be traced this way, see the .Sy PCSTRACE section in .Xr proc 4 . diff --git a/usr/src/man/man3proc/Psetsysentry.3proc b/usr/src/man/man3proc/Psetsysentry.3proc index f8759937d3..4c7cce76f4 100644 --- a/usr/src/man/man3proc/Psetsysentry.3proc +++ b/usr/src/man/man3proc/Psetsysentry.3proc @@ -46,19 +46,20 @@ The call to or .Fn Psetsysexit replaces the corresponding set of system call tracing flags entirely -with the new set. The system call entry tracing flags cause a thread to -stop on entry to the system call and the exit tracing flags cause a -thread to stop on return from the system call, before control returns -back to the user land process. For more information on the state of the -thread and for information on manipulating the +with the new set. +The system call entry tracing flags cause a thread to stop on entry to the +system call and the exit tracing flags cause a thread to stop on return from the +system call, before control returns back to the user land process. +For more information on the state of the thread and for information on +manipulating the .Sy sysset_t , see .Xr proc 4 . .Pp Note that only active processes may have their system call tracing flags -updated. Process handles that refer to core files, zombie processes, -and files do not have fault tracing flags and this function is a no-op -on them. +updated. +Process handles that refer to core files, zombie processes, and files do not +have fault tracing flags and this function is a no-op on them. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Psetwapt.3proc b/usr/src/man/man3proc/Psetwapt.3proc index 1751f04fb9..4ef992cb77 100644 --- a/usr/src/man/man3proc/Psetwapt.3proc +++ b/usr/src/man/man3proc/Psetwapt.3proc @@ -31,7 +31,8 @@ The function adds a watchpoint to the process handle .Fa P . Allowing the hardware to generate a trap when the specified area is -accessed. The watchpoint's parameters are described in +accessed. +The watchpoint's parameters are described in .Fa wp . For more information on watchpoints and the .Sy prwatch_t @@ -42,9 +43,9 @@ section in The watched area will persist until a subsequent call to .Xr Pdelwapt 3PROC . .Pp -Note, only active processes support watchpoints. It is an error to call -this function on process handles that correspond to core files, zombie -processes, or files. +Note, only active processes support watchpoints. +It is an error to call this function on process handles that correspond to core +files, zombie processes, or files. .Sh RETURN VALUES Upon successful completion, the .Fn Psetwapt diff --git a/usr/src/man/man3proc/Psetzoneid.3proc b/usr/src/man/man3proc/Psetzoneid.3proc index 4d163c8b17..7a83fc54fa 100644 --- a/usr/src/man/man3proc/Psetzoneid.3proc +++ b/usr/src/man/man3proc/Psetzoneid.3proc @@ -33,32 +33,34 @@ function moves the process handle into the zone specified by .Fa zoneid . A process that is in the non-global zone may only move between the -global zone and its original zone. A process that is in the global zone -may not use this interface to enter a non-global zone. This function -will fail if called from a non-global zone. This function only -manipulates the processes credentials. +global zone and its original zone. +A process that is in the global zone may not use this interface to enter a +non-global zone. +This function will fail if called from a non-global zone. +This function only manipulates the processes credentials. .Pp Care should be taken when moving a process around temporarily, such that if the process that is manipulating .Fa P dies, it does not cause .Fa P -to resume running while still in the global zone. It is suggested that -the +to resume running while still in the global zone. +It is suggested that the .Sy PR_KLC flag is set with .Xr Psetflags 3PROC which will cause the process to terminate if the process that holds .Fa P -unexpectedly terminates. See +unexpectedly terminates. +See .Xr proc 4 for more information on the .Sy PR_KLC flag. .Pp -Note, only active processes may change their zone. It is an error to -call this function on process handles that correspond to core files, -zombie processes, or files. +Note, only active processes may change their zone. +It is an error to call this function on process handles that correspond to core +files, zombie processes, or files. .Sh RETURN VALUES Upon successful completion, the .Fn Psetzoneid diff --git a/usr/src/man/man3proc/Psignal.3proc b/usr/src/man/man3proc/Psignal.3proc index 1930c1583e..1ff90096f6 100644 --- a/usr/src/man/man3proc/Psignal.3proc +++ b/usr/src/man/man3proc/Psignal.3proc @@ -54,7 +54,8 @@ may not be stopped. .Pp Note, only active processes may have their signal tracing flags updated. Process handles that refer to core files, zombie processes, and files do -not have signal tracing flags. Calling this function on them is an error. +not have signal tracing flags. +Calling this function on them is an error. .Sh RETURN VALUES Upon successful completion, the .Fn Psignal @@ -64,7 +65,8 @@ It returns .Sy 1 if it was set and .Sy 0 -if not. Otherwise, +if not. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Pstack_iter.3proc b/usr/src/man/man3proc/Pstack_iter.3proc index 75ffdba1f3..bd3da0d7cd 100644 --- a/usr/src/man/man3proc/Pstack_iter.3proc +++ b/usr/src/man/man3proc/Pstack_iter.3proc @@ -39,20 +39,23 @@ For each valid stack frame encountered, the callback function .Fa func is invoked with .Fa data -passed as argument. The full signature of +passed as argument. +The full signature of .Ft proc_stack_f is defined in .Xr libproc 3LIB . With each callback, a register set, argument set, and argument count -will be provided. In that register set, only a subset of the registers -will be valid, which include the frame pointer, program counter, and on -SPARC systems, the next program counter. These registers can be accessed -with the constants +will be provided. +In that register set, only a subset of the registers will be valid, which +include the frame pointer, program counter, and on SPARC systems, the next +program counter. +These registers can be accessed with the constants .Sy R_FP , .Sy R_PC , and .Sy R_nPC -respectively. These correspond to the registers +respectively. +These correspond to the registers .Em %ebp and .Em %eip @@ -70,36 +73,40 @@ on both SPARC and SPARCv9. Callers will receive a callback for the first stack frame indicated by .Fa regs and then will receive a subsequent callback for each caller of that -frame until no such frame can be found. Stack frames that logically come -after the frame indicated by +frame until no such frame can be found. +Stack frames that logically come after the frame indicated by .Fa regs will not receive callbacks. .Pp -The compiler can either facilitate or stymie the iteration of the -stack. Programs that have been compiled in such a way as to omit the -frame pointer will result in truncated stacks. Similarly, if the initial -set of registers passed in via +The compiler can either facilitate or stymie the iteration of the stack. +Programs that have been compiled in such a way as to omit the frame pointer will +result in truncated stacks. +Similarly, if the initial set of registers passed in via .Fa regs is invalid, then the ability to iterate the stack will be limited. The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 -then iteration continues. However, if +then iteration continues. +However, if .Fa func returns non-zero, then iteration will halt and that value will be used as the return value of the .Fn Pstack_iter -function. Because +function. +Because .Fn Pstack_iter returns .Sy -1 on internal failure it is recommended the callback function not return .Sy -1 -to indicate an error. Thus the caller may distinguish between the -failure of the callback function and the failure of the +to indicate an error. +Thus the caller may distinguish between the failure of the callback function and +the failure of the .Fn Pstack_iter function. .Sh RETURN VALUES @@ -109,7 +116,8 @@ function returns .Sy 0. If there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pstatus.3proc b/usr/src/man/man3proc/Pstatus.3proc index 6079c01b05..7a917ee5a0 100644 --- a/usr/src/man/man3proc/Pstatus.3proc +++ b/usr/src/man/man3proc/Pstatus.3proc @@ -38,7 +38,8 @@ number of threads, the size of the stack, and more. .Pp The returned pointer is only valid as long as the process handle .Fa P -is valid. After a call to +is valid. +After a call to .Xr Prelease 3PROC , the returned data pointer is invalid. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Pstopstatus.3proc b/usr/src/man/man3proc/Pstopstatus.3proc index 12eeb3366f..8ce88fb7a4 100644 --- a/usr/src/man/man3proc/Pstopstatus.3proc +++ b/usr/src/man/man3proc/Pstopstatus.3proc @@ -19,7 +19,7 @@ .Nm Pstopstatus , .Nm Pstop , .Nm Pwait , -.Nm Ldstop +.Nm Ldstop , .Nm Lstop , .Nm Lwait .Nd process and thread stop operations @@ -62,9 +62,10 @@ The function allows the caller to stop and optionally wait for the process handle referred to by .Fa P -to be stopped. Stopping a process causes all of its threads to stop -execution. Where in their execution the threads will halt is not -defined. Threads may be resumed with +to be stopped. +Stopping a process causes all of its threads to stop execution. +Where in their execution the threads will halt is not defined. +Threads may be resumed with .Xr Psetrun 3PROC and .Xr prun 1 . @@ -76,8 +77,8 @@ argument should be one of the following symbols: .It Dv PCSTOP Stop the process; wait for completion before returning. .It Dv PCDSTOP -Stop the process; do not wait for completion before returning. That -is, the stopping of the process is performed asynchronously in +Stop the process; do not wait for completion before returning. +That is, the stopping of the process is performed asynchronously in relation to the caller. .It Dv PCWSTOP Do not direct the process to stop; simply wait for it to stop. @@ -91,14 +92,17 @@ Both the and .Dv PCWSTOP requests allow an upper bound on the amount of time to wait for the -process to stop. The +process to stop. +The .Fa msec argument indicates the number of milliseconds to wait for the stop to -complete. If the value of +complete. +If the value of .Fa msec is .Sy 0 , -then it will wait forever. Callers should pass +then it will wait forever. +Callers should pass .Sy 0 for .Fa msec @@ -108,15 +112,17 @@ or .Dv PCNULL . .Pp When a non-zero timeout is specified, the process may or may not be -stopped upon return. The return value does not reflect the current -state of the process. For example, if the timeout expires during a +stopped upon return. +The return value does not reflect the current state of the process. +For example, if the timeout expires during a .Fa PCWSTOP request, the return value will be .Sy 0 regardless of the actual state of the process. .Pp -Only active processes may be stopped. Handles that refer to core -files, zombie processes, or files cannot be used; unless the value of +Only active processes may be stopped. +Handles that refer to core files, zombie processes, or files cannot be used; +unless the value of .Fa request is set to .Dv PCNULL . @@ -154,8 +160,8 @@ functions are equivalent to the .Fn Pstop , and .Fn Pwait -functions, respectively. Except, rather than operating on a process, -they operate on the thread handle +functions, respectively. +Except, rather than operating on a process, they operate on the thread handle .Fa L . A call to .Fn Lstop @@ -199,7 +205,8 @@ functions will fail if: .It Er EAGAIN Control over the handle .Fa P -was lost. Callers should call +was lost. +Callers should call .Xr Preopen 3PROC . For more information on losing control, see .Sy PROGRAMMING NOTES diff --git a/usr/src/man/man3proc/Psymbol_iter.3proc b/usr/src/man/man3proc/Psymbol_iter.3proc index 37b14ce822..2378a19b9b 100644 --- a/usr/src/man/man3proc/Psymbol_iter.3proc +++ b/usr/src/man/man3proc/Psymbol_iter.3proc @@ -93,7 +93,8 @@ In the case of the .Fn Pxsymbol_iter function an additional .Sy prsyminfo_t -argument will be provided to the callback. The definitions of +argument will be provided to the callback. +The definitions of .Sy proc_sym_f , .Sy proc_xsym_f , and @@ -104,14 +105,16 @@ are found in The .Fa object_name argument names the object that is a part of the controlled process which -will be searched for symbols. Only one object may be searched at any -given time. Valid object names may be obtained through the +will be searched for symbols. +Only one object may be searched at any given time. +Valid object names may be obtained through the .Xr Pobjname 3PROC and .Xr Pobject_iter 3PROC -functions, among others. The system also has two special object names -that may be passed in to refer to the objects of the executable file and -for ld.so.1. The symbol +functions, among others. +The system also has two special object names that may be passed in to refer to +the objects of the executable file and for ld.so.1. +The symbol .Dv PR_OBJ_EXEC refers to the executables object and the symbol .Dv PR_OBJ_LDSO @@ -122,33 +125,38 @@ The argument controls which of two possible symbol tables will be searched. If the argument is .Dv PR_SYMTAB -then the ELF symbol table will be searched. Otherwise, if it is +then the ELF symbol table will be searched. +Otherwise, if it is .Dv PR_DYNSYM then the symbol table associated with the dynamic section will be -searched instead. If any other value is specified for +searched instead. +If any other value is specified for .Fa which , then an error will be returned. .Pp The .Fa mask -argument controls which symbols will be included. The +argument controls which symbols will be included. +The .Fa mask argument allows for control over both the symbol's binding and the -symbol's type. These flags logically correspond to the various ELF -symbol bindings and types. The following values may be passed as a -bitwise-inclusive-OR into the +symbol's type. +These flags logically correspond to the various ELF symbol bindings and types. +The following values may be passed as a bitwise-inclusive-OR into the .Fa flags argument: .Bl -tag -width Dv -offset indent .It Dv BIND_LOCAL -The symbol is a local symbol. Local symbols are not visible outside of -their object file. +The symbol is a local symbol. +Local symbols are not visible outside of their object file. .It Dv BIND_GLOBAL -The symbol is a global symbol. Global symbols are visible outside of -their object file and may be referred to by other ELF objects. +The symbol is a global symbol. +Global symbols are visible outside of their object file and may be referred to +by other ELF objects. .It Dv BIND_WEAK -The symbol is a weak symbol. Weak symbols are visible outside of their -object file, but another definition of the symbol may be used instead. +The symbol is a weak symbol. +Weak symbols are visible outside of their object file, but another definition of +the symbol may be used instead. .It Dv BIND_ANY This is a combination of .Dv BIND_LOCAL , @@ -159,7 +167,8 @@ Every symbol's binding will match this value. .It Dv TYPE_NOTYPE The symbol's type is not specified. .It Dv TYPE_OBJECT -The symbol refers to a data object. For example, variables. +The symbol refers to a data object. +For example, variables. .It Dv TYPE_FUNC The symbol refers to a function. .It Dv TYPE_SECTION @@ -191,28 +200,35 @@ and .Fn Pxsymbol_iter functions allow for a link-map identifier to be specified in the .Fa lmid -argument. This will restrict the search for the object specified in +argument. +This will restrict the search for the object specified in .Fa object_name -to the specified link-map. There are three special link-map identifiers -that may be passed in. The symbol +to the specified link-map. +There are three special link-map identifiers that may be passed in. +The symbol .Dv PR_LMID_EVERY -indicates that every link-map should be searched. The symbol +indicates that every link-map should be searched. +The symbol .Dv LM_ID_BASE indicates that the base link-map, the one that is used for the -executable should be searched. Finally, the symbol +executable should be searched. +Finally, the symbol .Dv LM_ID_LDSO -refers to the link-map that is used by the run-time link editor, -ld.so.1. The functions which do not allow a link-map identifier to be -specified always search every link-map. +refers to the link-map that is used by the run-time link editor, ld.so.1. +The functions which do not allow a link-map identifier to be specified always +search every link-map. .Pp By default, symbols are iterated based on the order of the symbol -table being searched. However, it is also possible to iterate based on -the name of the symbol and based on the address of the symbol. To -iterate by name use the +table being searched. +However, it is also possible to iterate based on the name of the symbol and +based on the address of the symbol. +To iterate by name use the .Fn Psymbol_iter_by_name -function. To iterate by address use the +function. +To iterate by address use the .Fn Psymbol_iter_by_addr -function. The +function. +The .Fn Psymbol_iter , .Fn Psymbol_iter_by_lmid , and @@ -221,11 +237,13 @@ functions all sort based on the order of the symbol table. .Pp The return value of the callback function .Fa func -determines whether or not iteration continues. If +determines whether or not iteration continues. +If .Fa func returns .Sy 0, -then iteration will continue. However, if +then iteration will continue. +However, if .Fa func returns non-zero, then iteration will halt and that value will be used as the return value of the @@ -235,7 +253,8 @@ as the return value of the .Fn Psymbol_iter_by_name , and .Fn Pxsymbol_iter -functions. Because these functions return +functions. +Because these functions return .Sy -1 on internal failure, it is recommended that the callback function not return .Sy -1 @@ -253,7 +272,8 @@ functions return .Sy 0 . If there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Psync.3proc b/usr/src/man/man3proc/Psync.3proc index 48c7ad5f96..cc5637eedc 100644 --- a/usr/src/man/man3proc/Psync.3proc +++ b/usr/src/man/man3proc/Psync.3proc @@ -34,7 +34,8 @@ The .Fn Psync function synchronizes modifications to the process handle .Fa P -back to the underlying active process. The +back to the underlying active process. +The .Fn Psync function ensures that any outstanding process holds, register modifications, signal injections, and modifications to the various fault @@ -47,9 +48,9 @@ library, calling this function may be required. .Pp The .Fn Psync -function is only meaningful for active processes. It will do nothing on -process handles that refer to core files, zombie processes, and ELF -objects. +function is only meaningful for active processes. +It will do nothing on process handles that refer to core files, zombie +processes, and ELF objects. .Pp The .Fn Lsync diff --git a/usr/src/man/man3proc/Psysentry.3proc b/usr/src/man/man3proc/Psysentry.3proc index 1647b00a83..6190890410 100644 --- a/usr/src/man/man3proc/Psysentry.3proc +++ b/usr/src/man/man3proc/Psysentry.3proc @@ -43,8 +43,9 @@ functions controls what actions the process handle should take upon executing a system call. .Pp The system allows a process to be stopped on both entry and exit of a -system call. For information on the state of the process when it is -stopped due to system call tracing, see the +system call. +For information on the state of the process when it is stopped due to system +call tracing, see the .Sy PCSENTRY and .Sy PCSEXIT @@ -55,18 +56,20 @@ The value of the .Fa stop parameter controls whether or not the system call listed in .Fa which -causes the process to stop. A value of non-zero indicates the process -should stop; a value of 0 indicates it should not. +causes the process to stop. +A value of non-zero indicates the process should stop; +a value of 0 indicates it should not. .Pp The value of .Fa which -indicates which system call the change applies to. A value of 0 -applies to all system calls. Note, the system does not supply a stable -mapping from system call names to identifiers. +indicates which system call the change applies to. +A value of 0 applies to all system calls. +Note, the system does not supply a stable mapping from system call names to +identifiers. .Pp -These functions only apply to actively running processes. They do not -function on handles that refer to core files, zombie processes, or ELF -objects. +These functions only apply to actively running processes. +They do not function on handles that refer to core files, zombie processes, +or ELF objects. .Sh RETURN VALUES Upon successful completion, the .Fn Psetentry @@ -77,7 +80,8 @@ functions return the previous disposition of the system call -- if it was not set to stop and .Sy 1 if it was -- -and the system call state is updated. Otherwise, +and the system call state is updated. +Otherwise, .Sy -1 is returned, .Dv errno diff --git a/usr/src/man/man3proc/Pupdate_maps.3proc b/usr/src/man/man3proc/Pupdate_maps.3proc index bb5dedfb30..7fb482eae2 100644 --- a/usr/src/man/man3proc/Pupdate_maps.3proc +++ b/usr/src/man/man3proc/Pupdate_maps.3proc @@ -32,16 +32,17 @@ process .Fa P are still valid and update the cached data with any new information. This is generally called in response to activity by the run-time -link-editor. In general, the +link-editor. +In general, the .Sy libproc library takes care of managing the need to call this function; however, debuggers, introspection tools, and others that are interposing on rtld activity or other actions, may need to call this function. Note that the .Fn Pupdate_maps -function is only meaningful for active processes. It will do nothing on -process handles that refer to core files, zombie processes, and ELF -objects. +function is only meaningful for active processes. +It will do nothing on process handles that refer to core files, zombie +processes, and ELF objects. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Pupdate_syms.3proc b/usr/src/man/man3proc/Pupdate_syms.3proc index f2305cebd1..9e6e819aa5 100644 --- a/usr/src/man/man3proc/Pupdate_syms.3proc +++ b/usr/src/man/man3proc/Pupdate_syms.3proc @@ -34,16 +34,17 @@ updating, invalidating, and caching new symbol tables as appropriate for functions such as .Xr Psymbol_iter 3PROC . This is generally called in response to activity by the run-time -link-editor. In general, the +link-editor. +In general, the .Sy libproc library takes care of managing the need to call this function; however, debuggers, introspection tools, and others that are -interposing on rtld activity may need to call this function. Note that -the +interposing on rtld activity may need to call this function. +Note that the .Fn Pupdate_syms -function is only meaningful for active processes. It will do nothing on -process handles that refer to core files, zombie processes, and ELF -objects. +function is only meaningful for active processes. +It will do nothing on process handles that refer to core files, zombie +processes, and ELF objects. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Pwrite.3proc b/usr/src/man/man3proc/Pwrite.3proc index 575cea4a88..411dbb8aae 100644 --- a/usr/src/man/man3proc/Pwrite.3proc +++ b/usr/src/man/man3proc/Pwrite.3proc @@ -38,7 +38,8 @@ starting at the address .Fa address . It writes at most .Fa nbyte -of data. The +of data. +The .Fn Pwrite function is logically analogous to the .Xr pwrite 2 @@ -47,9 +48,10 @@ function. For live processes, this function is equivalent to writing to the /proc file system .Sy as -file for the process. For core files, it writes to the logical address -space of what was once the process and not the corresponding offset in -the on-disk file. ELF objects grabbed through +file for the process. +For core files, it writes to the logical address space of what was once the +process and not the corresponding offset in the on-disk file. +ELF objects grabbed through .Xr Pgrab_file 3PROC do not support being written to. .Pp @@ -70,7 +72,8 @@ Otherwise, it returns .Sy -1 and .Sy errno -is set to indicate an error. For the full list of errors see the +is set to indicate an error. +For the full list of errors see the .Sy DIAGNOSTICS section in .Xr proc 4 diff --git a/usr/src/man/man3proc/Pzonename.3proc b/usr/src/man/man3proc/Pzonename.3proc index 3b2cb8e64e..0dc78d5959 100644 --- a/usr/src/man/man3proc/Pzonename.3proc +++ b/usr/src/man/man3proc/Pzonename.3proc @@ -108,7 +108,7 @@ refers to a core file and zone information was not available in the core dump or .Fa P refers to an ELF object grabbed through -.Xr Pgrab_file . +.Xr Pgrab_file 3PROC . .It Er EFAULT .Fa P refers to an active process and diff --git a/usr/src/man/man3proc/pr_access.3proc b/usr/src/man/man3proc/pr_access.3proc index cc949a7e01..3b4bc1d92c 100644 --- a/usr/src/man/man3proc/pr_access.3proc +++ b/usr/src/man/man3proc/pr_access.3proc @@ -33,7 +33,8 @@ function injects the .Xr access 2 system call into the target process .Fa P -by means of the agent lwp. If the process handle +by means of the agent lwp. +If the process handle .Fa P is .Dv NULL @@ -55,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_access -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_access diff --git a/usr/src/man/man3proc/pr_close.3proc b/usr/src/man/man3proc/pr_close.3proc index af4185fb8d..40d03db923 100644 --- a/usr/src/man/man3proc/pr_close.3proc +++ b/usr/src/man/man3proc/pr_close.3proc @@ -53,9 +53,9 @@ system call and its arguments. .Pp The .Fn pr_close -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_close diff --git a/usr/src/man/man3proc/pr_creat.3proc b/usr/src/man/man3proc/pr_creat.3proc index 9434508002..ee68431f47 100644 --- a/usr/src/man/man3proc/pr_creat.3proc +++ b/usr/src/man/man3proc/pr_creat.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_creat -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_creat diff --git a/usr/src/man/man3proc/pr_door_info.3proc b/usr/src/man/man3proc/pr_door_info.3proc index d1de2ea0c2..7c813827fd 100644 --- a/usr/src/man/man3proc/pr_door_info.3proc +++ b/usr/src/man/man3proc/pr_door_info.3proc @@ -56,9 +56,9 @@ library call and its arguments. .Pp The .Fn pr_door_info -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_door_info diff --git a/usr/src/man/man3proc/pr_exit.3proc b/usr/src/man/man3proc/pr_exit.3proc index 1d156fef5d..30fee8c0ef 100644 --- a/usr/src/man/man3proc/pr_exit.3proc +++ b/usr/src/man/man3proc/pr_exit.3proc @@ -53,9 +53,9 @@ system call and its arguments. .Pp The .Fn pr_exit -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_exit diff --git a/usr/src/man/man3proc/pr_fcntl.3proc b/usr/src/man/man3proc/pr_fcntl.3proc index e6bd11db46..5d081c48ce 100644 --- a/usr/src/man/man3proc/pr_fcntl.3proc +++ b/usr/src/man/man3proc/pr_fcntl.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_fcntl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_fcntl diff --git a/usr/src/man/man3proc/pr_fstatvfs.3proc b/usr/src/man/man3proc/pr_fstatvfs.3proc index b08d834c6c..6e627c5cc4 100644 --- a/usr/src/man/man3proc/pr_fstatvfs.3proc +++ b/usr/src/man/man3proc/pr_fstatvfs.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_fstatvfs -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_fstatvfs diff --git a/usr/src/man/man3proc/pr_getitimer.3proc b/usr/src/man/man3proc/pr_getitimer.3proc index 0f3c5d32d0..43a242c081 100644 --- a/usr/src/man/man3proc/pr_getitimer.3proc +++ b/usr/src/man/man3proc/pr_getitimer.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_getitimer -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getitimer diff --git a/usr/src/man/man3proc/pr_getpeername.3proc b/usr/src/man/man3proc/pr_getpeername.3proc index bf0306c068..228ee7e22b 100644 --- a/usr/src/man/man3proc/pr_getpeername.3proc +++ b/usr/src/man/man3proc/pr_getpeername.3proc @@ -58,9 +58,9 @@ library call and its arguments. .Pp The .Fn pr_getpeername -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getpeername diff --git a/usr/src/man/man3proc/pr_getpeerucred.3proc b/usr/src/man/man3proc/pr_getpeerucred.3proc index 03d8023287..58ef001da1 100644 --- a/usr/src/man/man3proc/pr_getpeerucred.3proc +++ b/usr/src/man/man3proc/pr_getpeerucred.3proc @@ -56,9 +56,9 @@ library call and its arguments. .Pp The .Fn pr_getpeerucred -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getpeerucred diff --git a/usr/src/man/man3proc/pr_getprojid.3proc b/usr/src/man/man3proc/pr_getprojid.3proc index bc209e4eb2..88426b99c4 100644 --- a/usr/src/man/man3proc/pr_getprojid.3proc +++ b/usr/src/man/man3proc/pr_getprojid.3proc @@ -42,9 +42,9 @@ on the currently running process. .Pp The .Fn pr_getprojid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getprojid diff --git a/usr/src/man/man3proc/pr_getrctl.3proc b/usr/src/man/man3proc/pr_getrctl.3proc index 7f46a0ad48..5725417a6b 100644 --- a/usr/src/man/man3proc/pr_getrctl.3proc +++ b/usr/src/man/man3proc/pr_getrctl.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_getrctl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getrctl diff --git a/usr/src/man/man3proc/pr_getrlimit.3proc b/usr/src/man/man3proc/pr_getrlimit.3proc index c1f17bfa8a..adcb0480f8 100644 --- a/usr/src/man/man3proc/pr_getrlimit.3proc +++ b/usr/src/man/man3proc/pr_getrlimit.3proc @@ -63,17 +63,17 @@ system call and its arguments. .Pp The .Fn pr_getrlimit -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Pp The .Fn pr_getrlimit64 function is equivalent to .Fn pr_getrlimit ; -however, rather than having the rlimit information be subject to the -data model of the target process, they always provide 64-bit rlimit -information. See +however, rather than having the rlimit information be subject to the data model +of the target process, they always provide 64-bit rlimit information. +See .Xr lf64 5 for more information. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/pr_getsockname.3proc b/usr/src/man/man3proc/pr_getsockname.3proc index 125378d2ab..9ec6eca88e 100644 --- a/usr/src/man/man3proc/pr_getsockname.3proc +++ b/usr/src/man/man3proc/pr_getsockname.3proc @@ -58,9 +58,9 @@ library call and its arguments. .Pp The .Fn pr_getsockname -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getsockname diff --git a/usr/src/man/man3proc/pr_getsockopt.3proc b/usr/src/man/man3proc/pr_getsockopt.3proc index 6edb92fe08..1bd5dae0b9 100644 --- a/usr/src/man/man3proc/pr_getsockopt.3proc +++ b/usr/src/man/man3proc/pr_getsockopt.3proc @@ -62,9 +62,9 @@ system call and its arguments. .Pp The .Fn pr_getsockopt -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getsockopt diff --git a/usr/src/man/man3proc/pr_gettaskid.3proc b/usr/src/man/man3proc/pr_gettaskid.3proc index 0c52d800d4..783a5560bb 100644 --- a/usr/src/man/man3proc/pr_gettaskid.3proc +++ b/usr/src/man/man3proc/pr_gettaskid.3proc @@ -42,9 +42,9 @@ on the currently running process. .Pp The .Fn pr_gettaskid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_gettaskid diff --git a/usr/src/man/man3proc/pr_getzoneid.3proc b/usr/src/man/man3proc/pr_getzoneid.3proc index 8cd2e29c5c..8304eb232d 100644 --- a/usr/src/man/man3proc/pr_getzoneid.3proc +++ b/usr/src/man/man3proc/pr_getzoneid.3proc @@ -42,9 +42,9 @@ on the currently running process. .Pp The .Fn pr_getzoneid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getzoneid diff --git a/usr/src/man/man3proc/pr_ioctl.3proc b/usr/src/man/man3proc/pr_ioctl.3proc index 24b47be548..dbe1d52a49 100644 --- a/usr/src/man/man3proc/pr_ioctl.3proc +++ b/usr/src/man/man3proc/pr_ioctl.3proc @@ -68,9 +68,9 @@ target process. .Pp The .Fn pr_ioctl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_ioctl diff --git a/usr/src/man/man3proc/pr_link.3proc b/usr/src/man/man3proc/pr_link.3proc index a80012df77..b981405f39 100644 --- a/usr/src/man/man3proc/pr_link.3proc +++ b/usr/src/man/man3proc/pr_link.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_link -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_link diff --git a/usr/src/man/man3proc/pr_llseek.3proc b/usr/src/man/man3proc/pr_llseek.3proc index 28fa432dba..2d88e53ba6 100644 --- a/usr/src/man/man3proc/pr_llseek.3proc +++ b/usr/src/man/man3proc/pr_llseek.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_llseek -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_llseek diff --git a/usr/src/man/man3proc/pr_lseek.3proc b/usr/src/man/man3proc/pr_lseek.3proc index 8e96274898..bea7e7bb3a 100644 --- a/usr/src/man/man3proc/pr_lseek.3proc +++ b/usr/src/man/man3proc/pr_lseek.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_lseek -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_lseek diff --git a/usr/src/man/man3proc/pr_memcntl.3proc b/usr/src/man/man3proc/pr_memcntl.3proc index dba3f05a12..e77e7debd7 100644 --- a/usr/src/man/man3proc/pr_memcntl.3proc +++ b/usr/src/man/man3proc/pr_memcntl.3proc @@ -64,9 +64,9 @@ system call and its arguments. .Pp The .Fn pr_memcntl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_memcntl diff --git a/usr/src/man/man3proc/pr_meminfo.3proc b/usr/src/man/man3proc/pr_meminfo.3proc index 3da4983f91..7e6dfae222 100644 --- a/usr/src/man/man3proc/pr_meminfo.3proc +++ b/usr/src/man/man3proc/pr_meminfo.3proc @@ -64,9 +64,9 @@ system call and its arguments. .Pp The .Fn pr_meminfo -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_meminfo diff --git a/usr/src/man/man3proc/pr_mmap.3proc b/usr/src/man/man3proc/pr_mmap.3proc index 966979337f..988f79dede 100644 --- a/usr/src/man/man3proc/pr_mmap.3proc +++ b/usr/src/man/man3proc/pr_mmap.3proc @@ -64,9 +64,9 @@ system call and its arguments. .Pp The .Fn pr_mmap -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_mmap diff --git a/usr/src/man/man3proc/pr_munmap.3proc b/usr/src/man/man3proc/pr_munmap.3proc index ede8fcd12c..0573cc4a2a 100644 --- a/usr/src/man/man3proc/pr_munmap.3proc +++ b/usr/src/man/man3proc/pr_munmap.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_munmap -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_munmap diff --git a/usr/src/man/man3proc/pr_open.3proc b/usr/src/man/man3proc/pr_open.3proc index d462520976..9a15a11428 100644 --- a/usr/src/man/man3proc/pr_open.3proc +++ b/usr/src/man/man3proc/pr_open.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_open -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_open diff --git a/usr/src/man/man3proc/pr_processor_bind.3proc b/usr/src/man/man3proc/pr_processor_bind.3proc index 4890b051e7..f30d6095d5 100644 --- a/usr/src/man/man3proc/pr_processor_bind.3proc +++ b/usr/src/man/man3proc/pr_processor_bind.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_processor_bind -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_processor_bind diff --git a/usr/src/man/man3proc/pr_rename.3proc b/usr/src/man/man3proc/pr_rename.3proc index f7306778c5..a7b9a33762 100644 --- a/usr/src/man/man3proc/pr_rename.3proc +++ b/usr/src/man/man3proc/pr_rename.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_rename -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_rename diff --git a/usr/src/man/man3proc/pr_setitimer.3proc b/usr/src/man/man3proc/pr_setitimer.3proc index 8226390331..dc777fdd1d 100644 --- a/usr/src/man/man3proc/pr_setitimer.3proc +++ b/usr/src/man/man3proc/pr_setitimer.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_setitimer -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_setitimer diff --git a/usr/src/man/man3proc/pr_setrctl.3proc b/usr/src/man/man3proc/pr_setrctl.3proc index 186b1843cc..75ed161f20 100644 --- a/usr/src/man/man3proc/pr_setrctl.3proc +++ b/usr/src/man/man3proc/pr_setrctl.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_setrctl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_setrctl diff --git a/usr/src/man/man3proc/pr_setrlimit.3proc b/usr/src/man/man3proc/pr_setrlimit.3proc index 1282c86f1b..b7658278d2 100644 --- a/usr/src/man/man3proc/pr_setrlimit.3proc +++ b/usr/src/man/man3proc/pr_setrlimit.3proc @@ -63,17 +63,17 @@ system call and its arguments. .Pp The .Fn pr_setrlimit -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Pp The .Fn pr_setrlimit64 function is equivalent to .Fn pr_setrlimit ; -however, rather than having the rlimit information be subject to the -data model of the target process, they always provide 64-bit rlimit -information. See +however, rather than having the rlimit information be subject to the data model +of the target process, they always provide 64-bit rlimit information. +See .Xr lf64 5 for more information. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/pr_settaskid.3proc b/usr/src/man/man3proc/pr_settaskid.3proc index 663bb6ed83..368cc4243a 100644 --- a/usr/src/man/man3proc/pr_settaskid.3proc +++ b/usr/src/man/man3proc/pr_settaskid.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_settaskid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_settaskid diff --git a/usr/src/man/man3proc/pr_sigaction.3proc b/usr/src/man/man3proc/pr_sigaction.3proc index 937f2c1f18..4103a0e203 100644 --- a/usr/src/man/man3proc/pr_sigaction.3proc +++ b/usr/src/man/man3proc/pr_sigaction.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_sigaction -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_sigaction diff --git a/usr/src/man/man3proc/pr_stat.3proc b/usr/src/man/man3proc/pr_stat.3proc index 7c6f26ff4a..f9095db692 100644 --- a/usr/src/man/man3proc/pr_stat.3proc +++ b/usr/src/man/man3proc/pr_stat.3proc @@ -16,7 +16,7 @@ .Os .Sh NAME .Nm pr_fstat , -.Nm pr_fstat64 +.Nm pr_fstat64 , .Nm pr_lstat , .Nm pr_lstat64 , .Nm pr_stat , @@ -133,9 +133,9 @@ The .Fn pr_lstat , and .Fn pr_fstat -functions only work on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +functions only work on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Pp The .Fn pr_stat64 , @@ -147,9 +147,9 @@ functions are equivalent to .Fn pr_fstat , and .Fn pr_lstat -respectively; however, rather than having the stat information be -subject to the data model of the target process, they always provide -64-bit stat information. See +respectively; however, rather than having the stat information be subject to the +data model of the target process, they always provide 64-bit stat information. +See .Xr lf64 5 for more information. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/pr_statvfs.3proc b/usr/src/man/man3proc/pr_statvfs.3proc index 05dc23cf00..30a8a4c90b 100644 --- a/usr/src/man/man3proc/pr_statvfs.3proc +++ b/usr/src/man/man3proc/pr_statvfs.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_statvfs -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_statvfs diff --git a/usr/src/man/man3proc/pr_unlink.3proc b/usr/src/man/man3proc/pr_unlink.3proc index b1f96a2384..0dbf9702ef 100644 --- a/usr/src/man/man3proc/pr_unlink.3proc +++ b/usr/src/man/man3proc/pr_unlink.3proc @@ -53,9 +53,9 @@ system call and its arguments. .Pp The .Fn pr_unlink -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_unlink diff --git a/usr/src/man/man3proc/pr_waitid.3proc b/usr/src/man/man3proc/pr_waitid.3proc index 0efd563722..9eceeb7eab 100644 --- a/usr/src/man/man3proc/pr_waitid.3proc +++ b/usr/src/man/man3proc/pr_waitid.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_waitid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_waitid diff --git a/usr/src/man/man3proc/proc_arg_grab.3proc b/usr/src/man/man3proc/proc_arg_grab.3proc index be9c7c1b02..375ba4d67e 100644 --- a/usr/src/man/man3proc/proc_arg_grab.3proc +++ b/usr/src/man/man3proc/proc_arg_grab.3proc @@ -48,8 +48,8 @@ it. .Pp The string .Fa arg -contains the name of something to try and open. How it is interpreted -depends on the value of +contains the name of something to try and open. +How it is interpreted depends on the value of .Fa oflag . The following values may be passed in as a bitwise-exclusive-OR for .Fa oflag : @@ -69,8 +69,8 @@ Encompasses all of the previous opens. The argument .Fa gflag controls the behavior when the corresponding process grabbing function -is called by the underlying system. For a list of flags that may be -passed in here, see +is called by the underlying system. +For a list of flags that may be passed in here, see .Xr Pgrab 3PROC and .Xr Pgrab_core 3PROC . diff --git a/usr/src/man/man3proc/proc_arg_psinfo.3proc b/usr/src/man/man3proc/proc_arg_psinfo.3proc index 40af3572a3..2ebab46fc7 100644 --- a/usr/src/man/man3proc/proc_arg_psinfo.3proc +++ b/usr/src/man/man3proc/proc_arg_psinfo.3proc @@ -49,8 +49,8 @@ information from the process or core and fills it into .Pp The string .Fa arg -contains the name of something to try and open. How it is interpreted -depends on the value of +contains the name of something to try and open. +How it is interpreted depends on the value of .Fa oflag . The following values may be passed in as a bitwise-exclusive-OR for .Fa oflag : @@ -98,7 +98,8 @@ and .Fn proc_arg_xpsinfo functions return the process identifier and fill in .Fa psp -with the ps information of the process. Otherwise, +with the ps information of the process. +Otherwise, .Sy -1 is returned and .Fa perr diff --git a/usr/src/man/man3proc/proc_content2str.3proc b/usr/src/man/man3proc/proc_content2str.3proc index 01f3b6a979..4b01158d95 100644 --- a/usr/src/man/man3proc/proc_content2str.3proc +++ b/usr/src/man/man3proc/proc_content2str.3proc @@ -49,8 +49,8 @@ together with the or .Sy - characters, indicating that the subsequent token should be added or -subtracted from the previous ones. The full list of tokens and constants -is available in the +subtracted from the previous ones. +The full list of tokens and constants is available in the .Sy core_content_t portion of the .Sy TYPES diff --git a/usr/src/man/man3proc/proc_fltset2str.3proc b/usr/src/man/man3proc/proc_fltset2str.3proc index 08e43c531f..96c40eeab2 100644 --- a/usr/src/man/man3proc/proc_fltset2str.3proc +++ b/usr/src/man/man3proc/proc_fltset2str.3proc @@ -64,14 +64,16 @@ Up to .Fa buflen characters will be placed in .Fa buf , -including the null terminator. If +including the null terminator. +If .Fa buf is not large enough to hold the entire string, then an error will be returned. .Pp The .Fa members -argument controls which members of the set are written out. If +argument controls which members of the set are written out. +If .Fa members is .Sy 1 , @@ -86,8 +88,8 @@ then the members which are not in the set are placed in .Pp The string .Fa delim -will be placed in-between every member of the set. It will not come after -the last entry in the set. +will be placed in-between every member of the set. +It will not come after the last entry in the set. .Sh RETURN VALUES Upon successful completion, the .Fn proc_fltset2str , diff --git a/usr/src/man/man3proc/proc_get_cred.3proc b/usr/src/man/man3proc/proc_get_cred.3proc index dbdb08c379..ddff00283b 100644 --- a/usr/src/man/man3proc/proc_get_cred.3proc +++ b/usr/src/man/man3proc/proc_get_cred.3proc @@ -36,7 +36,8 @@ Up to .Fa ngroups supplemental groups will be read and written into .Fa credp -in addition to the normal information. If +in addition to the normal information. +If .Fa ngroups is more than one, than it is up to the caller to have allocated enough space for diff --git a/usr/src/man/man3proc/proc_get_priv.3proc b/usr/src/man/man3proc/proc_get_priv.3proc index bc83a7d604..d70c293cec 100644 --- a/usr/src/man/man3proc/proc_get_priv.3proc +++ b/usr/src/man/man3proc/proc_get_priv.3proc @@ -38,8 +38,8 @@ process The .Fn proc_get_priv function takes care of allocating memory for the privilege set and -ensures that it is large enough to hold all of the privilege sets. The -definition of the +ensures that it is large enough to hold all of the privilege sets. +The definition of the .Sy prpriv_t structure may be found in .Xr proc 4 . diff --git a/usr/src/man/man3proc/proc_initstdio.3proc b/usr/src/man/man3proc/proc_initstdio.3proc index 315f717f81..5576c33dfa 100644 --- a/usr/src/man/man3proc/proc_initstdio.3proc +++ b/usr/src/man/man3proc/proc_initstdio.3proc @@ -41,17 +41,19 @@ The and .Fn proc_finistdio functions are utilities provided to aid with the possibility of deadlock -while doing I/O operations. If a process is trying to do I/O, but -holding the process handle that would consume that I/O, then eventually -the program holding the process handle will block as none of its I/O has -been drained. However, because it is holding a process handle to that -process, it will never be drained. +while doing I/O operations. +If a process is trying to do I/O, but holding the process handle that would +consume that I/O, then eventually the program holding the process handle will +block as none of its I/O has been drained. +However, because it is holding a process handle to that process, it will never +be drained. .Pp Consider, for example, the following invocation: .Li pfiles `pgrep xterm` -where the command was launched from a shell on an xterm. Because the -xterm is stopped, it will not be able to write out any of the standard -out that gets passed to it, leading to a deadlock. The +where the command was launched from a shell on an xterm. +Because the xterm is stopped, it will not be able to write out any of the +standard out that gets passed to it, leading to a deadlock. +The .Li pfiles program cannot release the .Li xterm @@ -60,9 +62,9 @@ due to the same hold. .Pp To address this, these functions duplicate the standard output and standard error of the process to temporary files and then flushes it out -to the original file descriptors and streams later. When finished, the -original file descriptors are restored as standard out and standard -error. +to the original file descriptors and streams later. +When finished, the original file descriptors are restored as standard out and +standard error. .Pp The .Fn proc_initstdio @@ -72,9 +74,10 @@ descriptors and retains the originals. The .Fn proc_flushstdio functions flushes all of the cached data from the temporary standard out -and standard error back to the underlying ones. This function should -only be called after all process handles have been released. For -example, if iterating on multiple processes, calling this after handling +and standard error back to the underlying ones. +This function should only be called after all process handles have been +released. +For example, if iterating on multiple processes, calling this after handling each one is safe. .Pp The diff --git a/usr/src/man/man3proc/proc_lwp_in_set.3proc b/usr/src/man/man3proc/proc_lwp_in_set.3proc index 62f3596d6e..bea97c1a71 100644 --- a/usr/src/man/man3proc/proc_lwp_in_set.3proc +++ b/usr/src/man/man3proc/proc_lwp_in_set.3proc @@ -38,8 +38,8 @@ functions provide means for testing the validity of thread ranges and whether a thread is in a range. .Pp A thread range is a series of one or more series of range identifiers -which describe a collection of threads. These are often used by programs -such as +which describe a collection of threads. +These are often used by programs such as .Xr pbind 1M , .Xr pstack 1 , .Xr prun 1 , @@ -52,8 +52,8 @@ More formally, the thread range may be described as: lwp_range[,lwp_range]* .Ed .Pp -An LWP range may be specified as one of the following four strings. The -following table shows the string formats and the corresponding set of +An LWP range may be specified as one of the following four strings. +The following table shows the string formats and the corresponding set of valid threads that match it: .Bl -column -offset indent ".Sy n-m" "n <= lwpid <= m" .It Sy -n Ta lwpid <= n @@ -70,8 +70,8 @@ The .Fn proc_lwp_range_valid function determines whether or not the character string .Fa set -is a valid thread range based on the rules above. Note, the empty -string, the +is a valid thread range based on the rules above. +Note, the empty string, the .Dv NULL pointer, or otherwise are not valid. .Pp @@ -108,7 +108,8 @@ function returns .Sy 0 to indicate .Fa set -is valid. Otherwise, +is valid. +Otherwise, .Sy -1 is returned to indicate that the set is invalid. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/proc_str2flt.3proc b/usr/src/man/man3proc/proc_str2flt.3proc index 672fbf98bb..2b7ef2edff 100644 --- a/usr/src/man/man3proc/proc_str2flt.3proc +++ b/usr/src/man/man3proc/proc_str2flt.3proc @@ -63,7 +63,8 @@ and update .Fa signum , and .Fa sysnum -respectively. Otherwise, +respectively. +Otherwise, .Sy -1 is returned to indicate that a conversion could not take place. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/proc_str2fltset.3proc b/usr/src/man/man3proc/proc_str2fltset.3proc index ebc8e60be5..e1fd1f5359 100644 --- a/usr/src/man/man3proc/proc_str2fltset.3proc +++ b/usr/src/man/man3proc/proc_str2fltset.3proc @@ -91,8 +91,8 @@ Upon successful completion, .Dv NULL is returned and .Fa set -is filled in. Otherwise, a pointer to the first unknown character is -returned and +is filled in. +Otherwise, a pointer to the first unknown character is returned and .Sy errno is set to indicate the error. .Sh ERRORS diff --git a/usr/src/man/man3proc/proc_unctrl_psinfo.3proc b/usr/src/man/man3proc/proc_unctrl_psinfo.3proc index f5bff350a6..0ad264a4e8 100644 --- a/usr/src/man/man3proc/proc_unctrl_psinfo.3proc +++ b/usr/src/man/man3proc/proc_unctrl_psinfo.3proc @@ -31,10 +31,10 @@ function walks the process arguments of the .Fa psp structure (the .Sy pr_psargs -member) converting unprintable characters into spaces. The conversion -continues until a null character is encountered. Note, this routine only -will correctly handle 7-bit ASCII characters. Characters in other -encodings, e.g. UTF-8, may be misinterpreted as unprintable. +member) converting unprintable characters into spaces. +The conversion continues until a null character is encountered. +Note, this routine only will correctly handle 7-bit ASCII characters. +Characters in other encodings, e.g. UTF-8, may be misinterpreted as unprintable. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/proc_walk.3proc b/usr/src/man/man3proc/proc_walk.3proc index cc9a831bec..c1d1158d77 100644 --- a/usr/src/man/man3proc/proc_walk.3proc +++ b/usr/src/man/man3proc/proc_walk.3proc @@ -49,13 +49,15 @@ The value of controls whether or not information about the threads in the process are included and how many times the callback function .Fa func -is called. The following values may be passed in for +is called. +The following values may be passed in for .Fa flag : .Bl -tag -width Dv -offset indent .It Dv PR_WALK_PROC Indicates that the walker is only concerned with the process. .Fa func -will be called once for each process in the system. Only the +will be called once for each process in the system. +Only the .Sy psinfo will be read for the process and passed to .Fa func . @@ -66,8 +68,8 @@ will be passed as .It Dv PR_WALK_LWP The caller wants both process and thread information. .Fa func -will be called once for each thread in the system. In addition to the -process +will be called once for each thread in the system. +In addition to the process .Sy psinfo information, the ps specific information for a given thread will be included in the @@ -77,12 +79,13 @@ argument. .Pp The return value of the caller's .Fa func -function determines whether or not iteration will continue. If +function determines whether or not iteration will continue. +If .Fa func returns a non-zero value, then iteration will terminate and that -return value will be returned to the caller. To distinguish between -system errors and caller errors, it is recommended that the function -only return positive integers in the event of an error. +return value will be returned to the caller. +To distinguish between system errors and caller errors, it is recommended that +the function only return positive integers in the event of an error. .Sh RETURN VALUES Upon successful completion, the .Fn proc_walk |