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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)devname.3   8.2 (Berkeley) 4/29/95
  33 .\" $FreeBSD: src/lib/libc/gen/devname.3,v 1.7.2.7 2003/03/15 15:11:05 trhodes Exp $
  34 .\" $DragonFly: src/lib/libc/gen/devname.3,v 1.5 2007/05/17 08:19:00 swildner Exp $
  35 .\"
  36 .Dd August 11, 2009
  37 .Dt DEVNAME 3
  38 .Os
  39 .Sh NAME
  40 .Nm devname ,
  41 .Nm devname_r ,
  42 .Nm fdevname ,
  43 .Nm fdevname_r
  44 .Nd get device name
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/stat.h
  49 .In stdlib.h
  50 .Ft char *
  51 .Fn devname "dev_t dev" "mode_t type"
  52 .Ft char *
  53 .Fn devname_r "dev_t dev" "mode_t type" "char *buf" "size_t len"
  54 .Ft char *
  55 .Fn fdevname "int fd"
  56 .Ft int
  57 .Fn fdevname_r "int fd" "char *buf" "size_t len"
  58 .Sh DESCRIPTION
  59 The
  60 .Fn devname
  61 and
  62 .Fn devname_r
  63 functions return a pointer to the name of the block or character
  64 device in
  65 .Pa /dev
  66 with a device number of
  67 .Fa dev ,
  68 and a file type matching the one encoded in
  69 .Fa type
  70 which must be one of
  71 .Dv S_IFBLK
  72 or
  73 .Dv S_IFCHR .
  74 To find the right name,
  75 .Fn devname
  76 and
  77 .Fn devname_r
  78 first search the device database created by
  79 .Xr dev_mkdb 8 ;
  80 if that fails, it will format the information encapsulated in
  81 .Fa dev
  82 and
  83 .Fa type
  84 in a human-readable format.
  85 .Pp
  86 The
  87 .Fn fdevname
  88 and
  89 .Fn fdevname_r
  90 function obtain the device name directly from a file descriptor
  91 pointing to a character device.
  92 .Pp
  93 .Fn devname
  94 and
  95 .Fn fdevname
  96 returns a pointer to an internal static object; thus, subsequent calls will
  97 modify the same buffer.
  98 .Fn devname_r
  99 and
 100 .Fn fdevname_r
 101 avoid this problem by taking a buffer
 102 .Fa buf
 103 and a buffer length
 104 .Fa len
 105 as arguments.
 106 .Sh RETURN VALUES
 107 The
 108 .Fn devname ,
 109 .Fn devname_r
 110 and
 111 .Fn fdevname
 112 functions return a pointer to the name of the block or character
 113 device in
 114 .Pa /dev
 115 if successful; otherwise
 116 .Dv NULL
 117 is returned.
 118 If
 119 .Fn fdevname
 120 fails,
 121 .Va errno
 122 is set to indicate the error.
 123 .Pp
 124 The
 125 .Fn fdevname_r
 126 function returns 0 if successful.
 127 Otherwise an error number is returned.
 128 .Sh ERRORS
 129 The
 130 .Fn fdevname
 131 and
 132 .Fn fdevname_r
 133 functions may fail and return the following error codes:
 134 .Bl -tag -width Er
 135 .It Bq Er EBADF
 136 The
 137 .Fa fd
 138 is not a valid open file descriptor.
 139 .It Bq Er EINVAL
 140 The
 141 .Fa fd
 142 must belong to a character device.
 143 .El
 144 .Pp
 145 The
 146 .Fn fdevname_r
 147 function may fail and return the following error code:
 148 .Bl -tag -width Er
 149 .It Bq Er ERANGE
 150 The
 151 .Fa len
 152 argument is smaller than the length of the string to be returned.
 153 .El
 154 .Sh SEE ALSO
 155 .Xr stat 2 ,
 156 .Xr dev_mkdb 8
 157 .Sh HISTORY
 158 The
 159 .Fn devname
 160 function appeared in
 161 .Bx 4.4 .
 162 .Pp
 163 The
 164 .Fn devname_r
 165 function appeared in
 166 .Dx 1.0
 167 and the
 168 .Fn fdevname
 169 and
 170 .Fn fdevname_r
 171 functions appeared in
 172 .Dx 2.3 .