lib/libc/gen/devname.3

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd February 22, 2005
  29 .Dt DEVNAME 3
  30 .Os
  31 .Sh NAME
  32 .Nm devname
  33 .Nd "get device name"
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/stat.h
  38 .In stdlib.h
  39 .Ft char *
  40 .Fn devname "dev_t dev" "mode_t type"
  41 .Ft char *
  42 .Fn devname_r "dev_t dev" "mode_t type" "char *buf" "int len"
  43 .Ft char *
  44 .Fn fdevname "int fd"
  45 .Ft char *
  46 .Fn fdevname_r "int fd" "char *buf" "int len"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn devname
  50 function returns a pointer to the name of the block or character
  51 device in
  52 .Pa /dev
  53 with a device number of
  54 .Fa dev ,
  55 and a file type matching the one encoded in
  56 .Fa type
  57 which must be one of
  58 .Dv S_IFBLK
  59 or
  60 .Dv S_IFCHR .
  61 To find the right name,
  62 .Fn devname
  63 asks the kernel via the
  64 .Va kern.devname
  65 sysctl.
  66 If it is unable to come up with a suitable name,
  67 it will format the information encapsulated in
  68 .Fa dev
  69 and
  70 .Fa type
  71 in a human-readable format.
  72 .Pp
  73 The
  74 .Fn fdevname
  75 and
  76 .Fn fdevname_r
  77 function obtains the device name directly from a file descriptor
  78 pointing to a character device.
  79 If it is unable to come up with a suitable name, these functions will
  80 return a NULL pointer.
  81 .Pp
  82 .Fn devname
  83 and
  84 .Fn fdevname
  85 return the name stored in a static buffer which will be overwritten
  86 on subsequent calls.
  87 .Fn devname_r
  88 and
  89 .Fn fdevname_r
  90 take a buffer and length as argument to avoid this problem.
  91 .Sh EXAMPLES
  92 .Bd -literal -compact
  93 int fd;
  94 struct stat buf;
  95 char *name;
  96
  97         fd = open("/dev/tun");
  98         fstat(fd, &buf);
  99         printf("devname is /dev/%s\en", devname(buf.st_rdev, S_IFCHR));
 100         printf("fdevname is /dev/%s\en", fdevname(fd));
 101 .Ed
 102 .Sh SEE ALSO
 103 .Xr stat 2
 104 .Sh HISTORY
 105 The
 106 .Fn devname
 107 function appeared in
 108 .Bx 4.4 .
 109 The
 110 .Fn fdevname
 111 function appeared in
 112 .Fx 8.0 .