devnm(3)                                                           devnm(3)




 NAME    [Toc]    [Back]
      devnm - map device ID to file path

 SYNOPSIS    [Toc]    [Back]
      #include <devnm.h>

      int devnm (
         mode_t devtype,
         dev_t devid,
         char *path,
         size_t pathlen,
         int cache
      );

 DESCRIPTION    [Toc]    [Back]
      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.



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 devnm(3)                                                           devnm(3)




                     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    [Toc]    [Back]
      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    [Toc]    [Back]
      devnm() was created by HP.

 SEE ALSO    [Toc]    [Back]
      devnm(1M), stat(2), ftw(3C), malloc(3C), ttyname(3C), stat(5),
      thread_safety(5).


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003