NAME

upscli_init_default_connect_timeout - Initialize upsclient module aspect of default timeout for initial connections.

SYNOPSIS

        #include <upsclient.h>

        int upscli_init_default_connect_timeout(
                const char *cli_secs,
                const char *config_secs,
                const char *default_secs);

DESCRIPTION

The upscli_init_default_connect_timeout() function initializes upsclient module aspect of default connection timeout for upscli_connect(3), which may be important when e.g. upsc(8) scripting or upsmon(8) configuration refers to unresponsive hosts, or when the host name resolution lags, etc. By default, upscli_connect(3) blocks indefinitely in its attempts to connect (or until the system transport layer interrupts such an attempt).

It populates the value from different sources, mostly C strings which represent a floating-point non-negative number (invalid parsing is logged and may impact the return value), any or all of them may be NULL to skip, and in specific order (last valid hit wins):

  • built-in 0 meaning indefinitely blocking (NUT default for this method over at least 20 years);

  • the number from default_secs as a particular NUT or third-party client program’s built-in preferred (low-priority) default;

  • the number from NUT_DEFAULT_CONNECT_TIMEOUT environment variable as a site-local preference (generally pre-set in nut.conf(5));

  • the number from config_secs as a particular NUT or third-party client program’s configuration file default;

  • the number from cli_secs as a particular NUT or third-party client program’s setting from command line (highest priority).

Internally, calls upscli_set_default_connect_timeout(3) for most of the string related processing.

The upsclient module tracks if upscli_init_default_connect_timeout() function was called and succeeded, in order to call it once (if never used) from the upscli_connect(3) or upscli_init(3) methods. This allows unmodified (legacy) NUT clients to consistently benefit from presence of the NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

This tracking does not preclude programs from explicitly calling the method any amount of times.

RETURN VALUE

The upscli_init_default_connect_timeout() function returns 0 on success (either if all strings were NULL so the built-in default is applied, or at least one of those strings that were set was valid and its value got applied), or -1 if an error occurs (at least one string was not NULL, and none of the strings was valid).

SEE ALSO

upscli_connect(3), upscli_tryconnect(3), upscli_set_default_connect_timeout(3), upscli_get_default_connect_timeout(3), upscli_init(3)