NAME
upscli_readline, upscli_readline_timeout, upscli_readline_timeout_may_disconnect - Read a single response from a UPS
SYNOPSIS
#include <upsclient.h>
#include <time.h> /* or <sys/time.h> on some platforms */
ssize_t upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen);
ssize_t upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen,
const time_t timeout);
ssize_t upscli_readline_timeout_may_disconnect(UPSCONN_t *ups,
char *buf, size_t buflen, const time_t timeout,
int may_disconnect);DESCRIPTION
The upscli_readline() and upscli_readline_timeout() functions take
the pointer ups to a UPSCONN_t state structure, receive a single
line from the server, and copy up to buflen bytes of the response
into the buffer buf.
These functions read raw lines and do not interpret ERR messages from upsd(8). A successfully read ERR line returns 0; the caller must check the protocol response. Higher-level functions such as upscli_get(3) perform this checking.
The difference between the three functions is that upscli_readline_timeout() lets the caller decide the amount of time (timeout seconds) after which it should give up and return, whereas upscli_readline() does not offer this freedom, and uses NUT default network timeout (5 seconds). Both of these disconnect upon errors. The upscli_readline_timeout_may_disconnect() further allows to enable or disable such disconnections.
RETURN VALUE
The upscli_readline() and upscli_readline_timeout() functions return 0 on success, or -1 if an error occurs.
