vitalnix user management suite 3.2.0


General

#include <vitanlix/libvxdb/libvxdb.h>

struct vxdb_user;
struct vxdb_group;
struct vxdb_state;

Function overview

#include <vitalnix/libvxdb/libvxdb.h>

struct vxdb_state *vxdb_load(const char *module);
void vxdb_unload(struct vxdb_state *state);

vxdb_load

The vxdb_load() function loads a VXDB (user account database back-end driver, acquires and fixes up all symbols and returns a struct describing the loaded module. The module parameter can be one of:

The second way is not widely used, because it the filename extension of the shared library depends on the architecture Vitalnix runs on. Although the third point only lists .so as an example, the .dll extension is also tried when completing to a filename, even under non-Win32. Note that for any module which is not named in the fashion of libvxdb_*.so, there is only the second way.

On failure, vxdb_load() will return NULL and errno will be set.

vxdb_unload

Unloads the VXDB module.

Function overview -- Module access functions

#include <vitalnix/libvxdb/xafunc.h>

int vxdb_open(struct vxdb_state *state, long flags);
void vxdb_close(struct vxdb_state *state);
int vxdb_modctl(struct vxdb_state *state, long command, ...);
int vxdb_lock(struct vxdb_state *state);
int vxdb_unlock(struct vxdb_state *state);
int vxdb_useradd(struct vxdb_state *state, const struct vxdb_user *user);
int vxdb_usermod(struct vxdb_state *state, const struct vxdb_user *search_mask, const struct vxdb_user *replace_mask);
int vxdb_userdel(struct vxdb_state *state, const struct vxdb_user *search_mask);
int vxdb_userinfo(struct vxdb_state *state, const struct vxdb_user *search_mask, struct vxdb_user *result, size_t size);
void *vxdb_usertrav_init(struct vxdb_state *state);
int vxdb_usertrav_walk(struct vxdb_state *state, void *data, struct vxdb_user *result);
void vxdb_usertrav_free(struct vxdb_state *state, void *data);
int vxdb_groupadd(struct vxdb_state *state, const struct vxdb_group *group);
int vxdb_groupmod(struct vxdb_state *state, const struct vxdb_group *search_mask, const struct vxdb_group *replace_mask);
int vxdb_groupdel(struct vxdb_state *state, const struct vxdb_group *search_mask);
int vxdb_groupinfo(struct vxdb_state *state, const struct vxdb_group *search_mask, struct vxdb_group *result, size_t size);
void *vxdb_grouptrav_init(struct vxdb_state *state);
int vxdb_grouptrav_walk(struct vxdb_state *state, void *data, struct vxdb_group *result);
void vxdb_grouptrav_free(struct vxdb_state *state, void *data);

vxdb_open

Open the password database associated with state using flags. state must have been obtained using vxdb_load() before.

vxdb_close

vxdb_lock

Lock the database. Returns an AEE code. If the database does not implement it, either zero or -ENOSYS is returned.

vxdb_unlock

Unlock the database. Always succeeds (it really depends on the VXDB module -- and returns an AEE code).

vxdb_useradd

Returns -EINVAL if the username is empty, or -EEXIST if the username already exists. It is implementation-defined whether the creation of accounts with non-unique UID is allowed. If forbidden, -EEXIST is returned too.

vxdb_usermod

Returns -EINVAL if both username and uid in the search mask are empty, or returns -ENOENT if the user was not found.

vxdb_userdel

Returns -EINVAL if both username and uid in the search mask are empty, or returns -ENOENT if the user was not found.

Function overview -- Extra access functions

#include <vitalnix/libvxdb/xwfunc.h>

int vxdb_getpwnam(struct vxdb_state *state, const char *user, struct vxdb_user *result);
int vxdb_getpwuid(struct vxdb_state *state, unsigned int uid, struct vxdb_user *result);
int vxdb_getgrnam(struct vxdb_state *state, const char *group, struct vxdb_group *result);
int vxdb_getgrgid(struct vxdb_state *state, unsigned int gid, struct vxdb_group *result);

These functions provide simple wrappers around vxdb_userinfo() and vxdb_groupinfo() that take the burden off the user to create the search mask beforehand if one only wants to search for one paramter (in this case either name or uid/gid). Just as their underlying function, they will all allocate the internal data buffer in the struct vxdb_user/vxdb_group if necessary.

Auxiliary functions

#include <vitalnix/libvxdb/libvxdb.h>

void vxdb_user_clean(struct vxdb_user *user);
void vxdb_user_copy(struct vxdb_user *dest, const struct vxdb_user *src);
struct vxdb_user *vxdb_user_dup(const struct vxdb_user *src);
void vxdb_user_free(struct vxdb_user *user, int heap);
void vxdb_user_nomodify(struct vxdb_user *user);

void vxdb_group_clean(struct vxdb_group *group);
void vxdb_group_copy(struct vxdb_group *dest, const struct vxdb_group *src);
struct vxdb_user *vxdb_group_dup(const struct vxdb_group *src);
void vxdb_group_free(struct vxdb_user *user, bool heap);
void vxdb_group_nomodify(struct vxdb_group *group);

vxdb_user_clean

Fills the user structure pointed to by user with the defaults, which are:

->pw_name NULL
->pw_uid VXDB_NOUID
->pw_gid VXDB_NOGID
->pw_igrp (NOT IMPLEMENTED YET) NULL
->pw_real NULL
->pw_home NULL
->pw_shell NULL
->pw_sgrp (not fully implemented) NULL
->sp_passwd NULL
->sp_lastchg 0
->sp_min VXDB_DFL_KEEPMIN
->sp_max VXDB_DFL_KEEPMAX
->sp_warn VXDB_DFL_WARNAGE
->sp_expire VXDB_NO_EXPIRE
->sp_inact VXDB_NO_INACTIVE
->vs_uuid NULL
->vs_pvgrp NULL
->vs_defer 0

The internal buffer is not modified at all.

vxdb_group_clean

Fills the user structure pointed to by user with the defaults, which are:

->gr_name NULL
->gr_gid VXDB_NOGID

The internal buffer is not modified at all.

vxdb_user_copy
vxdb_group_copy

vxdb_user_dup
vxdb_group_dup

vxdb_user_free
vxdb_group_free

Free the structure or part thereof. If heap is non-zero, the object is freed in its entirety (do not use it for stack objects), or if it is zero, only free substructures which are on the heap.

vxdb_user_nomodify
vxdb_group_nomodify

Sets all fields in the struct vxdb_user or struct vxdb_group so that when passed to vxdb_usermod() or vxdb_groupmod(), respectively, as a modify mask, no changes to the user or group would occurr.

Per-user/per-group internal data

Some back-end modules store or cache the user data in memory using our very own struct vxdb_user (and/or struct vxdb_group, of course), where all pointers in these structs point to the module's address space. (Address space as in "allocated by the module", not in the sense of the operating system kernel.) Examples for this approach are libvxdb_shadow and the demonstrational libvxdb_nss.

Other modules, like libvxdb_mysql and libvxdb_ldap do not use a cache, so there is only the LDAP/MySQL server and the user program, but somewhere, the strings (such as username, home directory, etc.) must be stored. Rather than having fixed-length character arrays in struct vxdb_user, a dynamic buffer (exactly one) is used, and the string members, e.g. ->pw_name point to this buffer, which will not cease to be valid once the module has been unloaded, and therefore must be freed by the user application.
Because of lack of ideas, the process of copying strings into a local buffer is simply called "exporting" herein.

#include <vitalnix/libvxdb/libvxdb.h>

void vxdb_export_user(const struct vxdb_user *src, struct vxdb_user *dest);
void vxdb_export_group(const struct vxdb_group *src, struct vxdb_group *dest);

vxdb_export_user
vxdb_export_group

vxdb_export_user() and vxdb_export_group() will copy the strings pointed to by the struct vxdb_user or struct vxdb_group members into the local internal buffer, respectively. src and dest might point to the same structure, but no pointer in src may point to dest's internal buffer.