Device ID Library Functions devidget(3DEVID)
NAME
devidget, devidcompare, deviddeviceidtonmlist,
devidfree, devidfreenmlist, devidgetminorname,
devidsizeof, devidstrdecode, devidstrfree,
devidstrencode, devidvalid - device ID interfaces for
user applications
SYNOPSIS
cc [ flag... ] file... -ldevid [ library... ]
#include
int devidget(int fd, ddidevidt *retdevid);
void devidfree(ddidevidt devid);
int devidgetminorname(int fd, char **retminorname);
int deviddeviceidtonmlist(char *searchpath, ddidevidt devid,
char *minorname, devidnmlistt **retlist);
void devidfreenmlist(devidnmlistt *list);
int devidcompare(ddidevidt devid1, ddidevidt devid2);
sizet devidsizeof(ddidevidt devid);
int devidvalid(ddidevidt devid);
char *devidstrencode(ddidevidt devid, char *minorname);
int devidstrdecode(char *devidstr, ddidevidt *retdevid,
char **retminorname);
void devidstrfree(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 devidget(3DEVID)
The devidget() 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 the
devidfree() function.
The devidfree() function frees the space that was allocated
for the returned devid by devidget() and
devidstrdecode().
The devidgetminorname() function returns the minor name,
in retminorname, 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 retminorname string using devidstrfree().
The deviddeviceidtonmlist() function returns an array of
devidnmlist structures, where each entry matches the devid
and minorname passed in. If the minorname specified is one
of the special values (DEVIDMINORNAMEAL,
DEVIDMINORNAMEALCHR, or DEVIDMINORNAMEALBLK) ,
then all minor names associated with devid which also meet
the special minorname filtering requirements are returned.
The devidnmlist 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 at
searchpath. 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
devidfreenmlist() function. This function may take a long
time to complete if called with the device ID of an unat-
tached device.
The devidfreenmlist() function frees the memory allocated
by the deviddeviceidtonmlist() function.
The devidcompare() 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
SunOS 5.11 Last change: 30 Nov 2001 2
Device ID Library Functions devidget(3DEVID)
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 equal-
ity of two devids. This function may indicate equality for
arguments which by simple inspection appear different.
The devidsizeof() function returns the size of devid in
bytes.
The devidvalid() 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 ddidevidvalid() (see ddidevidcompare(9F)).
The devidstrencode() function encodes a devid and
minorname into a null-terminated ASCI 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 (,) charac-
ters. If there is an ASCI quote character in the binary
form of a devid, the string representation will be in hexid
form, not asciiid form. The comma (,) character is added
for "id1," at the head of the string devid. If both a devid
and a minorname are non-null, a slash (/)is used to
separate the devid from the minorname in the encoded
string. If minorname 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
devidstrfree().
The devidstrdecode() function takes a string previously
produced by the devidstrencode() or ddidevidstrencode()
(see ddidevidcompare(9F)) function and decodes the con-
tained device ID and minor name, allocating and returning
pointers to the extracted parts via the retdevid and
retminorname 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 devidfree() function. A non-null returned
minor name must be freed by calling devidstrfree().
The devidstrfree() function frees the character string
returned by devidstrencode() and the retminorname argu-
ment returned by devidstrdecode().
SunOS 5.11 Last change: 30 Nov 2001 3
Device ID Library Functions devidget(3DEVID)
RETURN VALUES
Upon successful completion, the devidget(),
devidgetminorname(), devidstrdecode(), and
deviddeviceidtonmlist() functions return 0. Otherwise,
they return -1.
The devidcompare() 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 devidsizeof() 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 com-
plete device ID is returned.
The devidvalid() function returns 1 if the devid is valid
and 0 if the devid is invalid.
The devidstrencode() function returns NUL 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 devidstrfree()
function.
EXAMPLES
Example 1 Using devidget(), devidgetminorname(), and
devidstrencode()
The following example shows the proper use of devidget(),
devidgetminorname(), and devidstrencode() to free the
space allocated for devid, minorname and encoded devid.
int fd;
ddidevidt devid;
char *minorname, *devidstr;
if ((fd = open("/dev/dsk/c0t3d0s0", ORDONLYONDELAY)) < 0) {
SunOS 5.11 Last change: 30 Nov 2001 4
Device ID Library Functions devidget(3DEVID)
...
}
if (devidget(fd, &devid) != 0) {
...
}
if (devidgetminorname(fd, &minorname) != 0) {
...
}
if ((devidstr = devidstrencode(devid, minorname)) == 0) {
...
}
printf("devid %s\n", devidstr);
devidstrfree(devidstr);
devidfree(devid);
devidstrfree(minorname);
Example 2 Using deviddeviceidtonmlist() and
devidfreenmlist()
The following example shows the proper use of
deviddeviceidtonmlist() and devidfreenmlist():
devidnmlistt *list = NUL;
int err;
if (deviddeviceidtonmlist("/dev/rdsk", devid,
minorname, &list))
return (-1);
/* loop through list and process device names and numbers */
devidfreenmlist(list);
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
Interface Stability Stable
SEE ALSO
free(3C), libdevid(3LIB), attributes(5),
ddidevidcompare(9F)
SunOS 5.11 Last change: 30 Nov 2001 5
|
