SATREADHEADERINFO(3C)                              SATREADHEADERINFO(3C)



NAME
     sat_read_header_info, sat_free_header_info - Portable interfaces to read
     audit record headers

SYNOPSIS
     #include <sat.h>

     int satreadheaderinfo (FILE *in, struct sathdrinfo int mask, int
          filemajor, int fileminor);

     void satfreeheaderinfo (struct sathdrinfo *header);

DESCRIPTION
     satreadheaderinfo reads an audit record header into a convenient
     struct for examining its contents (the disk format is neither convenient
     nor obvious).  Translation from older versions of audit files is handled
     transparently by the library routines.  The record header is read from
     file descriptor in and processed into the struct pointed to by header.
     The file_major, file_minor are the file version to translate from,
     obtained from the file header using the sat_read_file_info(3C) call.

     The sathdrinfo structure pointed to by header includes the following
     fields:

          int     satmagic;       /* sat header "magic number" */
          int     satrectype;     /* what type of record follows */
          int     satoutcome;     /* fail/success, due to dac/mac check */
          capvaluet satcap;    /* what capability affected the result */
          int     satsequence;    /* sequence # for this rec (by type) */
          int     saterrno;       /* system call error number */
          timet  sattime;        /* seconds since 1970 */
          int     satticks;       /* sub-second clock ticks (0-99) */
          int     satsyscall;     /* system call number */
          int     satsubsyscall;  /* system call "command" number */
          long    sathostid;     /* host id */
          uidt   satid;          /* SAT user-id */
          devt   sattty;         /* controlling tty, if present */
          pidt   satppid;        /* parent process id */
          pidt   satpid;         /* process id of record's generator */
          char    *satpname;      /* process name */
          maclabel *satplabel;   /* process label */
          capt   satpcap;       /* capability set */
          uidt   sateuid;        /* Effective user id */
          uidt   satruid;        /* Real user id */
          gidt   sategid;        /* Effective group id */
          gidt   satrgid;        /* Real group id */
          int     satngroups;     /* number of multi-group entries */
          gidt   *satgroups;     /* group list */
          char    *satcwd;        /* current working directory */
          char    *satrootdir;    /* current root directory */
          int     satrecsize;     /* bytes in the following record */
          int     sathdrsize;     /* no. of bytes in disk image of header */



                                                                        Page 1

SATREADHEADERINFO(3C)                              SATREADHEADERINFO(3C)



          char    *satbuffer;     /* buffer holding disk image of header */

     Due to the format that the record header is stored in on 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:

          SHI_NONE       Include none of the extra fields.

          SHI_GROUPS     Include the extended group list from the record
                         header.

          SHI_PLABEL     Include the process label from the record header.

          SHI_CWD        Include the current working directory from the record
                         header.

          SHI_ROOTDIR    Include the current root directory from the record
                         header.

          SHI_PNAME      Include the process name from the record header.

          SHI_BUFFER     Include the original disk image of the record header.

          SHI_ALL        Include everything.

     The process label is only available if sat_mac_enabled is set in the file
     header, otherwise this field will be NULL.  The current root directory
     (as changed by the chroot(2) command) may point to a null string.  If
     this is the case, '/' is intended.  If a field is not requested in the
     mask, the value in header will be NULL.  To specify combinations of the
     above masks, simply "or" them together, like so:

          (SHIGROUPS | SHICWD | SHIPNAME)

     Unlike the satreadfileinfo function, there is only one way to write
     out a record header.  That is to ask for the disk image using SHIBUFFER
     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 sathdrsize.  Be aware that there is also the record data following
     the record header, which must also be read and written to disk.  The size
     of the record body is found in the satrecsize field.  There are no
     library routines to read or interpret record bodies.

     satfreeheaderinfo is used to free any data that satreadheaderinfo
     allocated while constructing a sathdrinfo 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.






                                                                        Page 2

SATREADHEADERINFO(3C)                              SATREADHEADERINFO(3C)



DIAGNOSTICS
     satreadheaderinfo returns SHIOKAY on success or SHIERROR if any
     errors were detected.

SEE ALSO
     fopen(3S), fclose(3S), feof(3S), satreadfileinfo(3C),
     satwritefileinfo(3C), satfreefileinfo(3C), satintrppathname(3C).
















































                                                                        Page 3