.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 22, 2020
.Dt PROC_ARG_GRAB 3PROC
.Os
.Sh NAME
.Nm proc_arg_grab ,
.Nm proc_arg_xgrab
.Nd process grabbing utility function
.Sh SYNOPSIS
.Lb libproc
.In libproc.h
.Ft "struct ps_prochandle"
.Fo proc_arg_grab
.Fa "const char *arg"
.Fa "int oflag"
.Fa "int gflag"
.Fa "int *perr"
.Fc
.Ft "struct ps_prochandle"
.Fo proc_arg_xgrab
.Fa "const char *arg"
.Fa "const char *path"
.Fa "int oflag"
.Fa "int gflag"
.Fa "int *perr"
.Fa "const char **lwps"
.Fc
.Sh DESCRIPTION
The
.Fn proc_arg_grab
and
.Fn proc_arg_xgrab
functions are utility functions which process arguments pointing to a
currently active process or a core file and returns a process handle to
it.
.Pp
The string
.Fa arg
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 :
.Bl -tag -width Dv -offset indent
.It Dv PR_ARG_PIDS
Allows
.Fa arg
to specify process IDs and /proc arguments.
.It Dv PR_ARG_CORES
Allows
.Fa arg
to specify core files.
.It PR_ARG_ANY
Encompasses all of the previous flags.
.El
.Pp
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
.Xr Pgrab 3PROC
and
.Xr Pgrab_core 3PROC .
.Pp
The argument
.Fa perr
must be a
.Pf non- Dv NULL
pointer and in the event that the
.Fn proc_arg_grab
or
.Fn proc_arg_xgrab
functions fail, then
.Fa perr
will be updated with a more detailed error number.
.Pp
The
.Fa path
argument allows a search path for its binaries to be specified in case a
core file is found and opened.
.Pp
If the
.Fa lwps
argument is
.Pf non- Dv NULL ,
then the functions will treat any portion of
.Fa arg
after a
.Sq /
character as a thread range.
The thread range will be validated as though a call to the
.Xr proc_lwp_range_valid 3PROC
function had been made, and a pointer to the start of the range will be
stored in
.Fa lwps .
For a discussion of what constitutes a valid thread range, please see
.Xr proc_lwp_range_valid 3PROC .
.Sh RETURN VALUES
Upon successful completion, the
.Fn proc_arg_grab
and
.Fn proc_arg_xgrab
functions return a pointer to the process handle.
Otherwise,
.Dv NULL
is returned and
.Fa perr
is set to include a more specific error.
.Sh ERRORS
For a full list of additional errors, see the
.Sy ERRORS
section in
.Xr Pgrab 3PROC
and
.Xr Pgrab_core 3PROC .
.Pp
The
.Fn proc_arg_grab
and
.Fn proc_arg_xgrab
function will fail if:
.Bl -tag -width Er
.It Er G_BADLWPS
.Fa arg
contains an invalid thread specification.
.It Er G_NOCORE
.Dv PR_ARG_CORES
was set and no core file could be found corresponding to
.Fa arg .
.It Er G_NOPROC
.Dv PR_ARG_PIDS
was set and no process could be found corresponding to
.Fa arg .
.It Er G_NOPROCORCORE
Both
.Dv PR_ARG_CORES
and
.Dv PR_ARG_NOPROC
were set and no process or core file could be found corresponding to
.Fa arg .
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr Pgrab 3PROC ,
.Xr Pgrab_core 3PROC ,
.Xr Prelease 3PROC ,
.Xr proc_lwp_range_valid 3PROC ,
.Xr proc 5