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