| | 1 | .\" Copyright (c) 1994 |
| | 2 | .\" The Regents of the University of California. All rights reserved. |
| | 3 | .\" |
| | 4 | .\" This code is derived from software contributed to Berkeley by |
| | 5 | .\" Jan-Simon Pendry. |
| | 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 | .\" 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. |
| | 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 | .\" |
| | 31 | .\" @(#)realpath.3 8.2 (Berkeley) 2/16/94 |
| | 32 | .\" $FreeBSD: src/lib/libc/stdlib/realpath.3,v 1.14 2007/01/09 00:28:10 imp Exp $ |
| | 33 | .\" |
| | 34 | .Dd April 5, 2008 |
| | 35 | .Dt REALPATH 3 |
| | 36 | .Os |
| | 37 | .Sh NAME |
| | 38 | .Nm realpath |
| | 39 | .Nd returns the canonicalized absolute pathname |
| | 40 | .\" .Sh LIBRARY |
| | 41 | .\" .Lb libc |
| | 42 | .Sh SYNOPSIS |
| | 43 | .In stdlib.h |
| | 44 | .Ft "char *" |
| | 45 | .Fo realpath |
| | 46 | .Fa "const char *restrict file_name" |
| | 47 | .Fa "char *restrict resolved_name" |
| | 48 | .Fc |
| | 49 | .Sh DESCRIPTION |
| | 50 | The |
| | 51 | .Fn realpath |
| | 52 | function resolves all symbolic links, extra |
| | 53 | .Dq / |
| | 54 | characters, and references to |
| | 55 | .Pa /./ |
| | 56 | and |
| | 57 | .Pa /../ |
| | 58 | in |
| | 59 | .Fa file_name . |
| | 60 | If the |
| | 61 | .Fa resolved_name |
| | 62 | argument |
| | 63 | is non-NULL, the resulting absolute pathname is copied there (it |
| | 64 | .Em must |
| | 65 | refer to a buffer capable of storing at least |
| | 66 | .Dv PATH_MAX |
| | 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. |
| | 77 | .Pp |
| | 78 | The |
| | 79 | .Fn realpath |
| | 80 | function will resolve both absolute and relative paths |
| | 81 | and return the absolute pathname corresponding to |
| | 82 | .Fa file_name . |
| | 83 | All components of |
| | 84 | .Fa file_name |
| | 85 | must exist when |
| | 86 | .Fn realpath |
| | 87 | is called. |
| | 88 | .Sh "RETURN VALUES" |
| | 89 | On success, the |
| | 90 | .Fn realpath |
| | 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. |
| | 94 | If an error occurs, |
| | 95 | .Fn realpath |
| | 96 | returns |
| | 97 | .Dv NULL . |
| | 98 | If |
| | 99 | .Fa resolved_name |
| | 100 | was non-NULL, it will |
| | 101 | contain the pathname which caused the problem. |
| | 102 | .Sh VARIANTS |
| | 103 | Defining |
| | 104 | .Dv _DARWIN_C_SOURCE |
| | 105 | or |
| | 106 | .Dv _DARWIN_BETTER_REALPATH |
| | 107 | before including stdlib.h will cause the provided implementation of |
| | 108 | .Fn realpath |
| | 109 | to use F_GETPATH from |
| | 110 | .Xr fcntl 2 |
| | 111 | to discover the path. |
| | 112 | .Sh ERRORS |
| | 113 | The function |
| | 114 | .Fn realpath |
| | 115 | may fail and set the external variable |
| | 116 | .Va errno |
| | 117 | for any of the errors specified for the library functions |
| | 118 | .Xr alloca 3 , |
| | 119 | .Xr getattrlist 2 , |
| | 120 | .Xr getcwd 3 , |
| | 121 | .Xr lstat 2 , |
| | 122 | .Xr readlink 2 , |
| | 123 | .Xr stat 2 , |
| | 124 | and |
| | 125 | .Xr strdup 3 . |
| | 126 | .\" .Sh CAVEATS |
| | 127 | .\" This implementation of |
| | 128 | .\" .Fn realpath |
| | 129 | .\" differs slightly from the Solaris implementation. |
| | 130 | .\" The |
| | 131 | .\" .Bx 4.4 |
| | 132 | .\" version always returns absolute pathnames, |
| | 133 | .\" whereas the Solaris implementation will, |
| | 134 | .\" under certain circumstances, return a relative |
| | 135 | .\" .Fa resolved_name |
| | 136 | .\" when given a relative |
| | 137 | .\" .Fa file_name . |
| | 138 | .Sh LEGACY SYNOPSIS |
| | 139 | .Fd #include <sys/param.h> |
| | 140 | .Fd #include <stdlib.h> |
| | 141 | .Pp |
| | 142 | The include file |
| | 143 | .In sys/param.h |
| | 144 | is necessary. |
| | 145 | .Sh LEGACY DESCRIPTION |
| | 146 | In legacy mode, |
| | 147 | the last component of |
| | 148 | .Fa file_name |
| | 149 | does not need to exist when |
| | 150 | .Fn realpath |
| | 151 | is called. |
| | 152 | .Sh "SEE ALSO" |
| | 153 | .Xr free 3 , |
| | 154 | .Xr getcwd 3 , |
| | 155 | .Xr compat 5 |
| | 156 | .Sh HISTORY |
| | 157 | The |
| | 158 | .Fn realpath |
| | 159 | function first appeared in |
| | 160 | .Bx 4.4 . |
projects / apple / libc.git / blame_incremental