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