| libusb.3 (ca96e26a7165b6267b688a4fb8293c1c22c5771e) | libusb.3 (c8c1f2ec4d81af30c5d45a2eecfb430f44608fca) |
|---|---|
| 1.\" 2.\" Copyright (c) 2009 Sylvestre Gallon 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: --- 17 unchanged lines hidden (view full) --- 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd August 16, 2011 30.Dt LIBUSB 3 31.Os 32.Sh NAME 33.Nm libusb | 1.\" 2.\" Copyright (c) 2009 Sylvestre Gallon 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: --- 17 unchanged lines hidden (view full) --- 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd August 16, 2011 30.Dt LIBUSB 3 31.Os 32.Sh NAME 33.Nm libusb |
| 34. | |
| 35.Nd "USB access library" | 34.Nd "USB access library" |
| 36. 37. | |
| 38.Sh LIBRARY | 35.Sh LIBRARY |
| 39. 40. | |
| 41USB access library (libusb -lusb) | 36USB access library (libusb -lusb) |
| 42. 43. | |
| 44.Sh SYNOPSIS | 37.Sh SYNOPSIS |
| 45. 46. | |
| 47.In libusb.h | 38.In libusb.h |
| 48. 49. | |
| 50.Sh DESCRIPTION 51The 52.Nm 53library contains interfaces for directly managing a usb device. 54The current implementation supports v1.0 of the libusb API. | 39.Sh DESCRIPTION 40The 41.Nm 42library contains interfaces for directly managing a usb device. 43The current implementation supports v1.0 of the libusb API. |
| 55. 56. | |
| 57.Sh LIBRARY INITIALISATION / DEINITIALISATION | 44.Sh LIBRARY INITIALISATION / DEINITIALISATION |
| 58. | |
| 59.Pp | 45.Pp |
| 60. | |
| 61.Ft int 62.Fn libusb_init libusb_context **ctx | 46.Ft int 47.Fn libusb_init libusb_context **ctx |
| 63This function initialises libusb. Must be called at the beginning 64of the program. This function returns 0 on success or LIBUSB_ERROR on | 48This function initialises libusb. 49Must be called at the beginning 50of the program. 51This function returns 0 on success or LIBUSB_ERROR on |
| 65failure. | 52failure. |
| 66. | |
| 67.Pp | 53.Pp |
| 68. | |
| 69.Ft void 70.Fn libusb_exit "libusb_context *ctx" | 54.Ft void 55.Fn libusb_exit "libusb_context *ctx" |
| 71Deinitialise libusb. Must be called at the end of the application. 72. | 56Deinitialise libusb. 57Must be called at the end of the application. |
| 73.Pp | 58.Pp |
| 74. | |
| 75.Ft const char * 76.Fn libusb_strerror "int code" 77Get ASCII representation of the error given by the 78.Fa code 79argument. | 59.Ft const char * 60.Fn libusb_strerror "int code" 61Get ASCII representation of the error given by the 62.Fa code 63argument. |
| 80. 81. | |
| 82.Pp | 64.Pp |
| 83. | |
| 84.Ft void 85.Fn libusb_set_debug "libusb_context *ctx" "int level" 86Set debug to the 87.Fa level 88level. | 65.Ft void 66.Fn libusb_set_debug "libusb_context *ctx" "int level" 67Set debug to the 68.Fa level 69level. |
| 89. | |
| 90.Pp | 70.Pp |
| 91. | |
| 92.Ft ssize_t 93.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" 94Fill into | 71.Ft ssize_t 72.Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" 73Fill into |
| 95.Fa list 96the list of usb device available. All the device created by this 97function must be unref and free when you are done with them. This | 74.Fa list 75the list of usb device available. 76All the device created by this 77function must be unref and free when you are done with them. 78This |
| 98function returns the number of devices in list or a LIBUSB_ERROR code. | 79function returns the number of devices in list or a LIBUSB_ERROR code. |
| 99. | |
| 100.Pp | 80.Pp |
| 101. | |
| 102.Ft void 103.Fn libusb_free_device_list "libusb_device **list" "int unref_devices" | 81.Ft void 82.Fn libusb_free_device_list "libusb_device **list" "int unref_devices" |
| 104Free the list of devices discovered by libusb_get_device_list. If | 83Free the list of devices discovered by libusb_get_device_list. 84If |
| 105.Fa unref_device 106is set to 1 all devices are unref one time. | 85.Fa unref_device 86is set to 1 all devices are unref one time. |
| 107. | |
| 108.Pp | 87.Pp |
| 109. | |
| 110.Ft uint8_t 111.Fn libusb_get_bus_number "libusb_device *dev" 112Returns the number of the bus contained by the device 113.Fa dev. | 88.Ft uint8_t 89.Fn libusb_get_bus_number "libusb_device *dev" 90Returns the number of the bus contained by the device 91.Fa dev. |
| 114. | |
| 115.Pp | 92.Pp |
| 116. | |
| 117.Ft uint8_t 118.Fn libusb_get_device_address "libusb_device *dev" 119Returns the device_address contained by the device 120.Fa dev. | 93.Ft uint8_t 94.Fn libusb_get_device_address "libusb_device *dev" 95Returns the device_address contained by the device 96.Fa dev. |
| 121. | |
| 122.Pp | 97.Pp |
| 123. | |
| 124.Ft enum libusb_speed 125.Fn libusb_get_device_speed "libusb_device *dev" 126Returns the wire speed at which the device is connected. 127See the LIBUSB_SPEED_XXX enums for more information. 128LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed. | 98.Ft enum libusb_speed 99.Fn libusb_get_device_speed "libusb_device *dev" 100Returns the wire speed at which the device is connected. 101See the LIBUSB_SPEED_XXX enums for more information. 102LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed. |
| 129. | |
| 130.Pp | 103.Pp |
| 131. | |
| 132.Ft int 133.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" | 104.Ft int 105.Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" |
| 134Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the | 106Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the |
| 135endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. | 107endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. |
| 136. | |
| 137.Pp | 108.Pp |
| 138. | |
| 139.Ft libusb_device * 140.Fn libusb_ref_device "libusb_device *dev" 141Increment the reference counter of the device 142.Fa dev. | 109.Ft libusb_device * 110.Fn libusb_ref_device "libusb_device *dev" 111Increment the reference counter of the device 112.Fa dev. |
| 143. | |
| 144.Pp | 113.Pp |
| 145. | |
| 146.Ft void 147.Fn libusb_unref_device "libusb_device *dev" 148Decrement the reference counter of the device 149.Fa dev. | 114.Ft void 115.Fn libusb_unref_device "libusb_device *dev" 116Decrement the reference counter of the device 117.Fa dev. |
| 150. | |
| 151.Pp | 118.Pp |
| 152. | |
| 153.Ft int 154.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" | 119.Ft int 120.Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" |
| 155Open a device and obtain a device_handle. Returns 0 on success, 156LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS 157on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been | 121Open a device and obtain a device_handle. 122Returns 0 on success, 123LIBUSB_ERROR_NO_MEM on memory allocation problem, LIBUSB_ERROR_ACCESS 124on permission problem, LIBUSB_ERROR_NO_DEVICE if the device has been |
| 158disconnected and a LIBUSB_ERROR code on error. | 125disconnected and a LIBUSB_ERROR code on error. |
| 159. | |
| 160.Pp | 126.Pp |
| 161. | |
| 162.Ft libusb_device_handle * 163.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" | 127.Ft libusb_device_handle * 128.Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" |
| 164Convenience function to open a device with is 165.Fa vid 166and | 129Convenience function to open a device with is 130.Fa vid 131and |
| 167.Fa pid. 168Returns NULL on error. | 132.Fa pid. 133Returns NULL on error. |
| 169. | |
| 170.Pp | 134.Pp |
| 171. | |
| 172.Ft void 173.Fn libusb_close "libusb_device_handle *devh" 174Close a device handle. | 135.Ft void 136.Fn libusb_close "libusb_device_handle *devh" 137Close a device handle. |
| 175. | |
| 176.Pp | 138.Pp |
| 177. | |
| 178.Ft libusb_device * 179.Fn libusb_get_device "libusb_device_handle *devh" 180Get the device contained by devh. 181Returns NULL on error. | 139.Ft libusb_device * 140.Fn libusb_get_device "libusb_device_handle *devh" 141Get the device contained by devh. 142Returns NULL on error. |
| 182. | |
| 183.Pp | 143.Pp |
| 184. | |
| 185.Ft int 186.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" | 144.Ft int 145.Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" |
| 187Returns the bConfiguration value of the current configuration. Returns 0 188on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected | 146Returns the bConfiguration value of the current configuration. 147Returns 0 148on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected |
| 189and a LIBUSB_ERROR code on error. | 149and a LIBUSB_ERROR code on error. |
| 190. | |
| 191.Pp | 150.Pp |
| 192. | |
| 193.Ft int 194.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" 195Set the active configuration 196.Fa config 197for the device contained by 198.Fa devh. 199This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested | 151.Ft int 152.Fn libusb_set_configuration "libusb_device_handle *devh" "int config" 153Set the active configuration 154.Fa config 155for the device contained by 156.Fa devh. 157This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested |
| 200configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently 201claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a | 158configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently 159claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a |
| 202LIBUSB_ERROR code on failure. | 160LIBUSB_ERROR code on failure. |
| 203. | |
| 204.Pp | 161.Pp |
| 205. | |
| 206.Ft int 207.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" 208Claim an interface in a given libusb_handle 209.Fa devh. | 162.Ft int 163.Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" 164Claim an interface in a given libusb_handle 165.Fa devh. |
| 210This is a non-blocking function. It returns 0 success, LIBUSB_ERROR_NOT_FOUND 211if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or 212driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has | 166This is a non-blocking function. 167It returns 0 success, LIBUSB_ERROR_NOT_FOUND 168if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or 169driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has |
| 213been disconnected and a LIBUSB_ERROR code on failure. | 170been disconnected and a LIBUSB_ERROR code on failure. |
| 214. | |
| 215.Pp | 171.Pp |
| 216. | |
| 217.Ft int 218.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" | 172.Ft int 173.Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" |
| 219This function release an interface. All the claimed interface must be released 220before closing a device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the 221interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been | 174This function release an interface. 175All the claimed interface must be released 176before closing a device. 177Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the 178interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been |
| 222disconnected and LIBUSB_ERROR on failure. | 179disconnected and LIBUSB_ERROR on failure. |
| 223. | |
| 224.Pp | 180.Pp |
| 225. | |
| 226.Ft int 227.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" | 181.Ft int 182.Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" |
| 228Activate an alternate setting for an interface. Returns 0 on success, 229LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested 230setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been | 183Activate an alternate setting for an interface. 184Returns 0 on success, 185LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested 186setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been |
| 231disconnected and LIBUSB_ERROR code on failure. | 187disconnected and LIBUSB_ERROR code on failure. |
| 232. | |
| 233.Pp | 188.Pp |
| 234. | |
| 235.Ft int 236.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" | 189.Ft int 190.Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" |
| 237Clear an halt/stall for a endpoint. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND 238if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been | 191Clear an halt/stall for a endpoint. 192Returns 0 on success, LIBUSB_ERROR_NOT_FOUND 193if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been |
| 239disconnected and a LIBUSB_ERROR code on failure. | 194disconnected and a LIBUSB_ERROR code on failure. |
| 240. | |
| 241.Pp | 195.Pp |
| 242. | |
| 243.Ft int 244.Fn libusb_reset_device "libusb_device_handle *devh" | 196.Ft int 197.Fn libusb_reset_device "libusb_device_handle *devh" |
| 245Perform an USB port reset for an usb device. Returns 0 on success, | 198Perform an USB port reset for an usb device. 199Returns 0 on success, |
| 246LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has 247been disconnected and a LIBUSB_ERROR code on failure. | 200LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has 201been disconnected and a LIBUSB_ERROR code on failure. |
| 248. | |
| 249.Pp | 202.Pp |
| 250. | |
| 251.Ft int 252.Fn libusb_check_connected "libusb_device_handle *devh" | 203.Ft int 204.Fn libusb_check_connected "libusb_device_handle *devh" |
| 253Test if USB device is still connected. Returns 0 on success, | 205Test if USB device is still connected. 206Returns 0 on success, |
| 254LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR 255code on failure. | 207LIBUSB_ERROR_NO_DEVICE if has been disconnected and a LIBUSB_ERROR 208code on failure. |
| 256. | |
| 257.Pp | 209.Pp |
| 258. | |
| 259.Ft int 260.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" | 210.Ft int 211.Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" |
| 261Determine if a driver is active on a interface. Returns 0 if no kernel driver 262is active, returns 1 if a kernel driver is active, returns LIBUSB_ERROR_NO_DEVICE | 212Determine if a driver is active on a interface. 213Returns 0 if no kernel driver 214is active, returns 1 if a kernel driver is active, 215returns LIBUSB_ERROR_NO_DEVICE |
| 263if the device has been disconnected and returns a LIBUSB_ERROR code on failure. | 216if the device has been disconnected and returns a LIBUSB_ERROR code on failure. |
| 264. | |
| 265.Pp | 217.Pp |
| 266. | |
| 267.Ft int 268.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 269or 270.Ft int 271.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 272Gets the name of the driver attached to the given 273.Fa device 274and --- 4 unchanged lines hidden (view full) --- 279.Fa namelen . 280Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached 281to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does 282not exist. 283This function is non-portable. 284The buffer pointed to by 285.Fa name 286is only zero terminated on success. | 218.Ft int 219.Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 220or 221.Ft int 222.Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen" 223Gets the name of the driver attached to the given 224.Fa device 225and --- 4 unchanged lines hidden (view full) --- 230.Fa namelen . 231Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached 232to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does 233not exist. 234This function is non-portable. 235The buffer pointed to by 236.Fa name 237is only zero terminated on success. |
| 287. | |
| 288.Pp | 238.Pp |
| 289. | |
| 290.Ft int 291.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" 292or 293.Ft int 294.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface" 295Detach a kernel driver from an interface. 296This is needed to claim an interface required by a kernel driver. 297Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active, | 239.Ft int 240.Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" 241or 242.Ft int 243.Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface" 244Detach a kernel driver from an interface. 245This is needed to claim an interface required by a kernel driver. 246Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active, |
| 298LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. This function is non-portable. 299. | 247LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, 248LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 249and a LIBUSB_ERROR code on failure. 250This function is non-portable. |
| 300.Pp | 251.Pp |
| 301. | |
| 302.Ft int 303.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" | 252.Ft int 253.Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" |
| 304Re-attach an interface kernel driver previously detached. Returns 0 on success, 305LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE 306if the device has been disconnect, LIBUSB_ERROR_BUSY if the driver cannot be 307attached because the interface is claimed by a program or driver and a | 254Re-attach an interface kernel driver previously detached. 255Returns 0 on success, 256LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, 257LIBUSB_ERROR_NO_DEVICE 258if the device has been disconnect, LIBUSB_ERROR_BUSY if the driver cannot be 259attached because the interface is claimed by a program or driver and a |
| 308LIBUSB_ERROR code on failure. | 260LIBUSB_ERROR code on failure. |
| 309. | |
| 310.Pp | 261.Pp |
| 311. | |
| 312.Sh USB DESCRIPTORS | 262.Sh USB DESCRIPTORS |
| 313. | |
| 314.Pp | 263.Pp |
| 315. | |
| 316.Ft int 317.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" 318Get the USB device descriptor for the device 319.Fa dev. | 264.Ft int 265.Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" 266Get the USB device descriptor for the device 267.Fa dev. |
| 320This is a non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on | 268This is a non-blocking function. 269Returns 0 on success and a LIBUSB_ERROR code on |
| 321failure. | 270failure. |
| 322. | |
| 323.Pp | 271.Pp |
| 324.Ft int | 272.Ft int |
| 325.Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" | 273.Fn libsub_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" |
| 326Get the USB configuration descriptor for the active configuration. Returns 0 on 327success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state | 274Get the USB configuration descriptor for the active configuration. 275Returns 0 on 276success, returns LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state |
| 328and returns another LIBUSB_ERROR code on error. | 277and returns another LIBUSB_ERROR code on error. |
| 329. | |
| 330.Pp | 278.Pp |
| 331.Ft int | 279.Ft int |
| 332.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" | 280.Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" |
| 333Get USB configuration descriptor based on its index | 281Get USB configuration descriptor based on its index |
| 334.Fa idx. | 282.Fa idx. |
| 335Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist | 283Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist |
| 336and returns another LIBUSB_ERROR code on error. | 284and returns another LIBUSB_ERROR code on error. |
| 337. | |
| 338.Pp 339.Ft int 340.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" | 285.Pp 286.Ft int 287.Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" |
| 341Get a USB configuration descriptor with a specific bConfigurationValue. This is 342a non-blocking function which does not send request through the device. Returns 0 343on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and another | 288Get a USB configuration descriptor with a specific bConfigurationValue. 289This is 290a non-blocking function which does not send request through the device. 291Returns 0 292on success, LIBUSB_ERROR_NOT_FOUND if the configuration 293does not exist and another |
| 344LIBUSB_ERROR code on failure. | 294LIBUSB_ERROR code on failure. |
| 345. | |
| 346.Pp 347.Ft void 348.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" 349Free a configuration descriptor. | 295.Pp 296.Ft void 297.Fn libusb_free_config_descriptor "libusb_config_descriptor *config" 298Free a configuration descriptor. |
| 350. | |
| 351.Pp 352.Ft int 353.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" 354Retrieve a string descriptor in C style ascii. | 299.Pp 300.Ft int 301.Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" 302Retrieve a string descriptor in C style ascii. |
| 355Returns a positive number of bytes in the resulting ASCII string on success and a LIBUSB_ERROR code on failure. 356. | 303Returns a positive number of bytes in the resulting ASCII string 304on success and a LIBUSB_ERROR code on failure. |
| 357.Pp | 305.Pp |
| 358. | |
| 359.Sh USB ASYNCHRONOUS I/O | 306.Sh USB ASYNCHRONOUS I/O |
| 360. | |
| 361.Pp 362.Ft struct libusb_transfer * 363.Fn libusb_alloc_transfer "int iso_packets" 364Allocate a transfer with 365.Fa iso_packets 366numbers of isochronous packet descriptors. 367Returns NULL on error. | 307.Pp 308.Ft struct libusb_transfer * 309.Fn libusb_alloc_transfer "int iso_packets" 310Allocate a transfer with 311.Fa iso_packets 312numbers of isochronous packet descriptors. 313Returns NULL on error. |
| 368. | |
| 369.Pp 370.Ft void 371.Fn libusb_free_transfer "struct libusb_transfer *tr" 372Free a transfer. | 314.Pp 315.Ft void 316.Fn libusb_free_transfer "struct libusb_transfer *tr" 317Free a transfer. |
| 373. | |
| 374.Pp 375.Ft int 376.Fn libusb_submit_transfer "struct libusb_transfer *tr" 377This function will submit a transfer and returns immediately. | 318.Pp 319.Ft int 320.Fn libusb_submit_transfer "struct libusb_transfer *tr" 321This function will submit a transfer and returns immediately. |
| 378Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and | 322Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if 323the device has been disconnected and |
| 379LIBUSB_ERROR code on other failure. | 324LIBUSB_ERROR code on other failure. |
| 380. | |
| 381.Pp 382.Ft int 383.Fn libusb_cancel_transfer "struct libusb_transfer *tr" 384This function asynchronously cancel a transfer. 385Returns 0 on success and LIBUSB_ERROR code on failure. | 325.Pp 326.Ft int 327.Fn libusb_cancel_transfer "struct libusb_transfer *tr" 328This function asynchronously cancel a transfer. 329Returns 0 on success and LIBUSB_ERROR code on failure. |
| 386. | |
| 387.Pp 388.Sh USB SYNCHRONOUS I/O | 330.Pp 331.Sh USB SYNCHRONOUS I/O |
| 389. | |
| 390.Pp 391.Ft int 392.Fn libusb_control_transfer "libusb_device_handle *devh" "uint8_t bmRequestType" "uint8_t bRequest" "uint16_t wValue" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout" 393Perform a USB control transfer. 394Returns the actual number of bytes 395transferred on success in the range from and including zero until and 396including 397.Fa wLength . 398On error a libusb error code is returned, for example 399LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the 400control request was not supported, LIBUSB_ERROR_NO_DEVICE if the 401device has been disconnected or another LIBUSB_ERROR code on other failures. 402The libusb error codes are always negative. | 332.Pp 333.Ft int 334.Fn libusb_control_transfer "libusb_device_handle *devh" "uint8_t bmRequestType" "uint8_t bRequest" "uint16_t wValue" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout" 335Perform a USB control transfer. 336Returns the actual number of bytes 337transferred on success in the range from and including zero until and 338including 339.Fa wLength . 340On error a libusb error code is returned, for example 341LIBUSB_ERROR_TIMEOUT if the transfer timeout, LIBUSB_ERROR_PIPE if the 342control request was not supported, LIBUSB_ERROR_NO_DEVICE if the 343device has been disconnected or another LIBUSB_ERROR code on other failures. 344The libusb error codes are always negative. |
| 403. | |
| 404.Pp 405.Ft int 406.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 407Perform an USB bulk transfer. 408A timeout value of zero means no timeout. 409The timeout value is given in milliseconds. | 345.Pp 346.Ft int 347.Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 348Perform an USB bulk transfer. 349A timeout value of zero means no timeout. 350The timeout value is given in milliseconds. |
| 410Returns 0 on success, LIBUSB_ERROR_TIMEOUT 411if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 412supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 413LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and | 351Returns 0 on success, LIBUSB_ERROR_TIMEOUT 352if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 353supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 354LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and |
| 414LIBUSB_ERROR code on other failure. | 355LIBUSB_ERROR code on other failure. |
| 415. | |
| 416.Pp 417.Ft int 418.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 419Perform an USB Interrupt transfer. 420A timeout value of zero means no timeout. 421The timeout value is given in milliseconds. | 356.Pp 357.Ft int 358.Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" 359Perform an USB Interrupt transfer. 360A timeout value of zero means no timeout. 361The timeout value is given in milliseconds. |
| 422Returns 0 on success, LIBUSB_ERROR_TIMEOUT 423if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 424supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 425LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and | 362Returns 0 on success, LIBUSB_ERROR_TIMEOUT 363if the transfer timeout, LIBUSB_ERROR_PIPE if the control request was not 364supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, 365LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and |
| 426LIBUSB_ERROR code on other failure. | 366LIBUSB_ERROR code on other failure. |
| 427. | |
| 428.Pp 429.Sh USB EVENTS | 367.Pp 368.Sh USB EVENTS |
| 430. | |
| 431.Pp 432.Ft int 433.Fn libusb_try_lock_events "libusb_context *ctx" 434Try to acquire the event handling lock. 435Returns 0 if the lock was obtained and 1 if not. | 369.Pp 370.Ft int 371.Fn libusb_try_lock_events "libusb_context *ctx" 372Try to acquire the event handling lock. 373Returns 0 if the lock was obtained and 1 if not. |
| 436. | |
| 437.Pp 438.Ft void 439.Fn libusb_lock_events "libusb_context *ctx" | 374.Pp 375.Ft void 376.Fn libusb_lock_events "libusb_context *ctx" |
| 440Acquire the event handling lock. This function is blocking. 441. | 377Acquire the event handling lock. 378This function is blocking. |
| 442.Pp 443.Ft void 444.Fn libusb_unlock_events "libusb_context *ctx" | 379.Pp 380.Ft void 381.Fn libusb_unlock_events "libusb_context *ctx" |
| 445Release the event handling lock. This will wake up any thread blocked | 382Release the event handling lock. 383This will wake up any thread blocked |
| 446on libusb_wait_for_event(). | 384on libusb_wait_for_event(). |
| 447. | |
| 448.Pp 449.Ft int 450.Fn libusb_event_handling_ok "libusb_context *ctx" | 385.Pp 386.Ft int 387.Fn libusb_event_handling_ok "libusb_context *ctx" |
| 451Determine if it still OK for this thread to be doing event handling. Returns 1 452if event handling can start or continue. Returns 0 if this thread must give up | 388Determine if it still OK for this thread to be doing event handling. 389Returns 1 390if event handling can start or continue. 391Returns 0 if this thread must give up |
| 453the events lock. | 392the events lock. |
| 454. | |
| 455.Pp 456.Ft int 457.Fn libusb_event_handler_active "libusb_context *ctx" | 393.Pp 394.Ft int 395.Fn libusb_event_handler_active "libusb_context *ctx" |
| 458Determine if an active thread is handling events. Returns 1 if yes and 0 if there | 396Determine if an active thread is handling events. 397Returns 1 if yes and 0 if there |
| 459are no threads currently handling events. | 398are no threads currently handling events. |
| 460. | |
| 461.Pp 462.Ft void 463.Fn libusb_lock_event_waiters "libusb_context *ctx" | 399.Pp 400.Ft void 401.Fn libusb_lock_event_waiters "libusb_context *ctx" |
| 464Acquire the event_waiters lock. This lock is designed to be obtained under the | 402Acquire the event_waiters lock. 403This lock is designed to be obtained under the |
| 465situation where you want to be aware when events are completed, but some other 466thread is event handling so calling libusb_handle_events() is not allowed. | 404situation where you want to be aware when events are completed, but some other 405thread is event handling so calling libusb_handle_events() is not allowed. |
| 467. | |
| 468.Pp 469.Ft void 470.Fn libusb_unlock_event_waiters "libusb_context *ctx" 471Release the event_waiters lock. | 406.Pp 407.Ft void 408.Fn libusb_unlock_event_waiters "libusb_context *ctx" 409Release the event_waiters lock. |
| 472. | |
| 473.Pp | 410.Pp |
| 474.Ft int | 411.Ft int |
| 475.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" | 412.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" |
| 476Wait for another thread to signal completion of an event. Must be called 477with the event waiters lock held, see libusb_lock_event_waiters(). This will | 413Wait for another thread to signal completion of an event. 414Must be called 415with the event waiters lock held, see libusb_lock_event_waiters(). 416This will |
| 478block until the timeout expires or a transfer completes or a thread releases | 417block until the timeout expires or a transfer completes or a thread releases |
| 479the event handling lock through libusb_unlock_events(). Returns 0 after a | 418the event handling lock through libusb_unlock_events(). 419Returns 0 after a |
| 480transfer completes or another thread stops event handling, returns 1 if the 481timeout expired. | 420transfer completes or another thread stops event handling, returns 1 if the 421timeout expired. |
| 482. | |
| 483.Pp 484.Ft int 485.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" | 422.Pp 423.Ft int 424.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" |
| 486Handle any pending events by checking if timeouts have expired and by 487checking the set of file descriptors for activity. Returns 0 on success, or a | 425Handle any pending events by checking if timeouts have expired and by 426checking the set of file descriptors for activity. 427Returns 0 on success, or a |
| 488LIBUSB_ERROR code on failure. | 428LIBUSB_ERROR code on failure. |
| 489. | |
| 490.Pp 491.Ft int 492.Fn libusb_handle_events "libusb_context *ctx" | 429.Pp 430.Ft int 431.Fn libusb_handle_events "libusb_context *ctx" |
| 493Handle any pending events in blocking mode with a sensible timeout. Returns 0 | 432Handle any pending events in blocking mode with a sensible timeout. 433Returns 0 |
| 494on success, returns a LIBUSB_ERROR code on failure. | 434on success, returns a LIBUSB_ERROR code on failure. |
| 495. | |
| 496.Pp 497.Ft int 498.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" 499Handle any pending events by polling file desciptors, without checking if | 435.Pp 436.Ft int 437.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" 438Handle any pending events by polling file desciptors, without checking if |
| 500another threads are already doing so. Must be called with the event lock held. 501. | 439another threads are already doing so. 440Must be called with the event lock held. |
| 502.Pp 503.Ft int 504.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" | 441.Pp 442.Ft int 443.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" |
| 505Determine the next internal timeout that libusb needs to handle. Returns 0 | 444Determine the next internal timeout that libusb needs to handle. 445Returns 0 |
| 506if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR 507code on failure. | 446if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR 447code on failure. |
| 508. | |
| 509.Pp 510.Ft void 511.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" 512Register notification functions for file descriptor additions/removals. 513These functions will be invoked for every new or removed file descriptor 514that libusb uses as an event source. | 448.Pp 449.Ft void 450.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" 451Register notification functions for file descriptor additions/removals. 452These functions will be invoked for every new or removed file descriptor 453that libusb uses as an event source. |
| 515. | |
| 516.Pp 517.Ft const struct libusb_pollfd ** 518.Fn libusb_get_pollfds "libusb_context *ctx" | 454.Pp 455.Ft const struct libusb_pollfd ** 456.Fn libusb_get_pollfds "libusb_context *ctx" |
| 519Retrive a list of file descriptors that should be polled by your main loop as 520libusb event sources. Returns a NULL-terminated list on success or NULL on failure. 521. | 457Retrive a list of file descriptors that should be polled by your main loop as 458libusb event sources. 459Returns a NULL-terminated list on success or NULL on failure. |
| 522.Sh LIBUSB VERSION 0.1 COMPATIBILITY 523.Pp 524The library is also compliant with LibUSB version 0.1.12. 525.Pp 526.Fn usb_open 527.Fn usb_close 528.Fn usb_get_string 529.Fn usb_get_string_simple --- 20 unchanged lines hidden (view full) --- 550.Fn usb_set_debug 551.Fn usb_find_busses 552.Fn usb_find_devices 553.Fn usb_device 554.Fn usb_get_busses 555.Fn usb_check_connected 556.Fn usb_get_driver_np 557.Fn usb_detach_kernel_driver_np | 460.Sh LIBUSB VERSION 0.1 COMPATIBILITY 461.Pp 462The library is also compliant with LibUSB version 0.1.12. 463.Pp 464.Fn usb_open 465.Fn usb_close 466.Fn usb_get_string 467.Fn usb_get_string_simple --- 20 unchanged lines hidden (view full) --- 488.Fn usb_set_debug 489.Fn usb_find_busses 490.Fn usb_find_devices 491.Fn usb_device 492.Fn usb_get_busses 493.Fn usb_check_connected 494.Fn usb_get_driver_np 495.Fn usb_detach_kernel_driver_np |
| 558. | |
| 559.Sh SEE ALSO 560.Xr libusb20 3 , 561.Xr usb 4 , 562.Xr usbconfig 8 563.Pp 564.Pa http://libusb.sourceforge.net/ | 496.Sh SEE ALSO 497.Xr libusb20 3 , 498.Xr usb 4 , 499.Xr usbconfig 8 500.Pp 501.Pa http://libusb.sourceforge.net/ |
| 565. | |
| 566.Sh HISTORY | 502.Sh HISTORY |
| 567. | |
| 568.Nm 569support first appeared in 570.Fx 8.0 . | 503.Nm 504support first appeared in 505.Fx 8.0 . |