'\" te
.\" Copyright (c) 2009, 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 STMFSETLUPROP 3STMF "Jul 17, 2009"
.SH NAME
stmfSetLuProp, stmfGetLuProp \- set or get a logical unit property
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lstmf [ \fIlibrary\fR... ]
#include <libstmf.h>

\fBint\fR \fBstmfSetLuProp\fR(\fBluResource\fR \fIhdl\fR, \fBuint32_t\fR \fIprop\fR, \fBconst char *\fR\fIpropVal\fR);
.fi

.LP
.nf
\fBint\fR \fBstmfGetLuProp\fR(\fBluResource\fR \fIhdl\fR, \fBuint32_t\fR \fIprop\fR, \fBchar *\fR\fIpropVal\fR,
     \fBsize_t *\fR\fIpropLen\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIhdl\fR\fR
.ad
.RS 11n
A logical unit resource previously allocated by
\fBstmfCreateLuResource\fR(3STMF) or \fBstmfGetLuResource\fR(3STMF).
.RE

.sp
.ne 2
.na
\fB\fIprop\fR\fR
.ad
.RS 11n
A property type value. See DESCRIPTION for valid values.
.RE

.sp
.ne 2
.na
\fB\fIpropVal\fR\fR
.ad
.RS 11n
A property value.
.RE

.sp
.ne 2
.na
\fB\fIpropLen\fR\fR
.ad
.RS 11n
The length of the specified property value. If \fIpropLen\fR was of an
insufficient size to hold the returned property value, \fIpropLen\fR will
contain the required size of the buffer and \fBSTMF_ERROR_INVALID_ARG\fR will
be returned.
.RE

.SH DESCRIPTION
.sp
.LP
These functions set or get property values. All property values are expressed
in human-readable form. Boolean properties are expressed in case insensitive
form of "true" or "false". Properties that are represented by ASCII hexadecimal
contain no leading characters to indicate a base hexadecimal representation
(that is, no leading "0x"). The \fIprop\fR argument can be one of the following
values:
.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_ALIAS\fR\fR
.ad
.sp .6
.RS 4n
Up to 255 characters representing a user defined name for the device.
.sp
Default: Set to file name of backing store.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_BLOCK_SIZE\fR\fR
.ad
.sp .6
.RS 4n
Numeric value for block size in bytes in 2^n.
.sp
Default: 512
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_COMPANY_ID\fR\fR
.ad
.sp .6
.RS 4n
Organizational Unique Identifier. 6 hexadecimal ASCII characters representing
the IEEE OUI company id assignment. This will be used to generate the device
identifier (GUID).
.sp
Default: 00144F
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_DATA_FILENAME\fR\fR
.ad
.sp .6
.RS 4n
Character value representing the file name of the backing store device.
.sp
Default: None
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_GUID\fR\fR
.ad
.sp .6
.RS 4n
ASCII hexadecimal string of 32 characters representing the unique identifier
for the device. This must be of valid 32 hexadecimal ASCII characters
representing a valid NAA Registered Extended Identifier.
.sp
Default: Set by framework to a generated value.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_META_FILENAME\fR\fR
.ad
.sp .6
.RS 4n
Metadata file name. When specified, will be used to hold the SCSI metadata for
the logical unit.
.sp
Default: None. If this value is not specified, the value specified in
\fBSTMF_LU_PROP_DATA_FILENAME\fR will be used.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_MGMT_URL\fR\fR
.ad
.sp .6
.RS 4n
Up to 1024 characters representing Management Network Address URLs. More than
one URL can be passed using space delimited URLs.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_PID\fR\fR
.ad
.sp .6
.RS 4n
Up to 16 characters of product identification that will be reflected in the
Standard INQUIRY data returned for the device.
.sp
Default: sSet to COMSTAR.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_PRODUCT_REV\fR\fR
.ad
.sp .6
.RS 4n
Up to 4 characters of revision information that will be reflected in the
Standard INQUIRY data returned for the device.
.sp
Default: Set to 1.0.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_SERIAL_NUM\fR\fR
.ad
.sp .6
.RS 4n
Serial Number. Specifies the SCSI Vital Product Data Serial Number (page 80h).
It is a character value up to 252 bytes in length.
.sp
Default: None
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_SIZE\fR\fR
.ad
.sp .6
.RS 4n
Numeric value w/optional suffix, e.g. 100G, 1T, to specify unit of size.
.sp
Default: Size of the device specified in the \fBSTMF_LU_PROP_DATA_FILENAME\fR
property value.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_VID\fR\fR
.ad
.sp .6
.RS 4n
8 characters of vendor identification per SCSI SPC-3 and will be reflected in
the Standard INQUIRY data returned for the device.
.sp
Default: Set to SUN.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_WRITE_CACHE_DISABLE\fR\fR
.ad
.sp .6
.RS 4n
Write back cache disable. When specified as "true" or "false", specifies write
back cache disable behavior.
.sp
Default: Writeback cache setting of the backing store device specified by
\fBSTMF_LU_PROP_DATA_FILENAME\fR.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_LU_PROP_WRITE_PROTECT\fR\fR
.ad
.sp .6
.RS 4n
Write protect bit. When specified as "true" or "false", specifies whether the
device behaves as a write protected device.
.sp
Default: "false"
.RE

.SH RETURN VALUES
.sp
.LP
The following values are returned:
.sp
.ne 2
.na
\fB\fBSTMF_STATUS_SUCCESS\fR\fR
.ad
.sp .6
.RS 4n
The API call was successful.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_ERROR_INVALID_ARG\fR\fR
.ad
.sp .6
.RS 4n
Either \fIprop\fR or \fIpropVal\fR is unrecognized.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_ERROR_INVALID_PROPSIZE\fR\fR
.ad
.sp .6
.RS 4n
The size of \fIpropVal\fR is invalid.
.RE

.sp
.ne 2
.na
\fB\fBSTMF_ERROR_NO_PROP\fR\fR
.ad
.sp .6
.RS 4n
The value of \fIprop\fR is unknown for this resource type.
.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
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibstmf\fR(3LIB), \fBstmfCreateLuResource\fR(3STMF),
\fBstmfGetLuResource\fR(3STMF), \fBattributes\fR(5)