.\" $NetBSD: getenv.3,v 1.19 2005/09/26 10:56:54 wiz 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 September 25, 2005 .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 "const 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 given arguments .Ar name and .Ar value may be appended and prepended, respectively, with an equal sign .Dq Li \&= , except for .Fn unsetenv . .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 ``name=value'' and is equivalent to: .Bd -literal -offset indent setenv(name, value, 1); .Ed .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 unsetenv is a null pointer, points to an empty string, or points to a string containing an .Dq Li \&= character. .It Bq Er ENOMEM The function .Fn setenv or .Fn putenv failed because they were unable to allocate memory for the environment. .El 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 . The .Fn putenv function conforms to .St -xpg4 . The .Fn unsetenv function conforms 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 . 2010-04-13 09:51:07 +0000'>2010-04-13Include "ioconf.h" to declare struct cfdriver foo_cd.tsutsui 2009-08-23Use proper pointer types and names rather than casts for readability.tsutsui 2009-07-07KNF, ANSIfy, etc.tsutsui 2009-07-07Explicitly initialize the MFP Timer-B for delay(9) from atari_hwinit()tsutsui 2009-07-07Add a workaround for annoyingtsutsui 2009-03-18Ansify function definitions w/o arguments. Generated with sed.cegger 2009-03-14ANSIfy another 1261 function definitions.dsl 2009-03-14Change about 4500 of the K&R function definitions to ANSI ones.dsl 2009-03-14Remove all the __P() from sys (excluding sys/dist)dsl 2008-11-04Move tc_init(&clk_timecounter); to stop the "timecounter:" messageabs 2008-06-11Use device_private() and device_lookup_privat() to get softc.tsutsui 2008-01-08Convert Atari to generic TODR and timecounter.joerg 2008-01-03Simplify delay based on x86 version.joerg 2007-03-04Kill caddr_t; there will be some MI fallout, but it will be fixed shortly.christos 2005-12-24Remove leading __ from __(const|inline|signed|volatile) -- it is obsolete.perry 2005-12-11merge ktrace-lwp.christos 2005-06-04Adapt to compiling with -Wshadow and -Wcast-qual, by adding consthe 2003-08-07Move UCB-licensed code from 4-clause to 3-clause licence.agc 2003-07-15__KERNEL_RCSID()lukem 2003-01-17Merge the nathanw_sa branch.thorpej 2002-10-23merge kqueue branch into -currentjdolecek 2002-10-02Use CFATTACH_DECL().thorpej 2002-09-27Declare all cfattach structures const.thorpej 2002-09-06Merge the gehenna-devsw branch into the trunk.gehenna 2001-07-26Various typos in comments (neccessary, sceme, choise, ...).wiz 2001-06-18Symmetric has one s and two m's.wiz 2001-04-24Add sanity checking on register B of the mc146818.leo 2001-01-29Fix y2001 problem in the initial read of the RTC.leo 2000-06-07Mark 'n' explicitely as output of the 'mulul' instruction.leo 2000-05-31Fix some bugs in clkread(). These bugs caused strange time leaps.leo