SYNOPSIS

DESCRIPTION

       The Network UPS Tools (NUT) upsclient library provides a number of use-
       ful functions for programs to  use  when  communicating  with  upsd(8).
       Many of the low-level socket and protocol details are handled automati-
       cally when using this interface.

       State is maintained across calls in an opaque structure called UPSCONN.
       Callers  are expected to create one per connection.  These will be pro-
       vided to most of the upsclient functions.  The format of this structure
       is  subject  to change, and client programs must not reference elements
       within it directly.

NETWORK FUNCTIONS

       To create a new connection, use upscli_connect(3).  This will also ini-
       tialize  the  UPSCONN  structure.  To verify that a connection has been
       established later, upscli_fd(3) can be used to return the file descrip-
       tor.  Clients wishing to check for the presence and operation of SSL on
       a connection may call upscli_ssl(3).

       The majority of clients will use upscli_get(3) to retrieve single items
       from  the  server.  To retrieve a list, use upscli_list_start(3) to get
       it started, then call upscli_list_next(3) for each element.

       Raw lines of text may be sent to upsd with upscli_sendline(3).  Reading
       raw  lines  is  possible  with upscli_readline(3).  Client programs are
       expected to format these lines according to the protocol, as no  check-
       ing will be performed before transmission.

       At  the  end  of a connection, you must call upsclient_disconnect(3) to
       disconnect from upsd and release any dynamic memory associated with the
       UPSCONN structure.  Failure to call this function will result in memory
       and file descriptor leaks in your program.

ERROR HANDLING

       In the event of an error, upscli_strerror(3) will  provide  human-read-
       able  details on what happened.  upscli_upserror(3) may also be used to
       retrieve the error number.  These numbers are defined in upsclient.h as
       UPSCLI_ERR_*.

SEE ALSO

       upscli_connect(3),   upscli_disconnect(3),   upscli_fd(3),  upscli_get-
       var(3), upscli_list_next(3), upscli_list_start(3),  upscli_readline(3),
       upscli_sendline(3),      upscli_splitaddr(3),      upscli_splitname(3),
       upscli_ssl(3), upscli_strerror(3), upscli_upserror(3)



                                Mon Jan 22 2007                   UPSCLIENT(3)