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",BC5forBC50, 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-lineaudit()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.
| Code Block |
|---|
#include "gcomm.h" |
| Code Block |
|---|
/* create online context required for audit trail */
INT usrnum;
INT errcod;
INT nterms=1;
INT channel[1]={0}; |
| Code Block |
|---|
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 */ |
| Code Block |
|---|
/* open the audit trail file */
rc=audfOpen(&haud,"myfile.adt",AUDMODE_READWRITE); |
| Code Block |
|---|
/* check for error opening */
if (rc < AUDERR_OK) {
fprintf(stderr,"Error opening file: %d\n",rc);
return(1);
} |
| Code Block |
|---|
/* check for damaged file */
if (rc == AUDERR_DAMAGED) { |
| Code Block |
|---|
/* attempt to recover */
rc=audfRecover(haud); |
| Code Block |
|---|
/* check for error in recovery */
if (rc < AUDERR_OK) {
audfClose(haud);
fprintf(stderr,"Error recovering file: %d\n",rc);
return(1);
}
} |
| Code Block |
|---|
/* prepare online context (for Console) */
usrnum=AUDCHAN_CONSOLE;
errcod=0; |
| Code Block |
|---|
/* add a record */
rc=audfAddEntry(haud
,"AUDIT TRAIL TEST"
,"Testing the new Audit Trail API"); |
| Code Block |
|---|
/* check for error */
if (rc < AUDERR_OK) {
audfClose(haud);
fprintf(stderr,"Error writing to file: %d\n",rc);
return(1);
} |
| Code Block |
|---|
/* print the last ten entries */
nRecs=audfNumRecs(haud);
if (nRecs < 10) {
iStart=0;
}
else {
iStart=nRecs-10;
}
for (iRec=iStart ; iRec < nRecs ; ++iRec) { |
| Code Block |
|---|
/* read the current entry */
rc=audfReadEntry(haud,iRec,&recBuf,sizeof(recBuf)); |
| Code Block |
|---|
/* check for error */
if (rc < AUDERR_OK) {
audfClose(haud);
fprintf(stderr,"Error reading from file: %d\n",rc);
return(1);
} |
| Code Block |
|---|
/* 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); |
| Code Block |
|---|
/* 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");
} |
| Code Block |
|---|
/* 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.
| Code Block |
|---|
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 */
}; |
| Code Block |
|---|
#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 ('*').
| Code Block |
|---|
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) */
}; |
| Code Block |
|---|
#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.
| Code Block |
|---|
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).
| Code Block |
|---|
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);audAddfChannelStrappears nowhere inWGDEV/INC.
| Code Block |
|---|
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).
| Code Block |
|---|
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()
| Code Block |
|---|
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 ()
| Code Block |
|---|
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()
| Code Block |
|---|
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()
| Code Block |
|---|
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 ()
| Code Block |
|---|
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 ()
| Code Block |
|---|
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()
| Code Block |
|---|
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_READONLYandAUDMODE_READWRITEare enumerators (AUDAPI.h:35-38), not#defines, so#ifdef AUDMODE_READONLYwill 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()
| Code Block |
|---|
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()
| Code Block |
|---|
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()
| Code Block |
|---|
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()
| Code Block |
|---|
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()
| Code Block |
|---|
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