NAME
upscli_find_authconf_item, upscli_get_authconf_item, upscli_normalize_authconf_section_parts, upscli_split_authconf_section - Find authentication configuration items by their name components; help parse and normalize name components for authentication configuration items
SYNOPSIS
#include <authconf.h>
/* Item as it is on list, may be incomplete */
upscli_authconf_t *upscli_find_authconf_item(
const char *user,
const char *host,
const char *port);
/* Merge exact/host/global layers for a unique item */
upscli_authconf_t *upscli_get_authconf_item(
const char *user,
const char *host,
const char *port,
int add_to_list);
int upscli_normalize_authconf_section_parts(
char **out_normalized_sect_name,
char **p_sect_user,
int *out_fixed_sect_user,
char **p_sect_host,
char **p_sect_port);
int upscli_split_authconf_section(const char *sect_name,
char **normalized_sect_name,
char **normalized_sect_user,
int *out_fixed_sect_user,
char **normalized_sect_host,
char **normalized_sect_port);DESCRIPTION
The upscli_find_authconf_item() function searches the internal list of authentication configurations for the best match for the given user, host, and port, and returns that list entry "as is" (the way it was originally spelled in configuration files, adjusted just for section title normalization). This function is primarily a stepping stone for upscli_get_authconf_item() to do its work.
The matching logic follows this priority:
-
Exact match for
[user@host:port] -
Match for
[@host:port](host default) -
Global default section (if user, host, and port are all NULL, or if there was no exact or host default match)
The upscli_get_authconf_item() function goes a bit further and finds "parent"
entries (from exact match, to host defaults, to global defaults) to merge any
missing fields in that section to be inherited from the higher-level defaults.
If a specific user value was requested and only a non-exact match was found,
that fixed USER=... directive will be assumed and injected into the output.
If add_to_list is 0, this function would return a new instance of the
upscli_authconf_t structure, which owns a separate copy of any strings
involved, and can be safely discarded with upscli_free_authconf_item(3)
(and MUST be discarded by caller, it is not added into the list). Each call
with same arguments returns a new instance, even with same data (or different,
if e.g. global defaults were changed for fields not populated in the original
item on the list).
If add_to_list is 1, this function would return a new instance of the
structure and add it into the list, or would edit an existing item already
on the list by filling in the missing points inherited from higher levels.
On one hand, the caller does not have to manage freeing of this structure
and repetitive calls do not increase memory usage; on another, this precludes
adaptation to changing higher-level defaults (which is a reasonable approach
when configuration is loaded once).
The "upscli_split_authconf_section()" function splits a sect_name which may
be from a user-typed configuration file into user, host and port sections, and
with "upscli_normalize_authconf_section_parts()" normalizes the values (e.g. a
NULL host becomes localhost, a missing port is defaulted to NUT_PORT
defined at build configuration time, e.g. 3493 by default, and a non-numeric
string port is resolved in the naming database of the current operating
environment). The resulting normalized values are returned to caller using
pointers provided in the arguments (if not NULL in case of
"upscli_split_authconf_section()", must be not NULL in case of
"upscli_normalize_authconf_section_parts()").
A normalized_sect_name can be also constructed and returned, so that varying
but ultimately identical definitions of the section titles (e.g. [@localhost]
and [@localhost:3493] can be conflated when parsing configuration files or
searching in the list.
RETURN VALUE
The upscli_find_authconf_item() function returns a pointer to a upscli_authconf_t
structure containing the matched configuration, or NULL if no match is found.
Note that the returned pointer refers to an item in the internal list managed
by libupsclient; it should not be freed directly by the caller unless they
are managing their own list.
The upscli_free_authconf_item() function returns the last known value of the next
pointer field from the node being freed.