draft/man3/realpath.3

   1 .\" Copyright (C), 1994, Graeme W. Wilford. (Wilf.)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Rewritten old page, 990824, aeb@cwi.nl
  24 .\" 2004-12-14, mtk, added discussion of resolved_path == NULL
  25 .\"
  26 .\" Japanese Version Copyright (c) 1998 SHOJI Yasushi all rights reserved.
  27 .\" Translated 1998-03-22, SHOJI Yasushi <yashi@yashi.com>
  28 .\" Updated 1999-03-07, Shouichi Saito
  29 .\" Updated 2003-01-17, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  30 .\" Updated 2005-02-27, Akihiro MOTOKI
  31 .\" Updated 2005-09-06, Akihiro MOTOKI
  32 .\" Updated 2009-04-24, Akihiro MOTOKI, LDP v3.20
  33 .\"
  34 .\"WORD: bounded        制限がない
  35 .\"
  36 .TH REALPATH 3  2011-09-10 "" "Linux Programmer's Manual"
  37 .\"O .SH NAME
  38 .\"O realpath \- return the canonicalized absolute pathname
  39 .SH 名前
  40 realpath \- 正規化された絶対パス名を返す
  41 .\"O .SH SYNOPSIS
  42 .SH 書式
  43 .nf
  44 .B #include <limits.h>
  45 .B #include <stdlib.h>
  46 .sp
  47 .BI "char *realpath(const char *" path ", char *" resolved_path );
  48 .fi
  49 .sp
  50 .in -4n
  51 .\"O Feature Test Macro Requirements for glibc (see
  52 .\"O .BR feature_test_macros (7)):
  53 glibc 向けの機能検査マクロの要件
  54 .RB ( feature_test_macros (7)
  55 参照):
  56 .in
  57 .sp
  58 .BR realpath ():
  59 .ad l
  60 .RS 4
  61 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  62 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  63 .RE
  64 .ad
  65 .\"O .SH DESCRIPTION
  66 .SH 説明
  67 .\"O .BR realpath ()
  68 .\"O expands all symbolic links and resolves references
  69 .\"O to
  70 .\"O .IR "/./" ", " "/../"
  71 .\"O and extra \(aq/\(aq
  72 .\"O characters in the null-terminated string named by
  73 .\"O .I path
  74 .\"O to produce a canonicalized absolute pathname.
  75 .\"O The resulting pathname is stored as a null-terminated string,
  76 .\"O up to a maximum of
  77 .\"O .B PATH_MAX
  78 .\"O bytes,
  79 .\"O in the buffer pointed to by
  80 .\"O .IR resolved_path .
  81 .BR realpath ()
  82 は
  83 .I path
  84 として与えられた NULL 終端された文字列中の
  85 すべてのシンボリックリンクを展開し、
  86 .IR "/./" ", " "/../"
  87 による参照や余分な \(aq/\(aq
  88 を解決して、正規化された絶対パス名を生成する。
  89 得られた絶対パス名は、最大で
  90 .B PATH_MAX
  91 バイトの NULL 終端された文字列として、
  92 .I resolved_path
  93 により参照されるバッファに格納される。
  94 .\"O The resulting path will have no symbolic link,
  95 .\"O .I "/./"
  96 .\"O or
  97 .\"O .I "/../"
  98 .\"O components.
  99 結果として返るパスの中には、シンボリックリンクや
 100 .IR "/./" ", " "/../"
 101 といった要素は含まれない。
 102 .\"O If
 103 .\"O .I resolved_path
 104 .\"O is specified as NULL, then
 105 .\"O .BR realpath ()
 106 .\"O uses
 107 .\"O .BR malloc (3)
 108 .\"O to allocate a buffer of up to
 109 .\"O .B PATH_MAX
 110 .\"O bytes to hold the resolved pathname,
 111 .\"O and returns a pointer to this buffer.
 112 .\"O The caller should deallocate this buffer using
 113 .\"O .BR free (3).
 114 .I resolved_path
 115 に NULL が指定されると、
 116 .BR realpath ()
 117 は
 118 .BR malloc (3)
 119 を使って解決したパス名を保持するためのバッファを
 120 最大で
 121 .B PATH_MAX
 122 バイトまで割り当て、このバッファへのポインタを返す。
 123 呼び出し元は、
 124 .BR free (3)
 125 を使ってこのバッファを解放すべきである。
 126 .\"O .\" Even if we use resolved_path == NULL, then realpath() will still
 127 .\"O .\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX
 128 .\"O .\" bytes -- MTK, Dec 04
 129 .\" resolved_path == NULL を指定した場合でも、解決したパス名の長さが
 130 .\" PATH_MAX バイトを超えたときには、realpath() は前と同じく
 131 .\" ENAMETOOLONG を返す。-- MTK, Dec 04
 132 .\"O .\" .SH HISTORY
 133 .\" .SH 歴史
 134 .\"O .\" The
 135 .\"O .\" .BR realpath ()
 136 .\"O .\" function first appeared in 4.4BSD, contributed by Jan-Simon Pendry.
 137 .\" .BR realpath ()
 138 .\" 関数は 4.4BSD で初めて登場した (Jan-Simon Pendry により提供された)。
 139 .\"O .SH "RETURN VALUE"
 140 .SH 返り値
 141 .\"O If there is no error,
 142 .\"O .BR realpath ()
 143 .\"O returns a pointer to the
 144 .\"O .IR resolved_path .
 145 エラーがなかった場合、
 146 .BR realpath ()
 147 は
 148 .I resolved_path
 149 へのポインターを返す。
 150
 151 .\"O Otherwise it returns a NULL pointer, and the contents
 152 .\"O of the array
 153 .\"O .I resolved_path
 154 .\"O are undefined, and
 155 .\"O .I errno
 156 .\"O is set to indicate the error.
 157 それ以外の場合は、ヌル (NULL) ポインターが返り、配列
 158 .I resolved_path
 159 の内容は不定となり、
 160 .I errno
 161 にエラーの内容を示す値がセットされる。
 162 .\"O .SH ERRORS
 163 .SH エラー
 164 .TP
 165 .B EACCES
 166 .\"O Read or search permission was denied for a component of the path prefix.
 167 パスのディレクトリ部分に、読み出し許可または検索許可が与えられていない。
 168 .TP
 169 .B EINVAL
 170 .\"O .I path
 171 .\"O is NULL.
 172 .\"O .\" (In libc5 this would just cause a segfault.)
 173 .\"O (In glibc versions before 2.3,
 174 .\"O this error is also returned if
 175 .\"O .IR resolved_path
 176 .\"O is NULL.)
 177 .I path
 178 が NULL である。
 179 .\" (libc5 では、このような場合 segfault を起こすだけであろう)
 180 (バージョン 2.3 より前の glibc では、
 181 .I resolved_path
 182 が NULL の場合にもこのエラーが返される。)
 183 .TP
 184 .B EIO
 185 .\"O An I/O error occurred while reading from the file system.
 186 ファイルシステムを読むときに、I/Oエラーが起こった。
 187 .TP
 188 .B ELOOP
 189 .\"O Too many symbolic links were encountered in translating the pathname.
 190 パス名の変換にあたり、解決すべきシンボリック・リンクの数が多過ぎた。
 191 .TP
 192 .B ENAMETOOLONG
 193 .\"O A component of a pathname exceeded
 194 .\"O .B NAME_MAX
 195 .\"O characters, or an entire pathname exceeded
 196 .\"O .B PATH_MAX
 197 .\"O characters.
 198 パス名の一要素の文字数が
 199 .B NAME_MAX
 200 を越えている、またはパス名全体の文字数が
 201 .B PATH_MAX
 202 を越えている。
 203 .TP
 204 .B ENOENT
 205 .\"O The named file does not exist.
 206 指定されたファイルが存在しない。
 207 .TP
 208 .B ENOTDIR
 209 .\"O A component of the path prefix is not a directory.
 210 パスのディレクトリ要素が、ディレクトリでない。
 211 .\"O .SH VERSIONS
 212 .SH バージョン
 213 .\"O On Linux this function appeared in libc 4.5.21.
 214 この関数が Linux に登場したのは libc 4.5.21 である。
 215 .\"O .SH "CONFORMING TO"
 216 .SH 準拠
 217 4.4BSD, POSIX.1-2001.
 218
 219 .\"O POSIX.1-2001 says that the behavior if
 220 .\"O .I resolved_path
 221 .\"O is NULL is implementation-defined.
 222 .\"O POSIX.1-2008 specifies the behavior described in this page.
 223 POSIX.1-2001 では
 224 .I resolved_path
 225 が NULL の場合の動作は実装に依存するとしている。
 226 POSIX.1-2008 では、このマニュアルページに書かれている動作が規定されている。
 227 .\"O .SH NOTES
 228 .SH 注意
 229 .\"O In 4.4BSD and Solaris the limit on the pathname length is
 230 .\"O .B MAXPATHLEN
 231 .\"O (found in \fI<sys/param.h>\fP).
 232 .\"O SUSv2 prescribes
 233 .\"O .B PATH_MAX
 234 .\"O and
 235 .\"O .BR NAME_MAX ,
 236 .\"O as found in \fI<limits.h>\fP or provided by the
 237 .\"O .BR pathconf (3)
 238 .\"O function.
 239 .\"O A typical source fragment would be
 240 .\"O .LP
 241 .\"O .in +4n
 242 .\"O .nf
 243 .\"O #ifdef PATH_MAX
 244 .\"O   path_max = PATH_MAX;
 245 .\"O #else
 246 .\"O   path_max = pathconf(path, _PC_PATH_MAX);
 247 .\"O   if (path_max <= 0)
 248 .\"O          path_max = 4096;
 249 .\"O #endif
 250 .\"O .fi
 251 .\"O .in
 252 4.4BSD と Solaris では、パス名の長さの上限は
 253 (\fI<sys/param.h>\fP の中にある)
 254 .B MAXPATHLEN
 255 である。SUSv2 では
 256 .B PATH_MAX
 257 と
 258 .B NAME_MAX
 259 が規定されており、
 260 これらは \fI<limits.h>\fP で定義されているか、
 261 .BR pathconf (3)
 262 関数から得られる。以下のようなソースコードになっていることが多い。
 263 .LP
 264 .in +4n
 265 .nf
 266 #ifdef PATH_MAX
 267   path_max = PATH_MAX;
 268 #else
 269   path_max = pathconf(path, _PC_PATH_MAX);
 270   if (path_max <= 0)
 271          path_max = 4096;
 272 #endif
 273 .fi
 274 .in
 275 .LP
 276 .\"O (But see the BUGS section.)
 277 (バグの章も参照のこと。)
 278 .LP
 279 .\"O The 4.4BSD, Linux and SUSv2 versions always return an absolute
 280 .\"O pathname.
 281 .\"O Solaris may return a relative pathname when the
 282 .\"O .I path
 283 .\"O argument is relative.
 284 4.4BSD、Linux、SUSv2 では、返り値は常に絶対パス名である。
 285 Solaris では、
 286 引き数
 287 .I path
 288 が相対パスの場合、返り値が相対パスになることがある。
 289 .\"O The prototype of
 290 .\"O .BR realpath ()
 291 .\"O is given in \fI<unistd.h>\fP in libc4 and libc5,
 292 .\"O but in \fI<stdlib.h>\fP everywhere else.
 293 .BR realpath ()
 294 のプロトタイプ宣言は、
 295 libc4 と libc5 では \fI<unistd.h>\fP にあるが、
 296 それ以外の環境ではいずれも \fI<stdlib.h>\fP にある。
 297 .\"O .SH BUGS
 298 .SH バグ
 299 .\"O The POSIX.1-2001 standard version of this function is broken by design,
 300 .\"O since it is impossible to determine a suitable size for the output buffer,
 301 .\"O .IR resolved_path .
 302 .\"O According to POSIX.1-2001 a buffer of size
 303 .\"O .B PATH_MAX
 304 .\"O suffices, but
 305 .\"O .B PATH_MAX
 306 .\"O need not be a defined constant, and may have to be obtained using
 307 .\"O .BR pathconf (3).
 308 この関数の POSIX.1-2001 版は、設計段階から問題がある。
 309 出力バッファ
 310 .I resolved_path
 311 の適切なサイズを決定することができないからである。
 312 POSIX.1-2001 ではバッファ・サイズとして
 313 .B PATH_MAX
 314 は十分だとされているが、
 315 .B PATH_MAX
 316 は定義済の定数である必要はなく、
 317 .BR pathconf (3)
 318 を使って得られる値であってもよいことになっている。
 319 .\"O And asking
 320 .\"O .BR pathconf (3)
 321 .\"O does not really help, since, on the one hand POSIX warns that
 322 .\"O the result of
 323 .\"O .BR pathconf (3)
 324 .\"O may be huge and unsuitable for mallocing memory,
 325 .\"O and on the other hand
 326 .\"O .BR pathconf (3)
 327 .\"O may return \-1 to signify that
 328 .\"O .B PATH_MAX
 329 .\"O is not bounded.
 330 .BR pathconf (3)
 331 からバッファ・サイズを取得したとしても必ずしも十分ではない。
 332 なぜなら、POSIX で警告されているように、
 333 .BR pathconf (3)
 334 の返り値が大き過ぎて適切にメモリを確保することができない
 335 かもしれない一方で、
 336 .BR pathconf (3)
 337 は
 338 .B PATH_MAX
 339 に制限がないことを示す \-1 を返すかもしれないからである。
 340 .\"O The
 341 .\"O .I "resolved_path\ ==\ NULL"
 342 .\"O feature, not standardized in POSIX.1-2001,
 343 .\"O but standardized in POSIX.1-2008, allows this design problem to be avoided.
 344 .I "resolved_path\ ==\ NULL"
 345 の機能を使うと、この設計上の問題を回避することができる。
 346 この機能は POSIX.1-2001 では標準化されていないが、
 347 POSIX.1-2008 では標準化されている。
 348 .LP
 349 .\"O The libc4 and libc5 implementation contains a buffer overflow
 350 .\"O (fixed in libc-5.4.13).
 351 .\"O Thus, set-user-ID programs like
 352 .\"O .BR mount (8)
 353 .\"O need a private version.
 354 libc4 と libc5 の実装はバッファ・オーバーフローの可能性を持っている
 355 (libc-5.4.13 で修正されたが)。したがって、
 356 .BR mount (8)
 357 のような set-user-ID されるプログラムでは、
 358 この関数相当の関数を自前で持つ必要がある。
 359 .\"O .SH "SEE ALSO"
 360 .SH 関連項目
 361 .BR readlink (2),
 362 .BR canonicalize_file_name (3),
 363 .BR getcwd (3),
 364 .BR pathconf (3),
 365 .BR sysconf (3)