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 December 27, 2020 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 73first asks the kernel via the 74.Va kern.devname 75sysctl, 76and falls back to search the device database created by 77.Xr dev_mkdb 8 . 78If both fail, it will format the information encapsulated in 79.Fa dev 80and 81.Fa type 82in a human-readable format. 83.Pp 84The 85.Fn fdevname 86and 87.Fn fdevname_r 88function obtain the device name directly from a file descriptor 89pointing to a character device. 90.Pp 91.Fn devname 92and 93.Fn fdevname 94returns a pointer to an internal static object; thus, subsequent calls will 95modify the same buffer. 96.Fn devname_r 97and 98.Fn fdevname_r 99avoid this problem by taking a buffer 100.Fa buf 101and a buffer length 102.Fa len 103as arguments. 104.Sh RETURN VALUES 105The 106.Fn devname , 107.Fn devname_r 108and 109.Fn fdevname 110functions return a pointer to the name of the block or character 111device in 112.Pa /dev 113if successful; otherwise 114.Dv NULL 115is returned. 116If 117.Fn fdevname 118fails, 119.Va errno 120is set to indicate the error. 121.Pp 122The 123.Fn fdevname_r 124function returns 0 if successful. 125Otherwise an error number is returned. 126.Sh ERRORS 127The 128.Fn fdevname 129and 130.Fn fdevname_r 131functions may fail and return the following error codes: 132.Bl -tag -width Er 133.It Bq Er EBADF 134The 135.Fa fd 136is not a valid open file descriptor. 137.It Bq Er EINVAL 138The 139.Fa fd 140must belong to a character device. 141.El 142.Pp 143The 144.Fn fdevname_r 145function may fail and return the following error code: 146.Bl -tag -width Er 147.It Bq Er ERANGE 148The 149.Fa len 150argument is smaller than the length of the string to be returned. 151.El 152.Sh SEE ALSO 153.Xr stat 2 , 154.Xr dev_mkdb 8 155.Sh HISTORY 156The 157.Fn devname 158function appeared in 159.Bx 4.4 . 160.Pp 161The 162.Fn devname_r 163function appeared in 164.Dx 1.0 165and the 166.Fn fdevname 167and 168.Fn fdevname_r 169functions appeared in 170.Dx 2.3 . 171