ph_open(3)

NAME
ph_open, ph_close - manage PH server connections

SYNOPSIS
#include <phclient.h>

typedef void (*ph_debug_func_t)(void *, char *);
int ph_open(PH **ph, char *server, int flags, ph_debug_func_t sendhook, ph_debug_func_t recvhook, void *hook_data);
int ph_close(PH *ph, int flags);

VERSION
This man page documents version 1.2 of libphclient.

DESCRIPTION
The ph_open() function connects to the PH server specified by server. It allocates memory for a PH handle and sets the ph argument to point to the allocated handle. The handle can then be passed to other libphclient calls to communicate with the server. The flags argument is a bitwise-or of zero or more of the following values:

PH_OPEN_PRIVPORT
    Use a reserved port for the local part of the connection.

PH_OPEN_ROUNDROBIN
    If server is a round-robin DNS entry, try all IP addresses before giving up.

PH_OPEN_LOCAL
    Connect to a local process via a pipe, rather than to a remote network port. If this flag is given, the PH_OPEN_PRIVPORT and PH_OPEN_ROUNDROBIN flags are ignored, the server argument specifies a path to the PH server program on the local system. If PH_OPEN_LOCAL is not set, the server argument specifies the hostname of the remote PH server. It may optionally be suffixed with a ":" character followed by a numeric port number.

PH_OPEN_DONTID
    Do not send the library version string to the server upon connection.

The sendhook() and recvhook() arguments are optional pointers to functions which allow the calling application to monitor the communication between libphclient and the PH server. See ph_set_sendhook(3) for more information. The ph_close() function closes the PH server connection and frees memory associated with ph. If flags is set to PH_CLOSE_FAST, the connection is closed without sending the PH "quit" command.

RETURN VALUE
On successful completion, ph_open() and ph_close() will return 0. On failure, they will return -1 and set errno to an appropriate value.

ERRORS
The ph_open() function may fail with any error from the functions pipe(), close(), dup2(), vfork(), execl(), execlp(), gethostbyname(), rresvport(), socket(), connect(), or calloc(). The ph_close() function may fail with any error from the functions close() or write().

SEE ALSO
socket(2), connect(2), close(2)