audctl(2)

NAME

audctl() — start or halt the auditing system and set or get audit files

SYNOPSIS

#include <sys/audit.h>

int audctl(int cmd, char *cpath, char *npath, mode_t mode);

Remarks

This function is provided purely for backward compatibility. HP recommends that new applications use the audsys command to configure the auditing system. See audsys(1M).

DESCRIPTION

audctl() 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 AUDCONTROL 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:

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.
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 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 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, 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.

Security Restrictions

Some or all of the actions associated with this system call require the AUDCONTROL 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 0 is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

EXAMPLES

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

audctl() fails if one of the following is true:

EPERM: The caller does not have the AUDCONTROL privilege, or one or both of the given files are not regular files and cannot be used.
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_GET or AUD_SWITCH.

AUTHOR

audctl() was developed by HP.