Date: Tue, 8 Oct 2002 06:07:41 -0600 (MDT) From: Lyndon Nerenberg <lyndon@orthanc.ab.ca> To: FreeBSD-gnats-submit@FreeBSD.org Subject: bin/43823: [PATCH] update to environ(7) manpage Message-ID: <200210081207.g98C7fsg094752@orthanc.ab.ca>
next in thread | raw e-mail | index | archive | help
>Number: 43823 >Category: bin >Synopsis: [PATCH] update to environ(7) manpage >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-bugs >State: open >Quarter: >Keywords: >Date-Required: >Class: update >Submitter-Id: current-users >Arrival-Date: Tue Oct 08 05:10:01 PDT 2002 >Closed-Date: >Last-Modified: >Originator: Lyndon Nerenberg >Release: FreeBSD 4.7-RC i386 >Organization: The Frobozz Magic Homing Pigeon Company >Environment: System: FreeBSD orthanc.ab.ca 4.7-RC FreeBSD 4.7-RC #4: Wed Oct 2 12:47:18 MDT 2002 root@orthanc.ab.ca:/u/freebsd/cvssrc/RELENG_4/sys/compile/FROBOZZ i386 >Description: The environ(7) manpage is a bit stale. The enclosed patch addresses the following issues: 1) Rationalize the use of the mdoc macros, particulary w.r.t. misuses of .Dq and .Ar. 2) Some cleanup and expansion of the prose to (I hope) make it a bit easier to read. 3) Move the descriptions of the environment variables into the ENVIRONMENT section of the manpage. 4) Clean up the references in SEE ALSO to only include those manpages that directly address relevant environment issues. 5) Remove the entry for PWD, as it's very shell specific and cannot be relied upon in general. 6) Remove the entry for LANG. It's superseded by the LC_* variables, and isn't referenced by any of the system manpages under 4.7-RC. A grep through /usr/src for references to LANG shows that anything that does use it defers to LC_*. 7) Quite a few commonly referenced variables were added: CC, COLUMNS, DISPLAY, FTP_PROXY, HOSTALIASES, HTTP_PROXY, LC_*, LD, LD_LIBRARY_PATH, LINES, LOCALDOMAIN, LOGNAME, MANPATH, NNTPSERVER, ORGANIZATION, POSIXLY_CORRECT, and VISUAL That list is a bit arbitrary, but I tried to pick those that are common to several commands, or are just plain useful to know about. I avoided anything specific to just one command (but left EXINIT in anyway). 8) Remove the "warning" text at the end. It didn't really say anything useful, and made reference to a number of variables that were not described in the manpage to begin with. >How-To-Repeat: N/A >Fix: Index: environ.7 =================================================================== RCS file: /home/ncvs/src/share/man/man7/environ.7,v retrieving revision 1.13.2.4 diff -u -r1.13.2.4 environ.7 --- environ.7 2001/08/17 13:08:49 1.13.2.4 +++ environ.7 2002/10/08 11:35:24 @@ -1,5 +1,6 @@ .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. +.\" Copyright 2002 by Lyndon Nerenberg. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -32,95 +33,200 @@ .\" @(#)environ.7 8.3 (Berkeley) 4/19/94 .\" $FreeBSD: src/share/man/man7/environ.7,v 1.13.2.4 2001/08/17 13:08:49 ru Exp $ .\" -.Dd April 19, 1994 +.Dd October 8, 2002 .Dt ENVIRON 7 .Os .Sh NAME .Nm environ -.Nd user environment +.Nd process environment .Sh SYNOPSIS -.Ar extern char **environ ; +.Vt extern char **environ ; .Sh DESCRIPTION -An array of strings called the -.Ar environment -is made available by -.Xr execve 2 -when a process begins. By convention these strings have the form -.Dq Ar name=value . -The following names are used by various commands: -.Bl -tag -width BLOCKSIZE +An array of strings, called the +.Ar environment , +is made available to each process by +.Xr execve 2 . +By convention these strings have the form +.Va name Ns No = Ns Ar value , +and are referred to as +.Dq environment variables. +A process can query, update, and delete these strings using the +.Xr getenv 3 , +.Xr setenv 3 , +and +.Xr unsetenv 3 +functions, respectively. The shells also provide commands to +manipulate the environment; they are described in the +respective shell manual pages. +.Pp +What follows is a list of environment variables typically +seen on a +.Ux +system. It includes only those variables that a user +can expect to see during their +day-to-day use of the system, and is far +from complete. Environment variables specific to a particular +program or library function are documented in the +.Sx ENVIRONMENT +section of the appropriate manual page. +.Sh ENVIRONMENT +.Bl -tag -width LD_LIBRARY_PATH .It Ev BLOCKSIZE -The size of the block units used by several commands, most notably +The size of the block units used by several disk-related commands, +most notably .Xr df 1 , .Xr du 1 and .Xr ls 1 . .Ev BLOCKSIZE may be specified in units of a byte by specifying a number, -in units of a kilobyte by specifying a number followed by ``K'' or -``k'', in units of a megabyte by specifying a number followed by ``M'' -or ``m'' and in units of a gigabyte by specifying a number followed -by ``G'' or ``g''. +in units of a kilobyte by specifying a number followed by +.Ql K +or +.Ql k , +in units of a megabyte by specifying a number followed by +.Ql M +or +.Ql m , +and in units of a gigabyte by specifying a number followed +by +.Ql G +or +.Ql g . Sizes less than 512 bytes or greater than a gigabyte are ignored. +.It Ev CC +The command that invokes the C compiler. +.It Ev COLUMNS +Used to force a program to override the tty driver's notion of +the display width. +.It Ev DISPLAY +The default display used by X Window System clients. .It Ev EDITOR -Default editor name. +Default editor command name. .It Ev EXINIT A startup list of commands read by .Xr ex 1 and .Xr vi 1 . +.It Ev FTP_PROXY +The URL of a proxy that +.Xr fetch 3 +will use to satisfy FTP requests. .It Ev HOME -A user's login directory, set by +The current user's login directory, set by .Xr login 1 from the password file .Xr passwd 5 . -.It Ev LANG -This variable configures all programs which use -.Xr setlocale 3 -to use the specified locale. +.It Ev HOSTALIASES +The name of a file, containing hostname aliases, that is used to +map unqualified hostnames into fully-qualified hostnames (see +.Xr hostname 7 Ns ). +.It Ev HTTP_PROXY +The URL of a proxy that +.Xr fetch 3 +will use to satisfy HTTP requests. +.It Ev LC_ALL +Defines the default domain for all locale-related functions in the C library. +(See +.Xr setlocale 3 +for information about how the +.Ql LC_* +environment variables affect the operation of various functions in the +C library. The +.Ev LC_ALL +enviroment variable overrides the settings of all other +.Ql LC_* +environment variables.) +.It Ev LC_COLLATE +Defines the default locale for string collation routines. +.It Ev LC_TYPE +Defines the default locale for the +.Xr ctype 3 , +.Xr mbrune 3 , +.Xr multibyte 3 , +and +.Xr rune 3 +functions. +.It Ev LC_MESSAGES +Defines the default locale for message catalogs. +.It Ev LC_MONETARY +Defines the default locale for formatting monetary values. +.It Ev LC_NUMERIC +Defines the default locale for formatting numbers. +.It Ev LC_TIME +Defines the default locale for formatting dates and times. +.It Ev LD +The command that invokes the linker. +.It Ev LD_LIBRARY_PATH +A colon separated list of directories, overriding the +default search path for shared libraries. +.It Ev LINES +Used to force a program to override the tty driver's notion of +the display length. +.It Ev LOCALDOMAIN +The default domain to append to unqualified hostnames during +.Xr resolver 5 +lookups. +.It Ev LOGNAME +The name of the currently logged in user. .It Ev MAIL The location of the user's mailbox instead of the default in /var/mail, used by .Xr mail 1 , .Xr sh 1 , -and many other mailclients. +and other mail clients. +.It Ev MANPATH +The sequence of directories, separated by colons, searched by +.Xr man 1 +when looking for manual pages. +.It Ev NNTPSERVER +The hostname of the default NNTP server, used by NNTP-aware +usenet clients. +.It Ev ORGANIZATION +Most NNTP (and some mail) clients will insert the contents of this +variable into an +.Ql Organization: +header in any originated messages. .It Ev PAGER Default paginator program. The program specified by this variable is used by .Xr mail 1 , .Xr man 1 , .Xr ftp 1 , -etc, to display information which is longer than the current display. +etc, to display information which is longer than the current display +length. .It Ev PATH The sequence of directories, separated by colons, searched by -.Xr csh 1 , -.Xr sh 1 , -.Xr system 3 , +.Xr execlp 3 , .Xr execvp 3 , -etc, when looking for an executable file. +.Xr system 3 , +and the shells, +when looking for an executable file. .Ev PATH -is set to ``/usr/bin:/bin'' initially by -.Xr login 1 . +is initialized to +.Ql /bin:/usr/bin +by +.Xr login 1 . +.It Ev POSIXLY_CORRECT +When set to any value, this environment variable modifies the behaviour +of certain commands to (mostly) execute in a strictly POSIX-compliant manner. .It Ev PRINTER The name of the default printer to be used by .Xr lpr 1 , .Xr lpq 1 , and .Xr lprm 1 . -.It Ev PWD -The current directory pathname. .It Ev SHELL -The full pathname of the user's login shell. +The pathname of the user's login shell. .It Ev TERM -The kind of terminal for which output is to be prepared. +The type of terminal for which output is to be prepared. This information is used by commands, such as -.Xr nroff 1 +.Xr vi 1 or -.Xr plot 1 -which may exploit special terminal capabilities. See -.Pa /usr/share/misc/termcap -.Pq Xr termcap 5 -for a list of terminal types. +.Xr plot 1 , +to may exploit special terminal capabilities. +.Xr termcap 5 +describes the database of terminal types. .It Ev TERMCAP The string describing the terminal in .Ev TERM , @@ -138,67 +244,43 @@ is equivalent to a .Ev TERMPATH of -.Dq Pa $HOME/.termcap:/etc/termcap . +.Pa $HOME/.termcap:/etc/termcap . .Ev TERMPATH is ignored if .Ev TERMCAP contains a full pathname. .It Ev TMPDIR -The directory in which to store temporary files. +The directory in which to create temporary files. Most applications use either -.Dq /tmp +.Pa /tmp or -.Dq /var/tmp . -Setting this variable will make them use another directory. +.Pa /var/tmp . +Setting this variable will (usually) make them use the specified directory. .It Ev TZ The timezone to use when displaying dates. The normal format is a pathname relative to -.Dq Pa /usr/share/zoneinfo . +.Pa /usr/share/zoneinfo . For example, the command -.Dq env TZ=America/Los_Angeles date +.Ql env TZ=America/Los_Angeles date displays the current time in California. See .Xr tzset 3 for more information. .It Ev USER -The login name of the user. +See +.Ev LOGNAME . +.It Ev VISUAL +An editor command sometimes used in preference to +.Ev EDITOR +when the terminal supports direct cursor addressing. .El -.Pp -Further names may be placed in the environment by the -.Xr export -command and -.Ar name=value -arguments in -.Xr sh 1 , -or by the -.Xr setenv -command if you use -.Xr csh 1 . -It is unwise to change certain -.Xr sh 1 -variables that are frequently exported by -.Pa .profile -files, such as -.Ev MAIL , -.Ev PS1 , -.Ev PS2 , -and -.Ev IFS , -unless you know what you are doing. .Sh SEE ALSO -.Xr cd 1 , -.Xr csh 1 , -.Xr ex 1 , +.Xr env 1 , .Xr login 1 , -.Xr sh 1 , -.Xr execve 2 , -.Xr execle 3 , +.Xr execvp 2 , +.Xr execlp 3 , .Xr getenv 3 , -.Xr setenv 3 , .Xr setlocale 3 , -.Xr system 3 , -.Xr termcap 3 , -.Xr termcap 5 .Sh HISTORY The .Nm >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-bugs" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200210081207.g98C7fsg094752>