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 .\" $DragonFly: src/lib/libc/gen/devname.3,v 1.5 2007/05/17 08:19:00 swildner Exp $
  31 .\"
  32 .Dd August 11, 2009
  33 .Dt DEVNAME 3
  34 .Os
  35 .Sh NAME
  36 .Nm devname ,
  37 .Nm devname_r ,
  38 .Nm fdevname ,
  39 .Nm fdevname_r
  40 .Nd get device name
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/stat.h
  45 .In stdlib.h
  46 .Ft char *
  47 .Fn devname "dev_t dev" "mode_t type"
  48 .Ft char *
  49 .Fn devname_r "dev_t dev" "mode_t type" "char *buf" "size_t len"
  50 .Ft char *
  51 .Fn fdevname "int fd"
  52 .Ft int
  53 .Fn fdevname_r "int fd" "char *buf" "size_t len"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn devname
  57 and
  58 .Fn devname_r
  59 functions return a pointer to the name of the block or character
  60 device in
  61 .Pa /dev
  62 with a device number of
  63 .Fa dev ,
  64 and a file type matching the one encoded in
  65 .Fa type
  66 which must be one of
  67 .Dv S_IFBLK
  68 or
  69 .Dv S_IFCHR .
  70 To find the right name,
  71 .Fn devname
  72 and
  73 .Fn devname_r
  74 first search the device database created by
  75 .Xr dev_mkdb 8 ;
  76 if that 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 ERRORS
 125 The
 126 .Fn fdevname
 127 and
 128 .Fn fdevname_r
 129 functions may fail and return the following error codes:
 130 .Bl -tag -width Er
 131 .It Bq Er EBADF
 132 The
 133 .Fa fd
 134 is not a valid open file descriptor.
 135 .It Bq Er EINVAL
 136 The
 137 .Fa fd
 138 must belong to a character device.
 139 .El
 140 .Pp
 141 The
 142 .Fn fdevname_r
 143 function may fail and return the following error code:
 144 .Bl -tag -width Er
 145 .It Bq Er ERANGE
 146 The
 147 .Fa len
 148 argument is smaller than the length of the string to be returned.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr stat 2 ,
 152 .Xr dev_mkdb 8
 153 .Sh HISTORY
 154 The
 155 .Fn devname
 156 function appeared in
 157 .Bx 4.4 .
 158 .Pp
 159 The
 160 .Fn devname_r
 161 function appeared in
 162 .Dx 1.0
 163 and the
 164 .Fn fdevname
 165 and
 166 .Fn fdevname_r
 167 functions appeared in
 168 .Dx 2.3 .