'\" te
.\" Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH ea_open 3EXACCT "29 Nov 2001" "SunOS 5.11" "Extended Accounting File Access Library Functions"
.SH NAME
ea_open, ea_close \- open or close exacct files
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lexacct\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <exacct.h>

\fBint\fR \fBea_open\fR(\fBea_file_t *\fR\fIef\fR, \fBchar *\fR\fIname\fR, \fBchar *\fR\fIcreator\fR, \fBint\fR \fIaflags\fR,
     \fBint\fR \fIoflags\fR, \fBmode_t\fR \fImode\fR);
.fi

.LP
.nf
\fBint\fR \fBea_close\fR(\fBea_file_t *\fR\fIef\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBea_open()\fR function provides structured access to \fBexacct\fR files.
The \fIaflags\fR argument contains the appropriate \fBexacct\fR flags necessary
to describe the file. The \fIoflags\fR and \fImode\fR arguments contain the
appropriate flags and mode to open the file; see <\fBfcntl.h\fR>. If
\fBea_open()\fR is invoked with \fBEO_HEAD\fR specified in \fIaflags\fR, the
resulting file is opened with the object cursor located at the first object of
the file. If \fBea_open()\fR is invoked with \fBEO_TAIL\fR specified in
\fIaflags\fR, the resulting file is opened with the object cursor positioned
beyond the last object in the file. If \fBEO_NO_VALID_HDR\fR is set in
\fIaflags\fR along with \fBEO_HEAD\fR, the initial header record will be
returned as the first item read from the file. When creating a file, the
\fIcreator\fR argument should be set (system generated files use the value
"SunOS"); when reading a file, this argument should be set to \fINULL\fR if no
validation is required; otherwise it should be set to the expected value in the
file.
.sp
.LP
The \fBea_close()\fR function closes an open \fBexacct\fR file.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBea_open()\fR and \fBea_close()\fR return
\fB0\fR. Otherwise they return \fB\(mi1\fR and call \fBea_error\fR(3EXACCT) to
return the extended accounting error value describing the error.
.SH ERRORS
.sp
.LP
The \fBea_open()\fR and \fBea_close()\fR functions may fail if:
.sp
.ne 2
.mk
.na
\fB\fBEXR_SYSCALL_FAIL\fR\fR
.ad
.RS 20n
.rt  
A system call invoked by the function failed. The \fBerrno\fR variable contains
the error value set by the underlying call.
.RE

.sp
.LP
The \fBea_open()\fR function may fail if:
.sp
.ne 2
.mk
.na
\fB\fBEXR_CORRUPT_FILE\fR\fR
.ad
.RS 20n
.rt  
The file referred to by \fIname\fR is not a valid \fBexacct\fR file.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEXR_NO_CREATOR\fR\fR
.ad
.RS 20n
.rt  
In the case of file creation, the \fIcreator\fR argument was \fINULL\fR.  In
the case of opening an existing file, a \fIcreator\fR argument was not NULL and
does not match the \fIcreator\fR item of the \fBexacct\fR file.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEXR_UNKN_VERSION\fR\fR
.ad
.RS 20n
.rt  
The file referred to by \fIname\fR uses an \fBexacct\fR file version that
cannot be processed by this library.
.RE

.SH USAGE
.sp
.LP
The \fBexacct\fR file format can be used to represent data other than that in
the extended accounting format.  By using a unique creator type in the file
header, application writers can develop their own format suited to the needs of
their application.
.SH EXAMPLES
.LP
\fBExample 1 \fROpen and close \fBexacct\fR file.
.sp
.LP
The following example opens the extended accounting data file for processes.
The \fBexacct\fR file is then closed.

.sp
.in +2
.nf
#include <exacct.h>

ea_file_t ef;
if (ea_open(&ef, "/var/adm/exacct/proc", NULL, EO_HEAD,
    O_RDONLY, 0) == -1)
        exit(1);
(void) ea_close(&ef);
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.46i) |cw(3.04i) 
lw(2.46i) |lw(3.04i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityEvolving
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBea_error\fR(3EXACCT), \fBea_pack_object\fR(3EXACCT),
\fBea_set_item\fR(3EXACCT), \fBlibexacct\fR(3LIB), \fBattributes\fR(5)