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