xref: /dragonfly/lib/libc/gen/devname.3 (revision 0ca59c34) 
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
55The
56.Fn devname
57and
58.Fn devname_r
59functions return a pointer to the name of the block or character
60device in
61.Pa /dev
62with a device number of
63.Fa dev ,
64and a file type matching the one encoded in
65.Fa type
66which must be one of
67.Dv S_IFBLK
68or
69.Dv S_IFCHR .
70To find the right name,
71.Fn devname
72and
73.Fn devname_r
74first search the device database created by
75.Xr dev_mkdb 8 ;
76if that fails, it will format the information encapsulated in
77.Fa dev
78and
79.Fa type
80in a human-readable format.
81.Pp
82The
83.Fn fdevname
84and
85.Fn fdevname_r
86function obtain the device name directly from a file descriptor
87pointing to a character device.
88.Pp
89.Fn devname
90and
91.Fn fdevname
92returns a pointer to an internal static object; thus, subsequent calls will
93modify the same buffer.
94.Fn devname_r
95and
96.Fn fdevname_r
97avoid this problem by taking a buffer
98.Fa buf
99and a buffer length
100.Fa len
101as arguments.
102.Sh RETURN VALUES
103The
104.Fn devname ,
105.Fn devname_r
106and
107.Fn fdevname
108functions return a pointer to the name of the block or character
109device in
110.Pa /dev
111if successful; otherwise
112.Dv NULL
113is returned.
114If
115.Fn fdevname
116fails,
117.Va errno
118is set to indicate the error.
119.Pp
120The
121.Fn fdevname_r
122function returns 0 if successful.
123Otherwise an error number is returned.
124.Sh ERRORS
125The
126.Fn fdevname
127and
128.Fn fdevname_r
129functions may fail and return the following error codes:
130.Bl -tag -width Er
131.It Bq Er EBADF
132The
133.Fa fd
134is not a valid open file descriptor.
135.It Bq Er EINVAL
136The
137.Fa fd
138must belong to a character device.
139.El
140.Pp
141The
142.Fn fdevname_r
143function may fail and return the following error code:
144.Bl -tag -width Er
145.It Bq Er ERANGE
146The
147.Fa len
148argument 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
154The
155.Fn devname
156function appeared in
157.Bx 4.4 .
158.Pp
159The
160.Fn devname_r
161function appeared in
162.Dx 1.0
163and the
164.Fn fdevname
165and
166.Fn fdevname_r
167functions appeared in
168.Dx 2.3 .
169