.TH ph_serverlist_add 3 "Oct 2002" "University of Illinois" "C Library Calls"
.SH NAME
ph_serverlist_add, ph_serverlist_merge, ph_serverlist_iterate, ph_free_serverlist \- access list of known PH servers at other sites
.SH SYNOPSIS
.B #include <phclient.h>
.P
.BI "int ph_serverlist_add(struct ph_serverlist *" serverlist ","
.BI "char *" server ", char *" site ");"
.br
.BI "int ph_serverlist_merge(PH *" ph ", struct ph_serverlist *" serverlist ");"
.br
.BI "int ph_serverlist_iterate(struct ph_serverlist *" serverlist ","
.BI "char *" server ", char *" site ","
.BI "struct ph_serversite **" serversite ");"
.br
.BI "void ph_free_serverlist(struct ph_serverlist *" serverlist ");"
.SH VERSION
This man page documents version 1.2 of \fBlibphclient\fP.
.SH DESCRIPTION
The \fBph_serverlist_add\fP() function will add an entry for the PH
server \fIserver\fP at site \fIsite\fP to the list of servers in
\fIserverlist\fP.

The \fBph_serverlist_merge\fP() function will read the list of known PH
servers from the server associated with \fIph\fP and add any previously-
unknown entries to the list of servers in \fIserverlist\fP.

The \fBph_serverlist_iterate\fP() function allows the caller to cycle
through the list of known PH servers by setting \fIserversite\fP to
point to the next matching entry in \fIserverlist\fP on each successive
call.  To start at the beginning of the list, the caller initializes
\fIserversite\fP to \fINULL\fP.

If \fIserver\fP is not \fINULL\fP, only entries whose last two or more
domain name componants of the \fIserver\fP field match the \fIserver\fP
argument will be returned.  If \fIsite\fP is not \fINULL\fP, only
entries whose \fIsite\fP field contain the argument \fIsite\fP as a
substring will be returned.  If both \fIserver\fP and \fIsite\fP are
non-\fINULL\fP, only entries matching both criteria will be returned.
If both \fIserver\fP and \fIsite\fP are \fINULL\fP, all entries are
returned.

The \fBph_free_serverlist\fP() function frees memory associated with
the PH server list \fIserverlist\fP.
.SH RETURN VALUE
The \fBph_serverlist_add\fP() function returns 0 on success, or -1 on
error (and set \fIerrno\fP).

The \fBph_serverlist_merge\fP() function returns 0 on success,
\fIPH_ERR_DATAERR\fP if the server does not understand the query, or -1 on
error (and set \fIerrno\fP).

The \fBph_serverlist_iterate\fP() function returns 1 when a matching
entry is returned, 0 when no more matching entries have been found,
or -1 on error (and sets \fIerrno\fP).
.SH ERRORS
The \fBph_serverlist_merge\fP() function will fail with \fBEINVAL\fP if it
receives an unexpected response code from the server.

The \fBph_serverlist_iterate\fP() function will fail with \fBEINVAL\fP if
the \fIserver\fP argument is non-\fINULL\fP but specifies an illegal
domain name.
.SH SEE ALSO
.BR read (2),
.BR write (2),
.BR ph_open (3),
.BR ph_query (3)