1 files changed, 54 insertions, 43 deletions
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.