'\" 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 ADD_ALLOCATABLE 8 "Jul 20, 2007"
.SH NAME
add_allocatable \- add entries to allocation databases
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/add_allocatable\fR [\fB-f\fR] [\fB-s\fR] [\fB-d\fR] \fB-n\fR \fIname\fR \fB-t\fR \fItype\fR \fB-l\fR \fIdevice-list\fR
    [\fB-a\fR \fIauthorization\fR] [\fB-c\fR \fIclean\fR] [\fB-o\fR \fIkey\fR=\fIvalue\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBadd_allocatable\fR creates new entries for user allocatable devices that are
to be managed by the device allocation mechanism. \fBadd_allocatable\fR can
also be used to update existing entries of such devices.
.sp
.LP
\fBadd_allocatable\fR can also create and update entries for non-allocatable
devices, such as printers, whose label range is managed by the device
allocation mechanism.
.sp
.LP
\fBadd_allocatable\fR can be used in shell scripts, such as installation
scripts for driver packages, to automate the administrative work of setting up
a new device.
.sp
.LP
Use \fBlist_devices\fR(1) to see the names and types of allocatable devices,
their attributes, and device paths.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 20n
Force an update of an already-existing entry with the specified information.
\fBadd_allocatable\fR exits with an error if this option is not specified when
an entry with the specified device name already exists.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 20n
Turn on silent mode. \fBadd_allocatable\fR does not print any error or warning
messages.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 20n
If this option is present, \fBadd_allocatable\fR updates the system-supplied
default attributes of the device type specified with \fB-t\fR.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIname\fR\fR
.ad
.RS 20n
Adds or updates an entry for device that is specified by \fIname\fR.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItype\fR\fR
.ad
.RS 20n
Adds or updates device entries that are of a type that are specified by
\fItype\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIdevice-list\fR\fR
.ad
.RS 20n
Adds or updates device paths to the device that is specified with \fB-n\fR.
Multiple paths in \fIdevice-list\fR must be separated by white spaces and the
list must be quoted.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR \fIauthorization\fR\fR
.ad
.RS 20n
Adds or updates the authorization that is associated with either the device
that is specified with \fB-n\fR or with devices of the type that is specified
with \fB-t\fR. When more than one authorization is specified, the list must be
separated by commas and must be quoted. When the device is not allocatable,
\fIauthorization\fR is specified with an asterisk (*) and must be quoted. When
the device is allocatable by any user, \fIauthorization\fR is specified with
the at sign (@) and must be quoted. Default authorization is '@'.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIclean\fR\fR
.ad
.RS 20n
Specifies the \fBdevice_clean\fR(7) program \fIclean\fR to be used with the
device that is specified with \fB-n\fR or with devices of the type that is
specified with \fB-t\fR. The default clean program is \fB/bin/true\fR.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIkey\fR=\fIvalue\fR\fR
.ad
.RS 20n
Accepts a string of colon-separated \fB\fIkey\fR=\fIvalue\fR\fR pairs for a
device that is specified with \fB-n\fR or with devices of the type that is
specified with \fB-t\fR. The following keys are currently interpreted by the
system:
.sp
.ne 2
.na
\fB\fBminlabel\fR\fR
.ad
.RS 12n
The minimum label at which the device can be used.
.RE

.sp
.ne 2
.na
\fB\fBmaxlabel\fR\fR
.ad
.RS 12n
The maximum label at which the device can be used.
.RE

.sp
.ne 2
.na
\fB\fBclass\fR\fR
.ad
.RS 12n
Specifies a logical  grouping of devices. For example, all Sun
Ray\u\s-2TM\s+2\d devices of all device types is a logical grouping. The
\fBclass\fR keyword has no default value.
.RE

.sp
.ne 2
.na
\fB\fBxdpy\fR\fR
.ad
.RS 12n
Specifies the display name of the X session. This keyword is used to identify
devices that are associated with the X session. The \fBxdpy\fR keyword has no
default value.
.RE

.RE

.SH EXIT STATUS
.sp
.LP
When successful, \fBadd_allocate\fR returns an exit status of \fB0\fR (true).
\fBadd_allocate\fR returns a nonzero exit status in the event of an error. The
exit codes are as follows:
.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
Invocation syntax error
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Unknown system error
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 5n
An entry already exists for the specified device. This error occurs only when
the \fB-f\fR option is not specified.
.RE

.sp
.ne 2
.na
\fB\fB4\fR\fR
.ad
.RS 5n
Permission denied. User does not have DAC or MAC access record updates.
.RE

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The invocation is Uncommitted. The options are Uncommitted. The output is
Not-an-Interface.
.SH SEE ALSO
.sp
.LP
.BR allocate (1),
.BR deallocate (1),
.BR list_devices (1),
.BR attributes (7),
.BR device_clean (7),
.BR remove_allocatable (8)
.SH NOTES
.sp
.LP
The functionality described on this manual page is available only if the system
is configured with Trusted Extensions.