DataMuseum.dk

top - metrics - download

    Length: 5682 (0x1632)
    Types: TextFile
    Names: »services.tex«

└─⟦2d1937cfd⟧ Bits:30007241 EUUGD22: P.P 5.0
    └─⟦35176feda⟧ »EurOpenD22/isode/isode-6.tar.Z« 
        └─⟦de7628f85⟧ 
            └─⟦this⟧ »isode-6.0/doc/manual/services.tex« 

TextFile

% run this through LaTeX with the appropriate wrapper

\f

\chapter	{The ISODE Services Database}\label{isoservices}
The database \file{isoservices} in the ISODE \verb"ETCDIR" directory
(usually \file{/usr/etc/})
contains a simple mapping between
textual descriptions of services, service selectors, and local programs.

The database itself is an ordinary ASCII text file containing information
regarding the known services on the host.
Each line contains
\begin{itemize}
\item	the name of an entity and the provider on which the entity resides;

\item	the selector used to identify the entity to the provider,
	interpreted as a:
    \begin{describe}
    \item[number,]	if the selector starts with a hash-mark (`\verb"#"').
			More precisely, this denotes the so-called
			GOSIP method for denoting selectors, which
			uses a two octet, network byte-order representation.

    \item[ascii string,]
			if the selector appears in double-quotes (`\verb|"|').
			The usual escape mechanisms can be used to
			introduce non-printable characters.

    \item[octet string,]
			if all else fails.  The standard ``explosion''
			encoding is used, each octet in the string is
			represented by a two-digit hexadecimal quantity.
    \end{describe}
	and,

\item	the program and argument vector to \man execve(2) when the service is
	requested.
\end{itemize}
Blanks and/or tab characters are used to separate items.
All items after the first two are interpreted as an argument vector.
However, double-quotes may be used to prevent separation for items containing
embedded whitspace.
The sharp character (`\verb"#"') at the beginning of a line indicates a
commentary line.

\f

\section	{Accessing the Database}\label{isoservent}
The \man libicompat(3n) library contains the routines used to access the
database.
These routines ultimately manipulate an \verb"isoservent" structure,
which is the internal form.
\begin{quote}\index{isoservent}\small\begin{verbatim}
struct isoservent {
    char   *is_entity;
    char   *is_provider;

#define ISSIZE  64
    int     is_selectlen;
    char    is_selector[ISSIZE];

    char  **is_vec;
    char  **is_tail;
};
\end{verbatim}\end{quote}
The elements of this structure are:
\begin{describe}
\item[\verb"is\_entity":] the name of the entity;

\item[\verb"is\_provider":] the name of the provider on which the entity
resides;

\item[\verb"is\_selector"\verb"is\_selectlen":] the selector used to
identify the entity to the provider
(the element \verb"is_port" is an alias for this concept,
used to denote the entity to the provider by means of a two-octet number
specified in network-byte order);

\item[\verb"is\_vec":] the \man execve(2) vector;
and,

\item[\verb"is\_tail":] the next free slot in \verb"is_vec".
\end{describe}

The routine \verb"getisoservent" reads the next entry in the database,
opening the database if necessary.
\begin{quote}\index{getisoservent}\small\begin{verbatim}
struct isoservent *getisoservent ()
\end{verbatim}\end{quote}
It returns the manifest constant \verb"NULL" on error or end-of-file.

The routine \verb"setisoservent" opens and rewinds the database.
\begin{quote}\index{setisoservent}\small\begin{verbatim}
int     setisoservent (f)
int     f;
\end{verbatim}\end{quote}
The parameter to this procedure is:
\begin{describe}
\item[\verb"f":] the ``stayopen'' indicator,
if non-zero, then the database will remain open over subsequent calls to the
library.
\end{describe}
The routine \verb"endisoservent" closes the database.
\begin{quote}\index{endisoservent}\small\begin{verbatim}
int     endisoservent ()
\end{verbatim}\end{quote}
Both of these routines return non-zero on success and zero otherwise.

There are two routines used to fetch a particular entry in the database.
The routine \verb"getisoserventbyname" maps textual descriptions into the
internal form.
\begin{quote}\index{getisoserventbyname}\small\begin{verbatim}
struct isoservent *getisoserventbyname (entity, provider)
char   *entity,
       *provider;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"entity":] the entity providing the desired service;
and,

\item[\verb"provider":] the provider supporting the named \verb"entity".
\end{describe}
On a successful return,
the \verb"isoservent" structure describing that service is returned.
On failure, the manifest constant \verb"NULL" is returned instead.

The routine \verb"getisoserventbyselector" performs the inverse function.
\begin{quote}\index{getisoserventbyselector}\small\begin{verbatim}
struct isoservent *getisoserventbyselector (provider,
                        selector, selectlen)
char   *provider,
       *selector;
int     selectlen;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"provider":] the provider supporting the desired entity;
and,

\item[\verb"selector"/\verb"selectlen":] the selector on the provider
where the desired entity resides.
\end{describe}
On a successful return,
an \verb"isoservent" structure describing the entity residing on the provider
is returned.

The routine \verb"getisoserventbyport" performs a similar function.
\begin{quote}\index{getisoserventbyport}\small\begin{verbatim}
struct isoservent *getisoserventbyport (provider, port)
char   *provider;
unsigned short port;
\end{verbatim}\end{quote}
The parameters to this procedure are:
\begin{describe}
\item[\verb"provider":] the provider supporting the desired entity;
and,

\item[\verb"port":] the port on the provider (in network-byte order)
where the desired entity resides.
\end{describe}
On a successful return,
an \verb"isoservent" structure describing the entity residing on the provider
is returned.