1.\" 2.\" Copyright (c) 2020 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 February 2, 2020 35.Dt __REALPATH 2 36.Os 37.Sh NAME 38.Nm __realpath 39.Nd resolves the canonicalized absolute pathname 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.Ft "int" 44.Fn __realpath "const char * restrict pathname" "char * restrict resolved_path" "size_t len" 45.Sh DESCRIPTION 46The 47.Fn __realpath 48system call is used to support the libc 49.Fn realpath 50library call. 51It basically does the same thing but with a lower-level system-call 52compatible API. 53The system call differs from the libc function as follows: 54It requires that the target buffer and the size of the target 55buffer be supplied, it does not (obviously) allocate a target buffer if NULL 56is supplied, and it returns the string length of the target buffer (not 57including the terminator) or -1. 58If a failure occurs, the target buffer will not be modified (whereas it is 59in the libc function). 60.Pp 61The system call will resolves all symbolic links, extra 62.Dq / 63characters and references to 64.Pa /./ 65and 66.Pa /../ 67in 68.Fa pathname , 69and copies the resulting absolute pathname into 70the memory pointed to by 71.Fa resolved_path . 72The 73.Fa resolved_path 74argument 75.Em must 76point to a buffer capable of storing at least 77.Fa len 78characters, and may not be 79.Dv NULL . 80.Pp 81The 82.Fn __realpath 83function will resolve both absolute and relative paths 84and return the absolute pathname corresponding to 85.Fa pathname . 86All components of 87.Fa pathname 88must exist when 89.Fn __realpath 90is called, and all but the last component must name either directories or 91symlinks pointing to the directories. 92.Sh "RETURN VALUES" 93The 94.Fn realpath 95function returns 96the string length of the path stored in the target buffer, not including 97the terminator, or -1 on failure. 98.Sh ERRORS 99The function 100may fail and set the external variable 101.Va errno 102for any of the errors specified for the library function 103.Xr realpath 3 . 104.Sh SEE ALSO 105.Xr realpath 3 106.Sh HISTORY 107The 108.Fn __realpath 109function first appeared in 110.Dx 5.7 . 111.Sh CAVEATS 112This is the system call version of the libc 113.Fn realpath 114function, but is not a replacement for the libc function due to 115necessary API differences. 116