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 PFDINFO_ITER 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pfdinfo_iter
  19 .Nd iterate open files in a process
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft int
  24 .Fo Pfdinfo_iter
  25 .Fa "struct ps_prochandle *P"
  26 .Fa "proc_fdinfo_f *func"
  27 .Fa "void *data"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fn Pfdinfo_iter
  32 function iterates over the open files in the process represented by
  33 .Fa P .
  34 .Pp
  35 For each open file, the callback function
  36 .Fa func
  37 will be invoked and it will be passed the
  38 .Fa data
  39 argument as well as a pointer to a
  40 .Sy prfdinfo_t
  41 structure defined in
  42 .Xr libproc 3LIB .
  43 For the full signature of the
  44 .Vt proc_fdinfo_f
  45 see
  46 .Xr libproc 3LIB .
  47 .Pp
  48 The return value of
  49 .Fa func
  50 controls whether or not iteration continues.
  51 If
  52 .Fa func
  53 returns
  54 .Sy 0 ,
  55 then iteration will continue.
  56 However, if
  57 .Fa func
  58 instead returns a non-zero value, then iteration will halt and that
  59 value will be used as the return value of the
  60 .Fn Pfdinfo_iter
  61 function.
  62 Because the
  63 .Fn Pfdinfo_iter
  64 function returns
  65 .Sy -1
  66 to an indicate its own errors, it is recommended that the callback
  67 function does not return
  68 .Sy -1
  69 to indicate an error so that the caller may distinguish between the
  70 failure of the callback function and the failure of the
  71 .Fn Pfdinfo_iter
  72 function.
  73 .Sh RETURN VALUES
  74 Upon successful completion, the
  75 .Fn Pfdinfo_iter
  76 returns
  77 .Sy 0 .
  78 Otherwise, if there was an internal error then
  79 .Sy -1
  80 is returned.
  81 Otherwise, if the callback function
  82 .Fa func
  83 returns non-zero, then its return value will be returned instead.
  84 .Sh INTERFACE STABILITY
  85 .Sy Uncommitted
  86 .Sh MT-LEVEL
  87 See
  88 .Sy LOCKING
  89 in
  90 .Xr libproc 3LIB .
  91 .Sh SEE ALSO
  92 .Xr libproc 3LIB