usr/src/man/man3proc/proc_walk.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 PROC_WALK 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm proc_walk
  19 .Nd walk all processes or threads in /proc
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft int
  24 .Fo proc_walk
  25 .Fa "proc_walk_f *func"
  26 .Fa "void *arg"
  27 .Fa "int flag"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fn proc_walk
  32 function walks all threads and processes in /proc and calls the callback
  33 function
  34 .Fa func
  35 once for each one with the user specified
  36 .Fa arg .
  37 The definition of the
  38 .Sy proc_walk_f
  39 is available in
  40 .Xr libproc 3LIB .
  41 .Pp
  42 .Fa func
  43 will be called once for each process and will always have its first
  44 argument filled in with the value of the
  45 .Sy psinfo
  46 file of the process.
  47 The value of
  48 .Fa flag
  49 controls whether or not information about the threads in the process are
  50 included and how many times the callback function
  51 .Fa func
  52 is called.
  53 The following values may be passed in for
  54 .Fa flag :
  55 .Bl -tag -width Dv -offset indent
  56 .It Dv PR_WALK_PROC
  57 Indicates that the walker is only concerned with the process.
  58 .Fa func
  59 will be called once for each process in the system.
  60 Only the
  61 .Sy psinfo
  62 will be read for the process and passed to
  63 .Fa func .
  64 The second argument, the one for the
  65 .Sy lwpsinfo_t ,
  66 will be passed as
  67 .Dv NULL .
  68 .It Dv PR_WALK_LWP
  69 The caller wants both process and thread information.
  70 .Fa func
  71 will be called once for each thread in the system.
  72 In addition to the process
  73 .Sy psinfo
  74 information, the ps specific information for a given thread will be
  75 included in the
  76 .Fa lwpsinfo_t
  77 argument.
  78 .El
  79 .Pp
  80 The return value of the caller's
  81 .Fa func
  82 function determines whether or not iteration will continue.
  83 If
  84 .Fa func
  85 returns a non-zero value, then iteration will terminate and that
  86 return value will be returned to the caller.
  87 To distinguish between system errors and caller errors, it is recommended that
  88 the function only return positive integers in the event of an error.
  89 .Sh RETURN VALUES
  90 Upon successful completion, the
  91 .Fn proc_walk
  92 function returns
  93 .Sy 0 .
  94 Otherwise,
  95 .Sy -1
  96 is returned and
  97 .Sy errno
  98 is updated to reflect the error that occurred.
  99 .Sh ERRORS
 100 In addition to the errors listed below, the
 101 .Fn proc_walk
 102 function may fail for the same reasons as the
 103 .Xr opendir 3C ,
 104 .Xr readdir 3C ,
 105 and
 106 .Xr malloc 3C
 107 functions.
 108 .Bl -tag -width Er
 109 .It Er EINVAL
 110 .Fa flag is not one of
 111 .Dv PR_WALK_PROC
 112 or
 113 .Dv PR_WALK_LWP .
 114 .El
 115 .Sh INTERFACE STABILITY
 116 .Sy Uncommitted
 117 .Sh MT-LEVEL
 118 .Sy MT-Safe
 119 .Sh SEE ALSO
 120 .Xr malloc 3C ,
 121 .Xr opendir 3C ,
 122 .Xr readdir 3C ,
 123 .Xr libproc 3LIB ,
 124 .Xr proc 4