[apple/libc.git] / stdlib / FreeBSD / realpath.3

.\" Copyright (c) 1994
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Jan-Simon Pendry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)realpath.3	8.2 (Berkeley) 2/16/94
.\" $FreeBSD: src/lib/libc/stdlib/realpath.3,v 1.14 2007/01/09 00:28:10 imp Exp $
.\"
.Dd April 5, 2008
.Dt REALPATH 3
.Os
.Sh NAME
.Nm realpath
.Nd returns the canonicalized absolute pathname
.\" .Sh LIBRARY
.\" .Lb libc
.Sh SYNOPSIS
.In stdlib.h
.Ft "char *"
.Fo realpath
.Fa "const char *restrict file_name"
.Fa "char *restrict resolved_name"
.Fc
.Sh DESCRIPTION
The
.Fn realpath
function resolves all symbolic links, extra
.Dq /
characters, and references to
.Pa /./
and
.Pa /../
in
.Fa file_name .
If the
.Fa resolved_name
argument
is non-NULL, the resulting absolute pathname is copied there (it
.Em must
refer to a buffer capable of storing at least
.Dv PATH_MAX
characters).
.Pp
As a permitted extension to the standard, if
.Fa resolved_name
is NULL, 
memory is allocated for the resulting absolute pathname, and is returned by
.Fn realpath .
This memory should be freed by a call to
.Xr free 3
when no longer needed.
.Pp
The
.Fn realpath
function will resolve both absolute and relative paths
and return the absolute pathname corresponding to
.Fa file_name .
All components of
.Fa file_name
must exist when
.Fn realpath
is called.
.Sh "RETURN VALUES"
On success, the
.Fn realpath
function returns the address of the resulting absolute pathname, which is
.Fa resolved_name
if it was non-NULL, or the address of newly allocated memory.
If an error occurs,
.Fn realpath
returns
.Dv NULL .
If
.Fa resolved_name
was non-NULL, it will
contains the pathname which caused the problem.
.Sh ERRORS
The function
.Fn realpath
may fail and set the external variable
.Va errno
for any of the errors specified for the library functions
.Xr alloca 3 ,
.Xr getattrlist 2 ,
.Xr getcwd 3 ,
.Xr lstat 2 ,
.Xr readlink 2 ,
.Xr stat 2 ,
and
.Xr strdup 3 .
.\" .Sh CAVEATS
.\" This implementation of
.\" .Fn realpath
.\" differs slightly from the Solaris implementation.
.\" The
.\" .Bx 4.4
.\" version always returns absolute pathnames,
.\" whereas the Solaris implementation will,
.\" under certain circumstances, return a relative
.\" .Fa resolved_name
.\" when given a relative
.\" .Fa file_name .
.Sh LEGACY SYNOPSIS
.Fd #include <sys/param.h>
.Fd #include <stdlib.h>
.Pp
The include file
.In sys/param.h
is necessary.
.Sh LEGACY DESCRIPTION
In legacy mode,
the last component of
.Fa file_name
does not need to exist when
.Fn realpath
is called.
.Sh "SEE ALSO"
.Xr free 3 ,
.Xr getcwd 3 ,
.Xr compat 5
.Sh HISTORY
The
.Fn realpath
function first appeared in
.Bx 4.4 .
Commit	Line	Data
5b2abdfb	1	.\" Copyright (c) 1994
e9ce8d39 A	2	.\" The Regents of the University of California. All rights reserved.
e9ce8d39 A	3	.\"
5b2abdfb A	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Jan-Simon Pendry.
	6	.\"
e9ce8d39 A	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	.\" 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 the
	14	.\" documentation and/or other materials provided with the distribution.
e9ce8d39 A	15	.\" 4. Neither the name of the University nor the names of its contributors
	16	.\" may be used to endorse or promote products derived from this software
	17	.\" without specific prior written permission.
	18	.\"
	19	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	20	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	21	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	22	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	23	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	24	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	25	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	26	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	27	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	28	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	29	.\" SUCH DAMAGE.
	30	.\"
5b2abdfb	31	.\" @(#)realpath.3 8.2 (Berkeley) 2/16/94
1f2f436a	32	.\" $FreeBSD: src/lib/libc/stdlib/realpath.3,v 1.14 2007/01/09 00:28:10 imp Exp $
e9ce8d39	33	.\"
ad3c9f2a	34	.Dd April 5, 2008
5b2abdfb	35	.Dt REALPATH 3
e9ce8d39 A	36	.Os
e9ce8d39 A	37	.Sh NAME
5b2abdfb A	38	.Nm realpath
5b2abdfb A	39	.Nd returns the canonicalized absolute pathname
ad3c9f2a A	40	.\" .Sh LIBRARY
ad3c9f2a A	41	.\" .Lb libc
e9ce8d39	42	.Sh SYNOPSIS
5b2abdfb A	43	.In stdlib.h
5b2abdfb A	44	.Ft "char *"
ad3c9f2a A	45	.Fo realpath
	46	.Fa "const char *restrict file_name"
	47	.Fa "char *restrict resolved_name"
	48	.Fc
e9ce8d39 A	49	.Sh DESCRIPTION
e9ce8d39 A	50	The
5b2abdfb A	51	.Fn realpath
	52	function resolves all symbolic links, extra
	53	.Dq /
ad3c9f2a	54	characters, and references to
5b2abdfb	55	.Pa /./
e9ce8d39	56	and
5b2abdfb A	57	.Pa /../
5b2abdfb A	58	in
ad3c9f2a A	59	.Fa file_name .
	60	If the
	61	.Fa resolved_name
5b2abdfb	62	argument
ad3c9f2a	63	is non-NULL, the resulting absolute pathname is copied there (it
5b2abdfb A	64	.Em must
5b2abdfb A	65	refer to a buffer capable of storing at least
9385eb3d	66	.Dv PATH_MAX
ad3c9f2a A	67	characters).
	68	.Pp
	69	As a permitted extension to the standard, if
	70	.Fa resolved_name
	71	is NULL,
	72	memory is allocated for the resulting absolute pathname, and is returned by
	73	.Fn realpath .
	74	This memory should be freed by a call to
	75	.Xr free 3
	76	when no longer needed.
5b2abdfb A	77	.Pp
	78	The
	79	.Fn realpath
	80	function will resolve both absolute and relative paths
	81	and return the absolute pathname corresponding to
ad3c9f2a A	82	.Fa file_name .
	83	All components of
	84	.Fa file_name
5b2abdfb A	85	must exist when
	86	.Fn realpath
	87	is called.
	88	.Sh "RETURN VALUES"
ad3c9f2a	89	On success, the
5b2abdfb	90	.Fn realpath
ad3c9f2a A	91	function returns the address of the resulting absolute pathname, which is
	92	.Fa resolved_name
	93	if it was non-NULL, or the address of newly allocated memory.
5b2abdfb A	94	If an error occurs,
	95	.Fn realpath
	96	returns
ad3c9f2a A	97	.Dv NULL .
	98	If
	99	.Fa resolved_name
	100	was non-NULL, it will
5b2abdfb	101	contains the pathname which caused the problem.
e9ce8d39	102	.Sh ERRORS
5b2abdfb A	103	The function
	104	.Fn realpath
	105	may fail and set the external variable
	106	.Va errno
	107	for any of the errors specified for the library functions
ad3c9f2a A	108	.Xr alloca 3 ,
	109	.Xr getattrlist 2 ,
	110	.Xr getcwd 3 ,
5b2abdfb	111	.Xr lstat 2 ,
ad3c9f2a A	112	.Xr readlink 2 ,
ad3c9f2a A	113	.Xr stat 2 ,
5b2abdfb	114	and
ad3c9f2a A	115	.Xr strdup 3 .
	116	.\" .Sh CAVEATS
	117	.\" This implementation of
	118	.\" .Fn realpath
	119	.\" differs slightly from the Solaris implementation.
	120	.\" The
	121	.\" .Bx 4.4
	122	.\" version always returns absolute pathnames,
	123	.\" whereas the Solaris implementation will,
	124	.\" under certain circumstances, return a relative
	125	.\" .Fa resolved_name
	126	.\" when given a relative
	127	.\" .Fa file_name .
	128	.Sh LEGACY SYNOPSIS
	129	.Fd #include <sys/param.h>
	130	.Fd #include <stdlib.h>
	131	.Pp
	132	The include file
	133	.In sys/param.h
	134	is necessary.
	135	.Sh LEGACY DESCRIPTION
	136	In legacy mode,
	137	the last component of
	138	.Fa file_name
	139	does not need to exist when
5b2abdfb	140	.Fn realpath
ad3c9f2a	141	is called.
5b2abdfb	142	.Sh "SEE ALSO"
ad3c9f2a A	143	.Xr free 3 ,
	144	.Xr getcwd 3 ,
	145	.Xr compat 5
e9ce8d39 A	146	.Sh HISTORY
e9ce8d39 A	147	The
5b2abdfb	148	.Fn realpath
9385eb3d	149	function first appeared in
e9ce8d39	150	.Bx 4.4 .