usr/src/man/man3proc/Plwp_iter.3proc

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PLWP_ITER 3PROC
.Os
.Sh NAME
.Nm Plwp_iter ,
.Nm Plwp_iter_all
.Nd iterate over threads
.Sh SYNOPSIS
.Lb libproc
.In libproc.h
.Ft int
.Fo Plwp_iter
.Fa "struct ps_prochandle *P"
.Fa "proc_lwp_f *func",
.Fa "void *data"
.Fc
.Ft int
.Fo Plwp_iter_all
.Fa "struct ps_prochandle *P"
.Fa "proc_lwp_all_f *func"
.Fa "void *data"
.Fc
.Sh DESCRIPTION
The
.Fn Plwp_iter
and
.Fn Plwp_iter_all
functions iterates over threads in the given process handle
.Fa P .
The
.Fn Plwp_iter
function iterates over all active threads, where as the
.Fn Plwp_iter_all
function iterates over both active threads and zombie threads -- threads
waiting to be reaped.
.Pp
For each thread, the callback function
.Fa func
is called with the pointer to the private data argument,
.Fa data ,
and the thread's
.Sy lwpstatus_t
structure.
In the case of the
.Fn Plwp_iter_all
function, the thread's
.Sy lwpsinfo_t
is also included.
.Pp
The return value of
.Fa func
controls whether or not iteration continues.
If
.Fa func
returns
.Sy 0 ,
then both functions will continue iteration.
However, if
.Fa func
returns non-zero, then iteration will halt and that value will be used
as the return value of the
.Fn Plwp_iter
and
.Fn Plwp_iter_all
functions.
Because both functions return
.Sy -1
on internal failure, it is recommended that the callback function does
not return
.Sy -1
to indicate an error so that the caller may distinguish between the
failure of the callback function and the failure of the
.Fn Plwp_iter
and
.Fn Plwp_iter_all
functions.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Plwp_iter
and
.Fn Plwp_iter_all
functions return
.Sy 0 .
Otherwise, if there was an internal error or there is no thread data, then
.Sy -1
is returned.
Otherwise, if the callback function
.Fa func
returns non-zero, then its return value will be returned instead.
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB