NAME

getaidname, getclass, getevent, getgroup, getmask, getuser − caching functions

SYNOPSIS

#include <stdio.h>
#include <sys/types.h>
#include <aucache.h>
#include <audit_id.h>
 extern FILE ∗audit_id_fp;
struct audit_id ∗getaidname(aid)
uid_t aid;
 extern FILE ∗class_fp;
struct auclass ∗getclass(cid)
int cid;
 extern FILE ∗event_fp;
struct auevent ∗getevent(eid)
int eid;
 extern FILE ∗group_fp;
char ∗getgroup(gid)
gid_t gid;
 extern FILE ∗mask_fp;
struct aumask ∗getmask(user)
char ∗user;
 extern FILE ∗passwd_fp;
char ∗getuser(uid)
uid_t uid;

DESCRIPTION

getaidname, getclass, getevent, getgroup, getmask, and getuser maintain caches of audit IDs, audit classes, audit events, groups, audit masks, and users for rapid retrieval.  Each of the functions maintains a separate LRU (Least Recently Used) cache.  The functions are intended for use by programs that need to look up many data values (e.g., users or groups) with a high degree of repetition.  They use lower-level routines to read the appropriate data files when necessary. 

getaidname takes an audit authentication ID and returns a pointer to an audit_id structure (defined in <audit_id.h>).  If the authentication ID is already in the cache, the structure associated with the authentication ID will be returned.  Otherwise, the audit ID file is searched for the authentication ID.  If the authentication ID is not found, the uname (user name) field of the audit_id structure will be set to the textual representation of the numerical authentication ID that was passed.  If the authentication ID is found in the file, the audit_id structure (including the uname member) will be loaded into the cache from the file. 

If the global variable audit_id_fp is set, that file will be searched instead of the default /var/security/audit_id. 

getclass takes an audit class ID and returns a pointer to an auclass structure (defined in <auclass.h>).  If the audit class ID is already in the cache, the structure associated with the class will be returned.  Otherwise, the audit class file is searched for the audit class ID.  If the audit class is not found, the ac_name (audit class name) field of the auclass structure will be set to the textual representation of the audit class ID.  If the audit class is found, ac_name will be loaded into the cache from the file.  In any case, the ac_desc (audit class description) field of the auclass structure is always set to NULL. 

If the global variable class_fp is set, that file will be searched instead of the default /var/security/auclass. 

getevent takes an audit event type ID and returns a pointer to an auevent structure (defined in <auevent.h>).  If the audit event type ID is already in the cache, the structure associated with the event type will be returned.  Otherwise, the audit event file is searched for the audit event type ID.  If the audit event type is not found, the ae_name (audit event name) field of the auevent structure will be set to the textual representation of the audit event type ID.  If the audit event type is found, ae_name will be loaded into the cache from the file.  In any case, ae_desc (audit event description) field of the auevent structure is always set to NULL. 

If the global variable event_fp is set, that file will be searched instead of the default /var/security/auevent. 

getgroup takes a group ID and returns a pointer to the group name.  If the group ID is already in the cache, the name associated with the group will be returned.  Otherwise, the group file is searched for the group ID.  If the group ID is not found, the return value will be the textual representation of the group ID.  If the group ID is found, the group name will be loaded into the cache from the file. 

If the global variable group_fp is set, that file will be searched instead of the default /etc/group. 

getmask takes a user name and returns a pointer to an aumask structure (defined in <aumask.h>).  If the user’s mask is already in the cache, the mask structure associated with the user will be returned.  Otherwise, the audit mask file is searched for the user’s audit mask.  If the audit mask is not found, a NULL pointer will be returned.  If the audit mask is found, the am_aumask field of the aumask structure will be loaded into the cache from the file. 

If the global variable mask_fp is set, that file will be searched instead of the default /var/security/aumask. 

getuser takes a user ID and returns a pointer to the user name.  If the user ID is already in the cache, the name associated with the user will be returned.  Otherwise, the password file is searched for the user ID.  If the user ID is not found, the return value will be the textual representation of the user ID.  If the user ID is found, the user name will be loaded into the cache from the file. 

If the global variable passwd_fp is set, that file will be searched instead of the default /etc/passwd. 

Because all of these functions deal with a limited size cache, any particular call could destroy the data associated with a previous call.  Thus, data returned by any of these functions should be copied before using the same function again. 

FILES

/var/security/audit_id Default audit authentication ID file

/var/security/auclass Default audit class file

/var/security/auevent Default audit event file

/var/security/aumask Default audit mask file

/etc/group Default group file

/etc/passwd Default password file

SEE ALSO

getacent(3A), getaeent(3A), getaident(3A), getament(3A), getgrent(3A),
auclass(4), audit_id(4), auevent(4), aumask(4)

DIAGNOSTICS

A NULL pointer is returned if memory cannot be allocated, or if the appropriate file cannot be opened, or if the audit mask could not be found or converted (getmask only). 

(Security Enhancement)