1.\" 2.\" The contents of this file are subject to the terms of the 3.\" Common Development and Distribution License (the "License"). 4.\" You may not use this file except in compliance with the License. 5.\" 6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7.\" or http://www.opensolaris.org/os/licensing. 8.\" See the License for the specific language governing permissions 9.\" and limitations under the License. 10.\" 11.\" When distributing Covered Code, include this CDDL HEADER in each 12.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13.\" If applicable, add the following below this CDDL HEADER, with the 14.\" fields enclosed by brackets "[]" replaced with your own identifying 15.\" information: Portions Copyright [yyyy] [name of copyright owner] 16.\" 17.\" 18.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved 19.\" Copyright 2017 Nexenta Systems, Inc. 20.\" 21.Dd January 25, 2017 22.Dt DEVID_GET 3DEVID 23.Os 24.Sh NAME 25.Nm devid_get , 26.Nm devid_free , 27.Nm devid_get_minor_name , 28.Nm devid_deviceid_to_nmlist , 29.Nm devid_free_nmlist , 30.Nm devid_compare , 31.Nm devid_sizeof , 32.Nm devid_valid , 33.Nm devid_str_encode , 34.Nm devid_str_decode , 35.Nm devid_str_from_path , 36.Nm devid_str_free 37.Nd device ID interfaces for user applications 38.Sh SYNOPSIS 39.Lb libdevid 40.In devid.h 41.Ft int 42.Fo devid_get 43.Fa "int fd" 44.Fa "ddi_devid_t *retdevid" 45.Fc 46.Ft void 47.Fo devid_free 48.Fa "ddi_devid_t devid" 49.Fc 50.Ft int 51.Fo devid_get_minor_name 52.Fa "int fd" 53.Fa "char **retminor_name" 54.Fc 55.Ft int 56.Fo devid_deviceid_to_nmlist 57.Fa "char *search_path" 58.Fa "ddi_devid_t devid" 59.Fa "char *minor_name" 60.Fa "devid_nmlist_t **retlist" 61.Fc 62.Ft void 63.Fo devid_free_nmlist 64.Fa "devid_nmlist_t *list" 65.Fc 66.Ft int 67.Fo devid_compare 68.Fa "ddi_devid_t devid1" 69.Fa "ddi_devid_t devid2" 70.Fc 71.Ft size_t 72.Fo devid_sizeof 73.Fa "ddi_devid_t devid" 74.Fc 75.Ft int 76.Fo devid_valid 77.Fa "ddi_devid_t devid" 78.Fc 79.Ft char * 80.Fo devid_str_encode 81.Fa "ddi_devid_t devid" 82.Fa "char *minor_name" 83.Fc 84.Ft int 85.Fo devid_str_decode 86.Fa "char *devidstr" 87.Fa "ddi_devid_t *retdevid" 88.Fa "char **retminor_name" 89.Fc 90.Ft char * 91.Fo devid_str_from_path 92.Fa "const char *path" 93.Fc 94.Ft void 95.Fo devid_str_free 96.Fa "char *str" 97.Fc 98.Sh DESCRIPTION 99These functions provide unique identifiers 100.Pq device ID 101for devices. 102Applications and device drivers use these functions to identify and locate 103devices, independent of the device's physical connection or its logical device 104name or number. 105.Pp 106The 107.Fn devid_get 108function returns in 109.Fa retdevid 110the device ID for the device associated with the open file descriptor 111.Fa fd , 112which refers to any device. 113It returns an error if the device does not have an associated device ID. 114The caller must free the memory allocated for 115.Fa retdevid 116using the 117.Fn devid_free 118function. 119.Pp 120The 121.Fn devid_free 122function frees the space that was allocated for the returned 123.Fa devid 124by 125.Fn devid_get 126and 127.Fn devid_str_decode . 128.Pp 129The 130.Fn devid_get_minor_name 131function returns the minor name, in 132.Fa retminor_name , 133for the device associated with the open file descriptor 134.Fa fd . 135This name is specific to the particular minor number, but is 136.Qq instance number 137specific. 138The caller of this function must free the memory allocated for the returned 139.Fa retminor_name 140string using 141.Fn devid_str_free . 142.Pp 143The 144.Fn devid_deviceid_to_nmlist 145function returns an array of 146.Fa devid_nmlist 147structures, where each entry matches the 148.Fa devid 149and 150.Fa minor_name 151passed in. 152If the 153.Fa minor_name 154specified is one of the special values 155.Po 156.Dv DEVID_MINOR_NAME_ALL , 157.Dv DEVID_MINOR_NAME_ALL_CHR , 158or 159.Dv DEVID_MINOR_NAME_ALL_BLK 160.Pc , 161then all minor names associated with 162.Fa devid 163which also meet the special 164.Fa minor_name 165filtering requirements are returned. 166The 167.Fa devid_nmlist 168structure contains the device name and device number. 169The last entry of the array contains a null pointer for the 170.Fa devname 171and 172.Dv NODEV 173for the device number. 174This function traverses the file tree, starting at 175.Fa search_path . 176For each device with a matching device ID and minor name tuple, a device name 177and device number are added to the 178.Fa retlist . 179If no matches are found, an error is returned. 180The caller of this function must free the memory allocated for the returned 181array with the 182.Fn devid_free_nmlist 183function. 184This function may take a long time to complete if called with the device ID of 185an unattached device. 186.Pp 187The 188.Fn devid_free_nmlist 189function frees the memory allocated by the 190.Fn devid_deviceid_to_nmlist 191function and returned in the 192.Fa retlist . 193.Pp 194The 195.Fn devid_compare 196function compares two device IDs and determines both equality and sort order. 197The function returns an integer greater than 0 if the device ID pointed to by 198.Fa devid1 199is greater than the device ID pointed to by 200.Fa devid2 . 201It returns 0 if the device ID pointed to by 202.Fa devid1 203is equal to the device ID pointed to by 204.Fa devid2 . 205It returns an integer less than 0 if the device ID pointed to by 206.Fa devid1 207is less than the device ID pointed to by 208.Fa devid2 . 209This function is the only valid mechanism to determine the equality of two 210devids. 211This function may indicate equality for arguments which by simple inspection 212appear different. 213.Pp 214The 215.Fn devid_sizeof 216function returns the size of 217.Fa devid 218in bytes. 219.Pp 220The 221.Fn devid_valid 222function validates the format of a 223.Fa devid . 224It returns 1 if the format is valid, and 0 if invalid. 225This check may not be as complete as the corresponding kernel function 226.Fn ddi_devid_valid 227.Po see 228.Xr ddi_devid_compare 9F 229.Pc . 230.Pp 231The 232.Fn devid_str_encode 233function encodes a 234.Fa devid 235and 236.Fa minor_name 237into a null-terminated ASCII string, returning a pointer to that string. 238To avoid shell conflicts, the 239.Fa devid 240portion of the string is limited to uppercase and lowercase letters, digits, and 241the plus 242.Pq Qq Sy \&+ , 243minus 244.Pq Qq Sy \&- , 245period 246.Pq Qq Sy \&. , 247equals 248.Pq Qq Sy \&= , 249underscore 250.Pq Qq Sy \&_ , 251tilde 252.Pq Qq Sy \&~ , 253and comma 254.Pq Qq Sy \&, 255characters. 256If there is an ASCII quote character in the binary form of a 257.Fa devid , 258the string representation will be in hex_id form, not ascii_id form. 259The comma 260.Pq Qq Sy \&, 261character is added for 262.Qq id1, 263at the head of the string 264.Fa devid . 265If both a 266.Fa devid 267and a 268.Fa minor_name 269are non-null, a slash 270.Pq Qq Sy \&/ 271is used to separate the 272.Fa devid 273from the 274.Fa minor_name 275in the encoded string. 276If 277.Fa minor_name 278is null, only the 279.Fa devid 280is encoded. 281If the 282.Fa devid 283is null then the special string 284.Qq id0 285is returned. 286Note that you cannot compare the returned string against another string with 287.Xr strcmp 3C 288to determine devid equality. 289The string returned must be freed by calling 290.Fn devid_str_free . 291.Pp 292The 293.Fn devid_str_from_path 294is similar to 295.Fn devid_str_encode , 296but takes a 297.Fa path 298argument instead. 299If 300.Fa path 301includes the minor name, it will be encoded as well. 302The string returned must be freed by calling 303.Fn devid_str_free . 304.Pp 305The 306.Fn devid_str_decode 307function takes a string previously produced by the 308.Fn devid_str_encode 309or 310.Fn ddi_devid_str_encode 311.Po see 312.Xr ddi_devid_compare 9F 313.Pc 314function and decodes the contained device ID and minor name, allocating and 315returning pointers to the extracted parts via the 316.Fa retdevid 317and 318.Fa retminor_name 319arguments. 320If the special 321.Fa devidstr 322.Qq id0 323was specified, the returned device ID and minor name will both be null. 324A non-null returned devid must be freed by the caller by the 325.Fn devid_free 326function. 327A non-null returned minor name must be freed by calling 328.Fn devid_str_free . 329.Pp 330The 331.Fn devid_str_free 332function frees the character string returned by 333.Fn devid_str_encode 334and the 335.Fa retminor_name 336argument returned by 337.Fn devid_str_decode 338and 339.Fn devid_get_minor_name . 340.Sh RETURN VALUES 341Upon successful completion, the 342.Fn devid_get , 343.Fn devid_get_minor_name , 344.Fn devid_str_decode , 345and 346.Fn devid_deviceid_to_nmlist 347functions return 0. 348Otherwise, they return -1. 349.Pp 350The 351.Fn devid_compare 352function returns the following values: 353.Bl -tag -width Ds 354.It Sy -1 355The device ID pointed to by 356.Fa devid1 357is less than the device ID pointed to by 358.Fa devid2 . 359.It Sy 0 360The device ID pointed to by 361.Fa devid1 362is equal to the device ID pointed to by 363.Fa devid2 . 364.It Sy 1 365The device ID pointed to by 366.Fa devid1 367is greater than the device ID pointed to by 368.Fa devid2 . 369.El 370.Pp 371The 372.Fn devid_sizeof 373function returns the size of 374.Fa devid 375in bytes. 376If 377.Fa devid 378is null, the number of bytes that must be allocated and initialized to determine 379the size of a complete device ID is returned. 380.Pp 381The 382.Fn devid_valid 383function returns 1 if the 384.Fa devid 385is valid and 0 if the 386.Fa devid 387is invalid. 388.Pp 389The 390.Fn devid_str_encode 391and 392.Fn devid_str_from_path 393functions return NULL to indicate failure. 394Failure may be caused by attempting to encode an invalid string. 395If the return value is non-null, the caller must free the returned string by 396using the 397.Fn devid_str_free 398function. 399.Sh EXAMPLES 400.Bl -tag -width Ds 401.It Xo 402.Sy Example 1 403Using 404.Fn devid_get , 405.Fn devid_get_minor_name , 406and 407.Fn devid_str_encode 408.Xc 409The following example shows the proper use of 410.Fn devid_get , 411.Fn devid_get_minor_name , 412and 413.Fn devid_str_encode 414to free the space allocated for 415.Fa devid , 416.Fa minor_name 417and encoded 418.Fa devid . 419.Bd -literal 420int fd; 421ddi_devid_t devid; 422char *minor_name, *devidstr; 423 424if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) { 425 ... 426} 427if (devid_get(fd, &devid) != 0) { 428 ... 429} 430if (devid_get_minor_name(fd, &minor_name) != 0) { 431 ... 432} 433if ((devidstr = devid_str_encode(devid, minor_name)) == 0) { 434 ... 435} 436printf("devid %s\en", devidstr); 437devid_str_free(devidstr); 438devid_free(devid); 439devid_str_free(minor_name); 440.Ed 441.It Xo 442.Sy Example 2 443Using 444.Fn devid_deviceid_to_nmlist 445and 446.Fn devid_free_nmlist 447.Xc 448The following example shows the proper use of 449.Fn devid_deviceid_to_nmlist 450and 451.Fn devid_free_nmlist : 452.Bd -literal 453devid_nmlist_t *list = NULL; 454int err; 455 456if (devid_deviceid_to_nmlist("/dev/rdsk", devid, 457 minor_name, &list)) 458 return (-1); 459/* loop through list and process device names and numbers */ 460devid_free_nmlist(list); 461.Ed 462.El 463.Sh MT-LEVEL 464.Sy MT-Safe 465.Sh INTERFACE STABILITY 466.Sy Stable 467.Sh SEE ALSO 468.Xr free 3C , 469.Xr libdevid 3LIB , 470.Xr attributes 5 , 471.Xr ddi_devid_compare 9F 472