lib/libc/gen/getdevpath.3

   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
  49 takes a device name such as
  50 .Dq Pa da0 ,
  51 a device identifier such as
  52 .Dq Li V21JYQ0G ,
  53 a device path beginning with
  54 .Dq Pa /
  55 or
  56 .Dq Pa \&. ,
  57 or a device label from one of the
  58 .Pa devtab
  59 files, and returns an allocated path which may be used to open the device.
  60 .Pp
  61 Device names prefixed with
  62 .Dq Pa /
  63 or
  64 .Dq Pa \&.
  65 are assumed to be device paths and an exact allocated copy is simply returned.
  66 However, flags may modify the operation.
  67 .Pp
  68 Device names specified with a type prefix, such as
  69 .Dq Li serno:V21JYQ0G
  70 are assumed to be typed device identifiers and are directly translated to
  71 the appropriate path in
  72 .Pa /dev ,
  73 for example
  74 .Dq Pa /dev/serno/V21JYQ0G .
  75 .Pp
  76 Device labels are directly checked against
  77 .Pa /dev
  78 first, using
  79 .Fn lstat ,
  80 and if not found will be searched for in one of the
  81 .Pa devtab
  82 files.
  83 .Pp
  84 The following flags may be passed to
  85 .Fn getdevpath :
  86 .Bl -tag -width ".Dv GETDEVPATH_RAWDEV" -offset indent
  87 .It Dv GETDEVPATH_RAWDEV
  88 Normally,
  89 .Fn getdevpath
  90 returns a high level devfs path which often winds up being a softlink in
  91 devfs.
  92 If this flag is specified and the device path represents a softlink,
  93 .Fn getdevpath
  94 will do a
  95 .Xr readlink 2
  96 and return the actual raw device path instead.
  97 If the device path cannot be
  98 .Fn lstat Ap d
  99 this option will return
 100 .Dv NULL .
 101 .El
 102 .Sh RETURN VALUES
 103 .Fn getdevpath
 104 returns a pointer to a
 105 .Fn malloc Ap d
 106 path on success and
 107 .Dv NULL
 108 on failure.
 109 If a failure occurs
 110 .Va errno
 111 will be set appropriately.
 112 .Pp
 113 Note that a
 114 .Fn malloc Ap d
 115 path may be returned even if it does not exist in the filesystem.
 116 Callers should not assume that the device is accessible
 117 unless 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
 123 The
 124 .Nm
 125 function appeared in
 126 .Dx 2.3 .