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 169177 2007-05-01 16:02:44Z ache $
34.\"
35.Dd October 12, 2006
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 "const char *string"
54.Ft void
55.Fn unsetenv "const char *name"
56.Sh DESCRIPTION
57These functions set, unset and fetch environment variables from the
58host
59.Em environment list .
60For compatibility with differing environment conventions,
61the given arguments
62.Fa name
63and
64.Fa value
65may be appended and prepended,
66respectively,
67with an equal sign
68.Dq Li \&= .
69.Pp
70The
71.Fn getenv
72function obtains the current value of the environment variable,
73.Fa name .
74The application should not modify the string pointed
75to by the
76.Fn getenv
--- 15 unchanged lines hidden (view full) ---
92.Fa overwrite
93is zero, the
94variable is not reset, otherwise it is reset
95to the given
96.Fa value .
97.Pp
98The
99.Fn putenv
100function takes an argument of the form ``name=value'' and is
101equivalent to:
102.Bd -literal -offset indent
103setenv(name, value, 1);
104.Ed
105.Pp
106The
107.Fn unsetenv
108function
109deletes all instances of the variable name pointed to by
110.Fa name
111from the list.
112.Sh RETURN VALUES
113The
114.Fn getenv
115function returns the value of the environment variable as a
116.Dv NUL Ns
117-terminated string.
118If the variable
119.Fa name
120is not in the current environment,
121.Dv NULL
122is returned.
123.Pp
124.Rv -std setenv putenv
125.Sh ERRORS
126.Bl -tag -width Er
127.It Bq Er ENOMEM
128The function
129.Fn setenv
130or
131.Fn putenv
132failed because they were unable to allocate memory for the environment.
133.El
134.Sh SEE ALSO
135.Xr csh 1 ,
136.Xr sh 1 ,
137.Xr execve 2 ,
138.Xr environ 7
139.Sh STANDARDS
140The
141.Fn getenv
142function conforms to
143.St -isoC .
144.Sh HISTORY
145The functions
146.Fn setenv
147and
148.Fn unsetenv
149appeared in
150.At v7 .
151The
--- 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 169177 2007-05-01 16:02:44Z ache $
34.\"
35.Dd October 12, 2006
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 "const char *string"
54.Ft void
55.Fn unsetenv "const char *name"
56.Sh DESCRIPTION
57These functions set, unset and fetch environment variables from the
58host
59.Em environment list .
60For compatibility with differing environment conventions,
61the given arguments
62.Fa name
63and
64.Fa value
65may be appended and prepended,
66respectively,
67with an equal sign
68.Dq Li \&= .
69.Pp
70The
71.Fn getenv
72function obtains the current value of the environment variable,
73.Fa name .
74The application should not modify the string pointed
75to by the
76.Fn getenv
--- 15 unchanged lines hidden (view full) ---
92.Fa overwrite
93is zero, the
94variable is not reset, otherwise it is reset
95to the given
96.Fa value .
97.Pp
98The
99.Fn putenv
100function takes an argument of the form ``name=value'' and is
101equivalent to:
102.Bd -literal -offset indent
103setenv(name, value, 1);
104.Ed
105.Pp
106The
107.Fn unsetenv
108function
109deletes all instances of the variable name pointed to by
110.Fa name
111from the list.
112.Sh RETURN VALUES
113The
114.Fn getenv
115function returns the value of the environment variable as a
116.Dv NUL Ns
117-terminated string.
118If the variable
119.Fa name
120is not in the current environment,
121.Dv NULL
122is returned.
123.Pp
124.Rv -std setenv putenv
125.Sh ERRORS
126.Bl -tag -width Er
127.It Bq Er ENOMEM
128The function
129.Fn setenv
130or
131.Fn putenv
132failed because they were unable to allocate memory for the environment.
133.El
134.Sh SEE ALSO
135.Xr csh 1 ,
136.Xr sh 1 ,
137.Xr execve 2 ,
138.Xr environ 7
139.Sh STANDARDS
140The
141.Fn getenv
142function conforms to
143.St -isoC .
144.Sh HISTORY
145The functions
146.Fn setenv
147and
148.Fn unsetenv
149appeared in
150.At v7 .
151The
--- 22 unchanged lines hidden ---