Device ID Library Functions devid_get(3DEVID)
NAME
devid_get, devid_compare, devid_deviceid_to_nmlist,
devid_free, devid_free_nmlist, devid_get_minor_name,
devid_sizeof, devid_str_decode, devid_str_free,
devid_str_encode, devid_valid - device ID interfaces for
user applicationsSYNOPSIS
cc [ flag... ] file... -ldevid [ library... ]
#include
int devid_get(int fd, ddi_devid_t *retdevid);
void devid_free(ddi_devid_t devid);
int devid_get_minor_name(int fd, char **retminor_name);
int devid_deviceid_to_nmlist(char *search_path, ddi_devid_t devid,
char *minor_name, devid_nmlist_t **retlist);
void devid_free_nmlist(devid_nmlist_t *list);
int devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);
size_t devid_sizeof(ddi_devid_t devid);
int devid_valid(ddi_devid_t devid);
char *devid_str_encode(ddi_devid_t devid, char *minor_name);
int devid_str_decode(char *devidstr, ddi_devid_t *retdevid,
char **retminor_name);
void devid_str_free(char *str);
DESCRIPTION
These functions provide unique identifiers (device IDs) for devices. Applications and device drivers use these functions to identify and locate devices, independent of the device's physical connection or its logical device name or number.SunOS 5.11 Last change: 30 Nov 2001 1
Device ID Library Functions devid_get(3DEVID)
The devid_get() function returns in retdevid the device ID
for the device associated with the open file descriptor fd,which refers to any device. It returns an error if the dev-
ice does not have an associated device ID. The caller must free the memory allocated for retdevid using thedevid_free() function.
The devid_free() function frees the space that was allocated
for the returned devid by devid_get() and
devid_str_decode().
The devid_get_minor_name() function returns the minor name,
in retminor_name, for the device associated with the open
file descriptor fd. This name is specific to the particular minor number, but is "instance number" specific. The caller of this function must free the memory allocated for thereturned retminor_name string using devid_str_free().
The devid_deviceid_to_nmlist() function returns an array of
devid_nmlist structures, where each entry matches the devid
and minor_name passed in. If the minor_name specified is one
of the special values (DEVID_MINOR_NAME_ALL,
DEVID_MINOR_NAME_ALL_CHR, or DEVID_MINOR_NAME_ALL_BLK) ,
then all minor names associated with devid which also meetthe special minor_name filtering requirements are returned.
The devid_nmlist structure contains the device name and dev-
ice number. The last entry of the array contains a null pointer for the devname and NODEV for the device number. This function traverses the file tree, starting atsearch_path. For each device with a matching device ID and
minor name tuple, a device name and device number are added to the retlist. If no matches are found, an error is returned. The caller of this function must free the memory allocated for the returned array with thedevid_free_nmlist() function. This function may take a long
time to complete if called with the device ID of an unat-
tached device.The devid_free_nmlist() function frees the memory allocated
by the devid_deviceid_to_nmlist() function.
The devid_compare() function compares two device IDs and
determines both equality and sort order. The function returns an integer greater than 0 if the device ID pointed to by devid1 is greater than the device ID pointed to by devid2. It returns 0 if the device ID pointed to by devid1 is equal to the device ID pointed to by devid2. It returnsSunOS 5.11 Last change: 30 Nov 2001 2
Device ID Library Functions devid_get(3DEVID)
an integer less than 0 if the device ID pointed to by devid1 is less than the device ID pointed to by devid2. Thisfunction is the only valid mechanism to determine the equal-
ity of two devids. This function may indicate equality for arguments which by simple inspection appear different.The devid_sizeof() function returns the size of devid in
bytes.The devid_valid() function validates the format of a devid.
It returns 1 if the format is valid, and 0 if invalid. This check may not be as complete as the corresponding kernelfunction ddi_devid_valid() (see ddi_devid_compare(9F)).
The devid_str_encode() function encodes a devid and
minor_name into a null-terminated ASCII string, returning a
pointer to that string. To avoid shell conflicts, the devid portion of the string is limited to uppercase and lowercaseletters, digits, and the plus (+), minus (-), period (.),
equals (=), underscore (_), tilde (~), and comma (,) charac-
ters. If there is an ASCII quote character in the binaryform of a devid, the string representation will be in hex_id
form, not ascii_id form. The comma (,) character is added
for "id1," at the head of the string devid. If both a devidand a minor_name are non-null, a slash (/)is used to
separate the devid from the minor_name in the encoded
string. If minor_name is null, only the devid is encoded.
If the devid is null then the special string "id0" is returned. Note that you cannot compare the returned string against another string with strcmp(3C) to determine devid equality. The string returned must be freed by callingdevid_str_free().
The devid_str_decode() function takes a string previously
produced by the devid_str_encode() or ddi_devid_str_encode()
(see ddi_devid_compare(9F)) function and decodes the con-
tained device ID and minor name, allocating and returning pointers to the extracted parts via the retdevid andretminor_name arguments. If the special devidstr "id0" was
specified, the returned device ID and minor name will bothbe null. A non-null returned devid must be freed by the
caller by the devid_free() function. A non-null returned
minor name must be freed by calling devid_str_free().
The devid_str_free() function frees the character string
returned by devid_str_encode() and the retminor_name argu-
ment returned by devid_str_decode().
SunOS 5.11 Last change: 30 Nov 2001 3
Device ID Library Functions devid_get(3DEVID)
RETURN VALUES
Upon successful completion, the devid_get(),
devid_get_minor_name(), devid_str_decode(), and
devid_deviceid_to_nmlist() functions return 0. Otherwise,
they return -1.
The devid_compare() function returns the following values:
-1 The device ID pointed to by devid1 is less than the
device ID pointed to by devid2. 0 The device ID pointed to by devid1 is equal to the device ID pointed to by devid2. 1 The device ID pointed to by devid1 is greater than the device ID pointed to by devid2.The devid_sizeof() function returns the size of devid in
bytes. If devid is null, the number of bytes that must beallocated and initialized to determine the size of a com-
plete device ID is returned.The devid_valid() function returns 1 if the devid is valid
and 0 if the devid is invalid.The devid_str_encode() function returns NULL to indicate
failure. Failure may be caused by attempting to encode aninvalid string. If the return value is non-null, the caller
must free the returned string by using the devid_str_free()
function.EXAMPLES
Example 1 Using devid_get(), devid_get_minor_name(), and
devid_str_encode()
The following example shows the proper use of devid_get(),
devid_get_minor_name(), and devid_str_encode() to free the
space allocated for devid, minor_name and encoded devid.
int fd;ddi_devid_t devid;
char *minor_name, *devidstr;
if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) {
SunOS 5.11 Last change: 30 Nov 2001 4
Device ID Library Functions devid_get(3DEVID)
... }if (devid_get(fd, &devid) != 0) {
... }if (devid_get_minor_name(fd, &minor_name) != 0) {
... }if ((devidstr = devid_str_encode(devid, minor_name)) == 0) {
... }printf("devid %s\n", devidstr);
devid_str_free(devidstr);
devid_free(devid);
devid_str_free(minor_name);
Example 2 Using devid_deviceid_to_nmlist() and
devid_free_nmlist()
The following example shows the proper use ofdevid_deviceid_to_nmlist() and devid_free_nmlist():
devid_nmlist_t *list = NULL;
int err;if (devid_deviceid_to_nmlist("/dev/rdsk", devid,
minor_name, &list))
return (-1);
/* loop through list and process device names and numbers */devid_free_nmlist(list);
ATTRIBUTES
See attributes(5) for description of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
free(3C), libdevid(3LIB), attributes(5),ddi_devid_compare(9F)
SunOS 5.11 Last change: 30 Nov 2001 5