usr/src/man/man3bsm/getddent.3bsm

   1 '\" te
   2 .\" Copyright 2000 by 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 GETDDENT 3BSM "Jan 11, 2001"
   7 .SH NAME
   8 getddent, getddnam, setddent, endddent, setddfile \- get device_deallocate
   9 entry
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc \fR  [\fIflag\fR]... \fIfile\fR... \fB-lbsm\fR  [\fIlibrary\fR]...
  14 .fi
  15
  16 .LP
  17 .nf
  18 #include <bsm/devices.h>
  19
  20 \fBdevdealloc_t *\fR\fBgetddent\fR(\fBvoid\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBdevdealloc_t *\fR\fBgetddnam\fR(\fBchar *\fR\fIname\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBvoid\fR \fBsetddent\fR(\fBvoid\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBvoid\fR \fBendddent\fR(\fBvoid\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBsetddfile\fR(\fBchar *\fR\fIfile\fR);
  41 .fi
  42
  43 .SH DESCRIPTION
  44 .sp
  45 .LP
  46 The \fBgetddent()\fR and \fBgetddnam()\fR functions each return a
  47 \fBdevice_deallocate\fR entry. The \fBgetddent()\fR function enumerates all
  48 \fBdevice_deallocate\fR entries. Successive calls to this function return
  49 either successive \fBdevice_deallocate\fR entries or \fINULL\fR. The
  50 \fBgetddnam()\fR function searches for a \fBdevice_deallocate\fR entry with a
  51 given device name.
  52 .sp
  53 .LP
  54 The internal representation of a \fBdevice_deallocate\fR entry is a
  55 \fBdevdealloc_t\fR structure defined in <\fBbsm/devices.h\fR> with the
  56 following members:
  57 .sp
  58 .in +2
  59 .nf
  60 char *dd_devname;  /* device allocation name */
  61 char *dd_logout;   /* deallocation action on user logout */
  62 char *dd_boot;     /* deallocation action on system boot */
  63 .fi
  64 .in -2
  65
  66 .sp
  67 .LP
  68 The \fBsetddent()\fR function "rewinds" to the beginning of the enumeration of
  69 \fBdevice_deallocate\fR entries. Calls to \fBgetddnam()\fR may leave the
  70 enumeration in an indeterminate state, so \fBsetddent()\fR should be called
  71 before the first call to \fBgetddent()\fR.
  72 .sp
  73 .LP
  74 The \fBendddent()\fR function can be called to indicate that
  75 \fBdevice_deallocate\fR processing is complete. The library can then close any
  76 open\fBdevice_deallocate\fR file, deallocate any internal storage, and so
  77 forth.
  78 .sp
  79 .LP
  80 The \fBsetddfile()\fR function changes the pathname used by the other functions
  81 for opening the \fBdevice_deallocate\fR file, allowing use of
  82 \fBdevice_deallocate\fR files other than the default file,
  83 \fB/etc/security/device_deallocate\fR.
  84 .SH RETURN VALUES
  85 .sp
  86 .LP
  87 The \fBgetddent()\fR function returns a pointer to a \fBdevdealloc_t\fR if it
  88 successfully enumerates an entry. Otherwise it returns \fINULL\fR, indicating
  89 the end of the enumeration.
  90 .sp
  91 .LP
  92 The \fBgetddnam()\fR function returns a pointer to a \fBdevdealloc_t\fR if it
  93 successfully locates the requested entry. Otherwise it returns \fINULL\fR.
  94 .SH FILES
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fB/etc/security/device_deallocate\fR\fR
  99 .ad
 100 .sp .6
 101 .RS 4n
 102 Administrative file defining parameters for device deallocation.
 103 .RE
 104
 105 .SH ATTRIBUTES
 106 .sp
 107 .LP
 108 See \fBattributes\fR(5) for descriptions of the following attributes:
 109 .sp
 110
 111 .sp
 112 .TS
 113 box;
 114 c | c
 115 l | l .
 116 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 117 _
 118 MT-Level        Unsafe
 119 .TE
 120
 121 .SH SEE ALSO
 122 .sp
 123 .LP
 124 \fBfree\fR(3C),  \fBattributes\fR(5)
 125 .SH NOTES
 126 .sp
 127 .LP
 128 The \fBgetddent()\fR and \fBgetddnam()\fR functions allocate memory for the
 129 pointers they return. This memory can be deallocated with the \fBfree\fR(3C)
 130 function.