ph_get_option(3)

NAME
ph_get_option, ph_retrieve_options, ph_set_option, ph_option_iterate - show and set PH server options

SYNOPSIS
#include <phclient.h>

int ph_get_option(PH *ph, char *option, char **setting);
int ph_retrieve_options(PH *ph);
int ph_set_option(PH *ph, char *option, char *setting);
int ph_option_iterate(PH *ph, struct ph_option **svropt);
void ph_free_options(PH *ph);
int ph_is_optionlist_cached(PH *ph);

VERSION
This man page documents version 1.2 of libphclient.

DESCRIPTION
These functions allow the caller to access the list of options supported by the PH server associated with the PH handle ph. Each option is represented as a struct ph_option, which contains the fields option and setting. The ph_retrieve_options() function retrieves the option list from the PH server to be cached locally. If the option list is already cached locally, the call will return successfully without doing anything. The ph_is_optionlist_cached() macro determines if the option list is currently cached locally. The ph_free_options() function clears the local option list cache. A subsequent call to ph_retrieve_options() will reload the option list from the server. The ph_get_option() function sets the setting argument to point to the current value of the option named option. It automatically calls ph_retrieve_options() if the option list is not cached locally. The ph_set_option() function sets the value of option to setting. The ph_option_iterate() function allows the caller to iterate through all server options by setting svropt to point to the next option at each successive call. To begin at the beginning of the list, the caller initializes svropt to NULL.

RETURN VALUE
The ph_retrieve_options() function returns 0 on success, or -1 on error and sets errno. The ph_is_optionlist_cached() macro returns 1 if the option list is cached locally, or 0 otherwise. The ph_get_option() and ph_set_option() functions return 0 on success, or -1 on error, or PH_ERR_DATAERR if option is not found. The ph_option_iterate() function returns 1 when an option is returned, or 0 when the end of the list has been reached. On error, it returns -1 and sets errno.

ERRORS
The ph_get_options() function will fail with EINVAL if it receives an unexpected response code from the server. The ph_get_options() function may fail with any error from the functions read() or write().

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