'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.TH usb_get_string_descr 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_get_string_descr \- Get string descriptor from device
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>

\fBint\fR \fBusb_get_string_descr\fR(\fBdev_info_t *\fR\fIdip\fR, 
     \fBuint16_t\fR \fIlangid\fR, \fBuint8_t\fR \fIindex\fR,
     \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 10n
.rt  
Pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlangid\fR\fR
.ad
.RS 10n
.rt  
Language ID. Currently only USB_LANG_ID (English ascii) is valid.
.RE

.sp
.ne 2
.mk
.na
\fB\fIindex\fR\fR
.ad
.RS 10n
.rt  
String index indicating descriptor to retrieve.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbuf\fR\fR
.ad
.RS 10n
.rt  
Address into which the string descriptor is placed.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbuflen\fR\fR
.ad
.RS 10n
.rt  
Size of buf in bytes.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_get_string_descr()\fR function retrieves a parsed string descriptor from a device. \fIdip\fR specifies the device, while \fIindex\fR indicates which descriptor to return.
.sp
.LP
String descriptors provide information about other descriptors, or information that is encoded in other descriptors, in readable form. Many descriptor types have one or more index fields which identify string descriptors.  (See  Sections \fI9.5\fR and \fI9.6\fR of the \fIUSB 2.0\fR specification.) For example, a configuration descriptor's seventh byte contains the string descriptor index describing a specific configuration.
.sp
.LP
Retrieved descriptors that do not fit into \fIbuflen\fR bytes are truncated. All returned descriptors are null-terminated.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 20n
.rt  
String descriptor is returned in \fIbuf\fR.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 20n
.rt  
\fIdip\fR or \fIbuf\fR are \fBNULL\fR, or \fIindex\fR or \fIbuflen\fR is \fB0\fR.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 20n
.rt  
Descriptor cannot be retrieved.
.RE

.SH CONTEXT
.sp
.LP
May be called from user or kernel context.
.SH EXAMPLES
.sp
.in +2
.nf
   /* Get the first string descriptor. */

    char buf[SIZE];

    if (usb_get_string_descr(
        dip, USB_LANG_ID, 0, buf, SIZE) == USB_SUCCESS) {
            cmn_err (CE_NOTE, "%s%d: %s",
                ddi_driver_name(dip), ddi_get_instance(dip), buf);
    }
.fi
.in -2

.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
_
ArchitecturePCI-based systems
_
Interface StabilityCommitted
_
Availabilitysystem/io/usb
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBusb_get_dev_data\fR(9F), \fBusb_string_descr\fR(9S)