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