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)