xref: /freebsd/lib/libc/stdlib/realpath.3 (revision dc36d6f9bb1753f3808552f3afd30eda9a7b206a)
1d01a28e2SPeter Wemm.\" Copyright (c) 1994
2d01a28e2SPeter Wemm.\"	The Regents of the University of California.  All rights reserved.
3d01a28e2SPeter Wemm.\"
4d01a28e2SPeter Wemm.\" This code is derived from software contributed to Berkeley by
5d01a28e2SPeter Wemm.\" Jan-Simon Pendry.
6d01a28e2SPeter Wemm.\"
7d01a28e2SPeter Wemm.\" Redistribution and use in source and binary forms, with or without
8d01a28e2SPeter Wemm.\" modification, are permitted provided that the following conditions
9d01a28e2SPeter Wemm.\" are met:
10d01a28e2SPeter Wemm.\" 1. Redistributions of source code must retain the above copyright
11d01a28e2SPeter Wemm.\"    notice, this list of conditions and the following disclaimer.
12d01a28e2SPeter Wemm.\" 2. Redistributions in binary form must reproduce the above copyright
13d01a28e2SPeter Wemm.\"    notice, this list of conditions and the following disclaimer in the
14d01a28e2SPeter Wemm.\"    documentation and/or other materials provided with the distribution.
15*580b4d18SEd Maste.\" 3. Neither the name of the University nor the names of its contributors
16d01a28e2SPeter Wemm.\"    may be used to endorse or promote products derived from this software
17d01a28e2SPeter Wemm.\"    without specific prior written permission.
18d01a28e2SPeter Wemm.\"
19d01a28e2SPeter Wemm.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20d01a28e2SPeter Wemm.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21d01a28e2SPeter Wemm.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22d01a28e2SPeter Wemm.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23d01a28e2SPeter Wemm.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24d01a28e2SPeter Wemm.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25d01a28e2SPeter Wemm.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26d01a28e2SPeter Wemm.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27d01a28e2SPeter Wemm.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28d01a28e2SPeter Wemm.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29d01a28e2SPeter Wemm.\" SUCH DAMAGE.
30d01a28e2SPeter Wemm.\"
31fdbe55fcSKonstantin Belousov.Dd May 11, 2012
32d01a28e2SPeter Wemm.Dt REALPATH 3
33d01a28e2SPeter Wemm.Os
34d01a28e2SPeter Wemm.Sh NAME
35d01a28e2SPeter Wemm.Nm realpath
36d01a28e2SPeter Wemm.Nd returns the canonicalized absolute pathname
3725bb73e0SAlexey Zelkin.Sh LIBRARY
3825bb73e0SAlexey Zelkin.Lb libc
39d01a28e2SPeter Wemm.Sh SYNOPSIS
408aefde06SJeroen Ruigrok van der Werven.In stdlib.h
41d01a28e2SPeter Wemm.Ft "char *"
42da5dfd56SKevin Lo.Fn realpath "const char * restrict pathname" "char * restrict resolved_path"
43d01a28e2SPeter Wemm.Sh DESCRIPTION
44d01a28e2SPeter WemmThe
45d01a28e2SPeter Wemm.Fn realpath
46d01a28e2SPeter Wemmfunction resolves all symbolic links, extra
47d01a28e2SPeter Wemm.Dq /
48d01a28e2SPeter Wemmcharacters and references to
49d01a28e2SPeter Wemm.Pa /./
50d01a28e2SPeter Wemmand
51d01a28e2SPeter Wemm.Pa /../
52d01a28e2SPeter Wemmin
53d01a28e2SPeter Wemm.Fa pathname ,
54d01a28e2SPeter Wemmand copies the resulting absolute pathname into
55431c9bf2SKonstantin Belousovthe memory pointed to by
56cfc2d91bSChris Costello.Fa resolved_path .
57d01a28e2SPeter WemmThe
58cfc2d91bSChris Costello.Fa resolved_path
59d01a28e2SPeter Wemmargument
60d01a28e2SPeter Wemm.Em must
61431c9bf2SKonstantin Belousovpoint to a buffer capable of storing at least
62de216a83SJohan Karlsson.Dv PATH_MAX
639d79ec20SKonstantin Belousovcharacters, or be
649d79ec20SKonstantin Belousov.Dv NULL .
65d01a28e2SPeter Wemm.Pp
66d01a28e2SPeter WemmThe
67d01a28e2SPeter Wemm.Fn realpath
68d01a28e2SPeter Wemmfunction will resolve both absolute and relative paths
69d01a28e2SPeter Wemmand return the absolute pathname corresponding to
70d01a28e2SPeter Wemm.Fa pathname .
71fdbe55fcSKonstantin BelousovAll components of
72d01a28e2SPeter Wemm.Fa pathname
73d01a28e2SPeter Wemmmust exist when
74d01a28e2SPeter Wemm.Fn realpath
75fdbe55fcSKonstantin Belousovis called, and all but the last component must name either directories or
76fdbe55fcSKonstantin Belousovsymlinks pointing to the directories.
77d01a28e2SPeter Wemm.Sh "RETURN VALUES"
78d01a28e2SPeter WemmThe
79d01a28e2SPeter Wemm.Fn realpath
80d01a28e2SPeter Wemmfunction returns
81cfc2d91bSChris Costello.Fa resolved_path
82d01a28e2SPeter Wemmon success.
839d79ec20SKonstantin BelousovIf the function was supplied
849d79ec20SKonstantin Belousov.Dv NULL
859d79ec20SKonstantin Belousovas
869d79ec20SKonstantin Belousov.Fa resolved_path ,
879d79ec20SKonstantin Belousovand operation did not cause errors, the returned value is
889d79ec20SKonstantin Belousova null-terminated string in a buffer allocated by a call to
899d79ec20SKonstantin Belousov.Fn malloc 3 .
90d01a28e2SPeter WemmIf an error occurs,
91d01a28e2SPeter Wemm.Fn realpath
92d01a28e2SPeter Wemmreturns
93d01a28e2SPeter Wemm.Dv NULL ,
947e36a19dSKonstantin Belousovand if
95cfc2d91bSChris Costello.Fa resolved_path
967e36a19dSKonstantin Belousovis not
979d79ec20SKonstantin Belousov.Dv NULL ,
987e36a19dSKonstantin Belousovthe array that it points to contains the pathname which caused the problem.
99d01a28e2SPeter Wemm.Sh ERRORS
100d01a28e2SPeter WemmThe function
101d01a28e2SPeter Wemm.Fn realpath
102d01a28e2SPeter Wemmmay fail and set the external variable
103d01a28e2SPeter Wemm.Va errno
104d01a28e2SPeter Wemmfor any of the errors specified for the library functions
105d01a28e2SPeter Wemm.Xr lstat 2 ,
106d01a28e2SPeter Wemm.Xr readlink 2
107d01a28e2SPeter Wemmand
108d01a28e2SPeter Wemm.Xr getcwd 3 .
1090afc94c1SUlrich Spörlein.Sh SEE ALSO
1100afc94c1SUlrich Spörlein.Xr getcwd 3
11101e14bffSAndrey A. Chernov.\" .Sh STANDARDS
11201e14bffSAndrey A. Chernov.\" The
11301e14bffSAndrey A. Chernov.\" .Fn realpath
11401e14bffSAndrey A. Chernov.\" function conforms to
11501e14bffSAndrey A. Chernov.\" .St -p1003.1-2001 .
1160afc94c1SUlrich Spörlein.Sh HISTORY
1170afc94c1SUlrich SpörleinThe
1180afc94c1SUlrich Spörlein.Fn realpath
1190afc94c1SUlrich Spörleinfunction first appeared in
1200afc94c1SUlrich Spörlein.Bx 4.4 .
121d01a28e2SPeter Wemm.Sh CAVEATS
122d01a28e2SPeter WemmThis implementation of
123d01a28e2SPeter Wemm.Fn realpath
124d01a28e2SPeter Wemmdiffers slightly from the Solaris implementation.
125d01a28e2SPeter WemmThe
126d01a28e2SPeter Wemm.Bx 4.4
127d01a28e2SPeter Wemmversion always returns absolute pathnames,
128d01a28e2SPeter Wemmwhereas the Solaris implementation will,
129d01a28e2SPeter Wemmunder certain circumstances, return a relative
130d01a28e2SPeter Wemm.Fa resolved_path
131d01a28e2SPeter Wemmwhen given a relative
132d01a28e2SPeter Wemm.Fa pathname .
133