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. 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 80The return value of the caller's 81.Fa func 82function determines whether or not iteration will continue. 83If 84.Fa func 85returns a non-zero value, then iteration will terminate and that 86return value will be returned to the caller. 87To distinguish between system errors and caller errors, it is recommended that 88the function only return positive integers in the event of an error. 89.Sh RETURN VALUES 90Upon successful completion, the 91.Fn proc_walk 92function returns 93.Sy 0 . 94Otherwise, 95.Sy -1 96is returned and 97.Sy errno 98is updated to reflect the error that occurred. 99.Sh ERRORS 100In addition to the errors listed below, the 101.Fn proc_walk 102function may fail for the same reasons as the 103.Xr opendir 3C , 104.Xr readdir 3C , 105and 106.Xr malloc 3C 107functions. 108.Bl -tag -width Er 109.It Er EINVAL 110.Fa flag is not one of 111.Dv PR_WALK_PROC 112or 113.Dv PR_WALK_LWP . 114.El 115.Sh INTERFACE STABILITY 116.Sy Uncommitted 117.Sh MT-LEVEL 118.Sy MT-Safe 119.Sh SEE ALSO 120.Xr malloc 3C , 121.Xr opendir 3C , 122.Xr readdir 3C , 123.Xr libproc 3LIB , 124.Xr proc 4 125