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 magic string
"*"
which will select the default module as listed in/etc/vitalnix/libvxdb.conf
- the filename of the module, e.g.
"libvxdb_shadow.so"
- the canonical name of the module, e.g.
"mysql"
(which is completed to"libvxdb_mysql.so"
)
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.