DragonFly On-Line Manual Pages

ph_get_fieldinfo(3)             C Library Calls            ph_get_fieldinfo(3)

NAME
       ph_get_fieldinfo, ph_retrieve_fieldinfo, ph_fieldinfo_iterate,
       ph_decode_field_attributes - access field information from PH server

SYNOPSIS
       #include <phclient.h>

       int ph_get_fieldinfo(PH *ph, char *fieldname, struct ph_fieldinfo
       **fieldinfo);
       int ph_retrieve_fields(PH *ph);
       void ph_decode_field_attributes(unsigned long bitmask, char *buf, int
       bufsize);
       int ph_fieldinfo_iterate(PH *ph, struct ph_fieldinfo **fieldinfo);
       void ph_free_fieldinfo(PH *ph);
       int ph_is_fieldinfo_cached(PH *ph);

VERSION
       This man page documents version 1.2 of libphclient.

DESCRIPTION
       These functions allow the caller to access the field list from the PH
       server associated with the PH handle ph.  The information for a given
       field is encoded as a struct ph_fieldinfo, which includes the fields
       name (the field's name), id (the field's numeric ID), max_size (the
       maximum size of the field), description (a text string describing the
       field), and attrib (a bitmask of attributes associated with the field).

       The ph_retrieve_fieldinfo() function retrieves the field list from the
       server associated with ph and caches it locally.  If the field list is
       already cached before the call to ph_retrieve_fieldinfo(), it returns
       successfully without doing anything.

       The ph_free_fieldinfo() function frees the memory associated with the
       locally-cached field list.  A subsequent call to
       ph_retrieve_fieldinfo() will reload the cache from the server.

       The ph_is_fieldinfo_cached() macro determines whether or not the field
       list is cached locally.

       The ph_get_fieldinfo() function sets fieldinfo to point to the
       ph_fieldinfo structure describing fieldname.  If the field list has not
       been retrieved from the server, ph_retrieve_fieldinfo() is called.

       The ph_fieldinfo_iterate() function allows the calling application to
       iterate through the entire field list by setting fieldinfo to the next
       entry at each call.  To begin at the beginning of the list, the caller
       must initialize fieldinfo to NULL.

       The ph_decode_field_attributes() function generates a text
       representation of the attributes set in bitmask.  It writes the text
       string to the buffer of size bufsize pointed to by buf.

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

       The ph_is_fieldinfo_cached() macro returns 1 if the field list is
       cached locally, or 0 otherwise.

       The ph_fieldinfo_iterate() function returns 1 when field information is
       returned, or 0 when there are no more fields.  On error, it returns -1
       and sets errno.

       The ph_get_fieldinfo() function returns 0 on success, PH_ERR_DATAERR if
       fieldname is not found.  On error, it returns -1 and sets errno.

ERRORS
       The ph_retrieve_fieldinfo() and ph_get_fieldinfo() functions will fail
       with EINVAL if they receive an unexpected response code from the
       server.

       The ph_retrieve_fieldinfo() 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_fieldinfo(3)