sat_read_header_info(3C)

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

SYNOPSIS
     #include <sat.h>

     int sat_read_header_info (FILE *in, struct sat_hdr_info int mask, int
          file_major, int file_minor);

     void sat_free_header_info (struct sat_hdr_info *header);

DESCRIPTION
     sat_read_header_info 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 sat_hdr_info structure pointed to by header includes the following
     fields:

          int     sat_magic;       /* sat header "magic number" */
          int     sat_rectype;     /* what type of record follows */
          int     sat_outcome;     /* fail/success, due to dac/mac check */
          cap_value_t sat_cap;    /* what capability affected the result */
          int     sat_sequence;    /* sequence # for this rec (by type) */
          int     sat_errno;       /* system call error number */
          time_t  sat_time;        /* seconds since 1970 */
          int     sat_ticks;       /* sub-second clock ticks (0-99) */
          int     sat_syscall;     /* system call number */
          int     sat_subsyscall;  /* system call "command" number */
          long    sat_host_id;     /* host id */
          uid_t   sat_id;          /* SAT user-id */
          dev_t   sat_tty;         /* controlling tty, if present */
          pid_t   sat_ppid;        /* parent process id */
          pid_t   sat_pid;         /* process id of record's generator */
          char    *sat_pname;      /* process name */
          mac_label *sat_plabel;   /* process label */
          cap_t   sat_pcap;       /* capability set */
          uid_t   sat_euid;        /* Effective user id */
          uid_t   sat_ruid;        /* Real user id */
          gid_t   sat_egid;        /* Effective group id */
          gid_t   sat_rgid;        /* Real group id */
          int     sat_ngroups;     /* number of multi-group entries */
          gid_t   *sat_groups;     /* group list */
          char    *sat_cwd;        /* current working directory */
          char    *sat_rootdir;    /* current root directory */
          int     sat_recsize;     /* bytes in the following record */
          int     sat_hdrsize;     /* no. of bytes in disk image of header */
          char    *sat_buffer;     /* 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:

          (SHI_GROUPS | SHI_CWD | SHI_PNAME)

     Unlike the sat_read_file_info function, there is only one way to write
     out a record header.  That is to ask for the disk image using SHI_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_hdrsize.  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 sat_recsize field.  There are no
     library routines to read or interpret record bodies.

     sat_free_header_info is used to free any data that sat_read_header_info
     allocated while constructing a sat_hdr_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_header_info returns SHI_OKAY on success or SHI_ERROR if any
     errors were detected.

SEE ALSO
     fopen(3S), fclose(3S), feof(3S), sat_read_file_info(3C),
     sat_write_file_info(3C), sat_free_file_info(3C), sat_intrp_pathname(3C).