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