sunet/doc/latex/netrc.tex

143 lines
5.6 KiB
TeX

\section{Reading netrc-files}\label{sec:netrc}
%
\begin{description}
\item[Used files:] netrc.scm
\item[Name of the package:] netrc
\end{description}
%
\subsection{Overview}
This module provides procedures to parse authentication information
contained in \ex{~/.netrc}.
On Unix systems the \ex{~/.netrc} file (in the user's home directory)
may contain information allowing automatic login to remote hosts. The
format of the file is defined in the \ex{ftp}(1) manual page. Example
lines are
\begin{code}
machine ondine.cict.fr login marsden password secret
default login anonymous password user@site%
\end{code}
The \ex{~/.netrc} file should be protected by appropriate permissions, and
(like \ex{/usr/bin/ftp}) this library will refuse to read the file if it is
badly protected. (unlike \ex{ftp} this library will always refuse
to read the file -- \ex{ftp} refuses it only if the password is
given for a non-default account). Appropriate permissions are set if
only the user has permissions on the file.
Note following restrictions and differences:
\begin{itemize}
\item The macdef statement (defining macros) is not supported.
\item The settings for one machine must be on a single line.
\item The is no error proof while reading the file.
\item Default need not be the last line of the netrc-file.
\end{itemize}
\subsection{Entry points}
What you probably want, is to read out the default netrc-file. Do the
following:
\begin{code}
(let ((netrc-record (netrc:parse)))
(netrc:lookup netrc-record "name of the machine"))
\end{code}
and you will receive three values: \semvar{login-name},
\semvar{password} and \semvar{account-name}. If you only want the
login name or the password, use \ex{netrc:\ob{}lookup\=login} or
\ex{netrc:\ob{}lookup\=password}, resp.
You will get either the login / password for the specified machine, or
a default login / password if the machine is unknown.
\begin{defundesc}{user-mail-address}{}{string}
Calculate the user's email address, as per the Emacs function of the
same name. Will take into account the environment variable
\ex{REPLYTO}, if set. Otherwise the mail-address will look like
\ex{user@\ob{}hostname}.
\end{defundesc}
\defun{netrc:parse} {\ovar{filename \ovar{fallback-password
\ovar{fallback-login}}}} {netrc-record}
\begin{defundescx}{netrc:try-parse} {filename fallback-password
fallback-login} {netrc-record}
\ex{netrc:parse} parses the netrc file and returns a \ex{netrc}
record, containing all necessary information for the following
procedures.
\semvar{filename} defaults to ``~/.netrc'',
\semvar{fallback-password} defaults to the result of the call to
\ex{user\=mail\=address} and \semvar{fallback-login} defaults to
``anonymous''. If the netrc file does not provide a default password
or a default login (stated by the ``default'' statement),
\semvar{fallback-password} and \semvar{fallback-login} will be used
as default password or login, respectively (thus,
\ex{user\=mail\=address} is only called if the netrc file does not
contain a default specification). If the netrc file does not exist,
a netrc-record filled with default values is returned. If the netrc
file does not have the correct permissions, a message is printed to
the current error port and a netrc-record filled with default values
is returned.
\ex{netrc:try-parse} does the same as \ex{netrc:\ob{}parse}, except
of the following: if there is no file called \semvar{filename}, the
according error will be raised and if the specified file does not
have the correct permissions set, a \ex{netrc\=refuse\=warning} will
be signalled. So, if you don't like the error handling and behavior
of \ex{netrc:\ob{}parse}, use \ex{netrc:\ob{}try\=parse} and catch
the signalled conditions. Note, that \ex{netrc:\ob{}parse} resolves
\semvar{filename} for you, \ex{netrc:\ob{}try-parse} does not -- you
have to do it on your own.
\end{defundescx}
\defun{netrc:lookup}{netrc-record machine \ovar{default?}} {string
string string}
\defunx{netrc:lookup-password}{netrc-record machine
\ovar{default?}}{string}
\defunx{netrc:lookup-login}{netrc-record machine
\ovar{default?}}{string}
\begin{desc}
Return the login, password and / or account information for
\semvar{machine} specified by \semvar{netrc-record}, respectively.
If \semvar{default?} is \sharpt, default values are returned if no
such \semvar{machine} is specified in the \semvar{netrc-record}.
Otherwise [\sharpf\ \sharpf\ \sharpf] or \sharpf\ is returned,
respectively.
\end{desc}
\defun{netrc:default-login}{netrc-record}{string}
\begin{defundescx}{netrc:default-password}{netrc-record}{string}
Return the default values for the login or the password, respectively,
specified by \semvar{netrc-record}. If the netrc file did not
specify a default login, ``anonymous'' is returned by
\ex{netrc:\ob{}default\=login}. If the netrc file did not specify a
default password, the result of the call to \ex{user\=mail\=address}
is returned by \ex{netrc:\ob{}default\=password}.
\end{defundescx}
\subsection{Related work}
\begin{itemize}
\item Graham Barr has written a similar library for Perl, called
\ex{Netrc.pm}.
\item \ex{ange-ftp.el} (transparent remote file access for Emacs)
parses the user's netrc file.
\end{itemize}
\subsection{Desirable things}
\begin{itemize}
\item Remove restrictions (as stated in `\emph{Overview}') and behave like
\ex{/usr/\ob{}bin/\ob{}ftp} behaves
\item perhaps: adding case-insensitivity (for host names)
\item perhaps: better record-disclosers for netrc-entry- and
netrc-records
\end{itemize}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End: