Commit | Line | Data |
---|---|---|
7860c229 KB |
1 | .\" Copyright (c) 1988, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
c80211f9 | 3 | .\" |
043368e6 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" the American National Standards Committee X3, on Information | |
6 | .\" Processing Systems. | |
7 | .\" | |
adb19fe0 | 8 | .\" %sccs.include.redist.man% |
31b20f0a | 9 | .\" |
653ba8b6 | 10 | .\" @(#)getenv.3 8.2 (Berkeley) %G% |
31b20f0a | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt GETENV 3 | |
14 | .Os | |
15 | .Sh NAME | |
16 | .Nm getenv , | |
17 | .Nm putenv , | |
18 | .Nm setenv , | |
19 | .Nm unsetenv | |
20 | .Nd environment variable functions | |
21 | .Sh SYNOPSIS | |
22 | .Fd #include <stdlib.h> | |
23 | .Ft char * | |
24 | .Fn getenv "const char *name" | |
25 | .Ft int | |
26 | .Fn setenv "const char *name" "const char *value" "int overwrite" | |
27 | .Ft int | |
28 | .Fn putenv "const char *string" | |
29 | .Ft void | |
30 | .Fn unsetenv "const char *name" | |
31 | .Sh DESCRIPTION | |
32 | These functions set, unset and fetch environment variables from the | |
33 | host | |
34 | .Em environment list . | |
35 | For compatibility with differing environment conventions, | |
36 | the given arguments | |
37 | .Ar name | |
38 | and | |
39 | .Ar value | |
40 | may be appended and prepended, | |
41 | respectively, | |
42 | with an equal sign | |
43 | .Dq Li \&= . | |
44 | .Pp | |
45 | The | |
46 | .Fn getenv | |
47 | function obtains the current value of the environment variable, | |
48 | .Ar name . | |
49 | If the variable | |
50 | .Ar name | |
653ba8b6 | 51 | is not in the current environment, |
ae59e04c CL |
52 | a null pointer is returned. |
53 | .Pp | |
54 | The | |
55 | .Fn setenv | |
56 | function inserts or resets the environment variable | |
57 | .Ar name | |
58 | in the current environment list. | |
59 | If the variable | |
60 | .Ar name | |
61 | does not exist in the list, | |
62 | it is inserted with the given | |
63 | .Ar value. | |
64 | If the variable does exist, the argument | |
65 | .Ar overwrite | |
66 | is tested; if | |
67 | .Ar overwrite is | |
68 | zero, the | |
69 | variable is not reset, otherwise it is reset | |
70 | to the given | |
71 | .Ar value . | |
72 | .Pp | |
73 | The | |
74 | .Fn putenv | |
cc3a3d9b KB |
75 | function takes an argument of the form ``name=value'' and is |
76 | equivalent to: | |
ae59e04c | 77 | .Bd -literal -offset indent |
adb19fe0 | 78 | setenv(name, value, 1); |
ae59e04c CL |
79 | .Ed |
80 | .Pp | |
81 | The | |
82 | .Fn unsetenv | |
83 | function | |
84 | deletes all instances of the variable name pointed to by | |
85 | .Fa name | |
86 | from the list. | |
87 | .Sh RETURN VALUES | |
88 | The functions | |
89 | .Fn setenv | |
90 | and | |
91 | .Fn putenv | |
92 | return zero if successful; otherwise the global variable | |
93 | .Va errno | |
94 | is set to indicate the error and a | |
95 | \-1 is returned. | |
96 | .Sh ERRORS | |
97 | .Bl -tag -width [ENOMEM] | |
98 | .It Bq Er ENOMEM | |
99 | The function | |
100 | .Fn setenv | |
adb19fe0 | 101 | or |
ae59e04c | 102 | .Fn putenv |
adb19fe0 | 103 | failed because they were unable to allocate memory for the environment. |
ae59e04c CL |
104 | .El |
105 | .Sh SEE ALSO | |
106 | .Xr csh 1 , | |
107 | .Xr sh 1 , | |
108 | .Xr execve 2 , | |
109 | .Xr environ 7 | |
110 | .Sh STANDARDS | |
111 | The | |
112 | .Fn getenv | |
113 | function conforms to | |
114 | .St -ansiC . | |
115 | .Sh HISTORY | |
116 | The functions | |
117 | .Fn setenv | |
118 | and | |
119 | .Fn unsetenv | |
120 | appeared in | |
121 | .At v7 . | |
122 | The | |
123 | .Fn putenv | |
124 | function appeared in | |
125 | .Bx 4.3 Reno . |