Direct Access Transport Library Functions datiaclose(3DAT)
NAME
datiaclose - close an IA
SYNOPSIS
cc [ flag... ] file... -ldat [ library... ]
#include
DATRETURN
datiaclose (
IN DATIAHANDLE iahandle,
IN DATCLOSEFLAGS iaflags
)
PARAMETERS
iahandle Handle for an instance of a DAT IA.
iaflags Flags for IA closure. Flag definitions are:
DATCLOSEABRUPTFLAG Abrupt close. Abrupt
cascading close of
IA including all
Consumer created DAT
objects.
DATCLOSEGRACEFULFLAG Graceful close. Clo-
sure is successful
only if all DAT
objects created by
the Consumer have
been freed before
the graceful closure
call.
Default value of DATCLOSEDEFAULT =
DATCLOSEABRUPTFLAG represents abrupt closure
of IA.
DESCRIPTION
The datiaclose() function closes an IA (destroys an
instance of the Interface Adapter).
The iaflags specify whether the Consumer wants abrupt or
graceful close.
The abrupt close does a phased, cascading destroy. All DAT
Objects associated with an IA instance are destroyed. These
SunOS 5.11 Last change: 16 Jul 2004 1
Direct Access Transport Library Functions datiaclose(3DAT)
include all the connection oriented Objects: public and
reserved Service Points; Endpoints, Connection Requests,
LMRs (including lmrcontexts), RMRs (including
rmrcontexts), Event Dispatchers, CNOs, and Protection
Zones. All the waiters on all CNOs, including the OS Wait
Proxy Agents, are unblocked with the DATHANDLENUL handle
returns for an unblocking EVD. All direct waiters on all
EVDs are also unblocked and return with DATABORT.
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
DATINVALIDSTATE.
If async EVD was created as part of the of
datiaopen(3DAT), datiaclose() must destroy it. If
asyncevdhandle was passed in by the Consumer at
datiaopen(), this handle is not destroyed. This is appli-
cable to both abrupt and graceful iaflags values.
Because the Consumer did not create async EVD explicitly,
the Consumer does not need to destroy it for graceful close
to succeed.
RETURN VALUES
DATSUCES The operation was successful.
DATINSUFICIENTRESOURCES The operation failed due to
resource limitations. This is
a catastrophic error.
DATINVALIDHANDLE Invalid DAT handle; iahandle
is invalid.
DATINVALIDPARAMETER Invalid parameter; iaflags is
invalid.
DATINVALIDSTATE Parameter in an invalid state.
IA instance has Consumer-
created objects associated
with it.
SunOS 5.11 Last change: 16 Jul 2004 2
Direct Access Transport Library Functions datiaclose(3DAT)
USAGE
The datiaclose() function is the root cleanup method for
the Provider, and, thus, all Objects.
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.
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.
The techniques described in datcnofree(3DAT) and
datevdfree(3DAT) can be used for these purposes.
If the Consumer desires to shut down the IA as quickly as
possible, the Consumer can call datiaclose(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.
No provision is made for blocking on event completion or
pulling events from queues.
This is the general cleanup and last resort method for Con-
sumer recovery. An implementation must provide for success-
ful completion under all conditions, avoiding hidden
resource leakage (dangling memory, zombie processes, and so
on) eventually leading to a reboot of the operating system.
The datiaclose() function deletes all Objects that were
created using the IA handle.
The datiaclose() function can decrement a reference count
for the Provider Library that is incremented by
datiaopen() to ensure that the Provider Library cannot be
removed when it is in use by a DAT Consumer.
SunOS 5.11 Last change: 16 Jul 2004 3
Direct Access Transport Library Functions datiaclose(3DAT)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard: uDAPL, 1.1, 1.2
MT-Level Unsafe
SEE ALSO
datcnofree(3DAT), datevdfree(3DAT), datiaopen(3DAT),
libdat(3LIB), attributes(5)
SunOS 5.11 Last change: 16 Jul 2004 4
|
