SAT_READ_FILE_INFO(3C)SAT_READ_FILE_INFO(3C)NAME
sat_read_file_info, sat_write_file_info, sat_free_file_info - Portable
interfaces to read audit file headers
SYNOPSIS
#include <sat.h>
int sat_read_file_info (FILE *in, FILE *out, struct sat_file_info
*fheader, int mask);
int sat_write_file_info (FILE *out, struct sat_file_info *fheader);
void sat_free_file_info (struct sat_file_info *fheader);
DESCRIPTIONsat_read_file_info reads an audit file header into a convenient struct
for examining its contents. Translation from older versions of audit
files is handled transparently by the library routines. The file header
is read from file descriptor in and processed into the fheader struct.
If out is non-NULL, the data read from in is written back to out. The
data written is the disk image, not a processed struct.
The sat_file_info structure pointed to by fheader includes the following
fields:
int sat_major; /* version of audit data */
int sat_minor;
time_t sat_start_time; /* time header written */
time_t sat_stop_time; /* time file closed */
long sat_host_id; /* host id */
int sat_mac_enabled; /* boolean: ignore mac fields? */
char *sat_timezone; /* "TZ=(timezone)" */
char *sat_hostname; /* hostname */
char *sat_domainname; /* domainname */
int sat_fhdrsize; /* no. of bytes in disk image */
char *sat_buffer; /* buffer w/disk image of header */
int sat_user_entries; /* number of sat_list_ent structs */
int sat_group_entries; /* in the user, group, and */
int sat_host_entries; /* the hostid <-> name list */
struct sat_list_ent **sat_users; /* user entries */
struct sat_list_ent **sat_groups; /* group entries */
struct sat_list_ent **sat_hosts; /* hostid entries */
Due to the format that the file header is read from disk, several fields
in the file header require extra computation and memory. To allow the
user to select only the fields they are interested in, there is a mask
which specifies which fields to include. These are:
SFI_NONE Include none of the extra fields.
Page 1
SAT_READ_FILE_INFO(3C)SAT_READ_FILE_INFO(3C)
SFI_TIMEZONE Include sat_timezone from the file header.
SFI_HOSTNAME Include sat_hostname from the file header.
SFI_DOMNAME Include sat_domainname from the file header.
SFI_USERS Include an array of sat_list_ent structs containing
user name <-> user id mappings.
SFI_GROUPS Above, for group name <-> group id mappings.
SFI_HOSTS Above, for host name <-> host id mappings.
SFI_BUFFER Include the original disk image of the file header.
SFI_ALL Include everything.
Note that the timezone field has TZ= prepended to make a call to
putenv(3C). If this is not the intended use of the string, remember to
account for the extra three characters.
The user and group lists in particular require a fair amount of
computation and memory allocation to provide. If a field is not
requested in the mask, the value in fheader will be NULL. To specify
combinations of the above masks, simply "or" them together, like so:
(SFI_TIMEZONE | SFI_HOSTNAME | SFI_DOMNAME)
There are three ways to write out a file header that has been read in.
The first and easiest is to specify a file descriptor out in the
sat_read_file_info call. If output is not required, use NULL for this
value. The second method is to ask for the disk image using SFI_BUFFER
in the mask. When output is desired, use fwrite(3C) to write the
contents of sat_buffer to disk. The length of the data in sat_buffer is
in sat_fhdrsize. The third method is to call sat_write_file_info, which
is more computationally expensive, and can only be used for the most
current file version. Calling sat_write_file_info is only advisable if
some data in the header has been changed.
sat_free_file_info is used to free any data that sat_read_file_info
allocated while constructing a sat_file_info struct. It does not free
the struct itself, only certain fields within the struct. To make sure
the struct isn't used afterwards, it is zeroed after all the fields are
freed.
DIAGNOSTICSsat_read_file_info returns SFI_OKAY on success, SFI_WARNING if there was
no file header to be read, or SFI_ERROR if any errors were detected.
sat_write_file_info returns SFI_OKAY on success, or SFI_ERROR if any
errors were detected.
Page 2
SAT_READ_FILE_INFO(3C)SAT_READ_FILE_INFO(3C)
Error messages are also written to stderr. If an error occurs, it may be
useful to check feof(3S) and ferror(3S) on the file descriptors for
further diagnostics.
NOTE
If out is specified to sat_read_file_info, no checks are done on the
write performed. It is recommended that the user check ferror(3S) on the
file descriptor to make sure it was written successfully. Output error
checking is performed for sat_write_file_info.
SEE ALSOfopen(3S), fclose(3S), feof(3S), sat_read_header_info(3C),
sat_free_header_info(3C), sat_intrp_pathname(3C).
Page 3
