DragonFly On-Line Manual Pages

Search: Section:  

ph_get_option(3)                C Library Calls               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)

University of Illinois             Oct 2002                   ph_get_option(3)

Search: Section: