1.\" 2.\" Copyright (c) 2009 The DragonFly Project. All rights reserved. 3.\" 4.\" This code is derived from software contributed to The DragonFly Project 5.\" by Matthew Dillon <dillon@backplane.com> 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in 15.\" the documentation and/or other materials provided with the 16.\" distribution. 17.\" 3. Neither the name of The DragonFly Project nor the names of its 18.\" contributors may be used to endorse or promote products derived 19.\" from this software without specific, prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 24.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 25.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 31.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd July 10, 2009 35.Dt GETDEVPATH 3 36.Os 37.Sh NAME 38.Nm getdevpath 39.Nd retrieve device path given name or label 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In fstab.h 45.Ft char * 46.Fn getdevpath "const char *devname" "int flags" 47.Sh DESCRIPTION 48.Fn getdevpath 49takes a device name such as 50.Dq Pa da0 , 51a device identifier such as 52.Dq Li V21JYQ0G , 53a device path beginning with 54.Dq Pa / 55or 56.Dq Pa \&. , 57or a device label from one of the 58.Pa devtab 59files, and returns an allocated path which may be used to open the device. 60.Pp 61Device names prefixed with 62.Dq Pa / 63or 64.Dq Pa \&. 65are assumed to be device paths and an exact allocated copy is simply returned. 66However, flags may modify the operation. 67.Pp 68Device names specified with a type prefix, such as 69.Dq Li serno:V21JYQ0G 70are assumed to be typed device identifiers and are directly translated to 71the appropriate path in 72.Pa /dev , 73for example 74.Dq Pa /dev/serno/V21JYQ0G . 75.Pp 76Device labels are directly checked against 77.Pa /dev 78first, using 79.Fn lstat , 80and if not found will be searched for in one of the 81.Pa devtab 82files. 83.Pp 84The following flags may be passed to 85.Fn getdevpath : 86.Bl -tag -width ".Dv GETDEVPATH_RAWDEV" -offset indent 87.It Dv GETDEVPATH_RAWDEV 88Normally, 89.Fn getdevpath 90returns a high level devfs path which often winds up being a softlink in 91devfs. 92If this flag is specified and the device path represents a softlink, 93.Fn getdevpath 94will do a 95.Xr readlink 2 96and return the actual raw device path instead. 97If the device path cannot be 98.Fn lstat Ap d 99this option will return 100.Dv NULL . 101.El 102.Sh RETURN VALUES 103.Fn getdevpath 104returns a pointer to a 105.Fn malloc Ap d 106path on success and 107.Dv NULL 108on failure. 109If a failure occurs 110.Va errno 111will be set appropriately. 112.Pp 113Note that a 114.Fn malloc Ap d 115path may be returned even if it does not exist in the filesystem. 116Callers should not assume that the device is accessible 117unless they can also open the device. 118.Sh SEE ALSO 119.Xr devfs 5 , 120.Xr devtab 5 , 121.Xr fstab 5 122.Sh HISTORY 123The 124.Nm 125function appeared in 126.Dx 2.3 . 127