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.

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 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 the returned 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 meet the special minor_name filtering requirements are
returned. 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. This function may take a long time to
complete if called with the device ID of an unattached 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 returns an integer less than 0 if the device
ID pointed to by devid1 is less than the device ID
pointed to by devid2. This function is the only valid mechanism to
determine the equality 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 kernel function 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 lowercase letters, digits,
and the plus (+), minus (-), period (.), equals (=), underscore (_),
tilde (~), and comma (,) characters. If there is an ASCII quote
character in the binary form 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
devid and 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 calling devid_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 contained device ID and minor
name, allocating and returning pointers to the extracted parts via the retdevid
and retminor_name arguments. If the special devidstr "id0" was specified, the returned device
ID and minor name will both be 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 argument returned by devid_str_decode().

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 be allocated and initialized
to determine the size of a complete 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 an invalid string. If the return value
is non-null, the caller must free the returned string by using the
devid_str_free() function.