vitalnix user management suite 3.2.0


Name

libvxutil -- helper functions for various tasks

Syntax

#include <vitalnix/libvxutil/libvxutil.h>

Functions with separate manpages

vxutil_genpw(3) (Plaintext) password generation
vxutil_phash(3) Password hashing/encryption

Function: vxutil_azstr()

char *vxutil_azstr(const char *string);

vxutil_azstr() will return a pointer to a zero-length string if string is NULL, otherwise string. This essentially makes sure the returned pointer can always be dereferenced. Actual use for this function is somewhere between laziness and cleaner code, e.g.:

strcmp(vxutil_azstr(foo), "bar") == 0

Function: vxutil_have_display()

bool vxutil_have_display(void);

This function can be used to determine if a graphical X Windows environment is present by checking the DISPLAY environment variable.

Function: vxutil_now_iday()

unsigned int vxutil_now_iday(void);

Returns the current date measured in days from January 01 1970. This format is commonly used for password ageing monitoring.

Function: vxutil_only_digits()

bool vxutil_only_digits(const char *string);

Returns non-zero if there are only digits (as determined by isdigit()) in the string.

Function: vxutil_propose_home()

char *vxutil_propose_home(char *dest, size_t size, const char *base, const char *username, unsigned int level);

Generates a home directory path, whose exact structure is dependent on level. A larger level yields a deeper filesystem tree depth, but reduces the number of concurrent inodes within a directory (this reduces directory search time on legacy filesystems). Level 2 for example is used by SourceForge's public servers.

Level 0 /home/username
Level 1 /home/u/username
Level 2 /home/u/us/username

The result is put into buf. At most size-1 characters are written and the result is always '\0'-terminated.

Function: vxutil_propose_lname()

char *vxutil_propose_lname(char *dest, size_t size, const char *surname, const char *firstname);

Creates a login name in the style of FSSSSSS out of a real-world name. surname can be NULL, while firstname must not be NULL. The two strings must be UTF-8 encoded.

There is special handling if the surname has multiple parts -- let's take "van der Wies" as a fictional example. In this case, we consider the last part as what we would like to have in the username.

Function: vxutil_quote()

char *vxutil_quote(const char *src, unsigned int type, char **free_me);

Returns a the string src in its escaped form according to type. The function returns NULL on error, or a pointer to the escaped string on success. If extra space was allocated, the pointer is stored in *free_me, which is to be freed after usage. If no quoting was done, because it was not needed, *free_me is set to NULL. This allows you to use free() unconditionally:

char *free_me, *p;
p = vxutil_quote("o'really?", VXQUOTE_SINGLE, &free_me);
printf("%s\n", p);
free(free_me);

Function: vxutil_replace_run()

int vxutil_replace_run(const char *command, const struct HXbtree *varmap);

Replaces every occurrence of a %{}-tag in the command string by the defined value from varmap, then runs the expanded command using system() and returns its status.

Function: vxutil_slurp_file()

char *vxutil_slurp_file(const char *filename);

Reads in the file specified by filename in whole and returns a pointer to the newly allocated memory area, which should be freed after usage. On error, NULL is returned and errno will be set accordingly with the error from libc.

Function: vxutil_string_iday()

int vxutil_string_iday(const char *date);

Transforms the string pointed to by date, which is of either format of DD.MM.YYYY, MM/DD/YYYY or YYYY-MM-DD into an integer representing the days since January 01 1970. The function will return negative non-zero on (parsing) error.

Function: vxutil_string_xday()

int vxutil_string_xday(const char *date);

Transforms the string pointed to by date, which is of either format of DD.MM.YYYY, MM/DD/YYYY or YYYY-MM-DD into a BCD-style encoded integer representing the date.

Function: vxutil_valid_username()

bool vxutil_valid_username(const char *username);

Returns true if the username does not contain any illegal characters. Samba UNIX machine account names are also handled (and will be accepted if they are valid).

Function: vxuuid_vx3()

char *vxuuid_vx3(const char *full_name, unsigned int xday);

Generate a UUID from the string full_name and the integer xday. This is used for Data Sources which come without an UUID, so one is generated based on the (name, date) tuple we deem to be unique within the Data Source. Returns a pointer to the newly allocated string containing the UUID, or NULL on error.