draft/man2/readlink.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" And Copyright (C) 2011 Guillem Jover <guillem@hadrons.org>
   3 .\" And Copyright (C) 2006, 2014 Michael Kerrisk
   4 .\" All rights reserved.
   5 .\"
   6 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   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 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\" %%%LICENSE_END
  35 .\"
  36 .\"     @(#)readlink.2  6.8 (Berkeley) 3/10/91
  37 .\"
  38 .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu)
  39 .\" Modified Tue Jul  9 23:55:17 1996 by aeb
  40 .\" Modified Fri Jan 24 00:26:00 1997 by aeb
  41 .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>:
  42 .\"     Added text on dynamically allocating buffer + example program
  43 .\"
  44 .\"*******************************************************************
  45 .\"
  46 .\" This file was generated with po4a. Translate the source file.
  47 .\"
  48 .\"*******************************************************************
  49 .\"
  50 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  51 .\"         all rights reserved.
  52 .\" Translated 1997-12-12, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  53 .\" Updated 2005-02-10, Yuichi SATO <ysato444@yahoo.co.jp>
  54 .\" Updated 2006-07-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
  55 .\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05
  56 .\" Updated 2012-05-08, Akihiro MOTOKI <amotoki@gmail.com>
  57 .\"
  58 .TH READLINK 2 2014\-02\-21 Linux "Linux Programmer's Manual"
  59 .SH 名前
  60 readlink, readlinkat \- read value of a symbolic link
  61 .SH 書式
  62 .nf
  63 \fB#include <unistd.h>\fP
  64 .sp
  65 \fBssize_t readlink(const char *\fP\fIpathname\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbufsiz\fP\fB);\fP
  66 .sp
  67 \fB#include <fcntl.h>           \fP/* AT_* 定数の定義 */
  68 \fB#include <unistd.h>\fP
  69 .sp
  70 \fBint readlinkat(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB,\fP
  71 \fB               char *\fP\fIbuf\fP\fB, size_t \fP\fIbufsiz\fP\fB);\fP
  72 .sp
  73 .fi
  74 .in -4n
  75 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  76 .in
  77 .sp
  78 .ad l
  79 \fBreadlink\fP():
  80 .RS 4
  81 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L
  82 .RE
  83 .sp
  84 \fBreadlinkat\fP():
  85 .PD 0
  86 .ad l
  87 .RS 4
  88 .TP  4
  89 glibc 2.10 以降:
  90 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  91 .TP
  92 glibc 2.10 より前:
  93 _ATFILE_SOURCE
  94 .RE
  95 .ad b
  96 .PD
  97 .SH 説明
  98 \fBreadlink\fP()  places the contents of the symbolic link \fIpathname\fP in the
  99 buffer \fIbuf\fP, which has size \fIbufsiz\fP.  \fBreadlink\fP()  does not append a
 100 null byte to \fIbuf\fP.  It will truncate the contents (to a length of
 101 \fIbufsiz\fP characters), in case the buffer is too small to hold all of the
 102 contents.
 103 .SS readlinkat()
 104 \fBreadlinkat\fP() システムコールは \fBreadlink\fP() と全く同様に動作するが、以下で説明する点が異なる。
 105
 106 \fIpathname\fP で指定されたパス名が相対パスの場合、このパス名はファイルディスクリプター \fIdirfd\fP
 107 が参照するディレクトリに対する相対パスと解釈される (\fBreadlink\fP()
 108 に相対パス名を渡した場合のように、呼び出したプロセスのカレントワーキングディレクトリに対する相対パスではない)。
 109
 110 \fIpathname\fP で指定されたパス名が相対パスで、 \fIdirfd\fP が特別な値 \fBAT_FDCWD\fP の場合、 (\fBreadlink\fP()
 111 と同様に) \fIpathname\fP は呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと解釈される。
 112
 113 \fIpathname\fP で指定されたパス名が絶対パスの場合、 \fIdirfd\fP は無視される。
 114
 115 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 116 Since Linux 2.6.39, \fIpathname\fP can be an empty string, in which case the
 117 call operates on the file referred to by \fIdirfd\fP (which may have been
 118 obtained using the \fBopen\fP(2)  \fBO_PATH\fP flag).  In this case, \fIdirfd\fP can
 119 refer to any type of file, not just a directory.
 120 .PP
 121 \fBreadlinkat\fP() の必要性についての説明については \fBopenat\fP(2) を参照。
 122 .SH 返り値
 123 成功すると、これらのシステムコールは \fIbuf\fP に格納されたバイト数を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP
 124 にエラーを示す値を設定する。
 125 .SH エラー
 126 .TP
 127 \fBEACCES\fP
 128 パスのディレクトリ部分に検索許可が与えられていない (\fBpath_resolution\fP(7)  も参照すること)。
 129 .TP
 130 \fBEFAULT\fP
 131 \fIbuf\fP がプロセスに割り当てられたアドレス空間の外を指している。
 132 .TP
 133 \fBEINVAL\fP
 134 .\" At the glibc level, bufsiz is unsigned, so this error can only occur
 135 .\" if bufsiz==0.  However, the in the kernel syscall, bufsiz is signed,
 136 .\" and this error can also occur if bufsiz < 0.
 137 .\" See: http://thread.gmane.org/gmane.linux.man/380
 138 .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
 139 \fIbufsiz\fP が正でない。
 140 .TP
 141 \fBEINVAL\fP
 142 指定したファイルがシンボリックリンクでない。
 143 .TP
 144 \fBEIO\fP
 145 ファイルシステムの読み込み中に I/O エラーが起こった。
 146 .TP
 147 \fBELOOP\fP
 148 パス名にシンボリックリンクが多すぎる。
 149 .TP
 150 \fBENAMETOOLONG\fP
 151 パス名かパス名の一部分が長過ぎる。
 152 .TP
 153 \fBENOENT\fP
 154 その名前のファイルが存在しない。
 155 .TP
 156 \fBENOMEM\fP
 157 十分なカーネルメモリーがない。
 158 .TP
 159 \fBENOTDIR\fP
 160 パスのディレクトリ部分がディレクトリでない。
 161 .PP
 162 \fBreadlinkat\fP() では以下のエラーも発生する。
 163 .TP
 164 \fBEBADF\fP
 165 \fIdirfd\fP が有効なファイルディスクリプタではない。
 166 .TP
 167 \fBENOTDIR\fP
 168 \fIpathname\fP が相対パスで、 \fIdirfd\fP がディレクトリ以外のファイルを参照しているファイルディスクリプタである。
 169 .SH バージョン
 170 \fBreadlinkat\fP()  はカーネル 2.6.16 で Linux に追加された。 ライブラリによるサポートはバージョン 2.4 で glibc
 171 に追加された。
 172 .SH 準拠
 173 \fBreadlink\fP(): 4.4BSD (\fBreadlink\fP()  first appeared in 4.2BSD),
 174 POSIX.1\-2001, POSIX.1\-2008.
 175
 176 \fBreadlinkat\fP(): POSIX.1\-2008.
 177 .SH 注意
 178 バージョン 2.4 以前の glibc (バージョン 2.4 を含む) では、 \fBreadlink\fP()  の返り値の型は \fIint\fP
 179 で宣言されていた。現在では、返り値の型は \fIssize_t\fP である (返り値 \fIssize_t\fP は POSIX.1\-2001 で (新たに)
 180 必須となった)。
 181
 182 Using a statically sized buffer might not provide enough room for the
 183 symbolic link contents.  The required size for the buffer can be obtained
 184 from the \fIstat.st_size\fP value returned by a call to \fBlstat\fP(2)  on the
 185 link.  However, the number of bytes written by \fBreadlink\fP()  and
 186 \fBreadlinkat\fP()  should be checked to make sure that the size of the
 187 symbolic link did not increase between the calls.  Dynamically allocating
 188 the buffer for \fBreadlink\fP()  and \fBreadlinkat\fP()  also addresses a common
 189 portability problem when using \fIPATH_MAX\fP for the buffer size, as this
 190 constant is not guaranteed to be defined per POSIX if the system does not
 191 have such limit.
 192 .SH 例
 193 以下のプログラムは、 \fBreadlink\fP() が必要とするバッファを、
 194 \fBlstat\fP() が提供する情報に基づいて動的に割り当てる。
 195 また、両方の呼び出し間で競合条件がないことを保証している。
 196 .nf
 197
 198 #include <sys/types.h>
 199 #include <sys/stat.h>
 200 #include <stdio.h>
 201 #include <stdlib.h>
 202 #include <unistd.h>
 203
 204 int
 205 main(int argc, char *argv[])
 206 {
 207     struct stat sb;
 208     char *linkname;
 209     ssize_t r;
 210
 211     if (argc != 2) {
 212         fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
 213         exit(EXIT_FAILURE);
 214     }
 215
 216     if (lstat(argv[1], &sb) == \-1) {
 217         perror("lstat");
 218         exit(EXIT_FAILURE);
 219     }
 220
 221     linkname = malloc(sb.st_size + 1);
 222     if (linkname == NULL) {
 223         fprintf(stderr, "insufficient memory\en");
 224         exit(EXIT_FAILURE);
 225     }
 226
 227     r = readlink(argv[1], linkname, sb.st_size + 1);
 228
 229     if (r == \-1) {
 230         perror("readlink");
 231         exit(EXIT_FAILURE);
 232     }
 233
 234     if (r > sb.st_size) {
 235         fprintf(stderr, "symlink increased in size "
 236                         "between lstat() and readlink()\en");
 237         exit(EXIT_FAILURE);
 238     }
 239
 240     linkname[r] = \(aq\e0\(aq;
 241
 242     printf("\(aq%s\(aq points to \(aq%s\(aq\en", argv[1], linkname);
 243
 244     exit(EXIT_SUCCESS);
 245 }
 246 .fi
 247 .SH 関連項目
 248 \fBreadlink\fP(1), \fBlstat\fP(2), \fBstat\fP(2), \fBsymlink\fP(2),
 249 \fBpath_resolution\fP(7), \fBsymlink\fP(7)
 250 .SH この文書について
 251 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.63 の一部
 252 である。プロジェクトの説明とバグ報告に関する情報は
 253 http://www.kernel.org/doc/man\-pages/ に書かれている。