usr/src/man/man3proc/proc_arg_psinfo.3proc

   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 November 27, 2023
  15 .Dt PROC_ARG_PSINFO 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm proc_arg_psinfo ,
  19 .Nm proc_arg_xpsinfo
  20 .Nd process ps information utility function
  21 .Sh LIBRARY
  22 .Lb libproc
  23 .Sh SYNOPSIS
  24 .In libproc.h
  25 .Ft pid_t
  26 .Fo proc_arg_psinfo
  27 .Fa "const char *arg"
  28 .Fa "int oflag"
  29 .Fa "psinfo_t *psp"
  30 .Fa "int *perr"
  31 .Fc
  32 .Ft pid_t
  33 .Fo proc_arg_xpsinfo
  34 .Fa "const char *arg"
  35 .Fa "int oflag"
  36 .Fa "psinfo_t *psp"
  37 .Fa "int *perr"
  38 .Fa "const char **lwps"
  39 .Fc
  40 .Sh DESCRIPTION
  41 The
  42 .Fn proc_arg_psinfo
  43 and
  44 .Fn proc_arg_xpsinfo
  45 functions are utility functions which process an argument that may
  46 refer to a currently active process or core file and attempts to obtain the
  47 .Xr ps 1
  48 information from the process or core and fills it into
  49 .Fa psp .
  50 .Pp
  51 The string
  52 .Fa arg
  53 contains the name of something to try and open.
  54 How it is interpreted depends on the value of
  55 .Fa oflag .
  56 The following values may be passed in as a bitwise-exclusive-OR for
  57 .Fa oflag :
  58 .Bl -tag -width Dv -offset indent
  59 .It Dv PR_ARG_PIDS
  60 Allows
  61 .Fa arg
  62 to specify process IDs and /proc arguments.
  63 .It Dv PR_ARG_CORES
  64 Allows
  65 .Fa arg
  66 to specify core files.
  67 .It PR_ARG_ANY
  68 Encompasses all of the previous opens.
  69 .El
  70 .Pp
  71 The argument
  72 .Fa perr
  73 must be a
  74 .Pf non- Dv NULL
  75 pointer and in the event that the
  76 .Fn proc_arg_psinfo
  77 or
  78 .Fn proc_arg_xpsinfo
  79 functions fail, then
  80 .Fa perr
  81 will be updated with a more detailed error number.
  82 .Pp
  83 If the
  84 .Fa lwps
  85 argument is
  86 .Pf non- Dv NULL ,
  87 then if there is a thread specification present in
  88 .Fa arg ,
  89 it will be validated to see if it is a valid range and then a pointer to
  90 the start of the thread specification will be stored in
  91 .Fa lwps .
  92 For more information on determining process range validity, see
  93 .Xr proc_lwp_range_valid 3PROC
  94 for more information on valid and invalid tread specifications.
  95 .Sh RETURN VALUES
  96 Upon successful completion, the
  97 .Fn proc_arg_psinfo
  98 and
  99 .Fn proc_arg_xpsinfo
 100 functions return the process identifier and fill in
 101 .Fa psp
 102 with the ps information of the process.
 103 Otherwise,
 104 .Sy -1
 105 is returned and
 106 .Fa perr
 107 is filled in with the error's details.
 108 .Sh ERRORS
 109 For a full list of additional errors, see the
 110 .Sy ERRORS
 111 section in
 112 .Xr Pgrab_core 3PROC .
 113 .Bl -tag -width Er
 114 .It Er G_BADLWPS
 115 .Fa arg
 116 contains an invalid thread specification.
 117 .It Er G_NOCORE
 118 .Dv PR_ARG_CORES
 119 was set and no core file could be found corresponding to
 120 .Fa arg .
 121 .It Er G_NOPROC
 122 .Dv PR_ARG_PIDS
 123 was set and no process could be found corresponding to
 124 .Fa arg .
 125 .It Er G_NOPROCORCORE
 126 Both
 127 .Dv PR_ARG_CORES
 128 and
 129 .Dv PR_ARG_NOPROC
 130 were set and no process or core file could be found corresponding to
 131 .Fa arg .
 132 .El
 133 .Sh INTERFACE STABILITY
 134 .Sy Uncommitted
 135 .Sh MT-LEVEL
 136 .Sy MT-Safe
 137 .Sh SEE ALSO
 138 .Xr ps 1 ,
 139 .Xr libproc 3LIB ,
 140 .Xr Pgrab 3PROC ,
 141 .Xr Pgrab_core 3PROC ,
 142 .Xr Prelease 3PROC ,
 143 .Xr proc_lwp_range_valid 3PROC ,
 144 .Xr proc 5