release/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 .\" All rights reserved.
   4 .\"
   5 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\" %%%LICENSE_END
  34 .\"
  35 .\"     @(#)readlink.2  6.8 (Berkeley) 3/10/91
  36 .\"
  37 .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu)
  38 .\" Modified Tue Jul  9 23:55:17 1996 by aeb
  39 .\" Modified Fri Jan 24 00:26:00 1997 by aeb
  40 .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>:
  41 .\"     Added text on dynamically allocating buffer + example program
  42 .\"
  43 .\"*******************************************************************
  44 .\"
  45 .\" This file was generated with po4a. Translate the source file.
  46 .\"
  47 .\"*******************************************************************
  48 .\"
  49 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  50 .\"         all rights reserved.
  51 .\" Translated 1997-12-12, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  52 .\" Updated 2005-02-10, Yuichi SATO <ysato444@yahoo.co.jp>
  53 .\" Updated 2006-07-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
  54 .\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05
  55 .\" Updated 2012-05-08, Akihiro MOTOKI <amotoki@gmail.com>
  56 .\"
  57 .TH READLINK 2 2013\-07\-18 Linux "Linux Programmer's Manual"
  58 .SH 名前
  59 readlink \- シンボリックリンクの値を読む
  60 .SH 書式
  61 \fB#include <unistd.h>\fP
  62 .sp
  63 \fBssize_t readlink(const char *\fP\fIpath\fP\fB, char *\fP\fIbuf\fP\fB, size_t
  64 \fP\fIbufsiz\fP\fB);\fP
  65 .sp
  66 .in -4n
  67 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  68 .in
  69 .sp
  70 .ad l
  71 \fBreadlink\fP():
  72 .RS 4
  73 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L
  74 .RE
  75 .ad b
  76 .SH 説明
  77 \fBreadlink\fP()  は \fIpath\fP で与えられたシンボリックリンクの内容を \fIbuf\fP バッファーへ格納する、 \fIbuf\fP のサイズは
  78 \fIbufsiz\fP である。 \fBreadlink\fP()  は NULL バイトを \fIbuf\fP に追加しない。
  79 その内容全てを格納するのにバッファーが小さ過ぎる場合は、 (\fIbufsiz\fP バイトの長さに) 内容を切り詰める。
  80 .SH 返り値
  81 成功すると、 \fBreadlink\fP()  は \fIbuf\fP に格納されたバイト数を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP
  82 にエラーを示す値を設定する。
  83 .SH エラー
  84 .TP
  85 \fBEACCES\fP
  86 パスのディレクトリ部分に検索許可が与えられていない (\fBpath_resolution\fP(7)  も参照すること)。
  87 .TP
  88 \fBEFAULT\fP
  89 \fIbuf\fP がプロセスに割り当てられたアドレス空間の外を指している。
  90 .TP
  91 \fBEINVAL\fP
  92 .\" At the glibc level, bufsiz is unsigned, so this error can only occur
  93 .\" if bufsiz==0.  However, the in the kernel syscall, bufsiz is signed,
  94 .\" and this error can also occur if bufsiz < 0.
  95 .\" See: http://thread.gmane.org/gmane.linux.man/380
  96 .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
  97 \fIbufsiz\fP が正でない。
  98 .TP
  99 \fBEINVAL\fP
 100 指定したファイルがシンボリックリンクでない。
 101 .TP
 102 \fBEIO\fP
 103 ファイルシステムの読み込み中に I/O エラーが起こった。
 104 .TP
 105 \fBELOOP\fP
 106 パス名にシンボリックリンクが多すぎる。
 107 .TP
 108 \fBENAMETOOLONG\fP
 109 パス名かパス名の一部分が長過ぎる。
 110 .TP
 111 \fBENOENT\fP
 112 その名前のファイルが存在しない。
 113 .TP
 114 \fBENOMEM\fP
 115 十分なカーネルメモリーがない。
 116 .TP
 117 \fBENOTDIR\fP
 118 パスのディレクトリ部分がディレクトリでない。
 119 .SH 準拠
 120 4.4BSD (\fBreadlink\fP()  は 4.2BSD で初めて登場した), POSIX.1\-2001.
 121 .SH 注意
 122 バージョン 2.4 以前の glibc (バージョン 2.4 を含む) では、 \fBreadlink\fP()  の返り値の型は \fIint\fP
 123 で宣言されていた。現在では、返り値の型は \fIssize_t\fP である (返り値 \fIssize_t\fP は POSIX.1\-2001 で (新たに)
 124 必須となった)。
 125
 126 静的な大きさのバッファを使うと、シンボリックリンクの内容を
 127 格納するのに十分な領域がない場合がある。
 128 バッファに必要なサイズは、そのシンボリックリンクに対して \fBlstat\fP(2)
 129 の呼び出しで返される \fIstat.st_size\fP の値から取得できる。
 130 ただし、 \fBreadlink\fP() が書き込んだバイト数をチェックして、
 131 シンボリックリンクのサイズが \fBlstat\fP(2) と \fBreadlink\fP() の呼び出し
 132 の間で増えていないことを確認すべきである。
 133 \fBreadlink\fP() 用のバッファを動的に割り当てる方法でも、
 134 バッファサイズとして \fIPATH_MAX\fP を使用する場合に共通する移植性の
 135 問題を解決することができる。なぜなら、POSIX では、
 136 システムがそのような上限値を定義していない場合には、
 137 \fIPATH_MAX\fP が定義されることが保証されていないからである。
 138 .SH 例
 139 以下のプログラムは、 \fBreadlink\fP() が必要とするバッファを、
 140 \fBlstat\fP() が提供する情報に基づいて動的に割り当てる。
 141 また、両方の呼び出し間で競合条件がないことを保証している。
 142 .nf
 143
 144 #include <sys/types.h>
 145 #include <sys/stat.h>
 146 #include <stdio.h>
 147 #include <stdlib.h>
 148 #include <unistd.h>
 149
 150 int
 151 main(int argc, char *argv[])
 152 {
 153     struct stat sb;
 154     char *linkname;
 155     ssize_t r;
 156
 157     if (argc != 2) {
 158         fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
 159         exit(EXIT_FAILURE);
 160     }
 161
 162     if (lstat(argv[1], &sb) == \-1) {
 163         perror("lstat");
 164         exit(EXIT_FAILURE);
 165     }
 166
 167     linkname = malloc(sb.st_size + 1);
 168     if (linkname == NULL) {
 169         fprintf(stderr, "insufficient memory\en");
 170         exit(EXIT_FAILURE);
 171     }
 172
 173     r = readlink(argv[1], linkname, sb.st_size + 1);
 174
 175     if (r == \-1) {
 176         perror("lstat");
 177         exit(EXIT_FAILURE);
 178     }
 179
 180     if (r > sb.st_size) {
 181         fprintf(stderr, "symlink increased in size "
 182                         "between lstat() and readlink()\en");
 183         exit(EXIT_FAILURE);
 184     }
 185
 186     linkname[r] = \(aq\e0\(aq;
 187
 188     printf("\(aq%s\(aq points to \(aq%s\(aq\en", argv[1], linkname);
 189
 190     exit(EXIT_SUCCESS);
 191 }
 192 .fi
 193 .SH 関連項目
 194 \fBreadlink\fP(1), \fBlstat\fP(2), \fBreadlinkat\fP(2), \fBstat\fP(2), \fBsymlink\fP(2),
 195 \fBpath_resolution\fP(7), \fBsymlink\fP(7)
 196 .SH この文書について
 197 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.54 の一部
 198 である。プロジェクトの説明とバグ報告に関する情報は
 199 http://www.kernel.org/doc/man\-pages/ に書かれている。