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