.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright 2017 Nexenta Systems, Inc.
.\"
.Dd January 25, 2017
.Dt DEVID_GET 3DEVID
.Os
.Sh NAME
.Nm devid_get ,
.Nm devid_free ,
.Nm devid_get_minor_name ,
.Nm devid_deviceid_to_nmlist ,
.Nm devid_free_nmlist ,
.Nm devid_compare ,
.Nm devid_sizeof ,
.Nm devid_valid ,
.Nm devid_str_encode ,
.Nm devid_str_decode ,
.Nm devid_str_from_path ,
.Nm devid_str_free
.Nd device ID interfaces for user applications
.Sh SYNOPSIS
.Lb libdevid
.In devid.h
.Ft int
.Fo devid_get
.Fa "int fd"
.Fa "ddi_devid_t *retdevid"
.Fc
.Ft void
.Fo devid_free
.Fa "ddi_devid_t devid"
.Fc
.Ft int
.Fo devid_get_minor_name
.Fa "int fd"
.Fa "char **retminor_name"
.Fc
.Ft int
.Fo devid_deviceid_to_nmlist
.Fa "char *search_path"
.Fa "ddi_devid_t devid"
.Fa "char *minor_name"
.Fa "devid_nmlist_t **retlist"
.Fc
.Ft void
.Fo devid_free_nmlist
.Fa "devid_nmlist_t *list"
.Fc
.Ft int
.Fo devid_compare
.Fa "ddi_devid_t devid1"
.Fa "ddi_devid_t devid2"
.Fc
.Ft size_t
.Fo devid_sizeof
.Fa "ddi_devid_t devid"
.Fc
.Ft int
.Fo devid_valid
.Fa "ddi_devid_t devid"
.Fc
.Ft char *
.Fo devid_str_encode
.Fa "ddi_devid_t devid"
.Fa "char *minor_name"
.Fc
.Ft int
.Fo devid_str_decode
.Fa "char *devidstr"
.Fa "ddi_devid_t *retdevid"
.Fa "char **retminor_name"
.Fc
.Ft char *
.Fo devid_str_from_path
.Fa "const char *path"
.Fc
.Ft void
.Fo devid_str_free
.Fa "char *str"
.Fc
.Sh DESCRIPTION
These functions provide unique identifiers
.Pq device ID
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.
.Pp
The
.Fn devid_get
function returns in
.Fa retdevid
the device ID for the device associated with the open file descriptor
.Fa 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
.Fa retdevid
using the
.Fn devid_free
function.
.Pp
The
.Fn devid_free
function frees the space that was allocated for the returned
.Fa devid
by
.Fn devid_get
and
.Fn devid_str_decode .
.Pp
The
.Fn devid_get_minor_name
function returns the minor name, in
.Fa retminor_name ,
for the device associated with the open file descriptor
.Fa fd .
This name is specific to the particular minor number, but is
.Qq instance number
specific.
The caller of this function must free the memory allocated for the returned
.Fa retminor_name
string using
.Fn devid_str_free .
.Pp
The
.Fn devid_deviceid_to_nmlist
function returns an array of
.Fa devid_nmlist
structures, where each entry matches the
.Fa devid
and
.Fa minor_name
passed in.
If the
.Fa minor_name
specified is one of the special values
.Po
.Dv DEVID_MINOR_NAME_ALL ,
.Dv DEVID_MINOR_NAME_ALL_CHR ,
or
.Dv DEVID_MINOR_NAME_ALL_BLK
.Pc ,
then all minor names associated with
.Fa devid
which also meet the special
.Fa minor_name
filtering requirements are returned.
The
.Fa devid_nmlist
structure contains the device name and device number.
The last entry of the array contains a null pointer for the
.Fa devname
and
.Dv NODEV
for the device number.
This function traverses the file tree, starting at
.Fa search_path .
For each device with a matching device ID and minor name tuple, a device name
and device number are added to the
.Fa 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
.Fn devid_free_nmlist
function.
This function may take a long time to complete if called with the device ID of
an unattached device.
.Pp
The
.Fn devid_free_nmlist
function frees the memory allocated by the
.Fn devid_deviceid_to_nmlist
function and returned in the
.Fa retlist .
.Pp
The
.Fn 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
.Fa devid1
is greater than the device ID pointed to by
.Fa devid2 .
It returns 0 if the device ID pointed to by
.Fa devid1
is equal to the device ID pointed to by
.Fa devid2 .
It returns an integer less than 0 if the device ID pointed to by
.Fa devid1
is less than the device ID pointed to by
.Fa 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.
.Pp
The
.Fn devid_sizeof
function returns the size of
.Fa devid
in bytes.
.Pp
The
.Fn devid_valid
function validates the format of a
.Fa 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
.Fn ddi_devid_valid
.Po see
.Xr ddi_devid_compare 9F
.Pc .
.Pp
The
.Fn devid_str_encode
function encodes a
.Fa devid
and
.Fa minor_name
into a null-terminated ASCII string, returning a pointer to that string.
To avoid shell conflicts, the
.Fa devid
portion of the string is limited to uppercase and lowercase letters, digits, and
the plus
.Pq Qq Sy \&+ ,
minus
.Pq Qq Sy \&- ,
period
.Pq Qq Sy \&. ,
equals
.Pq Qq Sy \&= ,
underscore
.Pq Qq Sy \&_ ,
tilde
.Pq Qq Sy \&~ ,
and comma
.Pq Qq Sy \&,
characters.
If there is an ASCII quote character in the binary form of a
.Fa devid ,
the string representation will be in hex_id form, not ascii_id form.
The comma
.Pq Qq Sy \&,
character is added for
.Qq id1,
at the head of the string
.Fa devid .
If both a
.Fa devid
and a
.Fa minor_name
are non-null, a slash
.Pq Qq Sy \&/
is used to separate the
.Fa devid
from the
.Fa minor_name
in the encoded string.
If
.Fa minor_name
is null, only the
.Fa devid
is encoded.
If the
.Fa devid
is null then the special string
.Qq id0
is returned.
Note that you cannot compare the returned string against another string with
.Xr strcmp 3C
to determine devid equality.
The string returned must be freed by calling
.Fn devid_str_free .
.Pp
The
.Fn devid_str_from_path
is similar to
.Fn devid_str_encode ,
but takes a
.Fa path
argument instead.
If
.Fa path
includes the minor name, it will be encoded as well.
The string returned must be freed by calling
.Fn devid_str_free .
.Pp
The
.Fn devid_str_decode
function takes a string previously produced by the
.Fn devid_str_encode
or
.Fn ddi_devid_str_encode
.Po see
.Xr ddi_devid_compare 9F
.Pc
function and decodes the contained device ID and minor name, allocating and
returning pointers to the extracted parts via the
.Fa retdevid
and
.Fa retminor_name
arguments.
If the special
.Fa devidstr
.Qq 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
.Fn devid_free
function.
A non-null returned minor name must be freed by calling
.Fn devid_str_free .
.Pp
The
.Fn devid_str_free
function frees the character string returned by
.Fn devid_str_encode
and the
.Fa retminor_name
argument returned by
.Fn devid_str_decode
and
.Fn devid_get_minor_name .
.Sh RETURN VALUES
Upon successful completion, the
.Fn devid_get ,
.Fn devid_get_minor_name ,
.Fn devid_str_decode ,
and
.Fn devid_deviceid_to_nmlist
functions return 0.
Otherwise, they return -1.
.Pp
The
.Fn devid_compare
function returns the following values:
.Bl -tag -width Ds
.It Sy -1
The device ID pointed to by
.Fa devid1
is less than the device ID pointed to by
.Fa devid2 .
.It Sy 0
The device ID pointed to by
.Fa devid1
is equal to the device ID pointed to by
.Fa devid2 .
.It Sy 1
The device ID pointed to by
.Fa devid1
is greater than the device ID pointed to by
.Fa devid2 .
.El
.Pp
The
.Fn devid_sizeof
function returns the size of
.Fa devid
in bytes.
If
.Fa devid
is null, the number of bytes that must be allocated and initialized to determine
the size of a complete device ID is returned.
.Pp
The
.Fn devid_valid
function returns 1 if the
.Fa devid
is valid and 0 if the
.Fa devid
is invalid.
.Pp
The
.Fn devid_str_encode
and
.Fn devid_str_from_path
functions return 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
.Fn devid_str_free
function.
.Sh EXAMPLES
.Bl -tag -width Ds
.It Xo
.Sy Example 1
Using
.Fn devid_get ,
.Fn devid_get_minor_name ,
and
.Fn devid_str_encode
.Xc
The following example shows the proper use of
.Fn devid_get ,
.Fn devid_get_minor_name ,
and
.Fn devid_str_encode
to free the space allocated for
.Fa devid ,
.Fa minor_name
and encoded
.Fa devid .
.Bd -literal
int fd;
ddi_devid_t devid;
char *minor_name, *devidstr;

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) {
    ...
}
if ((devidstr = devid_str_encode(devid, minor_name)) == 0) {
    ...
}
printf("devid %s\en", devidstr);
devid_str_free(devidstr);
devid_free(devid);
devid_str_free(minor_name);
.Ed
.It Xo
.Sy Example 2
Using
.Fn devid_deviceid_to_nmlist
and
.Fn devid_free_nmlist
.Xc
The following example shows the proper use of
.Fn devid_deviceid_to_nmlist
and
.Fn devid_free_nmlist :
.Bd -literal
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);
.Ed
.El
.Sh MT-LEVEL
.Sy MT-Safe
.Sh INTERFACE STABILITY
.Sy Stable
.Sh SEE ALSO
.Xr free 3C ,
.Xr libdevid 3LIB ,
.Xr attributes 5 ,
.Xr ddi_devid_compare 9F