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)