xref: /illumos-gate/usr/src/man/man3proc/proc_arg_grab.3proc (revision a7d7cafedfa26f9e421bbcaf42b7387ef67c0a31)
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.\"
14*a7d7cafeSRobert Mustacchi.Dd November 27, 2023
1543051d27SRobert Mustacchi.Dt PROC_ARG_GRAB 3PROC
1643051d27SRobert Mustacchi.Os
1743051d27SRobert Mustacchi.Sh NAME
1843051d27SRobert Mustacchi.Nm proc_arg_grab ,
1995adbecaSRobert Mustacchi.Nm proc_arg_xgrab
2043051d27SRobert Mustacchi.Nd process grabbing utility function
21*a7d7cafeSRobert Mustacchi.Sh LIBRARY
2243051d27SRobert Mustacchi.Lb libproc
23*a7d7cafeSRobert Mustacchi.Sh SYNOPSIS
2443051d27SRobert Mustacchi.In libproc.h
2543051d27SRobert Mustacchi.Ft "struct ps_prochandle"
2695adbecaSRobert Mustacchi.Fo proc_arg_grab
2743051d27SRobert Mustacchi.Fa "const char *arg"
2843051d27SRobert Mustacchi.Fa "int oflag"
2943051d27SRobert Mustacchi.Fa "int gflag"
3043051d27SRobert Mustacchi.Fa "int *perr"
3143051d27SRobert Mustacchi.Fc
3243051d27SRobert Mustacchi.Ft "struct ps_prochandle"
3343051d27SRobert Mustacchi.Fo proc_arg_xgrab
3443051d27SRobert Mustacchi.Fa "const char *arg"
3543051d27SRobert Mustacchi.Fa "const char *path"
3643051d27SRobert Mustacchi.Fa "int oflag"
3743051d27SRobert Mustacchi.Fa "int gflag"
3843051d27SRobert Mustacchi.Fa "int *perr"
3943051d27SRobert Mustacchi.Fa "const char **lwps"
4043051d27SRobert Mustacchi.Fc
4143051d27SRobert Mustacchi.Sh DESCRIPTION
4243051d27SRobert MustacchiThe
4343051d27SRobert Mustacchi.Fn proc_arg_grab
4443051d27SRobert Mustacchiand
4543051d27SRobert Mustacchi.Fn proc_arg_xgrab
4643051d27SRobert Mustacchifunctions are utility functions which process arguments pointing to a
4743051d27SRobert Mustacchicurrently active process or a core file and returns a process handle to
4843051d27SRobert Mustacchiit.
4943051d27SRobert Mustacchi.Pp
5043051d27SRobert MustacchiThe string
5143051d27SRobert Mustacchi.Fa arg
5272d3dbb9SYuri Pankovcontains the name of something to try and open.
5372d3dbb9SYuri PankovHow it is interpreted depends on the value of
5443051d27SRobert Mustacchi.Fa oflag .
5543051d27SRobert MustacchiThe following values may be passed in as a bitwise-exclusive-OR for
5643051d27SRobert Mustacchi.Fa oflag :
5743051d27SRobert Mustacchi.Bl -tag -width Dv -offset indent
5843051d27SRobert Mustacchi.It Dv PR_ARG_PIDS
5943051d27SRobert MustacchiAllows
6043051d27SRobert Mustacchi.Fa arg
6143051d27SRobert Mustacchito specify process IDs and /proc arguments.
6243051d27SRobert Mustacchi.It Dv PR_ARG_CORES
6343051d27SRobert MustacchiAllows
6443051d27SRobert Mustacchi.Fa arg
6543051d27SRobert Mustacchito specify core files.
6643051d27SRobert Mustacchi.It PR_ARG_ANY
6795adbecaSRobert MustacchiEncompasses all of the previous flags.
6843051d27SRobert Mustacchi.El
6943051d27SRobert Mustacchi.Pp
7043051d27SRobert MustacchiThe argument
7143051d27SRobert Mustacchi.Fa gflag
7243051d27SRobert Mustacchicontrols the behavior when the corresponding process grabbing function
7372d3dbb9SYuri Pankovis called by the underlying system.
7472d3dbb9SYuri PankovFor a list of flags that may be passed in here, see
7543051d27SRobert Mustacchi.Xr Pgrab 3PROC
7643051d27SRobert Mustacchiand
7743051d27SRobert Mustacchi.Xr Pgrab_core 3PROC .
7843051d27SRobert Mustacchi.Pp
7943051d27SRobert MustacchiThe argument
8043051d27SRobert Mustacchi.Fa perr
8143051d27SRobert Mustacchimust be a
8243051d27SRobert Mustacchi.Pf non- Dv NULL
8343051d27SRobert Mustacchipointer and in the event that the
8443051d27SRobert Mustacchi.Fn proc_arg_grab
8543051d27SRobert Mustacchior
8643051d27SRobert Mustacchi.Fn proc_arg_xgrab
8743051d27SRobert Mustacchifunctions fail, then
8843051d27SRobert Mustacchi.Fa perr
8943051d27SRobert Mustacchiwill be updated with a more detailed error number.
9043051d27SRobert Mustacchi.Pp
9143051d27SRobert MustacchiThe
9243051d27SRobert Mustacchi.Fa path
9343051d27SRobert Mustacchiargument allows a search path for its binaries to be specified in case a
9443051d27SRobert Mustacchicore file is found and opened.
9543051d27SRobert Mustacchi.Pp
9643051d27SRobert MustacchiIf the
9743051d27SRobert Mustacchi.Fa lwps
9843051d27SRobert Mustacchiargument is
9943051d27SRobert Mustacchi.Pf non- Dv NULL ,
10095adbecaSRobert Mustacchithen the functions will treat any portion of
10195adbecaSRobert Mustacchi.Fa arg
10295adbecaSRobert Mustacchiafter a
10395adbecaSRobert Mustacchi.Sq /
10495adbecaSRobert Mustacchicharacter as a thread range.
10595adbecaSRobert MustacchiThe thread range will be validated as though a call to the
10643051d27SRobert Mustacchi.Xr proc_lwp_range_valid 3PROC
10795adbecaSRobert Mustacchifunction had been made, and a pointer to the start of the range will be
10895adbecaSRobert Mustacchistored in
10995adbecaSRobert Mustacchi.Fa lwps .
11095adbecaSRobert MustacchiFor a discussion of what constitutes a valid thread range, please see
11195adbecaSRobert Mustacchi.Xr proc_lwp_range_valid 3PROC .
11243051d27SRobert Mustacchi.Sh RETURN VALUES
11343051d27SRobert MustacchiUpon successful completion, the
11443051d27SRobert Mustacchi.Fn proc_arg_grab
11543051d27SRobert Mustacchiand
11643051d27SRobert Mustacchi.Fn proc_arg_xgrab
11795adbecaSRobert Mustacchifunctions return a pointer to the process handle.
11843051d27SRobert MustacchiOtherwise,
11943051d27SRobert Mustacchi.Dv NULL
12043051d27SRobert Mustacchiis returned and
12143051d27SRobert Mustacchi.Fa perr
12243051d27SRobert Mustacchiis set to include a more specific error.
12343051d27SRobert Mustacchi.Sh ERRORS
12443051d27SRobert MustacchiFor a full list of additional errors, see the
12543051d27SRobert Mustacchi.Sy ERRORS
12643051d27SRobert Mustacchisection in
12743051d27SRobert Mustacchi.Xr Pgrab 3PROC
12843051d27SRobert Mustacchiand
12943051d27SRobert Mustacchi.Xr Pgrab_core 3PROC .
13043051d27SRobert Mustacchi.Pp
13143051d27SRobert MustacchiThe
13243051d27SRobert Mustacchi.Fn proc_arg_grab
13343051d27SRobert Mustacchiand
13443051d27SRobert Mustacchi.Fn proc_arg_xgrab
13543051d27SRobert Mustacchifunction will fail if:
13643051d27SRobert Mustacchi.Bl -tag -width Er
13743051d27SRobert Mustacchi.It Er G_BADLWPS
13843051d27SRobert Mustacchi.Fa arg
13943051d27SRobert Mustacchicontains an invalid thread specification.
14043051d27SRobert Mustacchi.It Er G_NOCORE
14143051d27SRobert Mustacchi.Dv PR_ARG_CORES
14243051d27SRobert Mustacchiwas set and no core file could be found corresponding to
14343051d27SRobert Mustacchi.Fa arg .
14443051d27SRobert Mustacchi.It Er G_NOPROC
14543051d27SRobert Mustacchi.Dv PR_ARG_PIDS
14643051d27SRobert Mustacchiwas set and no process could be found corresponding to
14743051d27SRobert Mustacchi.Fa arg .
14843051d27SRobert Mustacchi.It Er G_NOPROCORCORE
14943051d27SRobert MustacchiBoth
15043051d27SRobert Mustacchi.Dv PR_ARG_CORES
15143051d27SRobert Mustacchiand
15243051d27SRobert Mustacchi.Dv PR_ARG_NOPROC
15343051d27SRobert Mustacchiwere set and no process or core file could be found corresponding to
15443051d27SRobert Mustacchi.Fa arg .
15543051d27SRobert Mustacchi.El
15643051d27SRobert Mustacchi.Sh INTERFACE STABILITY
15743051d27SRobert Mustacchi.Sy Uncommitted
15843051d27SRobert Mustacchi.Sh MT-LEVEL
15943051d27SRobert Mustacchi.Sy MT-Safe
16043051d27SRobert Mustacchi.Sh SEE ALSO
16143051d27SRobert Mustacchi.Xr libproc 3LIB ,
16243051d27SRobert Mustacchi.Xr Pgrab 3PROC ,
16343051d27SRobert Mustacchi.Xr Pgrab_core 3PROC ,
16443051d27SRobert Mustacchi.Xr Prelease 3PROC ,
16543051d27SRobert Mustacchi.Xr proc_lwp_range_valid 3PROC ,
166bbf21555SRichard Lowe.Xr proc 5
167