devid_get(3DEVID)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO

NAME

devid_get, devid_free, devid_get_minor_name, devid_deviceid_to_nmlist, devid_free_nmlist, devid_compare, devid_sizeof- device ID interfaces for user applications

SYNOPSIS

cc [ flag ... ] file ... -ldevid [ library ... ]
#include <devid.h>

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);

DESCRIPTION

These functions provide unique identifiers (device ID s) 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.

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 device does not have an associated device ID . The caller must free the memory allocated for retdevid using the devid_free() function.

The devid_free() function frees the space that was allocated for devid by devid_get() .

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 the returned string in retminor_name using the devid_free() function.

The devid_deviceid_to_nmlist() function returns an array of devid_nmlist structures, where each entry matches the devid and minor name passed in. The devid_nmlist structure contains the device name and device 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 at search_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 the devid_free_nmlist() function.

The devid_free_nmlist() function frees the memory allocated by the devid_deviceid_to_nmlist() function.

The devid_compare() function compares two device ID s byte-by-byte 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 returns an integer less than 0 if the device ID pointed to by devid1 is less than the device ID pointed to by devid2 .

The devid_sizeof() function returns the size in number of bytes allocated for the devid .

RETURN VALUES

Upon successful completion, the devid_get() , devid_get_minor_name() , and devid_deviceid_to_nmlist() functions return 0 . Otherwise, they return -1 and set errno to indicate the error.

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 in number of bytes allocated for the devid .

EXAMPLES

---

Example 1 Using devid_get() and devid_get_minor_name()




The following example shows the proper use of devid_get() and devid_get_minor_name() to free the space allocated for devid and minor_name .

int fd;
    ddi_devid_t    devid;
    char        *minor_name;
    if ((fd = open("/dev/dsk/c0t3d0s0", O_RDONLY|O_NDELAY)) < 0) {
        ...
    }
       if (devid_get(fd, &devid) != 0) {
        ...
    }
       if (devid_get_minor_name(fd, &minor_name) != 0) {
        ...
    }
    < process devid and minor_name >
    devid_free(devid);
    free(minor_name);

---

---

Example 2 Using devid_deviceid_to_nmlist() and devid_free_nmlist()




The following example shows the proper use of devid_deviceid_to_nmlist() and devid_free_nmlist() :

devid_nmlist_t  *list = NULL;
    int    err;
    err = devid_deviceid_to_nmlist("/dev/rdsk", devid, minor_name, &list);
    if (err)
        return (err);
    < loop through list and process device names and device numbers >
        devid_free_nmlist(list);

---

FILES

/usr/lib/libdevid.so.1

location of the device ID library interfaces

/usr/lib/libdevid.so

symlink to /usr/lib/libdevid.so.1

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT Level	MT-Safe

SEE ALSO

libdevid(3LIB) , attributes(5) , ddi_devid_compare(9F) , ddi_devid_free(9F) , ddi_devid_init(9F) , ddi_devid_register(9F) , ddi_devid_sizeof(9F) , ddi_devid_unregister(9F) , ddi_devid_valid(9F)

SunOS 5.8  Last Revised 11 Feb 1999

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO