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 .\"     @(#)devname.3   8.2 (Berkeley) 4/29/95
  29 .\" $FreeBSD: src/lib/libc/gen/devname.3,v 1.7.2.7 2003/03/15 15:11:05 trhodes Exp $
  30 .\"
  31 .Dd January 1, 2021
  32 .Dt DEVNAME 3
  33 .Os
  34 .Sh NAME
  35 .Nm devname ,
  36 .Nm devname_r ,
  37 .Nm fdevname ,
  38 .Nm fdevname_r
  39 .Nd get device name
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/stat.h
  44 .In stdlib.h
  45 .Ft char *
  46 .Fn devname "dev_t dev" "mode_t type"
  47 .Ft char *
  48 .Fn devname_r "dev_t dev" "mode_t type" "char *buf" "size_t len"
  49 .Ft char *
  50 .Fn fdevname "int fd"
  51 .Ft int
  52 .Fn fdevname_r "int fd" "char *buf" "size_t len"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn devname
  56 and
  57 .Fn devname_r
  58 functions return a pointer to the name of the block or character
  59 device in
  60 .Pa /dev
  61 with a device number of
  62 .Fa dev ,
  63 and a file type matching the one encoded in
  64 .Fa type
  65 which must be one of
  66 .Dv S_IFBLK
  67 or
  68 .Dv S_IFCHR .
  69 To find the right name,
  70 .Fn devname
  71 and
  72 .Fn devname_r
  73 asks the kernel via the
  74 .Va kern.devname
  75 sysctl.
  76 If it fails, it will format the information encapsulated in
  77 .Fa dev
  78 and
  79 .Fa type
  80 in a human-readable format.
  81 .Pp
  82 The
  83 .Fn fdevname
  84 and
  85 .Fn fdevname_r
  86 function obtain the device name directly from a file descriptor
  87 pointing to a character device.
  88 .Pp
  89 .Fn devname
  90 and
  91 .Fn fdevname
  92 returns a pointer to an internal static object; thus, subsequent calls will
  93 modify the same buffer.
  94 .Fn devname_r
  95 and
  96 .Fn fdevname_r
  97 avoid this problem by taking a buffer
  98 .Fa buf
  99 and a buffer length
 100 .Fa len
 101 as arguments.
 102 .Sh RETURN VALUES
 103 The
 104 .Fn devname ,
 105 .Fn devname_r
 106 and
 107 .Fn fdevname
 108 functions return a pointer to the name of the block or character
 109 device in
 110 .Pa /dev
 111 if successful; otherwise
 112 .Dv NULL
 113 is returned.
 114 If
 115 .Fn fdevname
 116 fails,
 117 .Va errno
 118 is set to indicate the error.
 119 .Pp
 120 The
 121 .Fn fdevname_r
 122 function returns 0 if successful.
 123 Otherwise an error number is returned.
 124 .Sh EXAMPLES
 125 The following code fragment determines the name of the cloned
 126 .Xr tun 4
 127 device that is created by opening
 128 .Pa /dev/tun .
 129 .Bd -literal -offset indent
 130 int fd;
 131 struct stat st;
 132
 133 fd = open("/dev/tun", O_RDONLY);
 134 fstat(fd, &st);
 135 printf("devname is /dev/%s\en", devname(st.st_rdev, S_IFCHR));
 136 printf("fdevname is /dev/%s\en", fdevname(fd));
 137 close(fd);
 138 .Ed
 139 .Sh ERRORS
 140 The
 141 .Fn fdevname
 142 and
 143 .Fn fdevname_r
 144 functions may fail and return the following error codes:
 145 .Bl -tag -width Er
 146 .It Bq Er EBADF
 147 The
 148 .Fa fd
 149 is not a valid open file descriptor.
 150 .It Bq Er EINVAL
 151 The
 152 .Fa fd
 153 must belong to a character device.
 154 .El
 155 .Pp
 156 The
 157 .Fn fdevname_r
 158 function may fail and return the following error code:
 159 .Bl -tag -width Er
 160 .It Bq Er ERANGE
 161 The
 162 .Fa len
 163 argument is smaller than the length of the string to be returned.
 164 .El
 165 .Sh SEE ALSO
 166 .Xr stat 2 ,
 167 .Xr devfs 5
 168 .Sh HISTORY
 169 The
 170 .Fn devname
 171 function appeared in
 172 .Bx 4.4 .
 173 .Pp
 174 The
 175 .Fn devname_r
 176 function appeared in
 177 .Dx 1.0
 178 and the
 179 .Fn fdevname
 180 and
 181 .Fn fdevname_r
 182 functions appeared in
 183 .Dx 2.3 .