usr.bin/printenv/printenv.1

   1 .\" Copyright (c) 1980, 1990, 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 Institute of Electrical and Electronics Engineers, Inc.
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)printenv.1  8.1 (Berkeley) 6/6/93
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd June 6, 1993
  38 .Dt PRINTENV 1
  39 .Os
  40 .Sh NAME
  41 .Nm printenv , env
  42 .Nd print out the environment, set and print environment
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Op Ar name
  46 .Nm env
  47 .Op Fl i
  48 .Op Ar name Ns = Ns Ar value ...
  49 .Op Ar utility Op Ar argument ...
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility prints out the names and values of the variables in the environment,
  54 with one name/value pair per line.
  55 If
  56 .Ar name
  57 is specified, only
  58 its value is printed.
  59 .Pp
  60 Some shells may provide a builtin
  61 .Nm
  62 command which is similar or identical to this utility.
  63 Consult the
  64 .Xr builtin 1
  65 manual page.
  66 .Pp
  67 The
  68 .Nm env
  69 utility executes
  70 .Ar utility
  71 after modifying the environment as
  72 specified on the command line.
  73 The option
  74 .Ar name Ns = Ns Ar value
  75 specifies
  76 an environment variable,
  77 .Ar name  ,
  78 with a value of
  79 .Ar value  .
  80 .Pp
  81 The options are as follows:
  82 .Bl -tag -width indent
  83 .It Fl i
  84 Execute the
  85 .Ar utility
  86 with only those environment values specified.
  87 The environment inherited
  88 by
  89 .Nm env
  90 is ignored completely.
  91 .El
  92 .Pp
  93 If no utility is specified,
  94 .Nm env
  95 prints out the names and values
  96 of the variables in the environment, with one name/value pair per line.
  97 .Pp
  98 The
  99 .Nm env
 100 utility is sometimes useful with the
 101 .Dq Li #!
 102 construct (see
 103 .Xr execve 2 ) .
 104 The only difference between
 105 .Dq Li #!/usr/local/bin/foo
 106 and
 107 .Dq Li "#!/usr/bin/env\ /usr/local/bin/foo"
 108 is that the latter works even if
 109 .Pa /usr/local/bin/foo
 110 is itself interpreted.
 111 Using
 112 .Nm env
 113 this way also allows one to reference
 114 .Pa foo
 115 without the path,
 116 as well as set up the environment as desired.
 117 .Sh ENVIRONMENT
 118 The
 119 .Nm env
 120 utility uses the
 121 .Ev PATH
 122 environment variable is used to locate the requested
 123 .Ar utility
 124 if the name contains no
 125 .Ql /
 126 characters.
 127 .Sh DIAGNOSTICS
 128 .Ex -std printenv
 129 .Pp
 130 .Ex -std env
 131 An exit status of 126 indicates
 132 .Ar utility
 133 was found, but could not be executed.
 134 An exit status of 127 indicates
 135 .Ar utility
 136 could not be found.
 137 .Sh COMPATIBILITY
 138 The
 139 .Nm env
 140 utility accepts the
 141 .Fl
 142 option as a synonym for
 143 .Fl i .
 144 .Sh SEE ALSO
 145 .Xr csh 1 ,
 146 .Xr sh 1 ,
 147 .Xr execvp 3 ,
 148 .Xr environ 7
 149 .Sh STANDARDS
 150 The
 151 .Nm env
 152 utility conforms to
 153 .St -p1003.1-2001 .
 154 .Sh HISTORY
 155 The
 156 .Nm
 157 command appeared in
 158 .Bx 3.0 .
 159 .Sh BUGS
 160 The
 161 .Nm env
 162 utility doesn't handle utility arguments with equal (``='') signs in their
 163 names, for obvious reasons.