audctl(2) audctl(2)
NAME [Toc] [Back]
audctl - start or halt the auditing system and set or get audit files
SYNOPSIS [Toc] [Back]
#include <sys/audit.h>
int audctl(int cmd, char *cpath, char *npath, mode_t mode);
DESCRIPTION [Toc] [Back]
audctl() sets or gets the auditing system "current" and "next" audit
files, and starts or halts the auditing system. This call is
restricted to superusers. 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:
AUD_ON The caller issues the AUD_ON command with the
required "current" and "next" files to turn
on the auditing system. If the auditing
system is currently 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; -1 is
returned and errno is set to EBUSY.
AUD_GET The caller issues the AUD_GET 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;
-1 is returned, and errno is set to ENOENT.
If the auditing system is off, no action is
performed; -1 is returned and errno is set to
EALREADY.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
audctl(2) audctl(2)
AUD_SET The caller issues the AUD_SET 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; -1 is returned
and errno is set to EALREADY.
AUD_SETCURR The caller issues the AUD_SETCURR 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; -1 is returned and errno is set
to EALREADY.
AUD_SETNEXT The caller issues the AUD_SETNEXT 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 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; -1 is returned, and errno is set
to EALREADY.
AUD_SWITCH The caller issues the AUD_SWITCH command to
cause 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 NULL.
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; -1 is returned,
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
audctl(2) audctl(2)
and errno is set to EALREADY. If the
auditing system is on and there is no
available "next" file, no action is
performed; -1 is returned, and errno is set
to ENOENT.
AUD_OFF The caller issues the AUD_OFF 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, -1 is returned and errno is set
to EALREADY.
RETURN VALUE [Toc] [Back]
Upon successful completion, a value of 0 is returned. Otherwise, -1
is returned and the global variable errno is set to indicate the
error.
EXAMPLES [Toc] [Back]
In the following example, audctl() 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\n");
return 0;
case default:
fprintf(stderr, "Audctl failed: errno=%d\n", errno);
return 1;
}
printf("The auditing system is ON: c_file=%s x_file=%s\n",
c_file, x_file);
return 0;
ERRORS [Toc] [Back]
audctl() fails if one of the following is true:
[EPERM] The caller does not have superuser privilege,
or one or both of the given files are not
regular files and cannot be used.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
audctl(2) audctl(2)
[EALREADY] The AUD_OFF, AUD_SET, AUD_SETCURR,
AUD_SETNEXT, AUD_SWITCH, or AUD_GET cmd was
specified while the auditing system is off.
[EBUSY] User attempt to start the auditing system
failed because auditing is already on.
[EFAULT] Bad pointer. One or more of the required
function parameters is not accessible.
[EINVAL] The cpath or npath is greater than PATH_MAX
in length, the cpath or npath specified is
not an absolute path name.
[ENOENT] No available "next" file when cmd is
AUD_GETNEXT or AUD_SWITCH.
AUTHOR [Toc] [Back]
audctl() was developed by HP.
SEE ALSO [Toc] [Back]
audit(5), audsys(1M), audomon(1M).
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003 [ Back ] |
