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 2019 Joyent, Inc. 13.\" 14.Dd December 2, 2019 15.Dt PROC_WALK 3PROC 16.Os 17.Sh NAME 18.Nm proc_walk 19.Nd walk all processes or threads in /proc 20.Sh SYNOPSIS 21.Lb libproc 22.In libproc.h 23.Ft int 24.Fo proc_walk 25.Fa "proc_walk_f *func" 26.Fa "void *arg" 27.Fa "int flag" 28.Fc 29.Sh DESCRIPTION 30The 31.Fn proc_walk 32function walks all threads and processes in /proc and calls the callback 33function 34.Fa func 35once for each one with the user specified 36.Fa arg . 37The definition of the 38.Sy proc_walk_f 39is available in 40.Xr libproc 3LIB . 41.Pp 42.Fa func 43will be called once for each process and will always have its first 44argument filled in with the value of the 45.Sy psinfo 46file of the process. 47The value of 48.Fa flag 49controls whether or not information about the threads in the process are 50included and how many times the callback function 51.Fa func 52is called. 53The following values may be passed in for 54.Fa flag : 55.Bl -tag -width Dv -offset indent 56.It Dv PR_WALK_PROC 57Indicates that the walker is only concerned with the process. 58.Fa func 59will be called once for each process in the system. 60Only the 61.Sy psinfo 62will be read for the process and passed to 63.Fa func . 64The second argument, the one for the 65.Sy lwpsinfo_t , 66will be passed as 67.Dv NULL . 68.It Dv PR_WALK_LWP 69The caller wants both process and thread information. 70.Fa func 71will be called once for each thread in the system. 72In addition to the process 73.Sy psinfo 74information, the ps specific information for a given thread will be 75included in the 76.Fa lwpsinfo_t 77argument. 78.El 79.Pp 80In addition, the following values may be combined with one of the above 81values of 82.Fa flag 83with a bitwise-inclusive-OR: 84.Bl -tag -width Dv -offset indent 85.It Dv PR_WALK_INCLUDE_SYS 86Include 87.Sy SYS 88.Pq system 89processes. 90Normally 91.Sy SYS 92processes are skipped during the walk of the process tree. 93.El 94.Pp 95The return value of the caller's 96.Fa func 97function determines whether or not iteration will continue. 98If 99.Fa func 100returns a non-zero value, then iteration will terminate and that 101return value will be returned to the caller. 102To distinguish between system errors and caller errors, it is recommended that 103the function only return positive integers in the event of an error. 104.Sh RETURN VALUES 105Upon successful completion, the 106.Fn proc_walk 107function returns 108.Sy 0 . 109Otherwise, 110.Sy -1 111is returned and 112.Sy errno 113is updated to reflect the error that occurred. 114.Sh ERRORS 115In addition to the errors listed below, the 116.Fn proc_walk 117function may fail for the same reasons as the 118.Xr opendir 3C , 119.Xr readdir 3C , 120and 121.Xr malloc 3C 122functions. 123.Bl -tag -width Er 124.It Er EINVAL 125.Fa flag 126is not one of 127.Dv PR_WALK_PROC 128or 129.Dv PR_WALK_LWP . 130.El 131.Sh INTERFACE STABILITY 132.Sy Uncommitted 133.Sh MT-LEVEL 134.Sy MT-Safe 135.Sh SEE ALSO 136.Xr malloc 3C , 137.Xr opendir 3C , 138.Xr readdir 3C , 139.Xr libproc 3LIB , 140.Xr proc 4 141