usr/src/man/man9f/usb_get_string_descr.9f

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.,
   3 .\" All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH USB_GET_STRING_DESCR 9F "Jan 5, 2004"
   8 .SH NAME
   9 usb_get_string_descr \- Get string descriptor from device
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/usb/usba.h>
  14
  15
  16
  17 \fBint\fR \fBusb_get_string_descr\fR(\fBdev_info_t *\fR\fIdip\fR,
  18      \fBuint16_t\fR \fIlangid\fR, \fBuint8_t\fR \fIindex\fR,
  19      \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI)
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIdip\fR\fR
  31 .ad
  32 .RS 10n
  33 Pointer to the device's \fBdev_info\fR structure.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIlangid\fR\fR
  40 .ad
  41 .RS 10n
  42 Language ID. Currently only USB_LANG_ID (English ascii) is valid.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIindex\fR\fR
  49 .ad
  50 .RS 10n
  51 String index indicating descriptor to retrieve.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIbuf\fR\fR
  58 .ad
  59 .RS 10n
  60 Address into which the string descriptor is placed.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIbuflen\fR\fR
  67 .ad
  68 .RS 10n
  69 Size of buf in bytes.
  70 .RE
  71
  72 .SH DESCRIPTION
  73 .sp
  74 .LP
  75 The \fBusb_get_string_descr()\fR function retrieves a parsed string descriptor
  76 from a device. \fIdip\fR specifies the device, while \fIindex\fR indicates
  77 which descriptor to return.
  78 .sp
  79 .LP
  80 String descriptors provide information about other descriptors, or information
  81 that is encoded in other descriptors, in readable form. Many descriptor types
  82 have one or more index fields which identify string descriptors.  (See
  83 Sections \fI9.5\fR and \fI9.6\fR of the \fIUSB 2.0\fR specification.) For
  84 example, a configuration descriptor's seventh byte contains the string
  85 descriptor index describing a specific configuration.
  86 .sp
  87 .LP
  88 Retrieved descriptors that do not fit into \fIbuflen\fR bytes are truncated.
  89 All returned descriptors are null-terminated.
  90 .SH RETURN VALUES
  91 .sp
  92 .ne 2
  93 .na
  94 \fBUSB_SUCCESS\fR
  95 .ad
  96 .RS 20n
  97 String descriptor is returned in \fIbuf\fR.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fBUSB_INVALID_ARGS\fR
 104 .ad
 105 .RS 20n
 106 \fIdip\fR or \fIbuf\fR are \fBNULL\fR, or \fIindex\fR or \fIbuflen\fR is
 107 \fB0\fR.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fBUSB_FAILURE\fR
 114 .ad
 115 .RS 20n
 116 Descriptor cannot be retrieved.
 117 .RE
 118
 119 .SH CONTEXT
 120 .sp
 121 .LP
 122 May be called from user or kernel context.
 123 .SH EXAMPLES
 124 .sp
 125 .in +2
 126 .nf
 127    /* Get the first string descriptor. */
 128
 129     char buf[SIZE];
 130
 131     if (usb_get_string_descr(
 132         dip, USB_LANG_ID, 0, buf, SIZE) == USB_SUCCESS) {
 133             cmn_err (CE_NOTE, "%s%d: %s",
 134                 ddi_driver_name(dip), ddi_get_instance(dip), buf);
 135     }
 136 .fi
 137 .in -2
 138
 139 .SH ATTRIBUTES
 140 .sp
 141 .LP
 142 See \fBattributes\fR(5) for descriptions of the following attributes:
 143 .sp
 144
 145 .sp
 146 .TS
 147 box;
 148 c | c
 149 l | l .
 150 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 151 _
 152 Architecture    PCI-based systems
 153 _
 154 Interface stability     Committed
 155 .TE
 156
 157 .SH SEE ALSO
 158 .sp
 159 .LP
 160 \fBattributes\fR(5), \fBusb_get_dev_data\fR(9F), \fBusb_string_descr\fR(9S)