192 lines
10 KiB
HTML
192 lines
10 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html><head>
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8"><!-- DO NOT EDIT THIS FILE-->
|
|
<!-- Edit the .tex version instead-->
|
|
|
|
|
|
<title>SRFI 98: An interface to access environment variables.</title>
|
|
</head><body>
|
|
|
|
<h1>Title</h1>
|
|
|
|
An interface to access environment variables.
|
|
|
|
<h1>Author</h1>
|
|
|
|
Taro Minowa(Higepon)
|
|
|
|
<h1>Status</h1>
|
|
|
|
This SRFI is currently in ``final'' status. To see an explanation of
|
|
each status that a SRFI can hold, see <a href="http://srfi.schemers.org/srfi-process.html">here</a>.
|
|
|
|
To provide input on this SRFI, please send email to
|
|
<a href="mailto:srfi%20minus%2098%20at%20srfi%20dot%20schemers%20dot%20org">
|
|
<code><srfi minus 98 at srfi dot schemers dot org></code></a>. See
|
|
<a href="http://srfi.schemers.org/srfi-list-subscribe.html">instructions here</a> to subscribe to
|
|
the list. You can access the discusssion via
|
|
<a href="http://srfi.schemers.org/srfi-98/mail-archive/maillist.html">the archive of the mailing list</a>.
|
|
You can access
|
|
post-finalization messages via
|
|
<a href="http://srfi.schemers.org/srfi-98/post-mail-archive/maillist.html">
|
|
the archive of the mailing list</a>.
|
|
<p></p><ul>
|
|
|
|
<li>Received: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.2">2008/07/06</a></li>
|
|
<li>Draft: 2008/07/06 - 2008/09/06</li>
|
|
<li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.3">2008/07/18</a></li>
|
|
<li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.4">2008/07/18</a></li>
|
|
<li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.5">2008/08/14</a></li>
|
|
<li>Final: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.7">2008/09/19</a></li>
|
|
<li>R6RS library name: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-98/srfi-98.html?rev=1.8">2009/02/16</a></li>
|
|
</ul>
|
|
|
|
<h1>Abstract</h1>
|
|
This SRFI specifies the procedure get-environment-variable, which gets
|
|
the value of the specified environment variable, and the procedure
|
|
get-environment-variables, which gets an association list of all
|
|
environment variables.
|
|
|
|
<h1>Rationale</h1>
|
|
<p>Most operating systems provide a mechanism for passing auxiliary
|
|
parameters implicitly to child processes. Usually, this mechanism is
|
|
called "the environment", and is conceptually a map from string names
|
|
to string values. The string names are called environment
|
|
variables.</p>
|
|
|
|
<p>Some applications rely on environment variables to modify their
|
|
behavior according to local settings. Also, various established
|
|
protocols rely on environment variables as a form of interprocess
|
|
communication. For example, most implementations of the common
|
|
gateway interface (CGI) use environment variables to pass
|
|
Meta-Variables from the server to the script <a href="#0.1_cgi">[1]</a>.
|
|
Environment variables are also required
|
|
by <a href="http://srfi.schemers.org/srfi-96/srfi-96.html" title="SRFI
|
|
96: SLIB Prerequisites">SRFI 96: SLIB Prerequisites</a>.
|
|
Providing a means to access environment variables is therefore
|
|
indispensable for writing practical programs in Scheme.
|
|
</p>
|
|
<p>Most widely-used Scheme implementations provide a function for
|
|
getting the value of a specified environment variable. The name for
|
|
this function is usually getenv, but varies (<a href="#0.1_appendix">see
|
|
below</a>). Some implementations also provide a way to get all the
|
|
environment variables, but others do not.</p>
|
|
<p>This SRFI specifies a uniform interface for accessing environment
|
|
variables. That should make it easier to write portable programs
|
|
that need access to their environment.
|
|
For example, a CGI program may portably obtain the values of the
|
|
Meta-Variables "QUERY_STRING", "CONTENT_LENGTH" and
|
|
"REQUEST_METHOD" as in the following examples:</p>
|
|
<pre>(get-environment-variable "QUERY_STRING") => "foo=bar&huga=hige"
|
|
(get-environment-variable "CONTENT_LENGTH") => "512"
|
|
(get-environment-variable "REQUEST_METHOD") => "post"
|
|
</pre>
|
|
|
|
<p><a name="0.1_cgi">[1]</a> The Common Gateway Interface (CGI) Version 1.1, RFC3875, <a href="http://www.ietf.org/rfc/rfc3875" target="_blank">http://www.ietf.org/rfc/rfc3875</a>.</p>
|
|
<h1>Specification</h1>
|
|
<pre>R6RS library name</pre>
|
|
The following two procedures belong to the R6RS library named (srfi :98 os-environment-variables).
|
|
<pre>Function: <a name="get-environment-variable">get-environment-variable</a> name</pre>Returns the value of
|
|
the named environment variable as a string, or #f if the named
|
|
environment variable is not found. The name argument is expected to be
|
|
a string.
|
|
get-environment-variable may use
|
|
locale-setting information to encode the name and decode the value of
|
|
the environment variable.
|
|
If get-environment-variable can't decode the value, get-environment-variable may raise an exception.
|
|
<pre>(get-environment-variable "PATH") => "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
|
|
</pre>
|
|
<pre>Function: <a name="get-environment-variables">get-environment-variables</a></pre>
|
|
Returns names and values of all the environment variables as an a-list.
|
|
The same decoding considerations as for get-environment-variable apply.
|
|
<pre>(get-environment-variables) => (("PATH" . "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin") ("USERNAME" . "taro"))
|
|
</pre>
|
|
|
|
<h1>Implementation</h1>
|
|
<h2>Gauche</h2>
|
|
<pre>(define get-environment-variable sys-getenv)
|
|
(define get-environment-variables sys-environ->alist)
|
|
</pre>
|
|
<h2>Scheme48</h2>
|
|
<pre>(define (get-environment-variable name)
|
|
(cond
|
|
((lookup-environment-variable name) => os-string->string)
|
|
(else #f)))
|
|
(define (get-environment-variables)
|
|
(map (lambda (p)
|
|
(cons (os-string->string (car p)) (os-string->string (cdr p))))
|
|
(environment-alist)))
|
|
</pre>
|
|
<h2>scsh</h2>
|
|
<pre>(define get-environment-variable getenv)
|
|
(define get-environment-variables env->alist)
|
|
</pre>
|
|
|
|
<h2>SCM</h2>
|
|
<pre>(define get-environment-variable getenv)
|
|
(define get-environment-variables getenv)
|
|
</pre>
|
|
|
|
<h1>Issues</h1>
|
|
<p>get-environment-variable is expected to return a "Scheme string".
|
|
Unfortunately, many current platforms, including POSIX-like ones, do
|
|
not require environment variables to be interpretable as sequences of
|
|
characters. In particular, environment variables can be used to name
|
|
files, and filenames on the system can amount to NULL-terminated byte
|
|
vectors, which, if the Scheme program were to collect uninterpreted
|
|
and pass to, say, the open call, would work just fine, but which might
|
|
not represent a string in the particular encoding the program expects.
|
|
While in principle it may be desirable to provide a mechanism for
|
|
accessing environment variables raw, this SRFI specifies a "string"
|
|
return type because that best represents the consensus of existing
|
|
implementations, and captures the semantically desirable behavior in
|
|
the common case that the byte sequence is interpretable as a string.</p>
|
|
|
|
<a name="0.1_appendix"></a>
|
|
<h1>Appendix: Existing implementations</h1>
|
|
<table border="1">
|
|
<tbody><tr><th>Scheme implementation</th><th>get environment variable</th><th>get all the environment variables as an a-list</th></tr>
|
|
<tr><td>Bigloo</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>CHICKEN</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>Gambit</td><td>(getenv name . <default>) =>(or string? <default> <Unbound OS environment variable error>) name:string?</td><td> </td></tr>
|
|
|
|
<tr><td>Gauche</td><td>(sys-getenv name) => (or string? false) name:string?</td><td>(sys-environ)</td></tr>
|
|
<tr><td>Guile</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>PLT</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>MIT/GNU Scheme</td><td>(get-environment-variable name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>Scheme48</td><td>(lookup-environment-variable name) => (or string? false) name:string?</td><td>(environment-alist)</td></tr>
|
|
|
|
<tr><td>SLIB</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>STk</td><td>(getenv name) => (or string? false) name:string?</td><td> </td></tr>
|
|
<tr><td>STklos</td><td>(getenv name) => (or string? false) name:string?</td><td>(getenv)</td></tr>
|
|
<tr><td>SCM</td><td>(getenv name) => (or string? false) name:string?</td><td>(getenv)</td></tr>
|
|
</tbody></table>
|
|
<h1>Acknowledgements</h1>
|
|
Thanks to Shiro Kawai, Alexey Radul, jmuk, Kokosabu, leque and all the members of the #Lisp_Scheme IRC channel on Freenode.
|
|
<h1>Copyright</h1>
|
|
Copyright (C) Taro Minowa(Higepon) (2008). All Rights Reserved.
|
|
<p>
|
|
Permission is hereby granted, free of charge, to any person obtaining a
|
|
copy of this software and associated documentation files (the
|
|
"Software"), to deal in the Software without restriction, including
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
|
permit persons to whom the Software is furnished to do so, subject to
|
|
the following conditions:
|
|
</p>
|
|
<p>
|
|
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
</p>
|
|
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
</p>
|
|
<hr>
|
|
<address>Editor: <a href="mailto:srfi-editors%20at%20srfi%20dot%20schemers%20dot%20org">Mike Sperber</a></address>
|
|
<!-- Last modified: Sun Jan 28 14:21:14 MET 2007 -->
|
|
</body></html>
|