devid_get(3)

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

#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

The following routines are used to provide unique identifiers, device ids, for devices. Specifically, applications and device drivers use these interfaces to identify and locate devices, independent of the device's physical connection or its logical device name or number.

devid_get() returns the device id, in retdevid, for the device associated with the open file descriptor fd, which refers to any device. If the device does not have a device id associated with it then an error is returned. The caller of this function must free the memory allocated for the retdevid returned, using the devid_free() function.

devid_free() frees the allocated space for the passed-in devid, allocated by devid_get().

devid_get_minor_name() 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.

devid_deviceid_to_nmlist() returns an array of devid_nmlist structures, where each entry matches the devid id and minor name passed in. The devid_nmlist structure contains the device name and device number. The last entry of the array has a null pointer for the devname and NODEV for the device number.

This function walks through 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.

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

devid_compare() compares two device ids byte-by-byte and determines both equality and sort order. The function returns an integer greater than zero if the device id pointed to by devid1 is greater than the device id pointed to by devid2. It returns zero if the device id pointed to by devid1 is equal to the device id pointed to by devid2. It returns an integer less than zero if the device id pointed to by devid1 is less than the device id pointed to by devid2.

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

RETURN VALUES

The following functions return 0 upon successful completion: devid_get(), devid_get_minor_name(), and devid_deviceid_to_nmlist().

Otherwise, -1 is returned and errno is set to indicate the error.

The function devid_compare() 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 return value from devid_sizeof() is the size in number of bytes allocated for the devid.

EXAMPLES

---

Example 1 Using the devid_get() and devid_get_minor_name() Functions




The following example shows the proper use of devid_get() and devid_get_minor_name() to free the space allocated for the device id 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 the devid_deviceid_to_nmlist() and devid_free_nmlist() Functions




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

The location of the device id library interfaces.

/usr/lib/libdevid.so

A 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(4), attributes(5), ddi_devid_devlist(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.7  Last Revised 10 Feb 1997

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