SATREADFILEINFO(3C)                                  SATREADFILEINFO(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 satreadfileinfo (FILE *in, FILE *out, struct satfileinfo
          *fheader, int mask);

     int satwritefileinfo (FILE *out, struct satfileinfo *fheader);

     void satfreefileinfo (struct satfileinfo *fheader);

DESCRIPTION
     satreadfileinfo 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 satfileinfo structure pointed to by fheader includes the following
     fields:

          int     satmajor;          /* version of audit data */
          int     satminor;
          timet  satstarttime;     /* time header written */
          timet  satstoptime;      /* time file closed */
          long    sathostid;        /* host id */
          int     satmacenabled;    /* boolean: ignore mac fields? */
          char    *sattimezone;      /* "TZ=(timezone)" */
          char    *sathostname;      /* hostname */
          char    *satdomainname;    /* domainname */
          int     satfhdrsize;       /* no. of bytes in disk image */
          char    *satbuffer;        /* buffer w/disk image of header */
          int     satuserentries;   /* number of satlistent structs */
          int     satgroupentries;  /* in the user, group, and */
          int     sathostentries;   /* the hostid <-> name list */
          struct satlistent **satusers;    /* user entries */
          struct satlistent **satgroups;   /* group entries */
          struct satlistent **sathosts;    /* 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

SATREADFILEINFO(3C)                                  SATREADFILEINFO(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:

          (SFITIMEZONE | SFIHOSTNAME | SFIDOMNAME)

     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
     satreadfileinfo call.  If output is not required, use NULL for this
     value.  The second method is to ask for the disk image using SFIBUFFER
     in the mask.  When output is desired, use fwrite(3C) to write the
     contents of satbuffer to disk.  The length of the data in satbuffer is
     in satfhdrsize.  The third method is to call satwritefileinfo, which
     is more computationally expensive, and can only be used for the most
     current file version.  Calling satwritefileinfo is only advisable if
     some data in the header has been changed.

     satfreefileinfo is used to free any data that satreadfileinfo
     allocated while constructing a satfileinfo 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
     satreadfileinfo returns SFIOKAY on success, SFIWARNING if there was
     no file header to be read, or SFIERROR if any errors were detected.

     satwritefileinfo returns SFIOKAY on success, or SFIERROR if any
     errors were detected.




                                                                        Page 2

SATREADFILEINFO(3C)                                  SATREADFILEINFO(3C)



     Error messages are also written to stderr.  If an error occurrs, it may
     be useful to check feof(3S) and ferror(3S) on the file descriptors for
     further diagnostics.

NOTE
     If out is specified to satreadfileinfo, 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 satwritefileinfo.

SEE ALSO
     fopen(3S), fclose(3S), feof(3S), satreadheaderinfo(3C),
     satfreeheaderinfo(3C), satintrppathname(3C).










































                                                                        Page 3