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

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