usb_string(9) [suse man page]

USB_STRING(9)							   USB Core APIs						     USB_STRING(9)

NAME

       usb_string - returns UTF-8 version of a string descriptor

SYNOPSIS

       int usb_string(struct usb_device * dev, int index, char * buf, size_t size);

ARGUMENTS

       dev
	   the device whose string descriptor is being retrieved

       index
	   the number of the descriptor

       buf
	   where to put the string

       size
	   how big is "buf"?

CONTEXT

       !in_interrupt ()

DESCRIPTION

       This converts the UTF-16LE encoded strings returned by devices, from usb_get_string_descriptor, to null-terminated UTF-8 encoded ones that
       are more usable in most kernel contexts. Note that this function chooses strings in the first language supported by the device.

       This call is synchronous, and may not be used in an interrupt context.

       Returns length of the string (>= 0) or usb_control_msg status (< 0).

COPYRIGHT

Kernel Hackers Manual 2.6.					     July 2010							     USB_STRING(9)

usb_get_string_descr(9F)				   Kernel Functions for Drivers 				  usb_get_string_descr(9F)

NAME

       usb_get_string_descr - Get string descriptor from device

SYNOPSIS

       #include <sys/usb/usba.h>

       int usb_get_string_descr(dev_info_t *dip,
	    uint16_t langid, uint8_t index,
	    char *buf, size_t buflen);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI)

PARAMETERS

       dip	 Pointer to the device's dev_info structure.

       langid	 Language ID. Currently only USB_LANG_ID (English ascii) is valid.

       index	 String index indicating descriptor to retrieve.

       buf	 Address into which the string descriptor is placed.

       buflen	 Size of buf in bytes.

DESCRIPTION

       The  usb_get_string_descr()  function  retrieves  a parsed string descriptor from a device. dip specifies the device, while index indicates
       which descriptor to return.

       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 9.5 and 9.6 of the USB 2.0 specifica-
       tion.) For example, a configuration descriptor's seventh byte contains the string descriptor index describing a specific configuration.

       Retrieved descriptors that do not fit into buflen bytes are truncated. All returned descriptors are null-terminated.

RETURN VALUES

       USB_SUCCESS	   String descriptor is returned in buf.

       USB_INVALID_ARGS    dip or buf are NULL, or index or buflen is 0.

       USB_FAILURE	   Descriptor cannot be retrieved.

CONTEXT

       May be called from user or kernel context.

EXAMPLES

	    /* 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);
	     }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Architecture		     |PCI-based systems 	   |
       +-----------------------------+-----------------------------+
       |Interface stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWusb			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       attributes(5), usb_get_dev_data(9F), usb_string_descr(9S)

SunOS 5.11							    5 Jan 2004						  usb_get_string_descr(9F)