upscli_readline3

Usage

        #include <upsclient.h>
        #include <time.h> /* or <sys/time.h> on some platforms */
        int upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen);
        int upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen,
                const time_t timeout);
        int upscli_readline_timeout_may_disconnect(UPSCONN_t *ups,
                char *buf, size_t buflen, const time_t timeout,
                int may_disconnect);

Overview

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.

Some parsing of the string occurs during reception. In particular, ERR messages from upsd(8) are detected and will cause this function to return -1.

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.