'\" te
.\" 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 device_clean 5 "14 Jun 2007" "SunOS 5.11" "Standards, Environments, and Macros"
.SH NAME
device_clean \- device clean programs
.SH DESCRIPTION
.sp
.LP
Each allocatable device has a device clean program associated with it. Device
clean programs are invoked by \fBdeallocate\fR(1) to clean device states,
registers, and any residual information in the device before the device is
allocated to a user. Such cleaning is required by the object reuse policy.
.sp
.LP
Use \fBlist_devices\fR(1) to obtain the names and types of allocatable devices
as well as the cleaning program and the authorizations that are associated with
each device.
.sp
.LP
On a system configured with Trusted Extensions, device clean programs are also
invoked by \fBallocate\fR(1), in which case the program can optionally mount
appropriate media for the caller.
.sp
.LP
The following device clean programs reside in \fB/etc/security/lib\fR.
.sp
.ne 2
.mk
.na
\fB\fBaudio_clean\fR\fR
.ad
.RS 15n
.rt  
audio devices
.RE

.sp
.ne 2
.mk
.na
\fB\fBfd_clean\fR\fR
.ad
.RS 15n
.rt  
floppy devices
.RE

.sp
.ne 2
.mk
.na
\fB\fBst_clean\fR\fR
.ad
.RS 15n
.rt  
tape devices
.RE

.sp
.ne 2
.mk
.na
\fB\fBsr_clean\fR\fR
.ad
.RS 15n
.rt  
CD-ROM devices
.RE

.sp
.LP
On a system configured with Trusted Extensions, the following additional
cleaning programs and wrappers are available.
.sp
.ne 2
.mk
.na
\fB\fBdisk_clean\fR\fR
.ad
.RS 23n
.rt  
floppy, CD-ROM, and other removable media devices. This program mounts the
device during the execution of \fBallocate\fR, if required.
.RE

.sp
.ne 2
.mk
.na
\fB\fBaudio_clean_wrapper\fR\fR
.ad
.RS 23n
.rt  
wrapper to make audio_clean work with CDE
.RE

.sp
.ne 2
.mk
.na
\fB\fBwdwwrapper\fR\fR
.ad
.RS 23n
.rt  
wrapper to make other cleaning programs work with CDE
.RE

.sp
.ne 2
.mk
.na
\fB\fBwdwmsg\fR\fR
.ad
.RS 23n
.rt  
CDE dialog boxes for cleaning programs
.RE

.sp
.LP
Administrators can create device clean programs for their sites. These programs
must adhere to the syntax described below.
.sp
.in +2
.nf
/etc/security/lib/\fIdevice-clean-program\fR [\(mii | \(mif | \(mis | \(miI] \e
\(mim \fImode\fR \(miu \fIuser-name\fR \(miz \fIzone-name\fR \(mip \fIzone-path\fR \fIdevice-name\fR
.fi
.in -2
.sp

.sp
.LP
where:
.sp
.ne 2
.mk
.na
\fB\fIdevice-name\fR\fR
.ad
.RS 15n
.rt  
The name of the device that is to be cleaned. Use \fBlist_devices\fR to obtain
the list of allocatable devices.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-i\fR\fR
.ad
.RS 15n
.rt  
Invoke boot-time initialization.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR\fR
.ad
.RS 15n
.rt  
Force cleanup by the administrator.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR\fR
.ad
.RS 15n
.rt  
Invoke standard cleanup by the user.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I\fR\fR
.ad
.RS 15n
.rt  
Same as \fB-i\fR, with no error or warning.
.RE

.sp
.LP
The following options are supported only when the system is configured with
Trusted Extensions.
.sp
.ne 2
.mk
.na
\fB\fB-m\fR \fImode\fR\fR
.ad
.RS 16n
.rt  
Specify the mode in which the clean program is invoked. Valid values are allo-
cate and deallocate. The default mode is allocate.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-u\fR \fIuser-name\fR\fR
.ad
.RS 16n
.rt  
Specify the name of user who executes the device clean program. The default
user is the caller.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-z\fR \fIzone-name\fR\fR
.ad
.RS 16n
.rt  
Specify the name of the zone in which the device is to be allocated or
deallocated. The default zone is the global zone.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR \fIzone-path\fR\fR
.ad
.RS 16n
.rt  
Establish the root path of the zone that is specified by \fIzone-name\fR.
Default is "/".
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
An error. Caller can place device in error state.
.RE

.sp
.ne 2
.mk
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
A system error. Caller can place device in error state.
.RE

.sp
.LP
On a system configured with Trusted Extensions, the following additional exit
values are returned:
.sp
.ne 2
.mk
.na
\fB\fB3\fR\fR
.ad
.sp .6
.RS 4n
Mounting of device failed. Caller shall not place device in error state.
.RE

.sp
.ne 2
.mk
.na
\fB\fB4\fR\fR
.ad
.sp .6
.RS 4n
Mounting of device succeeded.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/security/lib/*\fR\fR
.ad
.RS 23n
.rt  
device clean programs
.RE

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilitySee below.
.TE

.sp
.LP
The Invocation is Uncommitted. The Output is Not-an-interface.
.SH SEE ALSO
.sp
.LP
\fBallocate\fR(1), \fBdeallocate\fR(1), \fBlist_devices\fR(1),
\fBattributes\fR(5)
.sp
.LP
\fISystem Administration Guide: Security Services\fR