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