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