usr/src/man/man2/getacct.2

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GETACCT 2 "Jan 20, 2003"
   7 .SH NAME
   8 getacct, putacct, wracct \- get, put, or write extended accounting data
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/exacct.h>
  13
  14 \fBsize_t\fR \fBgetacct\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIbufsize\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBint\fR \fBputacct\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIbufsize\fR, \fBint\fR \fIflags\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBwracct\fR(\fBidtype_t\fR \fIidtype\fR, \fBid_t\fR \fIid\fR, \fBint\fR \fIflags\fR);
  25 .fi
  26
  27 .SH DESCRIPTION
  28 .sp
  29 .LP
  30 These functions provide access to the extended accounting facility.
  31 .sp
  32 .LP
  33 The \fBgetacct()\fR function returns extended accounting buffers from the
  34 kernel for currently executing tasks and processes. The resulting data buffer
  35 is a packed \fBexacct\fR object that can be unpacked using
  36 \fBea_unpack_object()\fR (see \fBea_pack_object\fR(3EXACCT)) and subsequently
  37 manipulated using the functions of the extended accounting library,
  38 \fBlibexacct\fR(3LIB).
  39 .sp
  40 .LP
  41 The \fBputacct()\fR function provides privileged processes the ability to tag
  42 accounting records with additional data specific to that process.  For
  43 instance, a queueing facility might want to record to which queue a given task
  44 or process was submitted prior to running. The \fIflags\fR argument determines
  45 whether the contents of \fIbuf\fR should be treated as raw data (\fBEP_RAW\fR)
  46 or as an embedded \fBexacct\fR structure (\fBEP_EXACCT_OBJECT\fR). In the case
  47 of \fBEP_EXACCT_OBJECT\fR, \fIbuf\fR must be a packed \fBexacct\fR object as
  48 returned by \fBea_pack_object\fR(3EXACCT). The use of an inappropriate flag or
  49 the inclusion of corrupt \fBexacct\fR data will likely corrupt the enclosing
  50 \fBexacct\fR file.
  51 .sp
  52 .LP
  53 The \fBwracct()\fR function requests the kernel to write, given its internal
  54 state of resource usage, the appropriate data for the specified task or
  55 process. The flags field determines whether a partial (\fBEW_PARTIAL\fR) or
  56 interval record (\fBEW_INTERVAL\fR) is written.
  57 .sp
  58 .LP
  59 These functions require root privilege, as they allow inquiry or reporting
  60 relevant to system tasks and processes other than the invoking process. The
  61 \fBputacct()\fR and \fBwracct()\fR functions also cause the kernel to write
  62 records to the system's extended accounting files.
  63 .SH RETURN VALUES
  64 .sp
  65 .LP
  66 The \fBgetacct()\fR function returns the number of bytes required to represent
  67 the extended accounting record for the requested system task or process.  If
  68 \fIbufsize\fR exceeds the returned size, \fIbuf\fR will contain a valid
  69 accounting record buffer. If \fIbufsize\fR is less than the return value,
  70 \fIbuf\fR will contain the first \fIbufsize\fR bytes of the record. If
  71 \fIbufsize\fR is 0, \fBgetacct()\fR returns only the number of  bytes required
  72 to represent the extended accounting record. In the event of failure,
  73 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
  74 .sp
  75 .LP
  76 The \fBputacct()\fR and \fBwracct()\fR functions return \fB0\fR if the record
  77 was successfully written. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is
  78 set to indicate the error.
  79 .SH ERRORS
  80 .sp
  81 .LP
  82 The \fBgetacct()\fR, \fBputacct()\fR, and \fBwracct()\fR functions will fail
  83 if:
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBEINVAL\fR\fR
  88 .ad
  89 .RS 14n
  90 The \fIidtype\fR argument was not \fBP_TASKID\fR or \fBP_PID\fR.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBENOSPC\fR\fR
  97 .ad
  98 .RS 14n
  99 The file system containing the extended accounting file is full.  The
 100 \fBwracct()\fR or \fBputacct()\fR function will fail if the record size would
 101 exceed the amount of space remaining on the file system.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBENOTACTIVE\fR\fR
 108 .ad
 109 .RS 14n
 110 The extended accounting facility for the requested \fBidtype_t\fR is not
 111 active.  Either \fBputacct()\fR attempted to write a task record when the task
 112 accounting file was unset, or \fBgetacct()\fR attempted to retrieve accounting
 113 data for a process when extended process accounting was inactive.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBEPERM\fR\fR
 120 .ad
 121 .RS 14n
 122 The {\fBPRIV_SYS_ACCT\fR} privilege is not asserted in the effective set of the
 123 calling process.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBERSCH\fR\fR
 130 .ad
 131 .RS 14n
 132 The \fIid\fR argument does not refer to a presently active system task \fBID\fR
 133 or process \fBID\fR.
 134 .RE
 135
 136 .sp
 137 .LP
 138 The \fBputacct()\fR and \fBwracct()\fR functions will fail if:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBEINVAL\fR\fR
 143 .ad
 144 .RS 10n
 145 The \fIflags\fR argument is neither \fBEW_PARTIAL\fR nor \fBEW_INTERVAL\fR.
 146 .RE
 147
 148 .SH ATTRIBUTES
 149 .sp
 150 .LP
 151 See \fBattributes\fR(5) for descriptions of the following attributes:
 152 .sp
 153
 154 .sp
 155 .TS
 156 box;
 157 c | c
 158 l | l .
 159 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 160 _
 161 MT-Level        Async-Signal-Safe
 162 .TE
 163
 164 .SH SEE ALSO
 165 .sp
 166 .LP
 167 \fBea_pack_object\fR(3EXACCT), \fBlibexacct\fR(3LIB)\fBattributes\fR(5)