lib/libc/sys/__realpath.2

   1 .\" Copyright (c) 2020 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .Dd February 2, 2020
  33 .Dt __REALPATH 2
  34 .Os
  35 .Sh NAME
  36 .Nm __realpath
  37 .Nd resolves the canonicalized absolute pathname
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .Ft "int"
  42 .Fn __realpath "const char * restrict pathname" "char * restrict resolved_path" "size_t len"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn __realpath
  46 system call is used to support the libc
  47 .Fn realpath
  48 library call.
  49 It basically does the same thing but with a lower-level system-call
  50 compatible API.
  51 The system call differs from the libc function as follows:
  52 It requires that the target buffer and the size of the target
  53 buffer be supplied, it does not (obviously) allocate a target buffer if NULL
  54 is supplied, and it returns the string length of the target buffer (not
  55 including the terminator) or -1.
  56 If a failure occurs, the target buffer will not be modified (whereas it is
  57 in the libc function).
  58 .Pp
  59 The system call will resolves all symbolic links, extra
  60 .Dq /
  61 characters and references to
  62 .Pa /./
  63 and
  64 .Pa /../
  65 in
  66 .Fa pathname ,
  67 and copies the resulting absolute pathname into
  68 the memory pointed to by
  69 .Fa resolved_path .
  70 The
  71 .Fa resolved_path
  72 argument
  73 .Em must
  74 point to a buffer capable of storing at least
  75 .Dv len
  76 characters, and may not be
  77 .Dv NULL .
  78 .Pp
  79 The
  80 .Fn __realpath
  81 function will resolve both absolute and relative paths
  82 and return the absolute pathname corresponding to
  83 .Fa pathname .
  84 All components of
  85 .Fa pathname
  86 must exist when
  87 .Fn __realpath
  88 is called, and all but the last component must name either directories or
  89 symlinks pointing to the directories.
  90 .Sh "RETURN VALUES"
  91 The
  92 .Fn realpath
  93 function returns
  94 the string length of the path stored in the target buffer, not including
  95 the terminator, or -1 on failure.
  96 .Sh ERRORS
  97 The function
  98 may fail and set the external variable
  99 .Va errno
 100 for any of the errors specified for the library function
 101 .Xr realpath 3 .
 102 .Sh SEE ALSO
 103 .Xr realpath 3
 104 .Sh HISTORY
 105 The
 106 .Fn __realpath
 107 function first appeared in
 108 .Dx 5.7 .
 109 .Sh CAVEATS
 110 This is the system call version of the libc
 111 .Fn realpath
 112 function, but is not a replacement for the libc function due to
 113 necessary API differences.