UPSCLI_INIT_DEFAULT_(3)           NUT Manual           UPSCLI_INIT_DEFAULT_(3)

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):

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

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

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

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

       o   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)

Network UPS Tools 2.8.3           05/29/2025           UPSCLI_INIT_DEFAULT_(3)