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 March 2, 2017
  15 .Dt PENV_ITER 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Penv_iter
  19 .Nd iterate process environment
  20 .Sh LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft int
  25 .Fo Penv_iter
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "proc_env_f *func"
  28 .Fa "void *data"
  29 .Fc
  30 .Sh DESCRIPTION
  31 The
  32 .Fn Penv_iter
  33 function iterates over the environment of the process represented by
  34 .Fa P .
  35 For each environment variable,
  36 .Fa func
  37 is passed the caller argument
  38 .Fa data
  39 along with the address of the environment variable and the key-value pair.
  40 For the full signature of the
  41 .Ft proc_env_f
  42 callback, see
  43 .Xr libproc 3LIB .
  44 .Pp
  45 The callback's return value controls whether or not iteration proceeds.
  46 If
  47 .Fa func
  48 returns zero, then iteration continues.
  49 Otherwise, iteration is terminated and the value is returned.
  50 It is recommended that callback functions do not return
  51 .Sy -1
  52 so as to distinguish between the failure of the
  53 .Fn Penv_iter
  54 function and the callback function.
  55 .Sh RETURN VALUES
  56 Upon successful completion, the
  57 .Fn Penv_iter
  58 function returns
  59 .Sy 0 .
  60 Otherwise, if there was an internal error, for example due to a
  61 corrupted environment, then
  62 .Sy -1
  63 is returned.
  64 Otherwise, if the callback function
  65 .Fa func
  66 returns non-zero, then its return value will be returned instead.
  67 .Sh INTERFACE STABILITY
  68 .Sy Uncommitted
  69 .Sh MT-LEVEL
  70 See
  71 .Sy LOCKING
  72 in
  73 .Xr libproc 3LIB .
  74 .Sh SEE ALSO
  75 .Xr libproc 3LIB