Return to services.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/services.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {The ISODE Services Database}\label{isoservices}
        !             4: The database \file{isoservices} in the ISODE \verb"ETCDIR" directory
        !             5: (usually \file{/usr/etc/})
        !             6: contains a simple mapping between
        !             7: textual descriptions of services, service selectors, and local programs.
        !             8: 
        !             9: The database itself is an ordinary ASCII text file containing information
        !            10: regarding the known services on the host.
        !            11: Each line contains
        !            12: \begin{itemize}
        !            13: \item  the name of an entity and the provider on which the entity resides;
        !            14: 
        !            15: \item  the selector used to identify the entity to the provider,
        !            16:        interpreted as a:
        !            17:     \begin{describe}
        !            18:     \item[number,]     if the selector starts with a hash-mark (`\verb"#"').
        !            19:                        More precisely, this denotes the so-called
        !            20:                        GOSIP method for denoting selectors, which
        !            21:                        uses a two octet, network byte-order representation.
        !            22: 
        !            23:     \item[ascii string,]
        !            24:                        if the selector appears in double-quotes (`\verb|"|').
        !            25:                        The usual escape mechanisms can be used to
        !            26:                        introduce non-printable characters.
        !            27: 
        !            28:     \item[octet string,]
        !            29:                        if all else fails.  The standard ``explosion''
        !            30:                        encoding is used, each octet in the string is
        !            31:                        represented by a two-digit hexadecimal quantity.
        !            32:     \end{describe}
        !            33:        and,
        !            34: 
        !            35: \item  the program and argument vector to \man execve(2) when the service is
        !            36:        requested.
        !            37: \end{itemize}
        !            38: Blanks and/or tab characters are used to separate items.
        !            39: All items after the first two are interpreted as an argument vector.
        !            40: However, double-quotes may be used to prevent separation for items containing
        !            41: embedded whitspace.
        !            42: The sharp character (`\verb"#"') at the beginning of a line indicates a
        !            43: commentary line.
        !            44: 
        !            45: \section      {Accessing the Database}\label{isoservent}
        !            46: The \man libicompat(3n) library contains the routines used to access the
        !            47: database.
        !            48: These routines ultimately manipulate an \verb"isoservent" structure,
        !            49: which is the internal form.
        !            50: \begin{quote}\index{isoservent}\small\begin{verbatim}
        !            51: struct isoservent {
        !            52:     char   *is_entity;
        !            53:     char   *is_provider;
        !            54: 
        !            55: #define ISSIZE  64
        !            56:     int     is_selectlen;
        !            57:     char    is_selector[ISSIZE];
        !            58: 
        !            59:     char  **is_vec;
        !            60:     char  **is_tail;
        !            61: };
        !            62: \end{verbatim}\end{quote}
        !            63: The elements of this structure are:
        !            64: \begin{describe}
        !            65: \item[\verb"is\_entity":] the name of the entity;
        !            66: 
        !            67: \item[\verb"is\_provider":] the name of the provider on which the entity
        !            68: resides;
        !            69: 
        !            70: \item[\verb"is\_selector"\verb"is\_selectlen":] the selector used to
        !            71: identify the entity to the provider
        !            72: (the element \verb"is_port" is an alias for this concept,
        !            73: used to denote the entity to the provider by means of a two-octet number
        !            74: specified in network-byte order);
        !            75: 
        !            76: \item[\verb"is\_vec":] the \man execve(2) vector;
        !            77: and,
        !            78: 
        !            79: \item[\verb"is\_tail":] the next free slot in \verb"is_vec".
        !            80: \end{describe}
        !            81: 
        !            82: The routine \verb"getisoservent" reads the next entry in the database,
        !            83: opening the database if necessary.
        !            84: \begin{quote}\index{getisoservent}\small\begin{verbatim}
        !            85: struct isoservent *getisoservent ()
        !            86: \end{verbatim}\end{quote}
        !            87: It returns the manifest constant \verb"NULL" on error or end-of-file.
        !            88: 
        !            89: The routine \verb"setisoservent" opens and rewinds the database.
        !            90: \begin{quote}\index{setisoservent}\small\begin{verbatim}
        !            91: int     setisoservent (f)
        !            92: int     f;
        !            93: \end{verbatim}\end{quote}
        !            94: The parameter to this procedure is:
        !            95: \begin{describe}
        !            96: \item[\verb"f":] the ``stayopen'' indicator,
        !            97: if non-zero, then the database will remain open over subsequent calls to the
        !            98: library.
        !            99: \end{describe}
        !           100: The routine \verb"endisoservent" closes the database.
        !           101: \begin{quote}\index{endisoservent}\small\begin{verbatim}
        !           102: int     endisoservent ()
        !           103: \end{verbatim}\end{quote}
        !           104: Both of these routines return non-zero on success and zero otherwise.
        !           105: 
        !           106: There are two routines used to fetch a particular entry in the database.
        !           107: The routine \verb"getisoserventbyname" maps textual descriptions into the
        !           108: internal form.
        !           109: \begin{quote}\index{getisoserventbyname}\small\begin{verbatim}
        !           110: struct isoservent *getisoserventbyname (entity, provider)
        !           111: char   *entity,
        !           112:        *provider;
        !           113: \end{verbatim}\end{quote}
        !           114: The parameters to this procedure are:
        !           115: \begin{describe}
        !           116: \item[\verb"entity":] the entity providing the desired service;
        !           117: and,
        !           118: 
        !           119: \item[\verb"provider":] the provider supporting the named \verb"entity".
        !           120: \end{describe}
        !           121: On a successful return,
        !           122: the \verb"isoservent" structure describing that service is returned.
        !           123: On failure, the manifest constant \verb"NULL" is returned instead.
        !           124: 
        !           125: The routine \verb"getisoserventbyselector" performs the inverse function.
        !           126: \begin{quote}\index{getisoserventbyselector}\small\begin{verbatim}
        !           127: struct isoservent *getisoserventbyselector (provider,
        !           128:                         selector, selectlen)
        !           129: char   *provider,
        !           130:        *selector;
        !           131: int     selectlen;
        !           132: \end{verbatim}\end{quote}
        !           133: The parameters to this procedure are:
        !           134: \begin{describe}
        !           135: \item[\verb"provider":] the provider supporting the desired entity;
        !           136: and,
        !           137: 
        !           138: \item[\verb"selector"/\verb"selectlen":] the selector on the provider
        !           139: where the desired entity resides.
        !           140: \end{describe}
        !           141: On a successful return,
        !           142: an \verb"isoservent" structure describing the entity residing on the provider
        !           143: is returned.
        !           144: 
        !           145: The routine \verb"getisoserventbyport" performs a similar function.
        !           146: \begin{quote}\index{getisoserventbyport}\small\begin{verbatim}
        !           147: struct isoservent *getisoserventbyport (provider, port)
        !           148: char   *provider;
        !           149: unsigned short port;
        !           150: \end{verbatim}\end{quote}
        !           151: The parameters to this procedure are:
        !           152: \begin{describe}
        !           153: \item[\verb"provider":] the provider supporting the desired entity;
        !           154: and,
        !           155: 
        !           156: \item[\verb"port":] the port on the provider (in network-byte order)
        !           157: where the desired entity resides.
        !           158: \end{describe}
        !           159: On a successful return,
        !           160: an \verb"isoservent" structure describing the entity residing on the provider
        !           161: is returned.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.