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