devnm.3 (2010 09)

d
devnm(3) devnm(3)
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
mal-
loc(), and later, whether to use that saved information instead of searching /dev
again. However, an attempt to refresh the saved information will be made if the cache
appears stale or if the file is not found. A subsequent call with cache non-zero can be
much faster, especially if /dev is a large tree, provided the saved information is not
refreshed. 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 immedi-
ately 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.
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.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1