'\" te
.\" Copyright 2000 by 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 GETDDENT 3BSM "Jan 11, 2001"
.SH NAME
getddent, getddnam, setddent, endddent, setddfile \- get device_deallocate
entry
.SH SYNOPSIS
.LP
.nf
\fBcc \fR  [\fIflag\fR]... \fIfile\fR... \fB-lbsm\fR  [\fIlibrary\fR]...
.fi

.LP
.nf
#include <bsm/devices.h>

\fBdevdealloc_t *\fR\fBgetddent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBdevdealloc_t *\fR\fBgetddnam\fR(\fBchar *\fR\fIname\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetddent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBendddent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetddfile\fR(\fBchar *\fR\fIfile\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetddent()\fR and \fBgetddnam()\fR functions each return a
\fBdevice_deallocate\fR entry. The \fBgetddent()\fR function enumerates all
\fBdevice_deallocate\fR entries. Successive calls to this function return
either successive \fBdevice_deallocate\fR entries or \fINULL\fR. The
\fBgetddnam()\fR function searches for a \fBdevice_deallocate\fR entry with a
given device name.
.sp
.LP
The internal representation of a \fBdevice_deallocate\fR entry is a
\fBdevdealloc_t\fR structure defined in <\fBbsm/devices.h\fR> with the
following members:
.sp
.in +2
.nf
char *dd_devname;  /* device allocation name */
char *dd_logout;   /* deallocation action on user logout */
char *dd_boot;     /* deallocation action on system boot */
.fi
.in -2

.sp
.LP
The \fBsetddent()\fR function "rewinds" to the beginning of the enumeration of
\fBdevice_deallocate\fR entries. Calls to \fBgetddnam()\fR may leave the
enumeration in an indeterminate state, so \fBsetddent()\fR should be called
before the first call to \fBgetddent()\fR.
.sp
.LP
The \fBendddent()\fR function can be called to indicate that
\fBdevice_deallocate\fR processing is complete. The library can then close any
open\fBdevice_deallocate\fR file, deallocate any internal storage, and so
forth.
.sp
.LP
The \fBsetddfile()\fR function changes the pathname used by the other functions
for opening the \fBdevice_deallocate\fR file, allowing use of
\fBdevice_deallocate\fR files other than the default file,
\fB/etc/security/device_deallocate\fR.
.SH RETURN VALUES
.sp
.LP
The \fBgetddent()\fR function returns a pointer to a \fBdevdealloc_t\fR if it
successfully enumerates an entry. Otherwise it returns \fINULL\fR, indicating
the end of the enumeration.
.sp
.LP
The \fBgetddnam()\fR function returns a pointer to a \fBdevdealloc_t\fR if it
successfully locates the requested entry. Otherwise it returns \fINULL\fR.
.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/security/device_deallocate\fR\fR
.ad
.sp .6
.RS 4n
Administrative file defining parameters for device deallocation.
.RE

.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
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBfree\fR(3C),  \fBattributes\fR(5)
.SH NOTES
.sp
.LP
The \fBgetddent()\fR and \fBgetddnam()\fR functions allocate memory for the
pointers they return. This memory can be deallocated with the \fBfree\fR(3C)
function.