xref: /dflybsd-src/lib/libc/gen/getdevpath.3 (revision 86d7f5d305c6adaa56ff4582ece9859d73106103)
186d7f5d3SJohn Marino.\"
286d7f5d3SJohn Marino.\" Copyright (c) 2009 The DragonFly Project.  All rights reserved.
386d7f5d3SJohn Marino.\"
486d7f5d3SJohn Marino.\" This code is derived from software contributed to The DragonFly Project
586d7f5d3SJohn Marino.\" by Matthew Dillon <dillon@backplane.com>
686d7f5d3SJohn Marino.\"
786d7f5d3SJohn Marino.\" Redistribution and use in source and binary forms, with or without
886d7f5d3SJohn Marino.\" modification, are permitted provided that the following conditions
986d7f5d3SJohn Marino.\" are met:
1086d7f5d3SJohn Marino.\"
1186d7f5d3SJohn Marino.\" 1. Redistributions of source code must retain the above copyright
1286d7f5d3SJohn Marino.\"    notice, this list of conditions and the following disclaimer.
1386d7f5d3SJohn Marino.\" 2. Redistributions in binary form must reproduce the above copyright
1486d7f5d3SJohn Marino.\"    notice, this list of conditions and the following disclaimer in
1586d7f5d3SJohn Marino.\"    the documentation and/or other materials provided with the
1686d7f5d3SJohn Marino.\"    distribution.
1786d7f5d3SJohn Marino.\" 3. Neither the name of The DragonFly Project nor the names of its
1886d7f5d3SJohn Marino.\"    contributors may be used to endorse or promote products derived
1986d7f5d3SJohn Marino.\"    from this software without specific, prior written permission.
2086d7f5d3SJohn Marino.\"
2186d7f5d3SJohn Marino.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
2286d7f5d3SJohn Marino.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
2386d7f5d3SJohn Marino.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
2486d7f5d3SJohn Marino.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
2586d7f5d3SJohn Marino.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
2686d7f5d3SJohn Marino.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
2786d7f5d3SJohn Marino.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
2886d7f5d3SJohn Marino.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
2986d7f5d3SJohn Marino.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
3086d7f5d3SJohn Marino.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
3186d7f5d3SJohn Marino.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
3286d7f5d3SJohn Marino.\" SUCH DAMAGE.
3386d7f5d3SJohn Marino.\"
3486d7f5d3SJohn Marino.Dd July 10, 2009
3586d7f5d3SJohn Marino.Dt GETDEVPATH 3
3686d7f5d3SJohn Marino.Os
3786d7f5d3SJohn Marino.Sh NAME
3886d7f5d3SJohn Marino.Nm getdevpath
3986d7f5d3SJohn Marino.Nd retrieve device path given name or label
4086d7f5d3SJohn Marino.Sh LIBRARY
4186d7f5d3SJohn Marino.Lb libc
4286d7f5d3SJohn Marino.Sh SYNOPSIS
4386d7f5d3SJohn Marino.In sys/types.h
4486d7f5d3SJohn Marino.In fstab.h
4586d7f5d3SJohn Marino.Ft char *
4686d7f5d3SJohn Marino.Fn getdevpath "const char *devname" "int flags"
4786d7f5d3SJohn Marino.Sh DESCRIPTION
4886d7f5d3SJohn Marino.Fn getdevpath
4986d7f5d3SJohn Marinotakes a device name such as
5086d7f5d3SJohn Marino.Dq Pa da0 ,
5186d7f5d3SJohn Marinoa device identifier such as
5286d7f5d3SJohn Marino.Dq Li V21JYQ0G ,
5386d7f5d3SJohn Marinoa device path beginning with
5486d7f5d3SJohn Marino.Dq Pa /
5586d7f5d3SJohn Marinoor
5686d7f5d3SJohn Marino.Dq Pa \&. ,
5786d7f5d3SJohn Marinoor a device label from one of the
5886d7f5d3SJohn Marino.Pa devtab
5986d7f5d3SJohn Marinofiles, and returns an allocated path which may be used to open the device.
6086d7f5d3SJohn Marino.Pp
6186d7f5d3SJohn MarinoDevice names prefixed with
6286d7f5d3SJohn Marino.Dq Pa /
6386d7f5d3SJohn Marinoor
6486d7f5d3SJohn Marino.Dq Pa \&.
6586d7f5d3SJohn Marinoare assumed to be device paths and an exact allocated copy is simply returned.
6686d7f5d3SJohn MarinoHowever, flags may modify the operation.
6786d7f5d3SJohn Marino.Pp
6886d7f5d3SJohn MarinoDevice names specified with a type prefix, such as
6986d7f5d3SJohn Marino.Dq Li serno:V21JYQ0G
7086d7f5d3SJohn Marinoare assumed to be typed device identifiers and are directly translated to
7186d7f5d3SJohn Marinothe appropriate path in
7286d7f5d3SJohn Marino.Pa /dev ,
7386d7f5d3SJohn Marinofor example
7486d7f5d3SJohn Marino.Dq Pa /dev/serno/V21JYQ0G .
7586d7f5d3SJohn Marino.Pp
7686d7f5d3SJohn MarinoDevice labels are directly checked against
7786d7f5d3SJohn Marino.Pa /dev
7886d7f5d3SJohn Marinofirst, using
7986d7f5d3SJohn Marino.Fn lstat ,
8086d7f5d3SJohn Marinoand if not found will be searched for in one of the
8186d7f5d3SJohn Marino.Pa devtab
8286d7f5d3SJohn Marinofiles.
8386d7f5d3SJohn Marino.Pp
8486d7f5d3SJohn MarinoThe following flags may be passed to
8586d7f5d3SJohn Marino.Fn getdevpath :
8686d7f5d3SJohn Marino.Bl -tag -width ".Dv GETDEVPATH_RAWDEV" -offset indent
8786d7f5d3SJohn Marino.It Dv GETDEVPATH_RAWDEV
8886d7f5d3SJohn MarinoNormally,
8986d7f5d3SJohn Marino.Fn getdevpath
9086d7f5d3SJohn Marinoreturns a high level devfs path which often winds up being a softlink in
9186d7f5d3SJohn Marinodevfs.
9286d7f5d3SJohn MarinoIf this flag is specified and the device path represents a softlink,
9386d7f5d3SJohn Marino.Fn getdevpath
9486d7f5d3SJohn Marinowill do a
9586d7f5d3SJohn Marino.Xr readlink 2
9686d7f5d3SJohn Marinoand return the actual raw device path instead.
9786d7f5d3SJohn MarinoIf the device path cannot be
9886d7f5d3SJohn Marino.Fn lstat Ap d
9986d7f5d3SJohn Marinothis option will return
10086d7f5d3SJohn Marino.Dv NULL .
10186d7f5d3SJohn Marino.El
10286d7f5d3SJohn Marino.Sh RETURN VALUES
10386d7f5d3SJohn Marino.Fn getdevpath
10486d7f5d3SJohn Marinoreturns a pointer to a
10586d7f5d3SJohn Marino.Fn malloc Ap d
10686d7f5d3SJohn Marinopath on success and
10786d7f5d3SJohn Marino.Dv NULL
10886d7f5d3SJohn Marinoon failure.
10986d7f5d3SJohn MarinoIf a failure occurs
11086d7f5d3SJohn Marino.Va errno
11186d7f5d3SJohn Marinowill be set appropriately.
11286d7f5d3SJohn Marino.Pp
11386d7f5d3SJohn MarinoNote that a
11486d7f5d3SJohn Marino.Fn malloc Ap d
11586d7f5d3SJohn Marinopath may be returned even if it does not exist in the filesystem.
11686d7f5d3SJohn MarinoCallers should not assume that the device is accessible
11786d7f5d3SJohn Marinounless they can also open the device.
11886d7f5d3SJohn Marino.Sh SEE ALSO
11986d7f5d3SJohn Marino.Xr devfs 5 ,
12086d7f5d3SJohn Marino.Xr devtab 5 ,
12186d7f5d3SJohn Marino.Xr fstab 5
12286d7f5d3SJohn Marino.Sh HISTORY
12386d7f5d3SJohn MarinoThe
12486d7f5d3SJohn Marino.Nm
12586d7f5d3SJohn Marinofunction appeared in
12686d7f5d3SJohn Marino.Dx 2.3 .
127