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 54The 55.Fn devname 56and 57.Fn devname_r 58functions return a pointer to the name of the block or character 59device in 60.Pa /dev 61with a device number of 62.Fa dev , 63and a file type matching the one encoded in 64.Fa type 65which must be one of 66.Dv S_IFBLK 67or 68.Dv S_IFCHR . 69To find the right name, 70.Fn devname 71and 72.Fn devname_r 73asks the kernel via the 74.Va kern.devname 75sysctl. 76If it 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 EXAMPLES 125The following code fragment determines the name of the cloned 126.Xr tun 4 127device that is created by opening 128.Pa /dev/tun . 129.Bd -literal -offset indent 130int fd; 131struct stat st; 132 133fd = open("/dev/tun", O_RDONLY); 134fstat(fd, &st); 135printf("devname is /dev/%s\en", devname(st.st_rdev, S_IFCHR)); 136printf("fdevname is /dev/%s\en", fdevname(fd)); 137close(fd); 138.Ed 139.Sh ERRORS 140The 141.Fn fdevname 142and 143.Fn fdevname_r 144functions may fail and return the following error codes: 145.Bl -tag -width Er 146.It Bq Er EBADF 147The 148.Fa fd 149is not a valid open file descriptor. 150.It Bq Er EINVAL 151The 152.Fa fd 153must belong to a character device. 154.El 155.Pp 156The 157.Fn fdevname_r 158function may fail and return the following error code: 159.Bl -tag -width Er 160.It Bq Er ERANGE 161The 162.Fa len 163argument 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 169The 170.Fn devname 171function appeared in 172.Bx 4.4 . 173.Pp 174The 175.Fn devname_r 176function appeared in 177.Dx 1.0 178and the 179.Fn fdevname 180and 181.Fn fdevname_r 182functions appeared in 183.Dx 2.3 . 184