1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd Aug 20, 2019
  15 .Dt PROC_ARG_GRAB 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm proc_arg_grab ,
  19 .Nm proc_arg_xgrab
  20 .Nd process grabbing utility function
  21 .Sh SYNOPSIS
  22 .Lb libproc
  23 .In libproc.h
  24 .Ft "struct ps_prochandle"
  25 .Fo proc_arg_grag
  26 .Fa "const char *arg"
  27 .Fa "int oflag"
  28 .Fa "int gflag"
  29 .Fa "int *perr"
  30 .Fc
  31 .Ft "struct ps_prochandle"
  32 .Fo proc_arg_xgrab
  33 .Fa "const char *arg"
  34 .Fa "const char *path"
  35 .Fa "int oflag"
  36 .Fa "int gflag"
  37 .Fa "int *perr"
  38 .Fa "const char **lwps"
  39 .Fc
  40 .Sh DESCRIPTION
  41 The
  42 .Fn proc_arg_grab
  43 and
  44 .Fn proc_arg_xgrab
  45 functions are utility functions which process arguments pointing to a
  46 currently active process or a core file and returns a process handle to
  47 it.
  48 .Pp
  49 The string
  50 .Fa arg
  51 contains the name of something to try and open.
  52 How it is interpreted depends on the value of
  53 .Fa oflag .
  54 The following values may be passed in as a bitwise-exclusive-OR for
  55 .Fa oflag :
  56 .Bl -tag -width Dv -offset indent
  57 .It Dv PR_ARG_PIDS
  58 Allows
  59 .Fa arg
  60 to specify process IDs and /proc arguments.
  61 .It Dv PR_ARG_CORES
  62 Allows
  63 .Fa arg
  64 to specify core files.
  65 .It PR_ARG_ANY
  66 Encompasses all of the previous opens.
  67 .El
  68 .Pp
  69 The argument
  70 .Fa gflag
  71 controls the behavior when the corresponding process grabbing function
  72 is called by the underlying system.
  73 For a list of flags that may be passed in here, see
  74 .Xr Pgrab 3PROC
  75 and
  76 .Xr Pgrab_core 3PROC .
  77 .Pp
  78 The argument
  79 .Fa perr
  80 must be a
  81 .Pf non- Dv NULL
  82 pointer and in the event that the
  83 .Fn proc_arg_grab
  84 or
  85 .Fn proc_arg_xgrab
  86 functions fail, then
  87 .Fa perr
  88 will be updated with a more detailed error number.
  89 .Pp
  90 The
  91 .Fa path
  92 argument allows a search path for its binaries to be specified in case a
  93 core file is found and opened.
  94 .Pp
  95 If the
  96 .Fa lwps
  97 argument is
  98 .Pf non- Dv NULL ,
  99 then if there is a thread specification present in
 100 .Fa arg ,
 101 it will be validated to see if it is a valid range and then a pointer to
 102 the start of the thread specification will be stored in
 103 .Fa lwps .
 104 For more information on determining process range validity, see
 105 .Xr proc_lwp_range_valid 3PROC
 106 for more information on valid and invalid tread specifications.
 107 .Sh RETURN VALUES
 108 Upon successful completion, the
 109 .Fn proc_arg_grab
 110 and
 111 .Fn proc_arg_xgrab
 112 functions return a pointer to the process handle is returned.
 113 Otherwise,
 114 .Dv NULL
 115 is returned and
 116 .Fa perr
 117 is set to include a more specific error.
 118 .Sh ERRORS
 119 For a full list of additional errors, see the
 120 .Sy ERRORS
 121 section in
 122 .Xr Pgrab 3PROC
 123 and
 124 .Xr Pgrab_core 3PROC .
 125 .Pp
 126 The
 127 .Fn proc_arg_grab
 128 and
 129 .Fn proc_arg_xgrab
 130 function will fail if:
 131 .Bl -tag -width Er
 132 .It Er G_BADLWPS
 133 .Fa arg
 134 contains an invalid thread specification.
 135 .It Er G_NOCORE
 136 .Dv PR_ARG_CORES
 137 was set and no core file could be found corresponding to
 138 .Fa arg .
 139 .It Er G_NOPROC
 140 .Dv PR_ARG_PIDS
 141 was set and no process could be found corresponding to
 142 .Fa arg .
 143 .It Er G_NOPROCORCORE
 144 Both
 145 .Dv PR_ARG_CORES
 146 and
 147 .Dv PR_ARG_NOPROC
 148 were set and no process or core file could be found corresponding to
 149 .Fa arg .
 150 .El
 151 .Sh INTERFACE STABILITY
 152 .Sy Uncommitted
 153 .Sh MT-LEVEL
 154 .Sy MT-Safe
 155 .Sh SEE ALSO
 156 .Xr libproc 3LIB ,
 157 .Xr Pgrab 3PROC ,
 158 .Xr Pgrab_core 3PROC ,
 159 .Xr Prelease 3PROC ,
 160 .Xr proc_lwp_range_valid 3PROC ,
 161 .Xr proc 4