DragonFly On-Line Manual Pages

ph_query(3)                     C Library Calls                    ph_query(3)

NAME
       ph_query, ph_free_entries, ph_free_query - retrieve data from a PH
       server

SYNOPSIS
       #include <phclient.h>

       int ph_query(PH *ph, struct ph_fieldselector query[], char
       *retfields[], ph_entry **entries);
       int ph_free_entries(ph_entry *entries);

VERSION
       This man page documents version 1.2 of libphclient.

DESCRIPTION
       The ph_query() function retrieves entries from the PH server associated
       with the PH handle ph.  The query argument selects which entries to
       return.  The retfields argument indicates which fields from the
       selected entries should be returned.  The resulting entries are stored
       in dynamicly-allocated memory, and the entries argument is set to point
       to them.

       The query argument is an array of structures which contain the
       following fields: field (a string representation of the field name),
       value (a string representation of the value to check for), and
       operation (a character value indicating how the field and value should
       be compared).  If field is NULL, the operation field is ignored and the
       value is matched against the default fields on the server.  The only
       universally-supported value for operation is '=', but other
       possibilities include '~', '<', and '>'.

       The retfields argument is a NULL-terminated array of strings which
       lists the fields to return.  If retfields is NULL, the default set of
       fields is returned from the server.

       The ph_free_entries() function is used to free memory allocated by
       ph_query() for the entries argument.

RETURN VALUE
       On success, the ph_query() function returns the number of entries which
       matched query.  If the query matched too many entries for the server to
       return them, it returns PH_ERR_TOOMANY.  If no entries matched, it
       returns PH_ERR_NOMATCH.  If the query was invalid, it returns
       PH_ERR_DATAERR.  On error, it returns -1 and sets errno.

ERRORS
       The ph_query() function will fail with EINVAL if it receives an
       unexpected response code from the server.  In addition, it 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_query(3)