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. 53How it is interpreted depends 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. 102Otherwise, 103.Sy -1 104is returned and 105.Fa perr 106is filled in with the error's details. 107.Sh ERRORS 108For a full list of additional errors, see the 109.Sy ERRORS 110section in 111.Xr Pgrab_core 3PROC . 112.Bl -tag -width Er 113.It Er G_BADLWPS 114.Fa arg 115contains an invalid thread specification. 116.It Er G_NOCORE 117.Dv PR_ARG_CORES 118was set and no core file could be found corresponding to 119.Fa arg . 120.It Er G_NOPROC 121.Dv PR_ARG_PIDS 122was set and no process could be found corresponding to 123.Fa arg . 124.It Er G_NOPROCORCORE 125Both 126.Dv PR_ARG_CORES 127and 128.Dv PR_ARG_NOPROC 129were 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 144