plucky (3) getwd.3.gz

名前

       getcwd, getwd, get_current_dir_name - カレントワーキングディレクトリ名の取得

書式

       #include <unistd.h>

       char *getcwd(char *buf, size_t size);

       char *getwd(char *buf);

       char *get_current_dir_name(void);

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

       get_current_dir_name():
              _GNU_SOURCE

       getwd():
           glibc 2.12 以降:
               (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
                   || /* Glibc 2.19 以降: */ _DEFAULT_SOURCE
                   || /* Glibc 2.19 以前: */ _BSD_SOURCE
           glibc 2.12 より前:
                _BSD_SOURCE || _XOPEN_SOURCE >= 500

説明

       これらの関数は、呼び出したプロセスのカレントワーキングディレクトリの  絶対パス名  (absolute  pathname) が
       入った文字列を返す。 返される文字列はヌルで終端される。 パス名は関数の結果として返され、引数 buf がある場
       合は buf 経由でも返される。

       getcwd()  関数はカレントワーキングディレクトリの絶対パス名を buf で示された size 長の配列にコピーする。

       終端のヌルバイトも含めた、カレントワーキングディレクトリの 絶対パス名の長さが size バイトを超えている場合
       は、返り値として NULL が返り errno に ERANGE がセットされる。  アプリケーションはこのエラーをチェックし、
       必要に応じてより長いバッファーを用意すべきである。

       POSIX.1-2001  標準の拡張として、 glibc では buf が NULL の場合、 getcwd()  は必要なバッファーを malloc(3)
       を用いて動的に割り当てる。 この場合、 size が 0 の場合を除き、バッファーの長さは size となる。 size が  0
       の場合には必要な大きさが確保される。 呼び出し側で、返されたバッファーを free(3)  すべきである。

       get_current_dir_name()    はカレントワーキングディレクトリの絶対パス名を収めるのに   十分な大きさの配列を
       malloc(3)   で獲得する。環境変数  PWD  が設定されておりその値が正しければ、その値が返される。  呼び出し側
       で、返されたバッファーを free(3)  すべきである。

       getwd()   は malloc(3)  によるメモリー獲得を一切行なわない。 buf 引数は少なくとも PATH_MAX バイトの長さを
       持つ配列へのポインターである必要がある。 終端のヌルバイトも含めた、カレントワーキングディレクトリの  絶対
       パス名の長さが PATH_MAX バイトを超えている場合、 NULL が返され、 errno に ENAMETOOLONG が設定される。 (シ
       ステムによっては、 PATH_MAX は必ずしもコンパイル時に決まる定数ではない点に注意すること。 また、ファイルシ
       ステムに依存する場合もある。  pathconf(3)  を参照。)  移植性とセキュリティ上の理由から、 getwd() の利用は
       推奨されない。

返り値

       成功すると、これらの関数はカレントワーキングディレクトリの絶対パス名 が入った文字列へのポインターを返す。
       getcwd()  と getwd()  の場合、返り値は buf と同じ値になる。

       失敗した場合、これらの関数は  NULL を返し、 errno にエラーを示す値を設定する。 buf が指す配列の内容は未定
       義である。

エラー

       EACCES ファイル名の構成要素に対する読み込みあるいは検索の権限がない。

       EFAULT buf が不正なアドレスを指している。

       EINVAL size 引数が 0 かつ、 buf 引数がヌルポインターでない。

       EINVAL getwd(): buf が NULL である。

       ENAMETOOLONG
              getwd(): 絶対パス名が入ったヌル終端された文字列の長さが PATH_MAX バイトを超えている。

       ENOENT カレントワーキングディレクトリが削除されている。

       ENOMEM メモリー不足。

       ERANGE size 引数の値がワーキングディレクトリの絶対パス名の長さより小さい。 長さには文字列の終端バイトも含
              まれる。 より大きい配列を確保してもう一度実行する必要がある。

属性

       この節で使用されている用語の説明については、 attributes(7) を参照。

       ┌────────────────────────┬───────────────┬─────────────┐
       │インターフェース        │ 属性          │ 値          │
       ├────────────────────────┼───────────────┼─────────────┤
       │ getcwd(), getwd()      │ Thread safety │ MT-Safe     │
       ├────────────────────────┼───────────────┼─────────────┤
       │ get_current_dir_name() │ Thread safety │ MT-Safe env │
       └────────────────────────┴───────────────┴─────────────┘

準拠

       getcwd()  は POSIX.1-2001 に準拠している。 POSIX.1-2001 は、 buf が NULL の場合の getcwd()   の動作を規定
       しないままとしている。

       getwd()    は  POSIX.1-2001  に存在しているが、「過去の名残(LEGACY)」とされている。  POSIX.1-2008  では、
       getwd()  の仕様が削除されている。 代わりに getcwd()  を使うこと。 POSIX.1-2001 は getwd()  に関するエラー
       を定義していない。

       get_current_dir_name()  は GNU 拡張である。

注意

       Under  Linux,  these  functions make use of the getcwd()  system call (available since Linux 2.1.92).  On
       older systems they would query /proc/self/cwd.  If both system call and proc filesystem  are  missing,  a
       generic implementation is called.  Only in that case can these calls fail under Linux with EACCES.

       これらの関数はしばしばカレントワーキングディレクトリの位置を保存し、  後で戻ってくるために利用される。 未
       使用のファイルディスクリプターが十分ある場合は、 現在のディレクトリ (".") を開いて fchdir(2) を呼び出すほ
       うが普通は高速で信頼性がある。 特に Linux 以外のプラットフォームの場合はそうである。

   C ライブラリとカーネルの違い
       On  Linux,  the  kernel provides a getcwd()  system call, which the functions described in this page will
       use if possible.  The system call takes the same arguments as the library function of the same name,  but
       is  limited  to  returning  at  most  PATH_MAX  bytes.   (Before Linux 3.12, the limit on the size of the
       returned pathname was the system page size.  On many architectures, PATH_MAX and the system page size are
       both  4096 bytes, but a few architectures have a larger page size.)  If the length of the pathname of the
       current working directory exceeds this limit, then the system call fails with the error ENAMETOOLONG.  In
       this case, the library functions fall back to a (slower) alternative implementation that returns the full
       pathname.

       Following a change in Linux 2.6.36, the pathname returned by the getcwd() system call  will  be  prefixed
       with  the  string "(unreachable)" if the current directory is not below the root directory of the current
       process (e.g., because the process set a new  filesystem  root  using  chroot(2)   without  changing  its
       current  directory  into  the  new  root).   Such  behavior can also be caused by an unprivileged user by
       changing the current directory into another mount namespace.  When dealing with pathname  from  untrusted
       sources,  callers  of  the functions described in this page should consider checking whether the returned
       pathname starts with '/' or '(' to avoid misinterpreting an unreachable path as a relative pathname.

バグ

       Since the Linux 2.6.36 change that added "(unreachable)" in the circumstances described above, the  glibc
       implementation  of getcwd()  has failed to conform to POSIX and returned a relative pathname when the API
       contract requires an absolute pathname.  With glibc 2.27 onwards  this  is  corrected;  calling  getcwd()
       from such a pathname will now result in failure with ENOENT.

関連項目

        pwd(1), chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)

この文書について

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