DragonFly On-Line Manual Pages

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

University of Illinois             Oct 2002                         ph_open(3)