'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, 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 DAT_IA_CLOSE 3DAT "Jul 16, 2004"
.SH NAME
dat_ia_close \- close an IA
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ia_close (
    IN    DAT_IA_HANDLE    \fIia_handle\fR,
    IN    DAT_CLOSE_FLAGS  \fIia_flags\fR
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIia_handle\fR\fR
.ad
.RS 13n
Handle for an instance of a DAT IA.
.RE

.sp
.ne 2
.na
\fB\fIia_flags\fR\fR
.ad
.RS 13n
Flags for IA closure. Flag definitions are:
.sp
.ne 2
.na
\fB\fBDAT_CLOSE_ABRUPT_FLAG\fR\fR
.ad
.RS 27n
Abrupt close. Abrupt cascading close of IA including all Consumer created DAT
objects.
.RE

.sp
.ne 2
.na
\fB\fBDAT_CLOSE_GRACEFUL_FLAG\fR\fR
.ad
.RS 27n
Graceful close. Closure is successful only if all DAT objects created by the
Consumer have been freed before the graceful closure call.
.RE

Default value of \fBDAT_CLOSE_DEFAULT\fR = \fBDAT_CLOSE_ABRUPT_FLAG\fR
represents abrupt closure of IA.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ia_close()\fR function closes an IA (destroys an instance of the
Interface Adapter).
.sp
.LP
The\fI ia_flags\fR specify whether the Consumer wants abrupt or graceful close.
.sp
.LP
The abrupt close does a phased, cascading destroy. All DAT Objects associated
with an IA instance are destroyed. These include all the connection oriented
Objects: public and reserved Service Points; Endpoints, Connection Requests,
LMRs (including lmr_contexts), RMRs (including rmr_contexts), Event
Dispatchers, CNOs, and Protection Zones. All the waiters on all CNOs, including
the OS Wait Proxy Agents, are unblocked with the DAT_HANDLE_NULL handle returns
for an unblocking EVD. All direct waiters on all EVDs are also unblocked and
return with DAT_ABORT.
.sp
.LP
The graceful close does a destroy only if the Consumer has done a cleanup of
all DAT objects created by the Consumer with the exception of the asynchronous
EVD. Otherwise, the operation does not destroy the IA instance and returns the
\fBDAT_INVALID_STATE\fR.
.sp
.LP
If async EVD was created as part of the of \fBdat_ia_open\fR(3DAT),
\fBdat_ia_close()\fR must destroy it. If \fIasync_evd_handle\fR was passed in
by the Consumer at \fBdat_ia_open()\fR, this handle is not destroyed. This is
applicable to both abrupt and graceful \fIia_flags\fR values.
.sp
.LP
Because the Consumer did not create async EVD explicitly, the Consumer does not
need to destroy it for graceful close to succeed.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
.ad
.RS 30n
The operation failed due to resource limitations. This is a catastrophic error.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
Invalid DAT handle; \fIia_handle\fR is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
Invalid parameter; \fIia_flags\fR is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_STATE\fR\fR
.ad
.RS 30n
Parameter in an invalid state. IA instance has Consumer-created objects
associated with it.
.RE

.SH USAGE
.sp
.LP
The \fBdat_ia_close()\fR function is the root cleanup method for the Provider,
and, thus, all Objects.
.sp
.LP
Consumers are advised to explicitly destroy all Objects they created prior to
closing the IA instance, but can use this function to clean up everything
associated with an open instance of IA. This allows the Consumer to clean up in
case of errors.
.sp
.LP
Note that an abrupt close implies destruction of EVDs and CNOs. Just as with
explicit destruction of an EVD or CNO, the Consumer should take care to avoid a
race condition where a Consumer ends up attempting to wait on an EVD or CNO
that has just been deleted.
.sp
.LP
The techniques described in \fBdat_cno_free\fR(3DAT) and
\fBdat_evd_free\fR(3DAT) can be used for these purposes.
.sp
.LP
If the Consumer desires to shut down the IA as quickly as possible, the
Consumer can call dat_ia_close(abrupt) without unblocking CNO and EVD waiters
in an orderly fashion. There is a slight chance that an invalidated DAT handle
will cause a memory fault for a waiter. But this might be an acceptable
behavior, especially if the Consumer is shutting down the process.
.sp
.LP
No provision is made for blocking on event completion or pulling events from
queues.
.sp
.LP
This is the general cleanup and last resort method for Consumer recovery. An
implementation must provide for successful completion under all conditions,
avoiding hidden resource leakage (dangling memory, zombie processes, and so on)
eventually leading to a reboot of the operating system.
.sp
.LP
The \fBdat_ia_close()\fR function deletes all Objects that were created using
the IA handle.
.sp
.LP
The \fBdat_ia_close()\fR function can decrement a reference count for the
Provider Library that is incremented by \fBdat_ia_open()\fR to ensure that the
Provider Library cannot be removed when it is in use by a DAT Consumer.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.1, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBdat_cno_free\fR(3DAT), \fBdat_evd_free\fR(3DAT), \fBdat_ia_open\fR(3DAT),
\fBlibdat\fR(3LIB), \fBattributes\fR(5)