next up previous contents
Next: Kerberos Database Up: Principal and Policy Databases Previous: Locking   Contents

Function descriptions

osa_adb_ret_t osa_adb_create_T_db(kadm5_config_params *params)
Create the database and lockfile specified in params. The database must not already exist, or EEXIST is returned. The lock file is only created after the database file has been created successfully.

osa_adb_ret_t osa_adb_rename_T_db(kadm5_config_params *fromparams,
				  kadm5_config_params *toparams)
Rename the database named by fromparams to that named by toparams. The fromparams database must already exist; the toparams database may exist or not. When the function returns, the database named by fromparams no longer exists, and toparams has been overwritten with fromparams. This function acquires a permanent lock on both databases for the duration of its operation, so a failure is likely to leave the databases unusable.

osa_adb_ret_t osa_adb_destroy_policy_db(kadm5_config_params *params)
Destroy the database named by params. The database file and lock file are deleted.

osa_adb_ret_t
osa_adb_open_T(osa_adb_T_t *db, char *filename);
Open the database named filename. Returns OSA_ADB_NOLOCKFILE if the database does not exist or if the lock file is missing. The database is not actually opened in the operating-system file sense until a lock is acquire.

osa_adb_ret_t
osa_adb_close_T(osa_adb_T_t db);
Release all shared or exclusive locks (on BOTH databases, since they use the same lock file) and close the database.

It is an error to exit while a permanent lock is held; OSA_ADB_NOLOCKFILE is returned in this case.

osa_adb_ret_t osa_adb_get_lock(osa_adb_T_t db, int mode)

Acquire a lock on the administration databases; note that both databases are locked simultaneously by a single call. The mode argument can be OSA_ADB_SHARED, OSA_ADB_EXCLUSIVE, or OSA_ADB_PERMANENT. The first two and the third are really disjoint locking semantics and should not be interleaved.

Shared and exclusive locks have the usual semantics, and a program can upgrade a shared lock to an exclusive lock by calling the function again. A reference count of open locks is maintained by this function and osa_adb_release_lock so the functions can be called multiple times; the actual lock is not released until the final osa_adb_release_lock. Note, however, that once a lock is upgraded from shared to exclusive, or from exclusive to permanent, it is not downgraded again until released completely. In other words, get_lock(SHARED), get_lock(EXCLUSIVE), release_lock() leaves the process with an exclusive lock with a reference count of one. An attempt to get a shared or exclusive lock that conflicts with another process results in the OSA_ADB_CANLOCK_DB error code.

This function and osa_adb_release_lock are called automatically as needed by all other osa_adb functions to acquire shared and exclusive locks and so are not normally needed. They can be used explicitly by a program that wants to perform multiple osa_adb functions within the context of a single lock.

Acquiring an OSA_ADB_PERMANENT lock is different. A permanent lock consists of first acquiring an exclusive lock and then deleting the lock file. Any subsequent attempt to acquire a lock by a different process will fail with OSA_ADB_NOLOCKFILE instead of OSA_ADB_CANTLOCK_DB (attempts in the same process will ``succeed'' because only the reference count gets incremented). The lock file is recreated by osa_adb_release_lock when the last pending lock is released.

The purpose of a permanent lock is to absolutely ensure that the database remain locked during non-atomic operations. If the locking process dies while holding a permanent lock, all subsequent osa_adb operations will fail, even through a system reboot. This is useful, for example, for ovsec_adm_import which creates both new database files in a temporary location and renames them into place. If both renames do not fully complete the database will probably be inconsistent and everything should stop working until an administrator can clean it up.

osa_adb_ret_t osa_adb_release_lock(osa_adb_T_t db)

Releases a shared, exclusive, or permanent lock acquired with osa_adb_get_lock, or just decrements the reference count if multiple locks are held. When a permanent lock is released, the lock file is re-created.

All of a process' shared or exclusive database locks are released when the process terminates. A permanent lock is not released when the process exits (although the exclusive lock it begins with obviously is).

osa_adb_ret_t
osa_adb_create_T(osa_adb_T_t db, osa_T_ent_t entry);
Adds the entry to the database. All fields are defined. Returns OSA_ADB_DUP if it already exists.

osa_adb_ret_t
osa_adb_destroy_T(osa_adb_T_t db, osa_T_t name);

Removes the named entry from the database. Returns OSA_ADB_NOENT if it does not exist.

osa_adb_ret_t
osa_adb_get_T(osa_adb_T_t db, osa_T_t name,
        osa_princ_ent_t *entry);

Looks up the named entry in the db, and returns it in *entry in allocated storage that must be freed with osa_adb_free_T. Returns OSA_ADB_NOENT if name does not exist, OSA_ADB_MEM if memory cannot be allocated.

osa_adb_ret_t
osadb_adb_put_T(osa_adb_T_t db, osa_T_ent_t entry);

Modifies the existing entry named in entry. All fields must be filled in. Returns OSA_DB_NOENT if the named entry does not exist. Note that this cannot be used to rename an entry; rename is implemented by deleting the old name and creating the new one (NOT ATOMIC!).

void osa_adb_free_T(osa_T_ent_t);

Frees the memory associated with an osa_T_ent_t allocated by osa_adb_get_T.

typedef osa_adb_ret_t (*osa_adb_iter_T_func)(void *data,
                                    osa_T_ent_t entry);

osa_adb_ret_t osa_adb_iter_T(osa_adb_T_t db, osa_adb_iter_T_func func, 
                    void *data);

Iterates over every entry in the database. For each entry ent in the database db, the function (*func)(data, ent) is called. If func returns an error code, osa_adb_iter_T returns an error code. If all invokations of func return OSA_ADB_OK, osa_adb_iter_T returns OSA_ADB_OK. The function func is permitted to access the database, but the consequences of modifying the database during the iteration are undefined.


next up previous contents
Next: Kerberos Database Up: Principal and Policy Databases Previous: Locking   Contents
Autobuild 2009-09-05