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 PLWP_ITER 3PROC
16.Os
17.Sh NAME
18.Nm Plwp_iter ,
19.Nm Plwp_iter_all
20.Nd iterate over threads
21.Sh LIBRARY
22.Lb libproc
23.Sh SYNOPSIS
24.In libproc.h
25.Ft int
26.Fo Plwp_iter
27.Fa "struct ps_prochandle *P"
28.Fa "proc_lwp_f *func",
29.Fa "void *data"
30.Fc
31.Ft int
32.Fo Plwp_iter_all
33.Fa "struct ps_prochandle *P"
34.Fa "proc_lwp_all_f *func"
35.Fa "void *data"
36.Fc
37.Sh DESCRIPTION
38The
39.Fn Plwp_iter
40and
41.Fn Plwp_iter_all
42functions iterates over threads in the given process handle
43.Fa P .
44The
45.Fn Plwp_iter
46function iterates over all active threads, where as the
47.Fn Plwp_iter_all
48function iterates over both active threads and zombie threads -- threads
49waiting to be reaped.
50.Pp
51For each thread, the callback function
52.Fa func
53is called with the pointer to the private data argument,
54.Fa data ,
55and the thread's
56.Sy lwpstatus_t
57structure.
58In the case of the
59.Fn Plwp_iter_all
60function, the thread's
61.Sy lwpsinfo_t
62is also included.
63.Pp
64The return value of
65.Fa func
66controls whether or not iteration continues.
67If
68.Fa func
69returns
70.Sy 0 ,
71then both functions will continue iteration.
72However, if
73.Fa func
74returns non-zero, then iteration will halt and that value will be used
75as the return value of the
76.Fn Plwp_iter
77and
78.Fn Plwp_iter_all
79functions.
80Because both functions return
81.Sy -1
82on internal failure, it is recommended that the callback function does
83not return
84.Sy -1
85to indicate an error so that the caller may distinguish between the
86failure of the callback function and the failure of the
87.Fn Plwp_iter
88and
89.Fn Plwp_iter_all
90functions.
91.Sh RETURN VALUES
92Upon successful completion, the
93.Fn Plwp_iter
94and
95.Fn Plwp_iter_all
96functions return
97.Sy 0 .
98Otherwise, if there was an internal error or there is no thread data, then
99.Sy -1
100is returned.
101Otherwise, if the callback function
102.Fa func
103returns non-zero, then its return value will be returned instead.
104.Sh INTERFACE STABILITY
105.Sy Uncommitted
106.Sh MT-LEVEL
107See
108.Sy LOCKING
109in
110.Xr libproc 3LIB .
111.Sh SEE ALSO
112.Xr libproc 3LIB
113