NAME
devnm — map device ID to file path
SYNOPSIS
#include <devnm.h>
int devnm (
mode_t devtype,
dev_t devid,
char *path,
size_t pathlen,
int cache
);
DESCRIPTION
Given a device type, a device
ID,
and a string in which to return the result,
devnm()
maps the type and
ID
to a block or character special file (device file) name by searching
/dev.
It returns in
path
the full path name of the first special file encountered
with a matching device type and
ID.
It searches
/dev
and all its subdirectories recursively in unspecified order.
The parameters are:
- devtype
One of the file type values
S_IFBLK
or
S_IFCHR
documented in
stat(5).
Bits other than those in the
S_IFMT
set are ignored.
Hence the value can be, for example, an
st_mode
value returned by
stat()
(see
stat(2)).
- devid
A device
ID
(the combined major and minor numbers) such as returned by
stat()
in the
st_dev
or
st_rdev
field.
- path
Pointer to the buffer in which to return the path name result.
- pathlen
Tells the available length of the
path
string, including the
NUL
terminator character.
If
path
is too short to hold the full path name,
only the first
pathlen
-1 characters are returned in a null-terminated string,
and the return value is altered (see below).
- cache
A flag that tells
devnm()
whether to save file information in
memory allocated by
malloc(),
and later,
whether to use that saved information instead of searching
/dev
again.
A subsequent call with
cache
non-zero can be much faster, especially if
/dev
is a large tree.
However, the first call with
cache
true might be slower because
devnm()
must read all of the
/dev
tree once to create the cache,
rather than returning immediately upon finding a matching file.
Any call with
cache
set to zero ignores the cache, if any, and reads the directory.
To allow for possible future enhancements,
cache
should be restricted to the values 0 and 1.
There is no way to tell
devnm()
to free its cached memory.
devnm()
ignores unreadable directories and files for which
stat()
fails.
APPLICATION USAGE
devnm()
is thread-safe. It is not async-cancel-safe.
A cancellation point may occur when a thread is executing
devnm().
RETURN VALUE
devnm()
returns one of the following values:
- 0
Successful.
The result is in
path.
- -1
ftw()
failed.
errno
contains the value returned from
ftw().
path
might be altered if
cache
is set.
If
cache
was set for the first time,
devnm()
freed any memory allocated by the current call.
- -2
No matching special file was found.
errno
is undefined.
path
is unaltered.
- -3
A matching special file was found,
but the name was truncated to fit in
path.
errno
is undefined.
If
malloc()
fails,
devnm()
silently abandons the attempt to do caching
in the current or any later call with
cache
true, and frees any memory allocated by the current call.
AUTHOR
devnm()
was created by
HP.
