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)