\chapter{Reading netrc-files}\label{cha:netrc}
%
\begin{description}
\item[Used files:] netrc.scm
\item[Name of the package:] netrc
\end{description}
%
\section{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{alltt}
machine ondine.cict.fr login marsden password secret
default login anonymous password user@site%
\end{alltt}

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}



\section{Entry points}

What you probably want, is to read out the default netrc-file. Do the
following:
\begin{alltt}
 (let ((netrc-record (netrc:parse)))
    (netrc:lookup netrc-record "name of the machine")) 
\end{alltt}
 
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}

\section{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}

\section{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: "man"
%%% End: