DragonFly On-Line Manual Pages

ph_get_siteinfo(3)              C Library Calls             ph_get_siteinfo(3)

NAME
       ph_retrieve_siteinfo, ph_get_siteinfo, ph_siteinfo_iterate - access
       site-specific information from PH server

SYNOPSIS
       #include <phclient.h>

       int ph_get_siteinfo(PH *ph, char *info, char **data);
       int ph_retrieve_siteinfo(PH *ph);
       int ph_siteinfo_iterate(PH *ph, struct ph_siteinfo **siteinfo);
       void ph_free_siteinfo(PH *ph);
       int ph_is_siteinfo_cached(PH *ph);

VERSION
       This man page documents version 1.2 of libphclient.

DESCRIPTION
       These functions allow the caller to access the list of site-specific
       settings from the PH server associated with the PH handle ph.  Site-
       specific settings are represented as ph_siteinfo structures, which
       contain the following fields: info (the name of the field, encoded as a
       string) and data (the string encoding of the data contained in the
       field).

       The ph_retrieve_siteinfo() function retrieves the siteinfo list from
       the PH server to be cached locally.  If the siteinfo data is already
       cached locally, the function returns successfully without doing
       anything.

       The ph_free_siteinfo() function clears the local siteinfo cache.  A
       subsequent call to ph_retrieve_siteinfo() will reload the siteinfo data
       from the server.

       The ph_is_siteinfo_cached() macro determines whether or not the
       siteinfo data is cached locally.

       The ph_get_siteinfo() function sets data to point to the value of the
       siteinfo field named by info.  It automatically calls
       ph_retrieve_siteinfo() if the siteinfo data is not cached locally.

       The ph_siteinfo_iterate() function allows the caller to cycle through
       the list of siteinfo entries by setting siteinfo to point to the next
       entry on each successive call.  To start at the beginning of the list,
       the caller initializes siteinfo to NULL.

RETURN VALUE
       The ph_retrieve_siteinfo() function returns 0 on success, or -1 on
       error and sets errno.

       The ph_is_siteinfo_cached() macro returns 1 if the siteinfo data is
       cached locally, or 0 otherwise.

       The ph_get_siteinfo() function returns 0 on success, -1 on error, or
       PH_ERR_DATAERR if there is no entry for info.

       The ph_siteinfo_iterate() function returns 1 when the next siteinfo
       entry is returned, 0 at the end of the list, or -1 on error (and sets
       errno).

ERRORS
       The ph_retrieve_siteinfo() function will fail with EINVAL if it
       receives an unexpected response code from the server.

       The ph_retrieve_siteinfo() function may fail with any error from the
       functions read() or write().

SEE ALSO
       read(2), write(2), ph_open(3)

University of Illinois             Oct 2002                 ph_get_siteinfo(3)