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);

DESCRIPTION
     sat_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.

          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.

DIAGNOSTICS
     sat_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.
     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 ALSO
     fopen(3S), fclose(3S), feof(3S), sat_read_header_info(3C),
     sat_free_header_info(3C), sat_intrp_pathname(3C).