\"      $NetBSD: getenv.3,v 1.26 2025/05/25 05:44:10 rillig Exp $
\"
\" Copyright (c) 1988, 1991, 1993
\"      The Regents of the University of California.  All rights reserved.
\"
\" This code is derived from software contributed to Berkeley by
\" the American National Standards Committee X3, on Information
\" Processing Systems.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\"    notice, this list of conditions and the following disclaimer in the
\"    documentation and/or other materials provided with the distribution.
\" 3. Neither the name of the University nor the names of its contributors
\"    may be used to endorse or promote products derived from this software
\"    without specific prior written permission.
\"
\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
\" SUCH DAMAGE.
\"
\"     from: @(#)getenv.3       8.2 (Berkeley) 12/11/93
\"
Dd May 25, 2025
Dt GETENV 3
Os
Sh NAME
Nm getenv ,
Nm getenv_r ,
Nm putenv ,
Nm setenv ,
Nm unsetenv
Nd environment variable functions
Sh LIBRARY
Lb libc
Sh SYNOPSIS
In stdlib.h
Ft char *
Fn getenv "const char *name"
Ft int
Fn getenv_r "const char *name" "char *buf" "size_t len"
Ft int
Fn setenv "const char *name" "const char *value" "int overwrite"
Ft int
Fn putenv "char *string"
Ft int
Fn unsetenv "const char *name"
Sh DESCRIPTION
These functions set, unset and fetch environment variables from the
host
Em environment list .
For compatibility with differing environment conventions,
the
Fn getenv
or
Fn getenv_r
given argument
Ar name
may be appended with an equal sign
Dq Li \&= .
Pp
The
Fn getenv
function obtains the current value of the environment variable
Ar name .
If the variable
Ar name
is not in the current environment, a
Dv NULL
pointer is returned.
Pp
The
Fn getenv_r
function obtains the current value of the environment variable
Fa name
and copies it to
Fa buf .
If
Fa name
is not in the current environment, or the string length of the value of
Fa name
is longer than
Fa len
characters, then \-1 is returned and
Va errno
is set to indicate the error.
Pp
The
Fn setenv
function inserts or resets the environment variable
Ar name
in the current environment list.
If the variable
Ar name
does not exist in the list,
it is inserted with the given
Ar value .
If the variable does exist, the argument
Ar overwrite
is tested; if
Ar overwrite is
zero, the
variable is not reset, otherwise it is reset
to the given
Ar value .
Pp
The
Fn putenv
function takes an argument of the form
Dq name=value
and it will set the environment variable
Dq name
equal to
Dq value
by altering an existing entry, or creating a new one if an existing
one does not exist.
The actual string argument passed to
Fn putenv
will become part of the environment.
If one changes the string, the environment will also change.
Pp
The
Fn unsetenv
function
deletes all instances of the variable name pointed to by
Fa name
from the list.
Sh RETURN VALUES
The functions
Fn getenv_r ,
Fn setenv ,
Fn putenv ,
and
Fn unsetenv
return zero if successful; otherwise the global variable
Va errno
is set to indicate the error and a
\-1 is returned.
Pp
If
Fn getenv
is successful, the string returned should be considered read-only.
Sh ERRORS
Bl -tag -width Er
It Bq Er EINVAL
The
Fa name
argument to
Fn setenv
or
Fn unsetenv
is a null pointer, points to an empty string, or points to a string
containing an
Dq Li \&=
character.
The
Fa value
argument to
Fn setenv
is a null pointer.
The
Fa string
argument to
Fn putenv
is a null pointer, or points to a string that either starts with a
Dq Li \&=
character or does not contain one at all.
It Bq Er ENOMEM
The function
Fn setenv
or
Fn putenv
failed because they were unable to allocate memory for the environment.
El
Pp
The function
Fn getenv_r
can return the following errors:
Bl -tag -width Er
It Bq Er ENOENT
The variable
Fa name
was not found in the environment.
It Bq Er ERANGE
The value of the named variable is too long to fit in the supplied buffer.
El
Sh SEE ALSO
Xr csh 1 ,
Xr sh 1 ,
Xr execve 2 ,
Xr environ 7
Sh STANDARDS
The
Fn getenv
function conforms to
St -ansiC .
Pp
The
Fn putenv
function conforms to
St -xpg4 .
Pp
The
Fn setenv
and
Fn unsetenv
functions conform to
St -p1003.1-2001 .
Sh HISTORY
The functions
Fn setenv
and
Fn unsetenv
appeared in
At v7 .
The
Fn putenv
function appeared in
Bx 4.3 Reno .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.