Audit Trail API

Applies to: WG3.x

Editor's note: this chapter is new in the WG3 layer. It is from section 8 ("Audit Trail API") of the Developer's Addendum for Worldgroup 3.12 (wg312dev; the earlier 3.10 edition, devad3, is the same text apart from "3.10" for "3.12", BC5 for BC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. It extends the one-line audit() call of chapter 8 (Operator Services) into a file API.

OVERVIEW

The Major BBS Audit Trail is used to track system events. A chronological list of these events can by listed by the system operator. Each event consists of a time stamp, a channel or other context description, a brief description of the event, and a detailed description of the event. The Major BBS keeps all of these event records in a single file with a specific format. The Audit Trail API provides a standard mechanism for reading from and writing to the Major BBS Audit Trail, and for creating other audit trails.

File Format

The files managed by this API are binary/text files. They are treated by the API as binary files with fixed-length records, and referenced by record number. Internally, the files are formatted as fixed-length ASCII text files, so that they can be read by generic data file utilities.

Each record consists of a time stamp, brief description, channel, and detailed description, in that order. Each field is separated from the next by at least one ASCII space character (32 decimal). Fields that are not as long as their maximum length are padded on the right end with ASCII space characters. Each record is equivalent to one line in a text file, thus each record ends with a carriage return and line feed (DOS-format text file).

The fields in each record are as follows:

Field Offset Length Description
Time Stamp 0 15 The date and time at which the entry was added to the file. It consists of a sort format date string, followed by a space, followed by a sort format time string. For example, October 28, 1997 at 4:25:34 PM is represented by: "19971028 162534".
Short Desc. 16 32 A short description of the event; usually all upper case and the same for each similar event.
Channel 49 16 A description of the channel or other context in which the event occurred.
Detail 66 127 A detailed description of the event; usually mixed case and may contain event-specific information.
EOL 194 2 End of line marker ("\r\n").
Total: 196

Online Context

Some audit trail functions require an online context to operate properly. The following global variables are required for the online context: usrnum, nterms, errcod, channel[]. These variables determine what is stored in the channel field of an audit trail record. This is determined as follows:

1. If usrnum is set to one of the special channel identifiers, the following text is used for the channel:

usrnum Channel Text

AUDCHAN_CONSOLE Console

AUDCHAN_CLEANUP Cleanup

AUDCHAN_EVENT Event #

The event number is calculated by errcod-10.

2. If usrnum is in the range zero to nterms-1, the channel text is "Chan XX" where XX is the hexadecimal value of the channel number as displayed in the channel grid. This number is gotten from channel[usrnum].

3. If usrnum is outside the range zero to nterms-1, the channel text is "U# XXXX" where XXXX is the hexadecimal value of usrnum.

Example

Below is a code example that opens an audit trail file, adds a record, reads and displays the last ten records, and then closes the file.

#include "gcomm.h"
/* create online context required for audit trail */
INT usrnum;
INT errcod;
INT nterms=1;
INT channel[1]={0};
INT
main(VOID)
{
     HAUDFILE haud;                /* audit trail file handle              */
     INT rc;                       /* return from audit trail functions    */
     ULONG nRecs;                  /* total number of records in file      */
     ULONG iStart;                 /* record at which to start printing    */
     ULONG iRec;                   /* record index for printing            */
     struct audEntry recBuf;       /* buffer for reading audit trail       */
     INT year;                     /* year part of time stamp              */
     INT month;                    /* month part of time stamp             */
     INT day;                      /* day part of time stamp               */
     INT hour;                     /* hour part of time stamp              */
     INT minute;                   /* minute part of time stamp            */
     INT second;                   /* second part of time stamp            */
     CHAR dateBuf[sizeof("September 31, 1999")]; /* buf for date string    */
     CHAR timeBuf[sizeof("11:59:59 PM")]; /* buffer for time string        */
     /* open the audit trail file */
     rc=audfOpen(&haud,"myfile.adt",AUDMODE_READWRITE);
     /* check for error opening */
     if (rc < AUDERR_OK) {
          fprintf(stderr,"Error opening file: %d\n",rc);
          return(1);
     }
     /* check for damaged file */
     if (rc == AUDERR_DAMAGED) {
          /* attempt to recover */
          rc=audfRecover(haud);
          /* check for error in recovery */
          if (rc < AUDERR_OK) {
               audfClose(haud);
               fprintf(stderr,"Error recovering file: %d\n",rc);
               return(1);
          }
     }
     /* prepare online context (for Console) */
     usrnum=AUDCHAN_CONSOLE;
     errcod=0;
     /* add a record */
     rc=audfAddEntry(haud
                    ,"AUDIT TRAIL TEST"
                    ,"Testing the new Audit Trail API");
     /* check for error */
     if (rc < AUDERR_OK) {
          audfClose(haud);
          fprintf(stderr,"Error writing to file: %d\n",rc);
          return(1);
     }
     /* print the last ten entries */
     nRecs=audfNumRecs(haud);
     if (nRecs < 10) {
          iStart=0;
     }
     else {
          iStart=nRecs-10;
     }
     for (iRec=iStart ; iRec < nRecs ; ++iRec) {
          /* read the current entry */
          rc=audfReadEntry(haud,iRec,&recBuf,sizeof(recBuf));
          /* check for error */
          if (rc < AUDERR_OK) {
               audfClose(haud);
               fprintf(stderr,"Error reading from file: %d\n",rc);
               return(1);
          }
          /* decode the time stamp */
          sDecodeDT(recBuf.stamp,&year,&month,&day,&hour,&minute,&second);
          prnDate(year,month,day,dateBuf,sizeof(dateBuf),PRND_MMMDYY,'\0');
          prnTime(hour,minute,second,timeBuf,sizeof(timeBuf),PRNT_HMS_PMC);
          /* print the entry */
          fprintf(stdout,"Entry #%lu\n",iRec);
          fprintf(stdout,"Time Stamp:   %s  %s\n",dateBuf,timeBuf);
          fprintf(stdout,"Channel:      %s\n",recBuf.channel);
          fprintf(stdout,"Description:  %s\n",recBuf.brief);
          fprintf(stdout,"Details:      %s\n",recBuf.detail);
          fprintf(stdout,"\n");
     }
     /* close and exit */
     audfClose(haud);
     return(0);
}

Result Codes

Most Audit Trail API functions return a code that describes the result of the operation. In general, a negative code indicates failure while a zero or positive code indicates success. The following is a list of all

of the result codes that may be returned by Audit Trail API functions.

Identifier Value Description
AUDERR_OK 0 The operation completed successfully.
AUDERR_NEW 1 When opening a file, the specified file was not found, so a new file was created.
AUDERR_DAMAGED 2 When opening a file, it was found to have been damaged, so you must recover the file before proceeding.
AUDERR_FIO -1 An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_MEMORY -2 There was not enough memory to complete the requested operation.
AUDERR_NOTOPEN -3 The file is not open, you must close and re-open it before you can use it.
AUDERR_MODE -4 The requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).
AUDERR_NOTFOUND -5 The requested record was not found (the record number was out of range).

Structures

The following is a list of structures defined by the Audit Trail API.

struct audEntry {                  /* audit trail record format            */
     CHAR stamp[AUDSTAMPSIZ];      /*   time stamp ("YYYYMMDD HHMMSS")     */
     CHAR brief[AUDBRIEFSIZ];      /*   brief description                  */
     CHAR channel[AUDCHANSIZ];     /*   channel/console/event/cleanup      */
     CHAR detail[AUDDETSIZ];       /*   detailed description               */
};
#define AUDSTAMPSIZ sizeof("YYYYMMDD HHMMSS")
#define AUDBRIEFSIZ (32+1)
#define AUDCHANSIZ  (16+1)
#define AUDDETSIZ   128

This is the standard structure for reading and writing audit trail records. The fields have the following uses:

stamp: The time and date stamp that describes when the record was added. It is stored in sort date and time format with the date first and a space between the date part and the time part.

brief: A brief description of the event. It is the same for each event of the same type (e.g., "SMTP MAIL RECEIVED").

channel: The channel or event which caused the event. This field usually contains one of the following:

Text Meaning
Chan XX The specified channel was being serviced when the event occurred. XX is the channel number in hexadecimal as seen in the channel grid.
U# XXXX The specified user number was in effect when the event occurred. XXXX is the user number in hexadecimal as represented by the global usrnum. This channel type is used when usrnum is outside the range of defined channels.
Console The event was generated by the Major BBS console or by a background task. This channel type is used when usrnum is equal to AUDCHAN_CONSOLE (-1)
Cleanup The event was generated during cleanup. This channel type is used when usrnum is equal to AUDCHAN_CLEANUP (-2).
Event # The event was generated while shutting down to perform a scheduled event. # is the event number in decimal. This channel type is used when usrnum is equal to AUDCHAN_EVENT (-3).

detail: Details on the event. This field may contain information specific to the particular event (e.g., "SMTP MAIL RECEIVED", "From: user@company.com To: Local User"). If the information to be placed in this field exceeded the maximum length, the last character before the terminating nul character will be an asterisk ('*').

struct audOldStyle {               /* old-style audit trail record format  */
     CHAR stamp[AUDOLDSTAMPSIZ];   /*   time stamp (not nul-terminated)    */
     CHAR brief[AUDOLDBRIEFSIZ];   /*   brief description (32 chars + sp)  */
     CHAR channel[AUDOLDCHANSIZ];  /*   chan/console/event (nul-terminated)*/
     CHAR unused[12];              /*   unused space (filled with nuls)    */
     CHAR detail[AUDOLDDETSIZ];    /*   long desc (63 chars + 2 nuls)      */
};
#define AUDOLDSTAMPSIZ   14
#define AUDOLDBRIEFSIZ   33
#define AUDOLDCHANSIZ    8
#define AUDOLDDETSIZ     65

This is a formalized representation of the pre-Worldgroup 3.12 Audit Trail record format. It is defined so that the API can provide backward compatibility with add-ons that read from the Audit Trail. In general,

add-ons that use the old format should continue to use the known offsets into a character buffer approach to extracting fields from old-style records rather than using this structure directly.

Functions

The following is an alphabetical list of all functions provided by the Audit Trail API.

audAddEntry()

Applies to: WG3.x

Header check: the function is audfAddEntry() (AUDAPI.h:92); the prototype printed below already shows that name.

INT                                /*   returns result code                */
audfAddEntry(                      /* add an entry to audit trail file     */
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *brief,                 /*   brief description                  */
const CHAR *detail,                /*   detailed description/format string */
...);                              /*   arguments to be formatted          */

Adds a record to an audit trail file, with variable arguments. It requires an online context as discussed above.

haud

The file to which to add the record. This handle must have been gotten from a successful call to audfOpen(). The file must have been opened with the mode AUDMODE_READWRITE.

brief

A brief description of the event. This is the same for each event of the same type. It will be truncated at AUDBRIEFSIZ-1 (32) characters.

detail

Details on the event. This is a printf()-style format string which can be used to record event-specific information. It will be truncated at AUDDETSIZ-1 (127) characters. If it is truncated, the last character before the terminating nul character will be an asterisk ('*').

Returns:

A code describing the result of the operation. It may be one of the following:

AUDERR_OK The operation completed successfully.
AUDERR_NEW The file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGED The file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.)
AUDERR_FIO An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_MODE The requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).

audAddLowLevel()

Applies to: WG3.x

Header check: the function is audfAddLowLevel() (AUDAPI.h:174).

INT                                /*   returns result code                */
audfAddLowLevel(                   /* low-level add entry                  */
HAUDFILE haud,                     /*   audit trail file to use            */
struct audEntry *src,              /*   formatted record to add            */
size_t srcSiz);                    /*   size of source buffer              */

Adds an already-formatted entry to an audit trail file.

haud

The file to which to add the record. This handle must have been gotten from a successful call to audfOpen(). The file must have been opened with the mode AUDMODE_READWRITE.

src

The record to add to the file. It must already have all fields filled in with valid quantities.

srcSiz

The size of the record to add. It should always be sizeof(struct audEntry).

Returns:

A code describing the result of the operation. It may be one of the following:

AUDERR_OK The operation completed successfully.
AUDERR_NEW The file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGED The file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.)
AUDERR_FIO An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_MODE The requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).

audAddfChannelStr ()

Applies to: WG3.x

Header check: the function is audfChannelStr() (AUDAPI.h:140); audAddfChannelStr appears nowhere in WGDEV/INC.

CHAR *                             /*   returns pointer to buffer          */
audfChannelStr(                    /* generate channel description string  */
CHAR *buf,                         /*   buffer (must be AUDCHANSIZ long)   */
size_t bufSiz);                    /*   size of buffer                     */
                                   /*   (implicit inputs: usrnum, nterms,  */
                                   /*    channel[], errcod)                */

Create a channel description string based on the current online context.

buf

The buffer to receive the channel description string. It should be at least AUDCHANSIZ (17) in size.

bufSiz

The actual size of the buf argument.

Returns:

A pointer to the buf argument.

audfclose()

Applies to: WG3.x

Header check: C identifiers are case-sensitive: the function is audfClose() (AUDAPI.h:80).

VOID
audfClose(                         /* close an audit trail file            */
HAUDFILE haud);                    /*   handle to close                    */

Closes an audit trail file. The handle is no longer valid once this function has been called.

haud

The handle of the file to close. This handle must have been gotten from a successful call to audfOpen().

audfCvtEntryToOld()

struct audOldStyle *               /*   returns pointer to buffer          */
audfCvtEntryToOld(                 /* convert an entry to old-style        */
const struct audEntry *src,        /*   new-style audit trail entry        */
struct audOldStyle *buf,           /*   buffer to receive converted entry  */
size_t bufSiz);                    /*   size of destination buffer         */

Converts a new (Worldgroup 3.12) audit trail entry to the old (Worldgroup 3.0 and earlier) format.

src

The buffer containing the new-style audit trail record.

buf

The buffer to receive the old-style audit trail record. Since the old Audit Trail typically used a simple character buffer to hold records, you can use a character buffer and typecast it when passing it to this function.

bufSiz

The actual size of the buffer to receive the old-style audit trail record. This should be at least AUDSIZ (132).

Returns:

A pointer to the buf argument.

audfCvtRawToEntry ()

struct audEntry *                  /*   returns pointer to buffer          */
audfCvtRawToEntry(                 /* convert raw file data to entry       */
const CHAR *src,                   /*   raw file data                      */
struct audEntry *buf,              /*   buffer to receive converted entry  */
size_t bufSiz);                    /*   size of destination buffer         */

Converts raw audit trail file data to an audit trail entry structure.

src

The raw data, directly from an audit trail data file. This should be the entire line, including space padding, and the carriage return and line feed at the end. (See above for details on the file format.)

buf

The buffer to receive the converted entry.

bufSiz

The actual size of the buf argument. It should always be sizeof(struct audEntry).

Returns:

A pointer to the buf argument.

audfFindEntryDOS()

INT                                /*   returns result code                */
audfFindEntryDOS(                  /* find an entry by DOS date and time   */
HAUDFILE haud,                     /*   audit trail file to use            */
USHORT dosDate,                    /*   DOS-style date to search for       */
USHORT dosTime,                    /*   DOS-style time to search for       */
ULONG *pRecNum,                    /*   buf for rec # (NULL if don't want) */
struct audEntry *buf,              /*   buf for entry (NULL if don't want) */
size_t bufSiz);                    /*   size of destination buffer         */

Finds a specific audit trail record given a time and date stamp in DOS packed format. If an exact match is not found, the next highest record will be returned. If the target time is greater than the last record in the file, the last record will be returned. If there is more than one record with the same time stamp, the first one will be returned.

haud

The handle of the file to read from. This handle must have been gotten from a successful call to audfOpen().

dosDate

The date portion of the time stamp to search for, in DOS packed format.

dosTime

The time portion of the time stamp to search for, in DOS packed format.

pRecNum

Pointer to the buffer to receive the record number of the record when found. This argument should be NULL if you do not want to know the record number.

buf

The buffer to receive the record when found. This argument should be NULL if you do not want to read the actual record.

bufSiz

The actual size of the buf argument. It should always be sizeof(struct audEntry).

Returns:

A code describing the result of the operation. It may be one of the following:

AUDERR_OK The operation completed successfully.
AUDERR_FIO An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUND The file is empty.

audfFindEntryStr()

INT                                /*   returns result code                */
audfFindEntryStr(                  /* find an entry by string date & time  */
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *strDate,               /*   YYYYMMDD date to search for        */
const CHAR *strTime,               /*   HHMMSS time to search for          */
ULONG *pRecNum,                    /*   buf for rec # (NULL if don't want) */
struct audEntry *buf,              /*   buf for entry (NULL if don't want) */
size_t bufSiz);                    /*   size of destination buffer         */

Finds a specific audit trail record given a time and date stamp in DOS packed format. If an exact match is not found, the next highest record will be returned. If the target time is greater than the last record in the file, the last record will be returned. If there is more than one record with the same time stamp, the first one will be returned.

haud

A handle to the Audit Trail file. This handle must have been gotten from a successful call to audfOpen().

strDate

The date portion of the time stamp to search for, in sort format.

strTime

The time portion of the time stamp to search for, in sort format.

pRecNum

Pointer to the buffer to receive the record number of the record when found. This argument should be NULL if you do not want to know the record number.

buf

The buffer to receive the record when found. This argument should be NULL if you do not want to read the actual record.

**
bufSiz**

The actual size of the buf argument. It should always be sizeof(struct audEntry).

Returns:

A code describing the result of the operation. It may be one of the following:

AUDERR_OK The operation completed successfully.
AUDERR_FIO An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUND The file is empty.

audfFormatEntry ()

struct audEntry *                  /*   returns pointer to destination     */
audfFormatEntry(                   /* create properly-formatted entry      */
struct audEntry *buf,              /*   buffer to receive entry            */
size_t bufSiz,                     /*   size of destination buffer         */
const CHAR *brief,                 /*   brief description                  */
const CHAR *chanStr,               /*   channel description string         */
const CHAR *detail,                /*   detailed description/format string */
va_list argList);                  /*   argument list                      */

Creates a properly-formatted audit trail record given its component parts.

buf

The buffer to receive the formatted record.

bufSiz

The actual size of the buf argument. It should always be sizeof(struct audEntry).

brief

The string to be used for the brief description. This is the same for each event of the same type. It will be truncated at AUDBRIEFSIZ-1 (32) characters.

chanStr

The string to be used for the channel description.

detail

A printf()-style format string which will be used to create the detailed description of the event. This field can be used to record event-specific information. It will be truncated at AUDDETSIZ-1 (127) characters. If it is truncated, the last character before the terminating nul character will be an asterisk ('*').

argList

A variable argument list created using the va_start() macro. This list along with the detail argument is used to create the detail field of the formatted record.

Returns:

A pointer to the buf argument.

audfNumRecs ()

ULONG
audfNumRecs(                       /* get number of records in file        */
HAUDFILE haud);                    /*   audit trail file to use            */

Gets the number of records in an audit trail file.

haud

A handle to the Audit Trail file. This handle must have been gotten from a successful call to audfOpen().

Returns:

The number of records in the file.

audfOpen()

INT                                /*   returns result code                */
audfOpen(                          /* open an audit trail file             */
HAUDFILE *phaud,                   /*   buffer to receive opened handle    */
const CHAR *fileName,              /*   name of file to open               */
AUDMODE mode);                     /*   mode in which to open              */

Opens an audit trail file. The file may be opened in one of the following modes:

AUDMODE_READONLY Open with read-only access to the file.

Applies to: WG3.x

Header check: AUDMODE_READONLY and AUDMODE_READWRITE are enumerators (AUDAPI.h:35-38), not #defines, so #ifdef AUDMODE_READONLY will not work.

AUDMODE_READWRITE Open with read and write access to the file.

If the file does not exist and you specify read-only mode, the function will return an I/O error response. If the file does not exist and you specify read/write mode, the file will be created and the function will return a file-created response.

If the file has been damaged, it will still be opened, but the function will return a file-damaged response. In this case, you must recover the file before you will be able to read from it.

phaud

Pointer to the buffer to receive a handle to the opened file.

fileName

The complete path and file name of the file to open.

mode

The mode in which to open the file. This must be either AUDMODE_READONLY or AUDMODE_READWRITE.

Returns:

AUDERR_OK The operation completed successfully.
AUDERR_NEW The specified file was not found, so a new file was created.
AUDERR_DAMAGED The file is damaged. You must recover the file before proceeding.
AUDERR_FIO An I/O error occurred while performing an operation; check the global variable errno for the specific error. This response will be returned if you try to open a non-existent file in read-only mode.
AUDERR_MEMORY There was not enough memory to open the file.

audfReadEntry()

INT                                /*   returns result code                */
audfReadEntry(                     /* read an entry by record number       */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audEntry *buf,              /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

Reads a record from an audit trail file.

haud

A handle of the Audit Trail file. This handle must have been gotten from a successful call to audfOpen().

recNum

The record number to read. This must be between zero and one less than the total number of records in the file.

buf

The buffer to receive the record.

bufSiz

The actual size of the buf argument. It should always be sizeof(struct audEntry).

Returns:

AUDERR_OK The record was read successfully.
AUDERR_FIO An I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUND The requested record was not found (the record number was out of range).

audfReadLowLevel()

INT                                /*   returns result code                */
audfReadLowLevel(                  /* low-level read an entry utility      */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
CHAR *buf,                         /*   buffer (must be AUDRECLEN+1 long)  */
size_t bufSiz);                    /*   size of buffer                     */

Reads a raw data record from an audit trail file but does not convert it into the standard entry structure. The raw data can be converted into an entry structure using audfCvtRawToEntry().

haud

A handle to the Audit Trail file. This handle must have been gotten from a successful call to audfOpen().

recNum

The record number to read. This must be between zero and one less than the total number of records in the file.

buf

The buffer to receive the raw data, directly from the audit trail data file. This will be the entire line, including space padding, and the carriage return and line feed at the end. (See above for details on the file format.) This buffer should be at least AUDRECLEN+1 (195) in size.

bufSiz

The actual size of the buf argument.

Returns:

AUDERR_OK The record was read successfully.
AUDERR_FIO An I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUND The requested record was not found (the record number was out of range).

audfReadOldStyle()

INT                                /*   returns result code                */
audfReadOldStyle(                  /* read an old-style entry              */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audOldStyle *buf,           /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

Reads a record from an audit trail file and converts to the old style (pre-Worldgroup 3.1).

haud

A handle to the Audit Trail file. This handle must have been gotten from a successful call to audfOpen().

recNum

The record number to read. This must be between zero and one less than the total number of records in the file.

buf

The buffer to receive the old-style audit trail record. Since the old Audit Trail typically used a simple character buffer to hold records, you can use a character buffer and typecast it when passing it to this function.

bufSiz

The actual size of the buffer to receive the old-style audit trail record. This should be at least AUDSIZ (132).

Returns:

AUDERR_OK The record was read successfully.
AUDERR_FIO An I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUND The requested record was not found (the record number was out of range).

audfRecover()

INT                                /*   returns result code                */
audfRecover(                       /* recover a damaged audit trail file   */
HAUDFILE haud);                    /*   handle to file to recover          */

Recovers a damaged audit trail file.

haud

The handle of the file to recover. This handle must have been gotten from a call to audfOpen() that returned AUDERR_DAMAGED.

Returns:

AUDERR_OK The operation completed successfully.
AUDERR_NEW The specified file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGED The file is still damaged. (This code will not be returned under normal conditions.)
AUDERR_FIO An I/O error occurred while recovering the file; check the global variable errno for the specific error.

audfVAddEntry()

INT                                /*   returns result code                */
audfVAddEntry(                     /* add entry with variable argument list*/
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *brief,                 /*   brief description                  */
const CHAR *detail,                /*   detailed description/format string */
va_list argList);                  /*   argument list                      */

Adds a record to an audit trail file; does not take variable arguments. It requires an online context as discussed above.

haud

The file to which to add the record. This handle must have been gotten from a successful call to audfOpen(). The file must have been opened with the mode AUDMODE_READWRITE.

brief

A brief description of the event. This is the same for each event of the same type. It will be truncated at AUDBRIEFSIZ-1 (32) characters.

detail

Details on the event. This is a printf()-style format string which can be used to record event-specific information. It will be truncated at AUDDETSIZ-1 (127) characters. If it is truncated, the last character before the terminating nul character will be an asterisk ('*').

argList

A variable argument list created using the va_start() macro. This list along with the detail argument is used to create the detail field of the formatted record.

Returns:

A code describing the result of the operation. It may be one of the following:

AUDERR_OK The operation completed successfully.
AUDERR_NEW The file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGED The file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.)
AUDERR_FIO An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPEN The file is not open, you must close and reopen it before you can use it.
AUDERR_MODE The requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).

Previous: Major BBS v10: 25 Searchable Memory Blocks  |  Contents  |  Next: Major BBS v10: 27 Date and Time API

  • No labels