HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

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. 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 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.
AUTHOR
devnm() was created by HP.
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−141