xref: /illumos-gate/usr/src/man/man3proc/Pgrab.3proc (revision bbf215553c7233fbab8a0afdf1fac74c44781867)
143051d27SRobert Mustacchi.\"
243051d27SRobert Mustacchi.\" This file and its contents are supplied under the terms of the
343051d27SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0.
443051d27SRobert Mustacchi.\" You may only use this file in accordance with the terms of version
543051d27SRobert Mustacchi.\" 1.0 of the CDDL.
643051d27SRobert Mustacchi.\"
743051d27SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this
843051d27SRobert Mustacchi.\" source.  A copy of the CDDL is also available via the Internet at
943051d27SRobert Mustacchi.\" http://www.illumos.org/license/CDDL.
1043051d27SRobert Mustacchi.\"
1143051d27SRobert Mustacchi.\"
1243051d27SRobert Mustacchi.\" Copyright 2015 Joyent, Inc.
1343051d27SRobert Mustacchi.\"
1443051d27SRobert Mustacchi.Dd May 11, 2016
1543051d27SRobert Mustacchi.Dt PGRAB 3PROC
1643051d27SRobert Mustacchi.Os
1743051d27SRobert Mustacchi.Sh NAME
1843051d27SRobert Mustacchi.Nm Pgrab
1943051d27SRobert Mustacchi.Nd grab and control a process
20ab618543SJohn Levon.Sh LIBRARY
2143051d27SRobert Mustacchi.Lb libproc
22ab618543SJohn Levon.Sh SYNOPSIS
2343051d27SRobert Mustacchi.In libproc.h
2443051d27SRobert Mustacchi.Ft "struct ps_prochandle *"
2543051d27SRobert Mustacchi.Fo Pgrab
2643051d27SRobert Mustacchi.Fa "pid_t pid"
2743051d27SRobert Mustacchi.Fa "int flags"
2843051d27SRobert Mustacchi.Fa "int *perr"
2943051d27SRobert Mustacchi.Fc
3043051d27SRobert Mustacchi.Sh DESCRIPTION
3143051d27SRobert MustacchiThe
3243051d27SRobert Mustacchi.Fn Pgrab
3343051d27SRobert Mustacchifunction attempts to grab the process identified by
3443051d27SRobert Mustacchi.Fa pid
3543051d27SRobert Mustacchiand returns a handle to it that allows the process to be controlled,
3672d3dbb9SYuri Pankovinterrogated, and manipulated.
3772d3dbb9SYuri PankovThis interface only works with processes that already exist.
3872d3dbb9SYuri PankovUse
3943051d27SRobert Mustacchi.Xr Pgrab_core 3PROC
4043051d27SRobert Mustacchifor core files and
4143051d27SRobert Mustacchi.Xr Pcreate 3PROC
4243051d27SRobert Mustacchito create processes.
4343051d27SRobert Mustacchi.Pp
4443051d27SRobert MustacchiA grabbed process undergoes the following changes unless
4543051d27SRobert Mustacchi.Fa flags
4643051d27SRobert Mustacchiis set to the contrary:
4743051d27SRobert Mustacchi.Bl -bullet -offset indent
4843051d27SRobert Mustacchi.It
4943051d27SRobert MustacchiThe process is stopped
5043051d27SRobert Mustacchi.It
5143051d27SRobert MustacchiAll other tracing flags are cleared
5243051d27SRobert Mustacchi.It
5372d3dbb9SYuri PankovThe grab is exclusive.
5472d3dbb9SYuri PankovIf any existing handles to this process exist or anyone else is using the
5572d3dbb9SYuri Pankovunderlying facilities of the /proc file system to control this process,
5672d3dbb9SYuri Pankovit will fail.
5743051d27SRobert Mustacchi.It
5843051d27SRobert MustacchiUnless the process is already stopped, the
5943051d27SRobert Mustacchi.Dv PR_RLC
6072d3dbb9SYuri Pankovflag is set indicating the process should run-on-last-close.
6172d3dbb9SYuri PankovAllowing the process to resume running if its controlling process dies.
6243051d27SRobert Mustacchi.El
6343051d27SRobert Mustacchi.Pp
6443051d27SRobert MustacchiGrabbing a process is a
6543051d27SRobert Mustacchi.Em destructive
6672d3dbb9SYuri Pankovaction.
6772d3dbb9SYuri PankovStopping a process stops execution of all its threads.
6872d3dbb9SYuri PankovThe impact of stopping a process depends on the purpose of that process.
6943051d27SRobert MustacchiFor example, if one stops a process that's primarily doing
7043051d27SRobert Mustacchicomputation, then its computation is delayed the entire time that it
7172d3dbb9SYuri Pankovis stopped.
7272d3dbb9SYuri PankovHowever, if instead this is an active TCP server, then the accept backlog may
7372d3dbb9SYuri Pankovfill causing connection errors and potentially connection time out errors.
7443051d27SRobert Mustacchi.Pp
7543051d27SRobert MustacchiSpecial care must be taken to ensure that a stopped process continues,
7672d3dbb9SYuri Pankoveven if the controlling process terminates.
7772d3dbb9SYuri PankovIf the controlling process disables the
7843051d27SRobert Mustacchi.Dv PR_RLC
7943051d27SRobert Mustacchiflag or the process was already stopped, then the process remains
8072d3dbb9SYuri Pankovstopped after the controlling process terminates.
8172d3dbb9SYuri PankovExercise caution when changing this behavior.
8243051d27SRobert Mustacchi.Pp
8343051d27SRobert MustacchiMany of these default behaviors can be controlled by passing values to
8443051d27SRobert Mustacchithe
8543051d27SRobert Mustacchi.Fa flags
8672d3dbb9SYuri Pankovargument.
8772d3dbb9SYuri PankovValues for
8843051d27SRobert Mustacchi.Fa flags
8943051d27SRobert Mustacchiare constructed by a bitwise-inclusive-OR of flags from the following
9043051d27SRobert Mustacchilist:
9143051d27SRobert Mustacchi.Bl -tag -width Dv -offset indent
9243051d27SRobert Mustacchi.It Dv PGRAB_RETAIN
9343051d27SRobert MustacchiIndicates that any existing tracing flags on
9443051d27SRobert Mustacchi.Fa pid
9572d3dbb9SYuri Pankovshould be retained.
9672d3dbb9SYuri PankovIf this flag is not specified, they will be cleared as part of creating the
9743051d27SRobert Mustacchi.Sy libproc
9843051d27SRobert Mustacchihandle for this process.
9943051d27SRobert Mustacchi.Pp
10043051d27SRobert MustacchiNormally extant tracing flags are cleared when a process is grabbed.
10143051d27SRobert Mustacchi.It Dv PGRAB_FORCE
10272d3dbb9SYuri PankovIndicates that the process should not be grabbed exclusively.
10372d3dbb9SYuri PankovCare should be taken with this option.
10472d3dbb9SYuri PankovIf other consumers are manipulating the process, then this may result in
10572d3dbb9SYuri Pankovsurprising behavior as the process is being manipulated from multiple points of
10672d3dbb9SYuri Pankovcontrol at the same time.
10743051d27SRobert Mustacchi.Pp
10843051d27SRobert MustacchiNormally an attempt will be made to grab the process exclusively and
10943051d27SRobert Mustacchifail if it is already in use.
11043051d27SRobert Mustacchi.It Dv PGRAB_RDONLY
11143051d27SRobert MustacchiIndicates that the process should be grabbed in a read-only fashion.
11243051d27SRobert MustacchiThis implies that both the
11343051d27SRobert Mustacchi.Dv PGRAB_RETAIN
11443051d27SRobert Mustacchiand
11543051d27SRobert Mustacchi.Dv PGRAB_NOSTOP
11672d3dbb9SYuri Pankovflags should be set.
11772d3dbb9SYuri PankovIf a process is opened read-only, then a caller can only read information about
11872d3dbb9SYuri Pankova process and cannot manipulate it, change its current state, or inject systems
11972d3dbb9SYuri Pankovcalls into it.
12043051d27SRobert Mustacchi.Pp
12172d3dbb9SYuri PankovNormally when a process is grabbed, it does so for both reading and writing.
12243051d27SRobert Mustacchi.It Dv PGRAB_NOSTOP
12372d3dbb9SYuri PankovDo not stop a process as it is grabbed.
12472d3dbb9SYuri PankovNote, any extant tracing flags on the process will still be cleared unless the
12543051d27SRobert Mustacchi.Dv PGRAB_RETAIN
12643051d27SRobert Mustacchiflag has been set.
12743051d27SRobert Mustacchi.Pp
12843051d27SRobert MustacchiNormally a process is stopped as a result of grabbing the process.
12943051d27SRobert Mustacchi.El
13043051d27SRobert Mustacchi.Pp
13143051d27SRobert MustacchiThe
13243051d27SRobert Mustacchi.Fa perr
13343051d27SRobert Mustacchiargument must be a
13443051d27SRobert Mustacchi.Pf non- Dv NULL
13543051d27SRobert Mustacchipointer which will store a more detailed error in the event that the
13643051d27SRobert Mustacchi.Fn Pgrab
13772d3dbb9SYuri Pankovfunction fails.
13872d3dbb9SYuri PankovA human-readable form of the error can be obtained with
13943051d27SRobert Mustacchi.Xr Pgrab_error 3PROC .
14043051d27SRobert Mustacchi.Pp
14143051d27SRobert MustacchiOnce a caller is done with the library handle it should call
14243051d27SRobert Mustacchi.Xr Prelease 3PROC
14372d3dbb9SYuri Pankovto release the grabbed process.
14472d3dbb9SYuri PankovFailure to properly release the handle may leave a process stopped and interfere
14572d3dbb9SYuri Pankovwith the ability of other software to obtain a handle.
14643051d27SRobert Mustacchi.Ss Permissions
14743051d27SRobert MustacchiUnprivileged users may grab and control their own processes only if both
14843051d27SRobert Mustacchithe user and group IDs of the target process match those of the calling
14972d3dbb9SYuri Pankovprocess.
15072d3dbb9SYuri PankovIn addition, the caller must have a super set of the target's privileges.
15172d3dbb9SYuri PankovProcesses with the
15243051d27SRobert Mustacchi.Sy PRIV_PROC_OWNER
15343051d27SRobert Mustacchiprivilege may manipulate any process on the system, as long as it has an
15472d3dbb9SYuri Pankovequal privilege set.
15572d3dbb9SYuri PankovFor more details on the security and programming considerations, please see the
15672d3dbb9SYuri Pankovsection
15743051d27SRobert Mustacchi.Sy PROGRAMMING NOTES
15843051d27SRobert Mustacchiin
159*bbf21555SRichard Lowe.Xr proc 5 .
16043051d27SRobert Mustacchi.Sh RETURN VALUES
16143051d27SRobert MustacchiUpon successful completion, the
16243051d27SRobert Mustacchi.Fn Pgrab
16372d3dbb9SYuri Pankovfunction returns a control handle to the process.
16472d3dbb9SYuri PankovOtherwise,
16543051d27SRobert Mustacchi.Dv NULL
16643051d27SRobert Mustacchiis returned with
16743051d27SRobert Mustacchi.Fa perr
16843051d27SRobert Mustacchicontaining the error code.
16943051d27SRobert Mustacchi.Sh ERRORS
17043051d27SRobert MustacchiThe
17143051d27SRobert Mustacchi.Fn Pgrab
17243051d27SRobert Mustacchifunction will fail if:
17343051d27SRobert Mustacchi.Bl -tag -width Er
17443051d27SRobert Mustacchi.It Er G_BUSY
17543051d27SRobert MustacchiThe process
17643051d27SRobert Mustacchi.Fa pid
17743051d27SRobert Mustacchiis already being traced and the
17843051d27SRobert Mustacchi.Dv PGRAB_FORCE
17943051d27SRobert Mustacchiflag was not passed in
18043051d27SRobert Mustacchi.Fa flags .
18143051d27SRobert Mustacchi.It Er G_LP64
18243051d27SRobert MustacchiThe calling process is a 32-bit process and process
18343051d27SRobert Mustacchi.Fa pid
18443051d27SRobert Mustacchiis 64-bit.
18543051d27SRobert Mustacchi.It Er G_NOFD
18672d3dbb9SYuri PankovToo many files are open.
18772d3dbb9SYuri PankovThis is logically equivalent to receiving
18843051d27SRobert Mustacchi.Er EMFILE .
18943051d27SRobert Mustacchi.It Er G_NOPROC
19043051d27SRobert MustacchiThe process referred to by
19143051d27SRobert Mustacchi.Fa pid
19243051d27SRobert Mustacchidoes not exist.
19343051d27SRobert Mustacchi.It Er G_PERM
19443051d27SRobert MustacchiThe calling process has insufficient permissions or privileges to open
19572d3dbb9SYuri Pankovthe specified process.
19672d3dbb9SYuri PankovSee
19743051d27SRobert Mustacchi.Sx Permissions
19843051d27SRobert Mustacchifor more information.
19943051d27SRobert Mustacchi.It Er G_SYS
20043051d27SRobert MustacchiThe process referred to by
20143051d27SRobert Mustacchi.Fa pid
20243051d27SRobert Mustacchiis a system process and cannot be grabbed.
20343051d27SRobert Mustacchi.It Er G_SELF
20443051d27SRobert MustacchiThe process referred to by
20543051d27SRobert Mustacchi.Fa pid
20643051d27SRobert Mustacchiis the process ID of the caller and the
20743051d27SRobert Mustacchi.Dv PGRAB_RDONLY
20872d3dbb9SYuri Pankovwas not passed.
20972d3dbb9SYuri PankovA process may only grab itself if it's read-only.
21043051d27SRobert Mustacchi.It Er G_STRANGE
21143051d27SRobert MustacchiAn unanticipated system error occurred while trying to grab the process
21243051d27SRobert Mustacchifile and create the handle.
21343051d27SRobert MustacchiThe value of
21443051d27SRobert Mustacchi.Sy errno
21543051d27SRobert Mustacchiindicates the system failure.
21643051d27SRobert Mustacchi.It Er G_ZOMB
21743051d27SRobert MustacchiThe process referred to by
21843051d27SRobert Mustacchi.Fa pid
21943051d27SRobert Mustacchiis a zombie and cannot be grabbed.
22043051d27SRobert Mustacchi.El
22143051d27SRobert Mustacchi.Sh INTERFACE STABILITY
22243051d27SRobert Mustacchi.Sy Uncommitted
22343051d27SRobert Mustacchi.Sh MT-LEVEL
22443051d27SRobert Mustacchi.Sy MT-Safe
22543051d27SRobert Mustacchi.Sh SEE ALSO
22643051d27SRobert Mustacchi.Xr errno 3C ,
22743051d27SRobert Mustacchi.Xr libproc 3LIB ,
22843051d27SRobert Mustacchi.Xr Pfree 3PROC ,
22943051d27SRobert Mustacchi.Xr Pgrab_core 3PROC ,
23043051d27SRobert Mustacchi.Xr Pgrab_error 3PROC ,
23143051d27SRobert Mustacchi.Xr Pgrab_file 3PROC ,
23243051d27SRobert Mustacchi.Xr Prelease 3PROC
233