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