UPSCLI_UPSLOG_SET_DEBUG_LEVEL(3)
================================

NAME
----

upscli_upslog_set_debug_level, upscli_upslog_get_debug_level,
upscli_upslog_cookie, upscli_upslog_setprocname,
upscli_upslog_setproctag, upscli_upslog_getproctag,
upscli_upslog_start_sync - manipulate
the possibly separate (identified via cookie) copies of the `nut_debug_level`
and sub-process tag variables in the `libupsclient` build

SYNOPSIS
--------

------
	#include <upsclient.h>

	const void *upscli_upslog_cookie(void);

	void upscli_set_debug_level(int, const void *cookie);
	int  upscli_get_debug_level(void);

	void upscli_setprocname(const char *full_procname, const void *cookie);
	void upscli_setproctag(const char *tag, const void *cookie);
	const char *upscli_getproctag(void);

	struct timeval *upscli_upslog_start_sync(struct timeval *tv, const void *cookie);
------

DESCRIPTION
-----------

On some platforms, 'libupsclient' builds tend to get a built-in copy
of the internal code from NUT 'libcommon' library, so for NUT client
programs using both libraries as dynamically-linked shared code,
the `nut_debug_level` setting is backed by independent variables in
active memory, and `upsdebugx()` calls suffer if the library's copy
is never changed from zero.

It can get even more confusing with libnutprivate-common being a shared
dynamically loaded library instance behind both the program and libupsclient,
hence the cookies: direct NUT-common code consumers like NUT in-tree clients
can use their `nut_common_cookie()` value to pass into methods here.
Third-party clients may safely pass 'NULL'.

These methods allow to set or retrieve the value of `nut_debug_level`
setting known by the 'libupsclient' library, regardless of build mode.

The most likely use (at least in NUT programs) is to call
`upscli_set_debug_level(nut_debug_level);` after changing the
original variable. Values of the debugging level are zero to disable
debug, may be negative for a few special cases, and generally are
positive numbers to cut off the more verbose logging attempts;
otherwise it is up to the code base and NUT style guide practices
to assign certain levels to some classes of messages.

If internal `upslog_start` value is not yet set, we can set it with
*upscli_upslog_start_sync()* from *tv (or current time if tv==NULL),
otherwise the method is no-op (keep and report the original setting).

Returns the pointer to the currently set value, so it
can be propagated or used in difftime() computations.

NOTE: In WIN32 builds also enforces line-buffering for
stdout and stderr streams.


RETURN VALUE
------------

There is no return value for the setter.

The getter returns the current value of the internal variable.

SEE ALSO
--------

linkman:upscli_init[3], linkman:upscli_report_build_details[3]
