audctl(2) System Calls Manual audctl(2)
NAME
audctl() - start or halt the auditing system and set or get audit files
SYNOPSIS
Remarks
This function is provided purely for backward compatibility. HP recommends that new applications use the command to configure the auditing
system. See audsys(1M).
DESCRIPTION
sets or gets the auditing system "current" and "next" audit files, and starts or halts the auditing system. This call is restricted to
processes with the privilege. cpath and npath hold the absolute path names of the "current" and "next" files. mode specifies the audit
file's permission bits. cmd is one of the following specifications:
The caller issues the
command with the required "current" and "next" files to turn on the auditing system. If the auditing system is cur-
rently off, it is turned on; the file specified by the cpath parameter is used as the "current" audit file, and the
file specified by the npath parameter is used as the "next" audit file. If the audit files do not already exist,
they are created with the mode specified. The auditing system then begins writing to the specified "current" file.
An empty string or NULL npath can be specified if the caller wants to designate that no "next" file be available to
the auditing system. If the auditing system is already on, no action is performed; is returned and is set to
The caller issues the
command to retrieve the names of the "current" and "next" audit files. If the auditing system is on, the names of
the "current" and "next" audit files are returned via the cpath and npath parameters (which must point to character
buffers of sufficient size to hold the file names). mode is ignored. If the auditing system is on and there is no
available "next" file, the "current" audit file name is returned via the cpath parameter, npath is set to an empty
string; is returned, and is set to If the auditing system is off, no action is performed; is returned and is set to
The caller issues the
command to change both the "current" and "next" files. If the audit system is on, the file specified by cpath is
used as the "current" audit file, and the file specified by npath is used as the "next" audit file. If the audit
files do not already exist, they are created with the specified mode. The auditing system begins writing to the
specified "current" file. Either an empty string or NULL npath can be specified if the caller wants to designate
that no "next" file be available to the auditing system. If the auditing system is off, no action is performed; is
returned and is set to
The caller issues the
command to change only the "current" audit file. If the audit system is on, the file specified by cpath is used as
the "current" audit file. If the specified "current" audit file does not exist, it is created with the specified
mode. npath is ignored. The auditing system begins writing to the specified "current" file. If the audit system is
off, no action is performed; is returned and is set to
The caller issues the
command to change only the "next" audit file. If the auditing system is on, the file specified by npath is used as
the "next" audit file. cpath is ignored. If the "next" audit file specified does not exist, it is created with the
specified mode. Either an empty string or npath can be specified if the caller wants to designate that no "next"
file be available to the auditing system. If the auditing system is off, no action is performed; is returned, and is
set to
The caller issues the
command to cause the auditing system to switch audit files. If the auditing system is on, it uses the "next" file as
the new "current" audit file and sets the new "next" audit file to cpath, npath,and mode are ignored. The auditing
system begins writing to the new "current" file. If the auditing system is off, no action is performed; is returned,
and is set to If the auditing system is on and there is no available "next" file, no action is performed; is
returned, and is set to
The caller issues the
command to halt the auditing system. If the auditing system is on, it is turned off and the "current" and "next"
audit files are closed. cpath, npath, and mode are ignored. If the audit system is already off, is returned and is
set to
Security Restrictions
Some or all of the actions associated with this system call require the privilege. Processes owned by the superuser have this privilege.
Processes owned by other users may have this privilege, depending on system configuration. See privileges(5) for more information about
privileged access on systems that support fine-grained privileges.
RETURN VALUE
Upon successful completion, a value of is returned. Otherwise, is returned and the global variable is set to indicate the error.
EXAMPLES
In the following example, is used to determine whether the auditing system is on, and to retrieve the names of the audit files that are
currently in use by the system.
char c_file[PATH_MAX+1], x_file[PATH_MAX+1];
int mode=0600;
if (audctl(AUD_GET, c_file, x_file, mode))
switch ( errno ) {
case ENOENT:
strcpy(x_file,"-none-");
break;
case EALREADY:
printf("The auditing system is OFF
");
return 0;
case default:
fprintf(stderr, "Audctl failed: errno=%d
", errno);
return 1;
}
printf("The auditing system is ON: c_file=%s x_file=%s
",
c_file, x_file);
return 0;
ERRORS
fails if one of the following is true:
The caller does not have the
privilege, or one or both of the given files are not regular files and cannot be used.
The or cmd was specified while the auditing system is off.
User attempt to start the auditing system failed
because auditing is already on.
Bad pointer. One or more of the required function parameters is not accessible.
The cpath or npath is greater than in length, the cpath or npath specified is not an absolute path name.
No available "next" file when
cmd is or
AUTHOR
was developed by HP.
SEE ALSO
audomon(1M), audsys(1M), audit(5), privileges(5).
TO BE OBSOLETED audctl(2)
