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_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. The following values may be passed in for 53.Fa flag : 54.Bl -tag -width Dv -offset indent 55.It Dv PR_WALK_PROC 56Indicates that the walker is only concerned with the process. 57.Fa func 58will be called once for each process in the system. Only the 59.Sy psinfo 60will be read for the process and passed to 61.Fa func . 62The second argument, the one for the 63.Sy lwpsinfo_t , 64will be passed as 65.Dv NULL . 66.It Dv PR_WALK_LWP 67The caller wants both process and thread information. 68.Fa func 69will be called once for each thread in the system. In addition to the 70process 71.Sy psinfo 72information, the ps specific information for a given thread will be 73included in the 74.Fa lwpsinfo_t 75argument. 76.El 77.Pp 78The return value of the caller's 79.Fa func 80function determines whether or not iteration will continue. If 81.Fa func 82returns a non-zero value, then iteration will terminate and that 83return value will be returned to the caller. To distinguish between 84system errors and caller errors, it is recommended that the function 85only return positive integers in the event of an error. 86.Sh RETURN VALUES 87Upon successful completion, the 88.Fn proc_walk 89function returns 90.Sy 0 . 91Otherwise, 92.Sy -1 93is returned and 94.Sy errno 95is updated to reflect the error that occurred. 96.Sh ERRORS 97In addition to the errors listed below, the 98.Fn proc_walk 99function may fail for the same reasons as the 100.Xr opendir 3C , 101.Xr readdir 3C , 102and 103.Xr malloc 3C 104functions. 105.Bl -tag -width Er 106.It Er EINVAL 107.Fa flag is not one of 108.Dv PR_WALK_PROC 109or 110.Dv PR_WALK_LWP . 111.El 112.Sh INTERFACE STABILITY 113.Sy Uncommitted 114.Sh MT-LEVEL 115.Sy MT-Safe 116.Sh SEE ALSO 117.Xr malloc 3C , 118.Xr opendir 3C , 119.Xr readdir 3C , 120.Xr libproc 3LIB , 121.Xr proc 4 122