名前

       readlink, readlinkat - シンボリックリンクの値を読む

書式

       #include <unistd.h>

       ssize_t readlink(const char *pathname, char *buf, size_t bufsiz);

       #include <fcntl.h>           /* AT_* 定数の定義 */
       #include <unistd.h>

       ssize_t readlinkat(int dirfd, const char *pathname,
                          char *buf, size_t bufsiz);

   glibc 向けの機能検査マクロの要件 (feature_test_macros(7)  参照):

       readlink():
            _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
               || /* glibc 2.19 以前: */ _BSD_SOURCE

       readlinkat():
           glibc 2.10 以降:
               _POSIX_C_SOURCE >= 200809L
           glibc 2.10 より前:
               _ATFILE_SOURCE

説明

       readlink()   は pathname で与えられたシンボリックリンクの内容を buf バッファーへ格納する、
       buf のサイズは bufsiz である。 readlink()  はヌルバイトを buf に追加しない。  その内容全て
       を格納するのにバッファーが小さ過ぎる場合は、  (bufsiz バイトの長さに) 内容を (黙って) 切り
       詰める。

   readlinkat()
       readlinkat()  システムコールは  readlink()  と全く同様に動作するが、以下で説明する点が異な
       る。

       pathname で指定されたパス名が相対パスの場合、このパス名はファイルディスクリプター dirfd が
       参照するディレクトリに対する相対パスと解釈される (readlink()  に相対パス名を渡した場合のよ
       うに、呼び出したプロセスのカレントワーキングディレクトリに対する相対パスではない)。

       pathname  で指定されたパス名が相対パスで、  dirfd が特別な値 AT_FDCWD の場合、 (readlink()
       と同様に) pathname  は呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと
       解釈される。

       pathname で指定されたパス名が絶対パスの場合、 dirfd は無視される。

       Linux  2.6.39 以降では、 pathname に空文字列を指定できる。 その場合、呼び出しは dirfd が参
       照するシンボリックリンクに対して行われる (dirfd はフラグ O_PATH と  O_NOFOLLOW  を指定した
       open(2) を使って取得すべきである)。

       readlinkat() の必要性についての説明については openat(2) を参照。

返り値

       On  success, these calls return the number of bytes placed in buf.  (If the returned value
       equals bufsiz, then truncation may have occurred.)  On error, -1 is returned and errno  is
       set to indicate the error.

エラー

       EACCES パスのディレクトリ部分に検索許可が与えられていない  (path_resolution(7)  も参照する
              こと)。

       EFAULT buf がプロセスに割り当てられたアドレス空間の外を指している。

       EINVAL bufsiz が正でない。

       EINVAL The named file (i.e., the final filename component of pathname)  is not a  symbolic
              link.

       EIO    ファイルシステムの読み込み中に I/O エラーが起こった。

       ELOOP  パス名にシンボリックリンクが多すぎる。

       ENAMETOOLONG
              パス名かパス名の一部分が長過ぎる。

       ENOENT その名前のファイルが存在しない。

       ENOMEM 十分なカーネルメモリーがない。

       ENOTDIR
              パスのディレクトリ部分がディレクトリでない。

       readlinkat() では以下のエラーも発生する。

       EBADF  dirfd が有効なファイルディスクリプターではない。

       ENOTDIR
              pathname  が相対パスで、  dirfd  がディレクトリ以外のファイルを参照しているファイル
              ディスクリプターである。

バージョン

       readlinkat()  はカーネル 2.6.16 で Linux に追加された。 ライブラリによるサポートはバージョ
       ン 2.4 で glibc に追加された。

準拠

       4.4BSD (readlink()  は 4.2BSD で初めて登場した), POSIX.1-2001, POSIX.1-2008.

       readlinkat(): POSIX.1-2008.

注意

       バージョン  2.4 以前の glibc (バージョン 2.4 を含む) では、 readlink()  の返り値の型は int
       で宣言されていた。現在では、返り値の型は ssize_t である (返り値 ssize_t は POSIX.1-2001 で
       (新たに) 必須となった)。

       静的な大きさのバッファーを使うと、  シンボリックリンクの内容を格納するのに十分な領域がない
       場合がある。 バッファーに必要なサイズは、 そのシンボリックリンクに対して lstat(2) の呼び出
       しで返される  stat.st_size の値から取得できる。 ただし、 readlink() や readlinkat() が書き
       込んだバイト数をチェックして、  シンボリックリンクのサイズが二つの呼び出しの間で増えていな
       いことを確認すべきである。 readlink() や readlinkat() 用のバッファーを動的に割り当てる方法
       でも、 バッファーサイズとして PATH_MAX  を使用する場合に共通する移植性の問題を解決すること
       ができる。   なぜなら、POSIX  では、  システムがそのような上限値を定義していない場合には、
       PATH_MAX が定義されることが保証されていないからである。

   glibc での注意
       readlinkat() が利用できない古いカーネルでは、 glibc ラッパー関数は  readlink()  を使用する
       モードにフォールバックする。  pathname  が相対パスの場合、  glibc  は dirfd 引数に対応する
       /proc/self/fd のシンボリックリンクに基づいてパス名を構成する。

例

       The following program allocates the buffer  needed  by  readlink()  dynamically  from  the
       information provided by lstat(2), falling back to a buffer of size PATH_MAX in cases where
       lstat(2)  reports a size of zero.

        #include <sys/types.h>
       #include <sys/stat.h>
       #include <limits.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

        int
       main(int argc, char *argv[])
       {
           struct stat sb;
           char *buf;
           ssize_t nbytes, bufsiz;

           if (argc != 2) {
               fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           if (lstat(argv[1], &sb) == -1) {
               perror("lstat");
               exit(EXIT_FAILURE);
           }

           /* Add one to the link size, so that we can determine whether
              the buffer returned by readlink() was truncated. */

           bufsiz = sb.st_size + 1;

           /* Some magic symlinks under (for example) /proc and /sys
              report 'st_size' as zero. In that case, take PATH_MAX as
              a "good enough" estimate. */

           if (sb.st_size == 0)
               bufsiz = PATH_MAX;

            buf = malloc(bufsiz);
           if (buf == NULL) {
               perror("malloc");
               exit(EXIT_FAILURE);
           }

            nbytes = readlink(argv[1], buf, bufsiz);
           if (nbytes == -1) {
               perror("readlink");
               exit(EXIT_FAILURE);
           }

            printf("'%s' points to '%.*s'\n", argv[1], (int) nbytes, buf);

           /* If the return value was equal to the buffer size, then the
              the link target was larger than expected (perhaps because the
              target was changed between the call to lstat() and the call to
              readlink()). Warn the user that the returned target may have
              been truncated. */

           if (nbytes == bufsiz)
               printf("(Returned buffer may have been truncated)\n");

            free(buf);
           exit(EXIT_SUCCESS);
       }

関連項目

       readlink(1), lstat(2), stat(2), symlink(2), realpath(3), path_resolution(7), symlink(7)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
       説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。