1.\" Copyright (c) 1988, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
--- 16 unchanged lines hidden (view full) ---
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93
33.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 169146 2007-04-30 19:37:10Z ache $
34.\"
35.Dd April 30, 2007
36.Dt GETENV 3
37.Os
38.Sh NAME
39.Nm getenv ,
40.Nm putenv ,
41.Nm setenv ,
42.Nm unsetenv
43.Nd environment variable functions
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In stdlib.h
48.Ft char *
49.Fn getenv "const char *name"
50.Ft int
51.Fn setenv "const char *name" "const char *value" "int overwrite"
52.Ft int
53.Fn putenv "char *string"
54.Ft int
55.Fn unsetenv "const char *name"
56.Sh DESCRIPTION
57These functions set, unset and fetch environment variables from the
58host
59.Em environment list .
60.Pp
61The
62.Fn getenv
63function obtains the current value of the environment variable,
64.Fa name .
65The application should not modify the string pointed
66to by the
67.Fn getenv
--- 15 unchanged lines hidden (view full) ---
83.Fa overwrite
84is zero, the
85variable is not reset, otherwise it is reset
86to the given
87.Fa value .
88.Pp
89The
90.Fn putenv
91function takes an argument of the form ``name=value'' and
92puts it directly into the current environment,
93so altering the argument shall change the environment.
94If the variable
95.Fa name
96does not exist in the list,
97it is inserted with the given
98.Fa value .
99If the variable
100.Fa name
101does exist, it is reset to the given
102.Fa value .
103.Pp
104The
105.Fn unsetenv
106function
107deletes all instances of the variable name pointed to by
108.Fa name
109from the list.
110.Sh RETURN VALUES
111The
112.Fn getenv
113function returns the value of the environment variable as a
114.Dv NUL Ns
115-terminated string.
116If the variable
117.Fa name
118is not in the current environment,
119.Dv NULL
120is returned.
121.Pp
122.Rv -std setenv putenv unsetenv
123.Sh ERRORS
124.Bl -tag -width Er
125.It Bq Er EINVAL
126The function
127.Fn setenv
128or
129.Fn unsetenv
130failed because the
131.Fa name
132is a
133.Dv NULL
134pointer, points to an empty string, or points to a string containing an
135.Dq Li \&=
136character.
137.It Bq Er ENOMEM
138The function
139.Fn setenv
140or
141.Fn putenv
142failed because they were unable to allocate memory for the environment.
143.El
144.Sh SEE ALSO
145.Xr csh 1 ,
146.Xr sh 1 ,
147.Xr execve 2 ,
148.Xr environ 7
149.Sh STANDARDS
150The
151.Fn getenv
152function conforms to
153.St -isoC .
154The
155.Fn setenv ,
156.Fn putenv
157and
158.Fn unsetenv
159functions conforms to
160.St -p1003.1-2001 .
161.Sh HISTORY
162The functions
163.Fn setenv
164and
165.Fn unsetenv
166appeared in
167.At v7 .
168The
--- 22 unchanged lines hidden ---
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
--- 16 unchanged lines hidden (view full) ---
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getenv.3 8.2 (Berkeley) 12/11/93
33.\" $FreeBSD: head/lib/libc/stdlib/getenv.3 169146 2007-04-30 19:37:10Z ache $
34.\"
35.Dd April 30, 2007
36.Dt GETENV 3
37.Os
38.Sh NAME
39.Nm getenv ,
40.Nm putenv ,
41.Nm setenv ,
42.Nm unsetenv
43.Nd environment variable functions
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In stdlib.h
48.Ft char *
49.Fn getenv "const char *name"
50.Ft int
51.Fn setenv "const char *name" "const char *value" "int overwrite"
52.Ft int
53.Fn putenv "char *string"
54.Ft int
55.Fn unsetenv "const char *name"
56.Sh DESCRIPTION
57These functions set, unset and fetch environment variables from the
58host
59.Em environment list .
60.Pp
61The
62.Fn getenv
63function obtains the current value of the environment variable,
64.Fa name .
65The application should not modify the string pointed
66to by the
67.Fn getenv
--- 15 unchanged lines hidden (view full) ---
83.Fa overwrite
84is zero, the
85variable is not reset, otherwise it is reset
86to the given
87.Fa value .
88.Pp
89The
90.Fn putenv
91function takes an argument of the form ``name=value'' and
92puts it directly into the current environment,
93so altering the argument shall change the environment.
94If the variable
95.Fa name
96does not exist in the list,
97it is inserted with the given
98.Fa value .
99If the variable
100.Fa name
101does exist, it is reset to the given
102.Fa value .
103.Pp
104The
105.Fn unsetenv
106function
107deletes all instances of the variable name pointed to by
108.Fa name
109from the list.
110.Sh RETURN VALUES
111The
112.Fn getenv
113function returns the value of the environment variable as a
114.Dv NUL Ns
115-terminated string.
116If the variable
117.Fa name
118is not in the current environment,
119.Dv NULL
120is returned.
121.Pp
122.Rv -std setenv putenv unsetenv
123.Sh ERRORS
124.Bl -tag -width Er
125.It Bq Er EINVAL
126The function
127.Fn setenv
128or
129.Fn unsetenv
130failed because the
131.Fa name
132is a
133.Dv NULL
134pointer, points to an empty string, or points to a string containing an
135.Dq Li \&=
136character.
137.It Bq Er ENOMEM
138The function
139.Fn setenv
140or
141.Fn putenv
142failed because they were unable to allocate memory for the environment.
143.El
144.Sh SEE ALSO
145.Xr csh 1 ,
146.Xr sh 1 ,
147.Xr execve 2 ,
148.Xr environ 7
149.Sh STANDARDS
150The
151.Fn getenv
152function conforms to
153.St -isoC .
154The
155.Fn setenv ,
156.Fn putenv
157and
158.Fn unsetenv
159functions conforms to
160.St -p1003.1-2001 .
161.Sh HISTORY
162The functions
163.Fn setenv
164and
165.Fn unsetenv
166appeared in
167.At v7 .
168The
--- 22 unchanged lines hidden ---