libs/src/misc/m_env.3

   1 .\"(c) Copyright 1992 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: m_env.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH ENV 3L "20 October 1992"
   7 .SH NAME
   8 env_create, env_destroy, env_make, env_addvar, env_addstr, env_remvar, env_lookup, env_getvars -- environment manipulation functions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "m_env.h"
  14 .LP
  15 .ft B
  16 env_h env_create( env )
  17 env_h env ;
  18 .LP
  19 .ft B
  20 void env_destroy( env )
  21 env_h env ;
  22 .LP
  23 .ft B
  24 env_h env_make( env_strings )
  25 char **env_strings ;
  26 .LP
  27 .ft B
  28 int env_addvar( env, from_env, var )
  29 env_h env ;
  30 env_h from_env ;
  31 char *var ;
  32 .LP
  33 .ft B
  34 int env_addstr( env, str )
  35 env_h env ;
  36 char *str ;
  37 .LP
  38 .ft B
  39 int env_remvar( env, var )
  40 env_h env ;
  41 char *var ;
  42 .LP
  43 .ft B
  44 char **env_getvars( env )
  45 env_h env ;
  46 .SH DESCRIPTION
  47 This library handles environments. An environment is a set of strings
  48 of the form
  49 .I "name=value".
  50 In the following, we will use the term string as a synonym of
  51 NUL-terminated array of
  52 .I char.
  53 .LP
  54 .B env_create()
  55 creates a new environment. The new environment will be empty unless
  56 the argument
  57 .I env
  58 is not
  59 .SB ENV_NULL.
  60 In that case, the new environment will be a duplicate of
  61 .I env
  62 (i.e. they will contain the same strings).
  63 .LP
  64 .B env_destroy()
  65 destroys the specified environment.
  66 .LP
  67 .B env_make()
  68 creates a new environment which includes the
  69 .I env_strings.
  70 .I env_strings
  71 should be a NULL-terminated array of strings.
  72 .LP
  73 .B env_addvar()
  74 adds the specified variable
  75 .I var
  76 to
  77 .I env.
  78 The variable value is obtained from the environment
  79 .I from_env.
  80 If the variable exists already in
  81 .I env
  82 the old value is replaced with the new value.
  83 .LP
  84 .B env_addstr()
  85 adds a string of the form
  86 .I "name=value"
  87 to
  88 .I env.
  89 .LP
  90 .B env_remvar()
  91 removes the specified variable
  92 .I var
  93 from the environment
  94 .I env.
  95 .LP
  96 .B env_lookup()
  97 searches
  98 .I env
  99 for variable
 100 .I var.
 101 It returns a string of the form
 102 .I "name=value"
 103 where
 104 .I name
 105 is the name of the variable
 106 (i.e. it is equal to
 107 .I var).
 108 .LP
 109 .B env_getvars
 110 returns a NULL-terminated array of strings of the form
 111 .I "name=value".
 112 .SH "RETURN VALUES"
 113 In case of error, all calls will place an error code in the global variable
 114 .I env_errno.
 115 Possible error codes:
 116 .TP 15
 117 .SB ENV_ENOMEM
 118 out of memory
 119 .TP
 120 .SB ENV_EBADVAR
 121 variable is not in environment
 122 .TP
 123 .SB ENV_EBADSTRING
 124 string is not well-formed (i.e. is not of the form \fIname=value\fR).
 125 .LP
 126 .B env_create()
 127 returns a handle or
 128 .SM ENV_NULL
 129 if it fails.
 130 .LP
 131 .B env_make()
 132 returns a handle or
 133 .SM ENV_NULL
 134 if it fails.
 135 .LP
 136 .B env_addvar()
 137 returns
 138 .SM ENV_OK
 139 on success or
 140 .SM ENV_ERR
 141 on failure.
 142 .LP
 143 .B env_addstr()
 144 returns
 145 .SM ENV_OK
 146 on success or
 147 .SM ENV_ERR
 148 on failure.
 149 .LP
 150 .B env_remvar()
 151 returns
 152 .SM ENV_OK
 153 on success or
 154 .SM ENV_ERR
 155 if the variable is not part of the environment.
 156 .LP
 157 .B env_loopkup()
 158 returns a string on success or
 159 .SM NULL
 160 on failure.
 161 .SH "SEE ALSO"
 162 environ(5)