From 6bd5dc2ce74cdd1940384bff80dc7bf12094d3b3 Mon Sep 17 00:00:00 2001 From: Akihiro MOTOKI Date: Tue, 26 Mar 2013 01:28:22 +0900 Subject: [PATCH] LDP: Update drafts (editorical only) --- manual/LDP_man-pages/draft/man2/access.2 | 165 ++++++ manual/LDP_man-pages/draft/man2/chown.2 | 236 +++++++++ manual/LDP_man-pages/draft/man2/fcntl.2 | 662 +++++++++++++++++++++++++ manual/LDP_man-pages/draft/man2/flock.2 | 137 +++++ manual/LDP_man-pages/draft/man2/getdents.2 | 240 +++++++++ manual/LDP_man-pages/draft/man2/getxattr.2 | 101 ++++ manual/LDP_man-pages/draft/man2/inotify_init.2 | 85 ++++ manual/LDP_man-pages/draft/man2/listxattr.2 | 113 +++++ manual/LDP_man-pages/draft/man2/poll.2 | 231 +++++++++ manual/LDP_man-pages/draft/man2/readdir.2 | 100 ++++ manual/LDP_man-pages/draft/man2/uname.2 | 107 ++++ manual/LDP_man-pages/draft/man2/vfork.2 | 171 +++++++ manual/LDP_man-pages/draft/man2/vhangup.2 | 65 +++ manual/LDP_man-pages/draft/man3/euidaccess.3 | 79 +++ manual/LDP_man-pages/draft/man3/exec.3 | 142 ++++++ manual/LDP_man-pages/draft/man3/getutent.3 | 216 ++++++++ manual/LDP_man-pages/draft/man3/login.3 | 78 +++ manual/LDP_man-pages/draft/man3/readdir.3 | 175 +++++++ manual/LDP_man-pages/draft/man5/shells.5 | 59 +++ manual/LDP_man-pages/draft/man5/utmp.5 | 233 +++++++++ manual/LDP_man-pages/draft/man7/epoll.7 | 313 ++++++++++++ manual/LDP_man-pages/draft/man7/inotify.7 | 288 +++++++++++ 22 files changed, 3996 insertions(+) create mode 100644 manual/LDP_man-pages/draft/man2/access.2 create mode 100644 manual/LDP_man-pages/draft/man2/chown.2 create mode 100644 manual/LDP_man-pages/draft/man2/fcntl.2 create mode 100644 manual/LDP_man-pages/draft/man2/flock.2 create mode 100644 manual/LDP_man-pages/draft/man2/getdents.2 create mode 100644 manual/LDP_man-pages/draft/man2/getxattr.2 create mode 100644 manual/LDP_man-pages/draft/man2/inotify_init.2 create mode 100644 manual/LDP_man-pages/draft/man2/listxattr.2 create mode 100644 manual/LDP_man-pages/draft/man2/poll.2 create mode 100644 manual/LDP_man-pages/draft/man2/readdir.2 create mode 100644 manual/LDP_man-pages/draft/man2/uname.2 create mode 100644 manual/LDP_man-pages/draft/man2/vfork.2 create mode 100644 manual/LDP_man-pages/draft/man2/vhangup.2 create mode 100644 manual/LDP_man-pages/draft/man3/euidaccess.3 create mode 100644 manual/LDP_man-pages/draft/man3/exec.3 create mode 100644 manual/LDP_man-pages/draft/man3/getutent.3 create mode 100644 manual/LDP_man-pages/draft/man3/login.3 create mode 100644 manual/LDP_man-pages/draft/man3/readdir.3 create mode 100644 manual/LDP_man-pages/draft/man5/shells.5 create mode 100644 manual/LDP_man-pages/draft/man5/utmp.5 create mode 100644 manual/LDP_man-pages/draft/man7/epoll.7 create mode 100644 manual/LDP_man-pages/draft/man7/inotify.7 diff --git a/manual/LDP_man-pages/draft/man2/access.2 b/manual/LDP_man-pages/draft/man2/access.2 new file mode 100644 index 00000000..084b3000 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/access.2 @@ -0,0 +1,165 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Removed note about old kernel (pre-1.1.44) using wrong id on path. +.\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): +.\" Stated more clearly how it behaves with symbolic links. +.\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 +.\" Modified 1996-09-07 by Michael Haardt: +.\" Restrictions for NFS +.\" Modified 1997-09-09 by Joseph S. Myers +.\" Modified 1998-01-13 by Michael Haardt: +.\" Using access is often insecure +.\" Modified 2001-10-16 by aeb +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-06-10, mtk, various parts rewritten, and added BUGS section. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH ACCESS 2 2013\-02\-28 Linux "Linux Programmer's Manual" +.SH 名前 +access \- ファイルに対する実ユーザーでのアクセス権をチェックする +.SH 書式 +.nf +\fB#include \fP +.sp +\fBint access(const char *\fP\fIpathname\fP\fB, int \fP\fImode\fP\fB);\fP +.fi +.SH 説明 +\fBaccess\fP() は、呼び出し元プロセスがファイル \fIpathname\fP にアクセスできるかどうかをチェックする。 \fIpathname\fP +がシンボリック・リンクの場合、シンボリック・リンクは展開される。 + +.\" F_OK is defined as 0 on every system that I know of. +\fImode\fP はチェックを行うアクセス権を指定するもので、その値は \fBF_OK\fP、 もしくは \fBR_OK\fP, \fBW_OK\fP, \fBX_OK\fP の +1個以上のビット単位の論理和から構成されるマスクである。 \fBF_OK\fP はファイルが存在するかどうかのみを検査する。 \fBR_OK\fP, +\fBW_OK\fP, \fBX_OK\fP は、ファイルが存在して、それぞれ読み込み、書き込み、実行の許可があるか を検査する。 + +チェックは、実際に操作が行われる際に使用される実効 (effective) ID でなく、 呼び出し元プロセスの \fI実 (real)\fP UID と +\fI実 (real)\fP GID を使って行われる。 これにより、set\-user\-ID プログラムで、プログラムを起動するユーザの権限を +簡単に決定することができる。 + +呼び出し元プロセスが特権プロセス (つまり、プロセスの実 UID が 0) の場合、 通常のファイルに対する \fBX_OK\fP +のチェックは、そのファイルの所有者、グループ、他人のいずれかの 実行許可が有効になっていれば成功する。 +.SH 返り値 +成功した場合 (要求した全てについて許可が得られたら)、ゼロが返される。 エラーの場合 (\fImode\fP +の少なくとも一つのビットで要求した許可がなかった場合や、 他のエラーが起こった場合)、\-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +\fBaccess\fP() は以下の場合に失敗する。 +.TP +\fBEACCES\fP +要求されたアクセスは そのファイル自身に拒否されたか \fIpathname\fP へ至るまでディレクトリのいずれかに対する検索許可 (search +permission) が得られなかった。 (\fBpath_resolution\fP(7) も参照のこと) +.TP +\fBELOOP\fP +\fIpathname\fP を解決するときに、解決すべきシンボリックリンクが多すぎた。 +.TP +\fBENAMETOOLONG\fP +\fIpathname\fP が長過ぎる。 +.TP +\fBENOENT\fP +\fIpathname\fP を構成するパスのいずれかが、存在しないか、 参照先のない (dangling) シンボリックリンクになっている。 +.TP +\fBENOTDIR\fP +\fIpathname\fP のディレクトリ部分が実際にはディレクトリでない。 +.TP +\fBEROFS\fP +読み込み専用 (read\-only) のファイル・システムに対して書き込み許可を 要求した。 +.PP +\fBaccess\fP() は以下の理由により失敗することがある。 +.TP +\fBEFAULT\fP +\fIpathname\fP がアクセス可能なアドレス空間の外を指している。 +.TP +\fBEINVAL\fP +\fImode\fP に不正な値が指定された。 +.TP +\fBEIO\fP +I/O エラーが発生した。 +.TP +\fBENOMEM\fP +カーネルに十分なメモリがない。 +.TP +\fBETXTBSY\fP +実行中のファイルに対して書き込みを要求した。 +.SH 準拠 +SVr4, 4.3BSD, POSIX.1\-2001. +.SH 注意 +.PP +\fB警告\fP: あるユーザが、例えば \fBopen\fP(2) によるアクセスが可能かどうかを、 +(実際に行う前に) \fBaccess\fP() を使ってチェックするのは、セキュリティホール +の原因になる。なぜならチェックをしてから 実際にファイルのオープン操作を +する間の短い間隔を悪用できるからである。 \fBこの理由があるので、この +システムコールを使うのは避けるべきである。\fP +(ここで説明した例の場合には、より安全な方法としては、 +そのプロセスの実効ユーザ ID を実ユーザ ID に一時的に切り替えてから +\fBopen\fP(2) を呼び出す方法がある。) +.PP +\fBaccess\fP() は常にシンボリックリンクの展開を行う。 +シンボリックリンクのアクセス許可を確認する必要がある場合は、 +\fBAT_SYMLINK_NOFOLLOW\fP フラグ付きで \fBfaccessat\fP(2) を使うこと。 +.PP +\fImode\fP で指定されたアクセス種別のいずれか一つでも拒否されると、 たとえ \fImode\fP で指定された他のアクセス種別が許可されたとしても、 +\fBaccess\fP() はエラーを返す。 +.PP +.\" HPU-UX 11 and Tru64 5.1 do this. +POSIX.1\-2001 では、 呼び出し元プロセスが適切な特権を持っている場合 (つまり、スーパーユーザの場合)、 +たとえファイルの実行許可ビットが全くセットされていなくても \fBX_OK\fP のチェックとして成功を返す実装が認められている。 Linux +はこのようにはなっていない。 +.PP +\fIpathname\fP のプレフィックスを構成するディレクトリの全てに対して 検索アクセス (すなわち、実行アクセス) が許可された場合にのみ、 +ファイルはアクセス可能となる。 いずれかのディレクトリがアクセス不可の場合、 ファイル自身のアクセス許可に関わらず、 \fBaccess\fP() +は失敗する。 +.PP +アクセス・ビットのみがチェックされ、ファイルの種類や内容はチェックされない。 従って、ディレクトリが書き込み可能となった場合は、ディレクトリに +ファイルを作成することが可能なことを意味するのであり、ディレクトリに ファイルとして書き込むことができるわけではない。 同様に DOS +のファイルは「実行可能」と判断されるが、 \fBexecve\fP(2) コールは失敗するだろう。 +.PP +\fBaccess\fP() は、 UID マッピングを使用した NFS ファイルシステムでは正常に機能しないかもしれない。なぜならば UID +のマッピングはサーバーで 行なわれ、権利のチェックをするクライアントには見えないからである。同様の問題は FUSE マウントでも起こり得る。 +.SH バグ +.\" This behavior appears to have been an implementation accident. +バージョン 2.4 (とそれ以前) のカーネルには、スーパーユーザでの \fBX_OK\fP のチェックの扱いに奇妙な点がある。 ディレクトリ以外のファイルで +(ユーザ、グループ、他人の) 全てのカテゴリについて 実行許可がない場合、 \fBaccess\fP() のチェックで \-1 が返るのは \fImode\fP に +\fBX_OK\fP だけが指定されたときだけであり \fImode\fP に \fBR_OK\fP や \fBW_OK\fP が一緒に指定された場合には +\fBaccess\fP() は 0 を返す。 (バージョン 2.6.3 以前の) 初期の 2.6 系のカーネルも 2.4 系のカーネルと同様の動作をする。 + +2.6.20 より前のカーネルでは、 ファイルが存在するファイルシステムを \fBmount\fP(2) する際に指定された \fBMS_NOEXEC\fP +フラグの効果を、 \fBaccess\fP() は無視していた。 カーネル 2.6.20 以降では、 \fBaccess\fP() +はこのフラグを考慮するようになっている。 +.SH 関連項目 +\fBchmod\fP(2), \fBchown\fP(2), \fBfaccessat\fP(2), \fBopen\fP(2), \fBsetgid\fP(2), +\fBsetuid\fP(2), \fBstat\fP(2), \fBeauidaccess\fP(3), \fBcredentials\fP(7), +\fBpath_resolution\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/chown.2 b/manual/LDP_man-pages/draft/man2/chown.2 new file mode 100644 index 00000000..37d0642e --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/chown.2 @@ -0,0 +1,236 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (c) 2007, 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1996-07-09 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-05-18 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-07-08, mtk, added an example program; updated SYNOPSIS +.\" 2008-05-08, mtk, Describe rules governing ownership of new files +.\" (bsdgroups versus sysvgroups, and the effect of the parent +.\" directory's set-group-ID permission bit). +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH CHOWN 2 2010\-11\-22 Linux "Linux Programmer's Manual" +.SH 名前 +chown, fchown, lchown \- ファイルの所有者を変更する +.SH 書式 +\fB#include \fP +.sp +\fBint chown(const char *\fP\fIpath\fP\fB, uid_t \fP\fIowner\fP\fB, gid_t \fP\fIgroup\fP\fB);\fP +.br +\fBint fchown(int \fP\fIfd\fP\fB, uid_t \fP\fIowner\fP\fB, gid_t \fP\fIgroup\fP\fB);\fP +.br +\fBint lchown(const char *\fP\fIpath\fP\fB, uid_t \fP\fIowner\fP\fB, gid_t \fP\fIgroup\fP\fB);\fP +.sp +.in -4n +glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): +.in +.sp +\fBfchown\fP(), \fBlchown\fP(): +.PD 0 +.ad l +.RS 4 +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br +|| /* glibc 2.12 以降: */ _POSIX_C_SOURCE\ >=\ 200809L +.RE +.ad +.PD +.SH 説明 +これらのシステムコールは、いずれもファイルの所有者 (owner) とグループを変更する。システムコール間の違いは、ファイルの指定の仕方だけである。 +.IP * 2 +\fBchown\fP() は \fIpath\fP で指定されたファイルの所有権を変更する。 \fIpath\fP +がシンボリック・リンクの場合は、リンクの展開が行われる。 +.IP * +\fBfchown\fP() はオープンされたファイルディスクリプタ \fIfd\fP により参照されるファイルの所有権を変更する。 +.IP * +\fBlchown\fP() は \fBchown\fP() と同じだが、シンボリック・リンクを展開しない点が異なる。 +.PP +特権を持つプロセス (Linux では \fBCAP_CHOWN\fP ケーパビリティ (capability) を持つプロセス) だけが +ファイルの所有者を変更できる。 ファイルの所有者は、その所有者が属しているグループのいずれかに ファイルのグループを変更することができる。 特権 +(Linux では \fBCAP_CHOWN\fP) を持つプロセスは、任意のグループに変更できる。 + +\fIowner\fP または \fIgroup\fP に \-1 が指定された場合、それらの ID は変更されない。 + +.\" In Linux 2.0 kernels, superuser was like everyone else +.\" In 2.2, up to 2.2.12, these bits were not cleared for superuser. +.\" Since 2.2.13, superuser is once more like everyone else. +非特権ユーザーにより実行ファイルの所有者またはグループが 変更された場合は \fBS_ISUID\fP と \fBISGID\fP モードビットはクリアされる。 +POSIX はこの動作やルートが \fBchown\fP() を行なった場合については特に指定されていない。 Linux +における動作はカーネルのバージョンに依存する。 非グループ実行ファイル (\fBS_IXGRP\fP ビットが設定されていないファイル) の場合には +\fBS_ISGID\fP ビットは強制ロック (mandatory locking) を意味している。 そしてそれは \fBchown\fP() +ではクリアできない。 +.SH 返り値 +成功した場合は 0 が返される。エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +ファイルシステムによっては他のエラーが返される事がある。 \fBchmod\fP で一般的なエラーを以下に挙げる。 +.TP +\fBEACCES\fP +パス名の構成要素に検索許可がない (\fBpath_resolution\fP(7) も見よ)。 +.TP +\fBEFAULT\fP +\fIpath\fP がアクセスできるアドレス空間外を指している。 +.TP +\fBELOOP\fP +\fIpath\fP を解決する際に遭遇したシンボリック・リンクが多過ぎる。 +.TP +\fBENAMETOOLONG\fP +\fIpath\fP が長過ぎる。 +.TP +\fBENOENT\fP +ファイルが存在しない。 +.TP +\fBENOMEM\fP +カーネルに十分なメモリがない。 +.TP +\fBENOTDIR\fP +パス名の構成要素がディレクトリではない。 +.TP +\fBEPERM\fP +呼び出したプロセスに所有者またはグループ (もしくはその両方) を変更するために 要求される許可 (上記を参照) がない。 +.TP +\fBEROFS\fP +ファイルが読み込み専用 (read only) のファイル・システム上にある。 +.PP +\fBfchown\fP() で一般的なエラーを以下に挙げる: +.TP +\fBEBADF\fP +ディスクリプターが有効でない。 +.TP +\fBEIO\fP +i ノード (inode) を変更する際に低レベル I/O エラーが発生した。 +.TP +\fBENOENT\fP +上記を参照。 +.TP +\fBEPERM\fP +上記を参照。 +.TP +\fBEROFS\fP +上記を参照。 +.SH 準拠 +4.4BSD, SVr4, POSIX.1\-2001. + +.\" chown(): +.\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no +.\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. +.\" fchown(): +.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK +.\" error conditions. +4.4BSD 版ではスーパー・ユーザーのみが使用できる (つまり、普通のユーザーはファイルを手放すことはできない)。 +.SH 注意 +元々の Linux の \fBchown\fP(), \fBfchown\fP(), \fBlchown\fP() システムコールは、 +16 ビットのユーザ ID とグループ ID だけに対応していた。 +その後、 32 ビットの ID に対応した \fBchown32\fP(), \fBfchown32\fP(), \fBlchown32\fP() +が Linux 2.4 で追加された。 +\fBchown\fP(), \fBfchown\fP(), and \fBlchown\fP() の glibc のラッパー関数は、 +カーネルのバージョンによる違いを吸収している。 + +(\fBopen\fP(2) や \fBmkdir\fP(2) などにより) 新しいファイルが作成されるとき、 +その所有者は呼び出したプロセスのファイルシステム・ユーザ ID と 同じに設定される。 そのファイルのグループはいくつかの要因により決定される。 +その要因としては、 ファイルシステムの種類、そのファイルシステムのマウント時に 使用されたオプション、親ディレクトリで set\-group\-ID +許可ビットが 有効になっているどうか、がある。 ファイルシステムが \fBmount\fP(8) オプションの \fI\-o\ grpid\fP (\fI\-o\ bsdgroups\fP も同義語) と \fI\-o\ nogrpid\fP (\fI\-o sysvgroups\fP も同義語) +に対応している場合、ルールは以下の通りとなる。 +.IP * 2 +ファイルシステムが \fI\-o\ grpid\fP 付きでマウントされている場合、新しいファイルのグループは 親ディレクトリのグループと同じになる。 +.IP * +ファイルシステムが \fI\-o\ nogrpid\fP 付きでマウントされており、親ディレクトリでは set\-group\-ID ビットが +無効になっている場合、新しいファイルのグループは プロセスのファイルシステム GID と同じになる。 +.IP * +ファイルシステムが \fI\-o\ nogrpid\fP 付きでマウントされており、親ディレクトリでは set\-group\-ID ビットが +有効になっている場合、新しいファイルのグループは 親ディレクトリのグループと同じになる。 +.PP +Linux 2.6.25 では、マウントオプション \fI\-o\ grpid\fP と \fI\-o\ nogrpid\fP に対応しているファイルシステムは +ext2, ext3, ext4, XFS である。 これらのマウントオプションに対応していないファイルシステムでは、 \fI\-o\ nogrpid\fP +に関するルールが適用される。 +.PP +\fBchown\fP() 方式は UID マッピングを使用した NFS ファイル・システムを侵害する。 +さらにファイルの内容にアクセスする全てのシステム・コールを侵害する。 これは \fBchown\fP() が既にオープンされたファイルに対する +アクセスをただちに取り消すことによる。 クライアント側のキャッシュにより所有権が変更されて +ユーザーのアクセスが許した時点と、実際に他のクライアントでユーザーによって ファイルにアクセスできる時点との間に時間差があるかもしれない。 + +Linux の 2.1.81 より前のバージョン (特に 2.1.46 以前) では、 \fBchown\fP() はシンボリック・リンクを追跡しない。 +Linux 2.1.81 以降では \fBchown\fP() はシンボリック・リンクを追跡し、新たなシステム・コール \fBlchown\fP() +はシンボリック・リンクを追跡しない。 Linux 2.1.86 以降ではこの新しいコール (古い \fBchown\fP() と全く同じ動作を行なう) +は同じシステムコール番号を持ち \fBchown\fP() は新しく導入された番号を持つ。 +.SH 例 +.PP +以下のプログラムは、 二つ目のコマンドライン引き数で指定された名前のファイルの所有者を、 一つ目のコマンドライン引き数で指定された値に変更する。 +新しい所有者は、数字のユーザ ID かユーザ名のいずれかで指定できる (ユーザ名で指定した場合には、 \fBgetpwnam\fP(3) +を使ってシステムのパスワードファイルの検索が行われ、 ユーザ ID への変換が行われる)。 +.nf + +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + uid_t uid; + struct passwd *pwd; + char *endptr; + + if (argc != 3 || argv[1][0] == \(aq\e0\(aq) { + fprintf(stderr, "%s \en", argv[0]); + exit(EXIT_FAILURE); + } + + uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */ + + if (*endptr != \(aq\e0\(aq) { /* Was not pure numeric string */ + pwd = getpwnam(argv[1]); /* Try getting UID for username */ + if (pwd == NULL) { + perror("getpwnam"); + exit(EXIT_FAILURE); + } + + uid = pwd\->pw_uid; + } + + if (chown(argv[2], uid, \-1) == \-1) { + perror("chown"); + exit(EXIT_FAILURE); + } + + exit(EXIT_SUCCESS); +} +.fi +.SH 関連項目 +\fBchmod\fP(2), \fBfchownat\fP(2), \fBflock\fP(2), \fBpath_resolution\fP(7), +\fBsymlink\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/fcntl.2 b/manual/LDP_man-pages/draft/man2/fcntl.2 new file mode 100644 index 00000000..340600e1 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/fcntl.2 @@ -0,0 +1,662 @@ +.\" t +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson; +.\" and Copyright (C) 1998 Jamie Lokier; +.\" and Copyright (C) 2002-2010 Michael Kerrisk. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-09-26 by Andries Brouwer +.\" and again on 960413 and 980804 and 981223. +.\" Modified 1998-12-11 by Jamie Lokier +.\" Applied correction by Christian Ehrhardt - aeb, 990712 +.\" Modified 2002-04-23 by Michael Kerrisk +.\" Added note on F_SETFL and O_DIRECT +.\" Complete rewrite + expansion of material on file locking +.\" Incorporated description of F_NOTIFY, drawing on +.\" Stephen Rothwell's notes in Documentation/dnotify.txt. +.\" Added description of F_SETLEASE and F_GETLEASE +.\" Corrected and polished, aeb, 020527. +.\" Modified 2004-03-03 by Michael Kerrisk +.\" Modified description of file leases: fixed some errors of detail +.\" Replaced the term "lease contestant" by "lease breaker" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool +.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. +.\" 2005-04-08 Jamie Lokier , mtk +.\" Described behavior of F_SETOWN/F_SETSIG in +.\" multithreaded processes, and generally cleaned +.\" up the discussion of F_SETOWN. +.\" 2005-05-20, Johannes Nicolai , +.\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4 +.\" and earlier. Added text on permissions required to send signal. +.\" 2009-09-30, Michael Kerrisk +.\" Note obsolete F_SETOWN behavior with threads. +.\" Document F_SETOWN_EX and F_GETOWN_EX +.\" 2010-06-17, Michael Kerrisk +.\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH FCNTL 2 2012\-04\-15 Linux "Linux Programmer's Manual" +.SH 名前 +fcntl \- ファイルディスクリプタの操作を行う +.SH 書式 +.nf +\fB#include \fP +\fB#include \fP +.sp +\fBint fcntl(int \fP\fIfd\fP\fB, int \fP\fIcmd\fP\fB, ... /* \fP\fIarg\fP\fB */ );\fP +.fi +.SH 説明 +\fBfcntl\fP() は、オープンされたファイルディスクリプタ \fIfd\fP に関して下記の操作を行う。操作は \fIcmd\fP によって決まる: + +\fBfcntl\fP() はオプションとして第三引き数をとることができる。 第三引き数が必要 +かどうかは \fIcmd\fP により決まる。必要な引き数の型は \fIcmd\fP 名の後ろの括弧内で +指定されている (ほとんどの場合、必要な型は \fIint\fP であり、この引き数を表すの +に \fIarg\fP という名前を使っている)。引き数が必要ない場合には \fIvoid\fP が指定さ +れている。 +.SS ファイルディスクリプタの複製 +.TP +\fBF_DUPFD\fP (\fIint\fP) +利用可能なファイルディスクリプタのうち、 \fIarg\fP 以上で最小のものを探し、 \fIfd\fP のコピーとする。これは別の形の \fBdup2\fP(2) +である。 \fBdup2\fP(2) では指定されたディスクリプタが使われる点が違う。 +.IP +成功すると、新しいディスクリプタが返される。 +.IP +詳細は \fBdup\fP(2) を参照のこと。 +.TP +\fBF_DUPFD_CLOEXEC\fP (\fIint\fP; Linux 2.6.24 以降) +\fBF_DUPFD\fP と同様だが、それに加えて複製されたディスクリプタに対して close\-on\-exec フラグをセットする。 +このフラグを指定することで、プログラムは \fBFD_CLOEXEC\fP フラグをセットするために \fBfcntl\fP() の \fBF_SETFD\fP +操作を追加で行う必要がなくなる。 このフラグがなぜ有用かについては、 \fBopen\fP(2) の \fBO_CLOEXEC\fP の説明を参照のこと。 +.SS ファイルディスクリプタ・フラグ +以下のコマンドを使って、ファイルディスクリプタに関連するフラグ を操作することができる。 現在のところ、定義されているフラグは一つだけである: +\fBFD_CLOEXEC\fP (close\-on\-exec フラグ)。 \fBFD_CLOEXEC\fP ビットが 0 なら、ファイルディスクリプタは +\fBexecve\fP(2) を行ってもオープンされたままだが、そうでない場合はクローズされる。 +.TP +\fBF_GETFD\fP (\fIvoid\fP) +ファイルディスクリプタ・フラグを読み出す。 \fIarg\fP は無視される。 +.TP +\fBF_SETFD\fP (\fIint\fP) +ファイルディスクリプタ・フラグに \fIarg\fP で指定した値を設定する。 +.SS ファイル状態フラグ +.\" or +.\" .BR creat (2), +オープンファイル記述 (open file description) には、 ファイル記述毎に設定される状態フラグがいくつかある。これらのフラグは +\fBopen\fP(2) によって初期化され、 \fBfcntl\fP(2) により変更することもできる。これらは、 (\fBdup\fP(2), +\fBfcntl\fP(F_DUPFD), \fBfork\fP(2) などで) 複製されたファイルディスクリプタ同士は 同じオープンファイル記述を参照する。 +そのため、 同じファイル状態フラグが共有される。 + +ファイル状態フラグとその意味は \fBopen\fP(2) で説明されている。 +.TP +\fBF_GETFL\fP (\fIvoid\fP) +ファイルのアクセスモードとファイル状態フラグを取得する。 +\fIarg\fP は無視される。 +.TP +\fBF_SETFL\fP (\fIint\fP) +.\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable +.\" via fcntl(2), but currently Linux does not permit this +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5994 +ファイル状態フラグに \fIarg\fP で指定された値を設定する。 \fIarg\fP のうち、ファイルのアクセスモード (\fBO_RDONLY\fP, +\fBO_WRONLY\fP, \fBO_RDWR\fP) とファイル作成フラグ (すなわち \fBO_CREAT\fP, \fBO_EXCL\fP, +\fBO_NOCTTY\fP, \fBO_TRUNC\fP) に関するビットは無視される。 Linux では、このコマンドで変更できるのは +\fBO_APPEND\fP, \fBO_ASYNC\fP, \fBO_DIRECT\fP, \fBO_NOATIME\fP, \fBO_NONBLOCK\fP フラグだけである。 +.SS アドバイザリ・ロック +\fBF_GETLK\fP, \fBF_SETLK\fP, \fBF_SETLKW\fP は、レコード・ロックの獲得／解放／テストのために使用する +(レコード・ロックはファイルセグメント・ロックや ファイル領域ロックとも呼ばれる)。 三番目の引き数 \fIlock\fP +は、以下に示すフィールドを含む構造体へのポインタである (フィールドの順序は関係なく、構造体に他のフィールドがあってもよい)。 +.in +4n +.nf +.sp +struct flock { + ... + short l_type; /* Type of lock: F_RDLCK, + F_WRLCK, F_UNLCK */ + short l_whence; /* How to interpret l_start: + SEEK_SET, SEEK_CUR, SEEK_END */ + off_t l_start; /* Starting offset for lock */ + off_t l_len; /* Number of bytes to lock */ + pid_t l_pid; /* PID of process blocking our lock + (F_GETLK only) */ + ... +}; +.fi +.in +.P +この構造体の \fIl_whence\fP, \fIl_start\fP, \fIl_len\fP フィールドで、ロックを行いたいバイト範囲を指定する。 +ファイルの末尾より後ろのバイトをロックすることはできるが、 ファイルの先頭より前のバイトをロックすることはできない。 + +\fIl_start\fP はロックを行う領域の開始オフセットである。 その意味は \fIl_whence\fP により異なる: \fIl_whence\fP が +\fBSEEK_SET\fP の場合はファイルの先頭からのオフセット、 \fIl_whence\fP が \fBSEEK_CUR\fP +の場合は現在のファイルオフセットからのオフセット、 \fIl_whence\fP が \fBSEEK_END\fP +の場合はファイルの末尾からのオフセットと解釈される。 後ろの２つの場合には、 ファイルの先頭より前にならない範囲で、 \fIl_start\fP +に負の値を指定することができる。 + +\fIl_len\fP はロックしたいバイト数を示す。 \fIl_len\fP が正の場合、ロックされるバイト範囲は \fIl_start\fP 以上 +\fIl_start\fP+\fIl_len\fP\-\fI1\fP 以下となる。 \fIl_len\fP に 0 を指定した場合は特別な意味を持つ: \fIl_whence\fP +and \fIl_start\fP で指定される位置からファイルの末尾までの全てのバイトをロックする +(ファイルがどんなに大きくなったとしてもファイルの末尾までロックする)。 + +POSIX.1\-2001 では、負の値の \fIl_len\fP をサポートする実装を認めている (必須ではない)。 \fIl_len\fP +が負の場合、ロックされるバイト範囲は \fIl_start\fP+\fIl_len\fP 以上 \fIl_start\fP\-1 以下となる。 この動作はカーネル +2.4.21 以降および 2.5.49 以降の Linux で サポートされている。 + +\fIl_type\fP フィールドは、ファイルに対して読み出しロック (\fBF_RDLCK\fP) と書き込みロック (\fBF_WRLCK\fP) のどちらを +設定するかを指定する。 ファイルのある領域に対して、読み出しロック (共有ロック) を保持できる プロセス数に制限はないが、書き込みロック +(排他ロック) を保持できる のは一つのプロセスだけである。排他ロックを設定すると、(共有ロックか 排他ロックにかかわらず) +他のロックは何も設定できない。 一つのプロセスは、ファイルのある領域に対して一種類のロックしか保持できない。 +新規のロックがロックが設定されている領域に対して適用されると、既存のロック は新規のロックの種別に変換される +(新規のロックで指定されたバイト範囲が既存ロックの範囲と一致する場合以外では、 変換の過程で既存のロックの分割、縮小、結合が行われることがある)。 +.TP +\fBF_SETLK\fP (\fIstruct flock *\fP) +(\fIl_type\fP が \fBF_RDLCK\fP か \fBF_WRLCK\fP の場合は) ロックの獲得を、 (\fBF_UNLCK\fP の場合は) +ロックの解放を、 \fIflock\fP 構造体のフィールド \fIl_whence\fP, \fIl_start\fP, \fIl_len\fP +で指定された範囲のバイトに対して行う。 指定されたロックが他のプロセスが設定しているロックと衝突する場合は、 \-1 を返し、 \fIerrno\fP に +\fBEACCES\fP か \fBEAGAIN\fP を設定する。 +.TP +\fBF_SETLKW\fP (\fIstruct flock *\fP) +\fBF_SETLK\fP と同様だが、こちらではそのファイルに対して衝突するロックが 適用されていた場合に、そのロックが解放されるのを待つ点が異なる。 +待っている間にシグナルを受けた場合は、システムコールは中断され、 (シグナルハンドラが戻った直後に) 返り値 \-1 を返す (また \fIerrno\fP に +\fBEINTR\fP が設定される; \fBsignal\fP(7) 参照)。 +.TP +\fBF_GETLK\fP (\fIstruct flock *\fP) +このコールの呼び出し時には、 \fIlock\fP にはそのファイルに適用しようとするロックに関する情報が入っている。 ロックを適用できる場合には、 +\fBfcntl\fP() は実際にはロックを行わず、構造体 \fIlock\fP の \fIl_type\fP フィールドに \fBF_UNLCK\fP +を設定し、他のフィールドは変更せずに、復帰する。 違う種別のロックが (一つもしくは複数) 適用されていて ロックを適用できないような場合には、 +\fBfcntl\fP() は、原因となったロックの一つについての詳細情報を構造体 \fIlock\fP のフィールド \fIl_type\fP, +\fIl_whence\fP, \fIl_start\fP, \fIl_len\fP に格納し、また \fIl_pid\fP にロックを保持しているプロセスの PID +を設定して、復帰する。 +.P +読み出しロックを適用するには、 \fIfd\fP は読み出し用にオープンされていなければならない。 書き込みロックを適用するには、 \fIfd\fP +は書き込み用にオープンされていなければならない。 読み書き両方のロックを適用するには、読み書き両用で ファイルをオープンしなければならない。 +.P +.\" (Additional file descriptors referring to the same file +.\" may have been obtained by calls to +.\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl ().) +レコードのロックは、 \fBF_UNLCK\fP により明示的に削除されるだけでなく、 プロセスが終了したときや、ロックが適用されているファイルを参照している +ファイルディスクリプタのいずれかがクローズされた場合にも解放される。 このロックの解放は自動的に行われる。 この動作はまずい: あるプロセスが +\fI/etc/passwd\fP や \fI/etc/mtab\fP といったファイルにロックを適用しているときに、 +あるライブラリ関数が何かの理由で同じファイルを open, read, close すると、そのファイルへのロックが失われることになる。 +.P +レコードのロックは \fBfork\fP(2) で作成された子プロセスには継承されないが、 \fBexecve\fP(2) の前後では保存される。 +.P +\fBstdio\fP(3) ではバッファリングが行われるので、 stdio 関連の関数ではレコードのロックの使用は回避される; 代わりに +\fBread\fP(2) や \fBwrite\fP(2) を使用すること。 +.SS "強制ロック (mandatory locking)" +上述のロックにはアドバイザリ・ロック (advisory lock) と強制ロック (mandatory lock) +の二種類があるが、デフォルトではアドバイザリ・ロックとなる。 + +アドバイザリ・ロックに強制力はなく、協調して動作するプロセス間でのみ 有効である。 + +強制ロックは全てのプロセスに対して効果がある。 あるプロセスが互換性のない強制ロックが適用されたファイル領域に対して (\fBread\fP(2) や +\fBwrite\fP(2) により) 互換性のないアクセスを実行しようとした場合、 アクセスの結果は そのファイルのオープンファイル記述で +\fBO_NONBLOCK\fP フラグが有効になっているかにより決まる。 \fBO_NONBLOCK\fP +フラグが有効になっていないときは、ロックが削除されるか、 ロックがアクセスと互換性のあるモードに変換されるまで、 システムコールは停止 (block) +される。 \fBO_NONBLOCK\fP フラグが有効になっているときは、システムコールはエラー \fBEAGAIN\fP で失敗する。 + +強制ロックを使用するためには、ロック対象のファイルが含まれるファイルシステム +と、ロック対象のファイル自身の両方について、強制ロックが有効になっていなけれ ばならない。ファイルシステムについて強制ロックを有効にするには、 +\fBmount\fP(8) に "\-o mand" オプションを渡すか、 \fBmount\fP(2) に \fBMS_MANDLOCK\fP +フラグを指定する。ファイルについて強制ロックを有効にするには、 そのファイルのグループ実行許可 (group execute permission) +を無効とし、 かつ set\-group\-ID 許可ビットを有効にする (\fBchmod\fP(1) と \fBchmod\fP(2) を参照)。 + +Linux の強制ロックの実装は信頼性に欠けるものである。 下記の「バグ」の節を参照のこと。 +.SS シグナルの管理 +\fBF_GETOWN\fP, \fBF_SETOWN\fP, \fBF_GETOWN_EX\fP, \fBF_SETOWN_EX\fP, \fBF_GETSIG\fP, +\fBF_SETSIG\fP は、I/O が利用可能になったことを示すシグナルを管理するために使用される。 +.TP +\fBF_GETOWN\fP (\fIvoid\fP) +ファイルディスクリプタ \fIfd\fP のイベントに対するシグナル \fBSIGIO\fP および \fBSIGURG\fP を受けているプロセスのプロセスID +かプロセスグループを (関数の結果として) 返す。 プロセスID は正の値として返される。 プロセスグループID は負の値として返される +(下記のバグの章を参照)。 \fIarg\fP は無視される。 +.TP +\fBF_SETOWN\fP (\fIint\fP) +ファイルディスクリプタ \fIfd\fP のイベント発生を知らせるシグナル \fBSIGIO\fP や \fBSIGURG\fP を受けるプロセスの プロセス ID +またはプロセスグループID を \fIarg\fP で指定された ID に設定する。 プロセスID は正の値として指定し、 プロセスグループID +は負の値として指定する。 ほとんどの場合、呼び出し元プロセスは所有者として自分自身を指定する (つまり \fIarg\fP に \fBgetpid\fP(2) +を指定する)。 + +.\" From glibc.info: +\fBfcntl\fP() の \fBF_SETFL\fP コマンドを使用してファイルディスクリプタに \fBO_ASYNC\fP +状態フラグを設定した場合には、そのファイルディスクリプタへの 入出力が可能になる度に \fBSIGIO\fP シグナルが送られる。 \fBF_SETSIG\fP は +\fBSIGIO\fP 以外の別のシグナルの配送を受けられるように するのにも使うことができる。 許可 (permission) +のチェックで失敗した場合には、 シグナルは黙って捨てられる。 + +\fBF_SETOWN\fP により指定された所有者のプロセス (またはプロセスグループ) に シグナルを送る際には、 \fBkill\fP(2) +に書かれているのと同じ許可のチェックが行われる。 このとき、シグナルを送信するプロセスは \fBF_SETOWN\fP を使ったプロセスである +(但し、下記の「バグ」の章を参照のこと)。 + +.\" The following appears to be rubbish. It doesn't seem to +.\" be true according to the kernel source, and I can write +.\" a program that gets a terminal-generated SIGIO even though +.\" it is not the foreground process group of the terminal. +.\" -- MTK, 8 Apr 05 +.\" +.\" If the file descriptor +.\" .I fd +.\" refers to a terminal device, then SIGIO +.\" signals are sent to the foreground process group of the terminal. +ファイルディスクリプタがソケットを参照している場合は、 \fBF_SETOWN\fP を使用して、ソケットに帯域外 (out\-of\-band) +データが届いた時に \fBSIGURG\fP シグナルを配送する相手を選択することもできる (\fBSIGURG\fP が送られた場合には \fBselect\fP(2) +がソケットが「特別な状態」にあると報告することだろう)。 + +バージョン 2.6.11 以前の 2.6.x カーネルでは、以下に示す動作であった。 +.RS +.IP +.\" The relevant place in the (2.6) kernel source is the +.\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 +.\" send_sigurg()/send_sigurg_to_task() bypasses +.\" kill_fasync()/send_sigio()/send_sigio_to_task() +.\" to directly call send_group_sig_info() +.\" -- MTK, Apr 2005 (kernel 2.6.11) +スレッドグループをサポートしているスレッドライブラリ (例えば NPTL) を 使って動作しているマルチスレッド・プロセスで \fBF_SETSIG\fP に +0 以外の値を指定した場合、 \fBF_SETOWN\fP に正の値を渡すと、その意味が違ってくる: プロセス全体を示すプロセスID +ではなく、プロセス内の特定の スレッドを示すスレッドID と解釈される。 したがって、 \fBF_SETSIG\fP +を使う場合には、きちんと結果を受け取るには、 \fBF_SETOWN\fP に渡す値を \fBgetpid\fP(2) ではなく \fBgettid\fP(2) +の返り値にする必要があるだろう。 (現状の Linux スレッド実装では、メイン・スレッドのスレッドID は そのスレッドのプロセスID +と同じである。つまり、 シグナル・スレッドのプログラムではこの場合 \fBgettid\fP(2) と \fBgetpid\fP(2) +は全く同じように使うことができる。) ただし、注意すべき点として、この段落で述べたことは、 ソケットの帯域外データが届いたときに生成される +\fBSIGURG\fP シグナルにはあてはまらない。 このシグナルは常にプロセスかプロセスグループに送られ、 送信先は \fBF_SETOWN\fP +に渡された値にしたがって決められる。 +.RE +.IP +上記の動作は、Linux 2.6.12 で図らずも削除され、 元に戻されない予定である。 Linux 2.6.32 以降で、特定のスレッド宛にシグナル +\fBSIGIO\fP と \fBSIGURG\fP を送るには \fBF_SETOWN_EX\fP を使うこと。 +.TP +\fBF_GETOWN_EX\fP (struct f_owner_ex *) (Linux 2.6.32 以降) +直前の \fBF_SETOWN_EX\fP 操作で定義された現在のファイルディスクリプタの所有者設定 を返す。情報は \fIarg\fP +が指す構造体に格納されて返される。構造体は以下の通りである。 +.nf +.in +4n + +struct f_owner_ex { + int type; + pid_t pid; +}; + +.in +.fi +\fItype\fP フィールドは、 \fBF_OWNER_TID ,\fP \fBF_OWNER_PID ,\fP \fBF_OWNER_PGRP\fP +のいずれか一つの値となる。 \fIpid\fP フィールドは、スレッド ID、プロセス ID、プロセスグループ ID を 表す正の整数である。詳細は +\fBF_SETOWN_EX\fP を参照。 +.TP +\fBF_SETOWN_EX\fP (struct f_owner_ex *) (Linux 2.6.32 以降) +この操作は \fBF_SETOWN\fP と同様の処理を行う。 この操作を使うと、I/O が利用可能になったことを示すシグナルを、 +特定のスレッド、プロセス、プロセスグループに送ることができる ようになる。 呼び出し元は、 \fIarg\fP 経由でシグナルの配送先を指定する。 +\fIarg\fP は \fIf_owner_ex\fP 構造体へのポインタである。 \fItype\fP フィールドは以下のいずれかの値を取り、 この値により +\fIpid\fP がどのように解釈されるかが規定される。 +.RS +.TP +\fBF_OWNER_TID\fP +スレッド ID が \fIpid\fP で指定された値のスレッドにそのシグナルを送る (スレッド ID は \fBclone\fP(2) や +\fBgettid\fP(2) の呼び出しで返される値である)。 +.TP +\fBF_OWNER_PID\fP +ID が \fIpid\fP で指定された値のプロセスにそのシグナルを送る。 +.TP +\fBF_OWNER_PGRP\fP +ID が \fIpid\fP で指定された値のプロセスグループにそのシグナルを送る。 (\fBF_SETOWN\fP と異なり、プロセスグループ ID +には正の値を指定する点に注意すること。) +.RE +.TP +\fBF_GETSIG\fP (\fIvoid\fP) +入力や出力が可能になった場合に送るシグナルを (関数の結果として) 返す。 値ゼロは \fBSIGIO\fP を送ることを意味する。 (\fBSIGIO\fP +を含む) 他の値はいずれも、 \fBSIGIO\fP の代わりに送るシグナル番号を表す。 後者の場合、シグナルハンドラを \fBSA_SIGINFO\fP +フラグ付きで設定すれば、ハンドラで追加の情報を得ることができる。 \fIarg\fP は無視される。 +.TP +\fBF_SETSIG\fP (\fIint\fP) +.\" +.\" The following was true only up until 2.6.11: +.\" +.\" Additionally, passing a nonzero value to +.\" .B F_SETSIG +.\" changes the signal recipient from a whole process to a specific thread +.\" within a process. +.\" See the description of +.\" .B F_SETOWN +.\" for more details. +入力や出力が可能になった場合に送るシグナルを \fIarg\fP に指定された値に設定する。 値ゼロは \fBSIGIO\fP を送ることを意味する。 +(\fBSIGIO\fP を含む) 他の値はいずれも、 \fBSIGIO\fP の代わりに送るシグナル番号を表す。 後者の場合、シグナルハンドラを +\fBSA_SIGINFO\fP フラグ付きで設定すれば、 ハンドラで追加の情報を得ることができる。 + +\fBF_SETSIG\fP にゼロ以外の値を設定し、シグナルハンドラに \fBSA_SIGINFO\fP フラグを設定すると、 (\fBsigaction\fP(2) +を参照) I/O イベントに関する追加の情報が \fIsiginfo_t\fP 構造体でシグナルハンドラへ渡される。 \fIsi_code\fP +フィールドが示すシグナルの原因が \fBSI_SIGIO\fP である場合、 \fIsi_fd\fP +フィールドにはイベントに対応するファイルディスクリプタが入っている。 それ以外の場合は、どのファイルディスクリプタが利用可能かを示す情報は +ないので、どのファイルディスクリプタで I/O が可能かを判断するためには 通常の機構 (\fBselect\fP(2), \fBpoll\fP(2), +\fBO_NONBLOCK\fP を設定した \fBread\fP(2) など) を使用しなければならない。 + +リアルタイムシグナル (値が \fBSIGRTMIN\fP 以上) を選択している場合は、 同じシグナル番号を持つ複数の I/O +イベントがキューに入ることがある (キューに入れるかどうかは利用可能なメモリに依存している)。 上記と同様、 \fBSA_SIGINFO\fP +が設定されている場合、シグナルハンドラのための追加の情報が得られる。 + +.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 +以下の点に注意すること。 Linux では一つのプロセスに対してキューに入れられるリアルタイム シグナルの数に上限が設けられており +(\fBgetrlimit\fP(2) と \fBsignal\fP(7) を参照)、この上限に達するとカーネルは \fBSIGIO\fP シグナルを配送する。この +\fBSIGIO\fP シグナルは、指定されたスレッドではなくプロセス全体に送られる。 +.PP +これらの機構を使用することで、ほとんどの場合で \fBselect\fP(2) や \fBpoll\fP(2) を使用せずに完全な非同期 I/O +を実装することができる。 +.PP +\fBO_ASYNC\fP, \fBF_GETOWN\fP, \fBF_SETOWN\fP の使用は BSD と Linux に特有である。 +\fBF_GETOWN_EX\fP, \fBF_SETOWN_EX\fP, \fBF_GETSIG\fP, \fBF_SETSIG\fP は Linux 固有である。POSIX +には、同様のことを行うために、非同期 I/O と \fIaio_sigevent\fP 構造体がある。Linux では、GNU C ライブラリ (Glibc) +の一部として これらも利用可能である。 +.SS "リース (leases)" +(Linix 2.4 以降で利用可能) \fBF_SETLEASE\fP は、 \fIfd\fP +が参照するオープンファイル記述に対して新しいリースを設定するのに使用される。 \fBF_GETLEASE\fP は、 \fIfd\fP +が参照するオープンファイル記述に対して設定されている 現在のリースを取得するのに使用される。 ファイルのリースにより、 あるプロセス ("lease +breaker") がそのファイルディスクリプタが参照 しているファイルに対して \fBopen\fP(2) や \fBtruncate\fP(2) +を行おうとした際に、リースを保持しているプロセス ("lease holder") へ (シグナルの配送による) 通知が行われるという機構が提供される。 +.TP +\fBF_SETLEASE\fP (\fIint\fP) +\fIarg\fP の内容に基いてファイルのリースの設定、削除を行う。整数 \fIarg\fP には以下の値が指定できる: +.RS +.TP +\fBF_RDLCK\fP +.\" The following became true in kernel 2.6.10: +.\" See the man-pages-2.09 Changelog for further info. +読み出しリースを取得する。これにより、 そのファイルが書き込み用にオープンされたり、ファイルが切り詰められた場合に、 +呼び出し元のプロセスに通知が行われるようになる。 読み出しリースを設定できるのは、読み出し専用でオープンされている +ファイルディスクリプタに対してのみである。 +.TP +\fBF_WRLCK\fP +書き込みリースを取得する。これにより、 (読み出し用か書き込み用にかかわらず) そのファイルがオープンされたり、 +ファイルが切り詰められた場合に、呼び出し元のプロセスに通知が行われるようになる。 +書き込みリースは、そのファイルに対するオープンされたファイルディスクリプタが 他にない場合にのみ設定できる。 +.TP +\fBF_UNLCK\fP +そのファイルからリースを削除する。 +.RE +.P +リースはオープンファイル記述に対して関連付けられる (\fBopen\fP(2) 参照)。 つまり、 (\fBfork\fP(2) や \fBdup\fP(2) +などにより作成された) ファイルディスクリプタの複製は同じリースを参照し、 複製も含めたどのファイルディスクリプタを使ってもこのリースを変更したり +解放したりできる。 また、これらのファイルディスクリプタのいずれかに対して \fBF_UNLCK\fP +操作が明示的に実行された場合や、すべてのファイルディスクリプタが 閉じられた場合にも、リースは解放される。 +.P +リースの取得は通常のファイル (regular file) に対してのみ可能である。 非特権プロセスがリースを取得できるのは、UID (所有者) +がプロセスの ファイルシステム UID と一致するファイルに対してだけである。 \fBCAP_LEASE\fP +ケーパビリティを持つプロセスは任意のファイルに対してリースを取得できる。 +.TP +\fBF_GETLEASE\fP (\fIvoid\fP) +ファイルディスクリプタ \fIfd\fP に対して設定されているリースの種別を取得する。 \fBF_RDLCK\fP, \fBF_WRLCK\fP, \fBF_UNLCK\fP +のいずれかが返される。 \fBF_RDLCK\fP, \fBF_WRLCK\fP はそれぞれ、読み出しリース、書き込みリースが設定されていることを示し、 +\fBF_UNLCK\fP はリースが何も設定されていないことを示す。 \fIarg\fP は無視される。 +.PP +あるプロセス ("lease breaker") が \fBF_SETLEASE\fP で設定されたリースと矛 +盾するような \fBopen\fP(2) や \fBtruncate\fP(2) を実行した場合、 そのシステム +コールはカーネルによって停止され、 カーネルは lease holder にシグナル +(デフォルトでは \fBSIGIO\fP) を送って通知を行う。 lease holder はこのシグ +ナルを受信したときにはきちんと対応すべきである。 具体的には、別のプロセ +スがそのファイルにアクセスするための準備として 必要な後片付け (例えば、 +キャッシュされたバッファのフラッシュ) を すべて行ってから、そのファイル +のリースの削除または格下げを行う。リースを削除をするには、 \fIarg\fP に +\fBF_UNLCK\fP を指定して \fBF_SETLEASE\fP を実行する。lease holder がファイル +に書き込みリースを保持していて、 lease breaker が読み出し用にそのファイ +ルをオープンしている場合、 lease holder が保持しているリースを読み出し +リースに格下げすれば 十分である。これをするには、 \fIarg\fP に \fBF_RDLCK\fP +を指定して \fBF_SETLEASE\fP を実行する。 + +lease holder が \fI/proc/sys/fs/lease\-break\-time\fP +で指定された秒数以内にリースの格下げか削除を行えなかった場合、 カーネルは強制的にその lease holder のリースを削除もしくは格下げを行う。 + +いったん lease break が開始されると、 lease holder が自発的にそのリース +の格下げか削除を行うか、lease break timer の満了後にカーネルが強制的に +リースの格下げか削除を行うまで、 \fBF_GETLEASE\fP は対象となるリースの型を +返す (リースの型は \fBF_RDLCK\fP か \fBF_UNLCK\fP のどちらであり、lease +breaker と互換性のある型となる)。 + +一度リースの削除か格下げが自発的もしくは強制的に行われると、 lease breaker がまだシステムコールを再開していない場合には、 カーネルが +lease breaker のシステムコールの続行を許可する。 + +lease breaker が実行した \fBopen\fP(2) や \fBtruncate\fP(2) が停止中にシグナルハンドラにより中断された場合、 +そのシステムコールは \fBEINTR\fP エラーで失敗するが、上で述べた他の処理は そのまま行われる。 \fBopen\fP(2) や +\fBtruncate\fP(2) が停止中に lease breaker がシグナルにより kill された場合、 上で述べた他の処理はそのまま行われる。 +lease breaker が \fBopen\fP(2) を呼ぶ際に \fBO_NONBLOCK\fP フラグを指定した場合、そのシステムコールは +\fBEWOULDBLOCK\fP エラーで直ちに失敗するが、上で述べた他の処理はそのまま行われる。 + +lease holder への通知に使われるデフォルトのシグナルは \fBSIGIO\fP だが、 \fBfcntl\fP() の \fBF_SETSIG\fP +コマンドで変更することができる。 \fBF_SETSIG\fP コマンドが実行され (\fBSIGIO\fP を指定された場合も含む)、 \fBSA_SIGINFO\fP +フラグ付きでシグナルハンドラが設定されている場合には、 ハンドラの第二引き数として \fIsiginfo_t\fP 構造体が渡され、この引き数の +\fIsi_fd\fP フィールドには別のプロセスがアクセスしたリース設定済みファイルの ディスクリプタが入っている +(この機能は複数のファイルに対してリースを設定する場合に有用である)。 +.SS "ファイルやディレクトリの変更の通知 (dnotify)" +.TP +\fBF_NOTIFY\fP (\fIint\fP) +(Linux 2.4 以降) \fIfd\fP で参照されるディレクトリか、その中にあるファイルに変更があった場合に 通知を行う。どのイベントを通知するかは +\fIarg\fP で指定する。 \fIarg\fP はビットマスクで、以下のビットの 0個以上の論理和をとったものを指定する。 +.RS +.sp +.PD 0 +.TP 12 +\fBDN_ACCESS\fP +ファイルへのアクセスがあった (read, pread, readv) +.TP +\fBDN_MODIFY\fP +ファイルの内容が変更された (write, pwrite, writev, truncate, ftruncate). +.TP +\fBDN_CREATE\fP +ファイルが作成された (open, creat, mknod, mkdir, link, symlink, rename). +.TP +\fBDN_DELETE\fP +ファイルが削除 (unlink) された (unlink, 別のディレクトリへの rename, rmdir) +.TP +\fBDN_RENAME\fP +ディレクトリ内でのファイル名の変更があった (rename) +.TP +\fBDN_ATTRIB\fP +ファイル属性が変更された (chown, chmod, utime[s]) +.PD +.RE +.IP +(上記の定義を利用するには、\fIどの\fP ヘッダファイルをインクルードするより前に、 +\fB_GNU_SOURCE\fP 機能検査マクロを定義しなければならない。) + +ディレクトリの変更通知は通常「一回限り (one\-shot)」であり、 アプリケーション側でその後さらに通知を受信したい場合は +再登録しなければならない。 \fIarg\fP に \fBDN_MULTISHOT\fP が含まれていた場合には、 +変更通知は明示的に解除されるまで有効状態が継続する。 + +.\" The following does seem a poor API-design choice... +\fBF_NOTIFY\fP 要求は積算されていく。つまり、 \fIarg\fP で指定されたイベントがすでにモニタされている イベント集合に加算される形になる。 +すべてのイベントの通知を無効にするには、 \fIarg\fP に 0 を指定して \fBF_NOTIFY\fP を呼び出す必要がある。 + +通知はシグナルの配送で行われる。 デフォルトのシグナルは \fBSIGIO\fP だが、 \fBfcntl\fP() の \fBF_SETSIG\fP +コマンドで変更することができる。 後者の場合には、 (\fBSA_SIGINFO\fP フラグ付きでシグナルハンドラが設定されている場合には) +ハンドラの第二引き数として \fIsiginfo_t\fP 構造体が渡され、この構造体の \fIsi_fd\fP +フィールドには通知の行われたファイルディスクリプタが入っている (この機能は複数のディレクトリに対して通知を設定する場合に有用である)。 + +特に \fBDN_MULTISHOT\fP を使う場合は、通知にはリアルタイムシグナルを使うべきである。 +それは、リアルタイムシグナルを使うことで、複数の通知をキューに入れる ことができるからである。 + +\fB注意:\fP 新しくアプリケーションを書く際には、(カーネル 2.6.13 以降で利用可能となった) \fIinotify\fP +インタフェースを使用すべきである。 \fIinotify\fP はファイルシステムイベントの通知を取得するための ずっと優れたインタフェースである。 +\fBinotify\fP(7) を参照。 +.SS パイプの容量の変更 +.TP +\fBF_SETPIPE_SZ\fP (\fIint\fP; Linux 2.6.35 以降) +\fIfd\fP が参照するパイプの容量を少なくとも \fIarg\fP バイトに変更する。 +非特権プロセスは、パイプの容量として、 +システムのページサイズと \fI/proc/sys/fs/pipe\-max\-size\fP で定義される +上限値 (\fBproc\fP(5) 参照) の間の任意の値を設定できる。 +パイプの容量をページサイズよりも小さな値に設定しようとした場合は、 +暗黙のうちにページサイズに切り上げられる。 +非特権プロセスがパイプの容量を \fI/proc/sys/fs/pipe\-max\-size\fP で定義 +された上限より大きな値に設定しようとした場合は、エラー \fBEPERM\fP が +発生する。特権プロセス (\fBCAP_SYS_RESOURCE\fP ケーパビリティを持つ +プロセス) はこの上限を上書きできる。 +パイプにバッファを割り当てる場合、実装側の都合に応じて、 +カーネルは \fIarg\fP よりも大きな容量を割り当ててもよい。 +\fBF_GETPIPE_SZ\fP 操作では実際に使用されている大きさが返される。 +パイプの容量を現在データを格納するのに使用されているバッファの +サイズよりも小さくしようとした場合は、エラー \fBEBUSY\fP が発生する。 +.TP +\fBF_GETPIPE_SZ\fP (\fIvoid\fP; Linux 2.6.35 以降) +\fIfd\fP が参照するパイプの容量を (関数の結果として) 返す。 +.SH 返り値 +成功した場合の返り値は操作の種類により違う: +.TP 0.9i +\fBF_DUPFD\fP +新しいディスクリプタを返す。 +.TP +\fBF_GETFD\fP +ファイルディスクリプタ・フラグの値 +.TP +\fBF_GETFL\fP +ファイル状態フラグの値 +.TP +\fBF_GETLEASE\fP +ファイルディスクリプタに対して保持されているリースの種別を返す。 +.TP +\fBF_GETOWN\fP +ディスクリプタの所有者を返す。 +.TP +\fBF_GETSIG\fP +読み込みや書き出しが可能になった時に送られるシグナルの値、もしくは 伝統的な \fBSIGIO\fP 動作の場合にはゼロを返す。 +.TP +\fBF_GETPIPE_SZ\fP +パイプの容量。 +.TP +他の全てのコマンド +0 を返す。 +.PP +エラーの時は \-1 が返され、 \fIerrno\fP に適切な値が設定される。 +.SH エラー +.TP +\fBEACCES\fP か \fBEAGAIN\fP +他のプロセスが保持しているロックによって操作が禁止されている。 +.TP +\fBEAGAIN\fP +そのファイルは他のプロセスによってメモリ・マップされているため、 操作が禁止されている。 +.TP +\fBEBADF\fP +\fIfd\fP がオープンされたファイルディスクリプタでない。 あるいはコマンドが \fBF_SETLK\fP または \fBF_SETLKW\fP +だったが、対象のファイルディスクリプタのオープンモードが 必要となるロックの型にマッチしていない。 +.TP +\fBEDEADLK\fP +指定された \fBF_SETLKW\fP コマンドを実行した場合にはデッドロックになることが検出された。 +.TP +\fBEFAULT\fP +\fIlock\fP が利用可能なアドレス空間の外部にある。 +.TP +\fBEINTR\fP +\fBF_SETLKW\fP コマンドがシグナルにより割り込まれた (\fBsignal\fP(7) 参照)。 \fBF_GETLK\fP と \fBF_SETLK\fP +の場合、ロックを確認したり取得したりする前にシグナルによって割り込まれた。 これはたいていリモートのファイルをロックする場合 (例えば NFS +上でロックする場合) に起こる。 しかしローカルでも起こる場合がある。 +.TP +\fBEINVAL\fP +\fBF_DUPFD\fPで、 \fIarg\fP が負か、もしくは許される最大値よりも大きい。 \fBF_SETSIG\fP の場合、 \fIarg\fP +が利用可能なシグナル番号ではない。 +.TP +\fBEMFILE\fP +\fBF_DUPFD\fPで、 プロセスがすでに最大数までファイルディスクリプタをオープンしている。 +.TP +\fBENOLCK\fP +オープンされているロックの数が多過ぎて、ロック・テーブルがいっぱいである。 または remote locking protocol (例えば NFS +上のロック) が失敗した。 +.TP +\fBEPERM\fP +追加専用属性が設定されたファイルの \fBO_APPEND\fP フラグをクリアしようと試みた。 +.SH 準拠 +SVr4, 4.3BSD, POSIX.1\-2001. POSIX.1\-2001 で規定されている操作は、 +\fBF_DUPFD\fP, \fBF_GETFD\fP, \fBF_SETFD\fP, \fBF_GETFL\fP, \fBF_SETFL\fP, +\fBF_GETLK\fP, \fBF_SETLK\fP, \fBF_SETLKW\fP だけである。 + +\fBF_GETOWN\fP と \fBF_SETOWN\fP は POSIX.1\-2001 で規定されている。 +(これら定義するには、 \fBBSD_SOURCE\fP を定義するか、 +\fB_XOPEN_SOURCE\fP を 500 以上の値で定義するか、 +\fB_POSIX_C_SOURCE\fP を 200809L 以上の値で定義すること。) + +\fBF_DUPFD_CLOEXEC\fP は POSIX.1\-2008 で規定されている。 +(これら定義するには、 +\fB_POSIX_C_SOURCE\fP を 200809L 以上の値で定義するか、 +\fB_XOPEN_SOURCE\fP を 700 以上の値で定義すること。) + +.\" .PP +.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. +\fBF_GETOWN_EX\fP, \fBF_SETOWN_EX\fP, \fBF_SETPIPE_SZ\fP, \fBF_GETPIPE_SZ\fP, +\fBF_GETSIG\fP, +\fBF_SETSIG\fP, \fBF_NOTIFY\fP, \fBF_GETLEASE\fP, \fBF_SETLEASE\fP は Linux 固有である +(これらの定義を有効にするには \fB_GNU_SOURCE\fP マクロを定義すること)。 +.SH 注意 +元々の Linux の \fBfcntl\fP() システムコールは (\fIflock\fP 構造体で) 大きな +ファイルオフセットを扱えるように設計されていなかった。 +その結果、Linux 2.4 で \fBfcntl64\fP() システムコールが追加された。 +この新しいシステムコールは、ファイルのロックに \fIflock64\fP という別の +構造体を利用し、これに対応するコマンドとして \fBF_GETLK64\fP, +\fBF_SETLK64\fP, \fBF_SETLKW64\fP を使用する。 +しかし、 glibc を使うアプリケーションではこれらの詳細を無視することが +できる。 glibc の \fBfcntl\fP のラッパー関数は新しいシステムコールが +利用できる場合はそれを利用するようになっているからである。 + +エラーの際の返り値が \fBdup2\fP(2) と \fBF_DUPFD\fP では異なっている。 + +カーネル 2.0 以降では、 \fBflock\fP(2) と \fBfcntl\fP() が設定するロック種別の間に相互作用はない。 + +.\" e.g., Solaris 8 documents this field in fcntl(2), and Irix 6.5 +.\" documents it in fcntl(5). mtk, May 2007 +システムによっては、 \fIstruct flock\fP に上記以外のフィールドがあるものもある (例えば \fIl_sysid\fP)。 +はっきりと言えることは、ロックを保持しているプロセスが別のマシンに存在 する場合には、 \fIl_pid\fP +だけはあまり役にたたないだろうということである。 +.SH バグ +.\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h +.\" mtk, Dec 04: some limited testing on alpha and ia64 seems to +.\" indicate that ANY negative PGID value will cause F_GETOWN +.\" to misinterpret the return as an error. Some other architectures +.\" seem to have the same range check as i386. +いくつかのアーキテクチャ (特に i386) における Linux システムコールの慣習 +のため以下の制限が存在する。 +\fBF_GETOWN\fP が返す (負の) プロセスグループID が \-1 から \-4095 の範囲に入った場合、 +glibc はこの返り値をシステムコールでエラーが起こったと間違って解釈してしまう。 +つまり、 \fBfcntl\fP() の返り値は \-1 となり、 \fIerrno\fP には (正の) プロセスグループID +が設定されることになる。Linux 固有の \fBF_GETOWN_EX\fP ではこの問題を回避できる。 +glibc バージョン 2.11 以降では、glibc では \fBF_GETOWN_EX\fP を使って +\fBF_GETOWN\fP を実装することで、カーネルの \fBF_GETOWN\fP の問題を見えないようにしている。 + +Linux 2.4 以前では、非特権プロセスが \fBF_SETOWN\fP を使って、ソケットのファイルディスクリプタの所有者に 呼び出し元以外のプロセス +(やプロセスグループ) を指定すると 発生するバグがある。この場合、 呼び出し元が所有者として指定したプロセス (やプロセスグループ) に +シグナルを送る許可を持っていたとしても、 \fBfcntl\fP() が \-1 を返し \fIerrno\fP に \fBEPERM\fP を設定することがある。 +このエラーが返ったにもかかわらず、ファイルディスクリプタの所有者 は設定され、シグナルはその所有者に送られる。 + +.\" http://marc.info/?l=linux-kernel&m=119013491707153&w=2 +これまでの Linux の全てのバージョンにおける強制ロックの実装は、 競合条件下で強制ロックが不完全になるような場合がある。 +ロックと重なって実行された \fBwrite\fP(2) の呼び出しは強制ロックが獲得された後にもデータを変更することができる。 ロックと重なって実行された +\fBread\fP(2) の呼び出しは強制ロックが獲得された後になって行われたデータの変更を 検出することができる。 同様の競合条件が強制ロックと +\fBmmap\fP(2) の間にも存在する。それゆえ、強制ロックに頼るのはお薦めできない。 +.SH 関連項目 +\fBdup2\fP(2), \fBflock\fP(2), \fBopen\fP(2), \fBsocket\fP(2), \fBlockf\fP(3), +\fBcapabilities\fP(7), \fBfeature_test_macros\fP(7) + +Linux カーネルソースの \fIDocumentation/filesystems/\fP ディレクトリ内の \fIlocks.txt\fP, +\fImandatory\-locking.txt\fP, \fIdnotify.txt\fP (以前のカーネルでは、これらのファイルは +\fIDocumentation/\fP ディレクトリ直下にあり、 \fImandatory\-locking.txt\fP は \fImandatory.txt\fP +という名前であった) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/flock.2 b/manual/LDP_man-pages/draft/man2/flock.2 new file mode 100644 index 00000000..5a710c1d --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/flock.2 @@ -0,0 +1,137 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" and Copyright 2002 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Fri Jan 31 16:26:07 1997 by Eric S. Raymond +.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier +.\" Modified 24 Apr 2002 by Michael Kerrisk +.\" Substantial rewrites and additions +.\" 2005-05-10 mtk, noted that lock conversions are not atomic. +.\" +.\" FIXME: Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE +.\" which only have effect for SAMBA. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH FLOCK 2 2013\-02\-11 Linux "Linux Programmer's Manual" +.SH 名前 +flock \- オープンされたファイルに対するアドバイザリ・ロックの適用、解除を行う +.SH 書式 +\fB#include \fP +.sp +\fBint flock(int \fP\fIfd\fP\fB, int \fP\fIoperation\fP\fB);\fP +.SH 説明 +オープンされたファイルにアドバイザリ・ロック (advisory lock) の適用 や解除を行う。 ファイルは \fIfd\fP で指定する。引き数 +\fIoperation\fP には以下のいずれか一つを指定する: +.RS 4 +.TP 9 +\fBLOCK_SH\fP +共有ロックを適用する。 指定したファイルに対して、 一つ以上のプロセスが同時に共有ロックを保持することができる。 +.TP +\fBLOCK_EX\fP +排他ロックを適用する。 指定したファイルに対して、 ただ一つのプロセスだけが同時に排他ロックを保持することができる。 +.TP +\fBLOCK_UN\fP +このプロセスが保持している既存のロックを解除する。 +.RE +.PP +\fBflock\fP() を呼び出したときに、指定したロック種別と異なるロックが別プロセスによって 保持されていると、 \fBflock\fP() は停止 +(block) されることがある。 非停止 (nonblocking) タイプの要求を行うためには、 上記の操作 (operation) に +\fBLOCK_NB\fP を論理和の形で指定する。 + +一つのファイルに共有ロックと排他ロックを同時に設定することはできない。 + +\fBflock\fP() によって作られるロックは、 オープンされたファイルのテーブル・エントリと関連付けられる。 +したがって、ファイル・ディスクリプタの複製 (\fBfork\fP(2) や \fBdup\fP(2) などにより作成される) は同じロックを参照し、 +これらのファイル・ディスクリプタのどれを使っても このロックを変更したり解放したりできる。 また、ロックの解放は、 +上記の複数のファイル・ディスクリプタのいずれかに対して 明示的に \fBLOCK_UN\fP 操作を指示した場合か、これらのファイル・ディスクリプタがすべて +閉じられた場合に行われる。 + +あるプロセスが \fBopen\fP(2) (もしくは同様の方法) を使って同じファイルに対して 複数のディスクリプタを取得した場合、 \fBflock\fP() +はこれら複数のディスクリプタを各々独立のものとして扱う。 これらのファイル・ディスクリプタの一つを使ってファイルをロックしようと +した際、そのロック要求は、呼び出し元のプロセスがそのファイルの別の ディスクリプタ経由ですでに設定しているロックによって拒否される場合がある。 + +一つのプロセスは、一つのファイルに対して (共有ロックと排他ロックのうち) いずれか一種類のロックしか設定できない。 既にロックされたファイルに対して +\fBflock\fP() を呼び出すと、既存のロックを新しいロックモードに変更することになる。 + +\fBflock\fP() により作成されたロックは \fBexecve\fP(2) の前後で保存される。 + +共有ロックも排他ロックも、ファイルがどのモードでオープンされたかに 関係なく適用することができる。 +.SH 返り値 +成功した場合は 0 が返される。エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +.TP +\fBEBADF\fP +\fIfd\fP がオープンされたファイル・ディスクリプタではない。 +.TP +\fBEINTR\fP +ロックの獲得を待っている間に、ハンドラにより捕捉されたシグナルを 受信し、 \fBflock\fP() が中断された。 \fBsignal\fP(7) 参照。 +.TP +\fBEINVAL\fP +\fIoepration\fP が無効である。 +.TP +\fBENOLCK\fP +ロック・レコードを割り当てるためのメモリが不足している。 +.TP +\fBEWOULDBLOCK\fP +指定したファイルがロックされており、 \fBLOCK_NB\fP フラグが指定されている。 +.SH 準拠 +4.4BSD (\fBflock\fP() コールは 4.2BSD で最初に登場した)。 \fBfcntl\fP(2) で実装されているものなどを含めると、 +\fBflock\fP() の機能はほとんどの UNIX システムで実装されている。 +.SH 注意 +\fBflock\fP() は NFS 上のファイルのロックをしない。代わりに \fBfcntl\fP(2) +を使用すること。これにより、十分に新しいバージョンの Linux と、ロック機能を サポートした NFS サーバを使用することにより、NFS +上でロックができる。 +.PP +kernel 2.0 以降では、 \fBflock\fP() は、GNU C ライブラリでの \fBfcntl\fP(2) +を呼び出してのエミュレーションではなく、 それ自体がシステムコールとして実装されている。 これにより正真正銘の BSD での動作が達成される: +\fBflock\fP() と \fBfcntl\fP(2) で適用されるロックの種別には相互作用がなくなり、 \fBflock\fP() +がデッドロックを検出しなくなる。 +.PP +\fBflock\fP() アドバイザリ・ロックだけを適用する。したがって、ファイルに適切なアクセス権を 付与していれば、プロセスは \fBflock\fP() +の使用に無視して、ファイルへの入出力を行うことができる。 +.PP +\fBflock\fP() と \fBfcntl\fP(2) は fork されたプロセスと \fBdup\fP(2) で違った動作をする。 \fBflock\fP() +を \fBfcntl\fP(2) を使って実装しているシステムでは、 \fBflock\fP() +の動作はこのマニュアル・ページに記載されているものとは違うだろう。 +.PP +.\" Kernel 2.5.21 changed things a little: during lock conversion +.\" it is now the highest priority process that will get the lock -- mtk +ロックの変換 (共有ロックから排他ロックへ、もしくはその反対) がアトミックに 行われることは保証されていない: +既存のロックがまず削除され、それから新しい ロックが設定される。この 2つのステップの間に、他のプロセスからの処理待ちの +ロック要求が認められるかもしれず、結果として変換は停止 (block) したり、 (\fBLOCK_NB\fP が指定された場合には) 失敗したりする。 +(これは元々の BSD の動作であり、多くの他の実装でも起こる。) +.SH 関連項目 +\fBflock\fP(1), \fBclose\fP(2), \fBdup\fP(2), \fBexecve\fP(2), \fBfcntl\fP(2), \fBfork\fP(2), +\fBopen\fP(2), \fBlockf\fP(3) + +Linux カーネルソース内の \fIDocumentation/filesystem/locks.txt\fP (以前のカーネルでは +\fIDocumentation/locks.txt\fP) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/getdents.2 b/manual/LDP_man-pages/draft/man2/getdents.2 new file mode 100644 index 00000000..c2602238 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/getdents.2 @@ -0,0 +1,240 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" Derived from 'readdir.2'. +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH GETDENTS 2 2012\-08\-03 Linux "Linux Programmer's Manual" +.SH 名前 +getdents \- ディレクトリ・エントリを取得する +.SH 書式 +.nf +\fBint getdents(unsigned int \fP\fIfd\fP\fB, struct linux_dirent *\fP\fIdirp\fP\fB,\fP +\fB unsigned int \fP\fIcount\fP\fB);\fP +.fi + +\fI注\fP: このシステムコールに対する glibc のラッパー関数は用意されていない。「注意」の節を参照のこと。 +.SH 説明 +これはあなたの関心を引くような関数ではない。 POSIX 準拠の C ライブラリインターフェースについては \fBreaddir\fP(3) を見ること。 +このページは、カーネルシステムコールの生のインターフェースについて 記載したものである。 +.PP +\fBgetdents\fP() システムコールは、オープン済みのファイルディスクリプタ \fIfd\fP で参照されるディレクトリから +\fIlinux_dirent\fP 構造体をいくつか読み出し、 \fIdirp\fP が指しているバッファに格納する。 \fIcount\fP +引き数はそのバッファのサイズを示す。 +.PP +\fIlinux_dirent\fP 構造体は以下のように宣言されている: +.PP +.in +4n +.nf +struct linux_dirent { + unsigned long d_ino; /* Inode number */ + unsigned long d_off; /* Offset to next \fIlinux_dirent\fP */ + unsigned short d_reclen; /* Length of this \fIlinux_dirent\fP */ + char d_name[]; /* Filename (null\-terminated) */ + /* length is actually (d_reclen \- 2 \- + offsetof(struct linux_dirent, d_name) */ + /* + char pad; // Zero padding byte + char d_type; // File type (only since Linux 2.6.4; + // offset is (d_reclen \- 1)) + */ + +} +.fi +.in +.PP +\fId_ino\fP は inode 番号である。 \fId_off\fP はディレクトリの先頭から次の \fIlinux_dirent\fP の先頭までの距離である。 +\fId_reclen\fP はこの \fIlinux_dirent\fP 全体のサイズである。 \fId_name\fP +はヌル(null)文字で終わるファイル名である。 + +\fId_type\fP は、構造体の最後のバイトであり、ファイルタイプを示す。 \fId_type\fP は以下の値の一つを取る +(\fI\fP で定義されている)。 +.TP 12 +\fBDT_BLK\fP +ブロックデバイスである。 +.TP +\fBDT_CHR\fP +キャラクタデバイスである。 +.TP +\fBDT_DIR\fP +ディレクトリである。 +.TP +\fBDT_FIFO\fP +名前付きパイプ (FIFO) である。 +.TP +\fBDT_LNK\fP +シンボリックリンクである。 +.TP +\fBDT_REG\fP +通常のファイルである。 +.TP +\fBDT_SOCK\fP +UNIX ドメインソケットである。 +.TP +\fBDT_UNKNOWN\fP +ファイルタイプが不明である。 +.PP +\fId_type\fP フィールドは Linux 2.6.4 から実装されている。 これは \fIlinux_dirent\fP +構造体のうち、以前はゼロで埋められていた空間に配置されている。 従って、2.6.3 以前のカーネルでは、このフィールドにアクセスしようとすると 常に値 +0 (\fBDT_UNKNOWN\fP) が返される。 +.PP +.\" kernel 2.6.27 +.\" The same sentence is in readdir.2 +現在のところ、 \fId_type\fP でファイルタイプを返す機能が完全にサポートされているのは、 いくつかのファイルシステムにおいてのみである +(Btrfs, ext2, ext3, ext4 はサポートしている)。 どのアプリケーションも、 \fBDT_UNKNOWN\fP +が返された際に適切に処理できなければならない。 +.SH 返り値 +成功した場合は、読み込んだバイト数が返される。 ディレクトリの終わりならば 0 が返される。 エラーの場合は \-1 を返され、 \fIerrno\fP +に適切な値が設定される。 +.SH エラー +.TP +\fBEBADF\fP +ファイルディスクリプタ \fIfd\fP が不正である。 +.TP +\fBEFAULT\fP +引き数が呼び出したプロセスのアドレス空間外を指している。 +.TP +\fBEINVAL\fP +結果用のバッファーが小さすぎる。 +.TP +\fBENOENT\fP +そのようなディレクトリは存在しない。 +.TP +\fBENOTDIR\fP +ファイルディスクリプタがディレクトリを参照していない。 +.SH 準拠 +.\" SVr4 documents additional ENOLINK, EIO error conditions. +SVr4. +.SH 注意 +glibc はこのシステムコールに対するラッパー関数を提供していないので、 \fBsyscall\fP(2) を使って呼び出すこと。 +\fIlinux_dirent\fP 構造体は自分で定義する必要がある。しかし、たいていはこのシステムコールではなく \fBreaddir\fP(3) +を使うべき場面のことが多い。 + +このシステムコールは \fBreaddir\fP(2) を置き換えるものである。 + +元々の Linux の \fBgetdents\fP() システムコールは、大きなファイルシステムと +大きなファイルオフセットを扱うことができなかった。 +その結果、Linux 2.4 で \fBgetdents64\fP() が追加された。 +\fBgetdents64\fP() では、\fIlinux_dirent\fP 構造体のフィールド \fId_ino\fP と +\fId_off\fP でビット幅の大きなデータ型が使われている。 +.SH 例 +.\" FIXME: This program uses the older getdents(0 system call +.\" and the structure with smaller field widths. +下記のプログラムは \fBgetdents\fP() の使用例を示したものである。 以下は、このプログラムを ext2 ディレクトリで実行した際に得られる +出力の例である。 + +.in +4n +.nf +$\fB ./a.out /testfs/\fP +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=120 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +i\-node# file type d_reclen d_off d_name + 2 directory 16 12 . + 2 directory 16 24 .. + 11 directory 24 44 lost+found + 12 regular 16 56 a + 228929 directory 16 68 sub + 16353 directory 16 80 sub2 + 130817 directory 16 4096 sub3 +.fi +.in +.SS プログラムのソース +\& +.nf +#define _GNU_SOURCE +#include /* Defines DT_* constants */ +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +struct linux_dirent { + long d_ino; + off_t d_off; + unsigned short d_reclen; + char d_name[]; +}; + +#define BUF_SIZE 1024 + +int +main(int argc, char *argv[]) +{ + int fd, nread; + char buf[BUF_SIZE]; + struct linux_dirent *d; + int bpos; + char d_type; + + fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY); + if (fd == \-1) + handle_error("open"); + + for ( ; ; ) { + nread = syscall(SYS_getdents, fd, buf, BUF_SIZE); + if (nread == \-1) + handle_error("getdents"); + + if (nread == 0) + break; + + printf("\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=%d \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\en", nread); + printf("i\-node# file type d_reclen d_off d_name\en"); + for (bpos = 0; bpos < nread;) { + d = (struct linux_dirent *) (buf + bpos); + printf("%8ld ", d\->d_ino); + d_type = *(buf + bpos + d\->d_reclen \- 1); + printf("%\-10s ", (d_type == DT_REG) ? "regular" : + (d_type == DT_DIR) ? "directory" : + (d_type == DT_FIFO) ? "FIFO" : + (d_type == DT_SOCK) ? "socket" : + (d_type == DT_LNK) ? "symlink" : + (d_type == DT_BLK) ? "block dev" : + (d_type == DT_CHR) ? "char dev" : "???"); + printf("%4d %10lld %s\en", d\->d_reclen, + (long long) d\->d_off, d\->d_name); + bpos += d\->d_reclen; + } + } + + exit(EXIT_SUCCESS); +} +.fi +.SH 関連項目 +\fBreaddir\fP(2), \fBreaddir\fP(3) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/getxattr.2 b/manual/LDP_man-pages/draft/man2/getxattr.2 new file mode 100644 index 00000000..15872313 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/getxattr.2 @@ -0,0 +1,101 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH GETXATTR 2 2013\-01\-19 Linux "Linux Programmer's Manual" +.SH 名前 +getxattr, lgetxattr, fgetxattr \- 拡張属性の値を取得する +.SH 書式 +.fam C +.nf +\fB#include \fP +\fB#include \fP +.sp +\fBssize_t getxattr(const char\ *\fP\fIpath\fP\fB, const char\ *\fP\fIname\fP\fB,\fP +\fB void\ *\fP\fIvalue\fP\fB, size_t \fP\fIsize\fP\fB);\fP +\fBssize_t lgetxattr(const char\ *\fP\fIpath\fP\fB, const char\ *\fP\fIname\fP\fB,\fP +\fB void\ *\fP\fIvalue\fP\fB, size_t \fP\fIsize\fP\fB);\fP +\fBssize_t fgetxattr(int \fP\fIfd\fP\fB, const char\ *\fP\fIname\fP\fB,\fP +\fB void\ *\fP\fIvalue\fP\fB, size_t \fP\fIsize\fP\fB);\fP +.fi +.fam T +.SH 説明 +拡張属性は、inode (ファイル、ディレクトリ、シンボリックリンク等) に 関連付けられた \fIname\fP:\fIvalue\fP の対である。 +これらは、システム上のすべての inode に関連付けられた通常の属性 (\fBstat\fP(2) が返すデータ) を拡張するものである。 +拡張属性のコンセプトは \fBattr\fP(5) に書かれている。 +.PP +\fBgetxattr\fP() は、ファイルシステム内の指定された \fIpath\fP に対応する、名前 \fIname\fP の拡張属性の \fIvalue\fP +(値) を取得する。 属性 \fIvalue\fP の長さが返される。 +.PP +\fBlgetxattr\fP() は \fBgetxattr\fP() と同じだが、シンボリックリンクの場合に、リンクが参照しているファイル +ではなく、リンクそのものの情報を取得する点だけが異なる。 +.PP +\fBfgetxattr\fP() は \fBgetxattr\fP() と同じだが、 \fIpath\fP の代わりに \fIfd\fP +で参照されたオープン済みファイルの情報だけを取得する点が異なる (\fIfd\fP は \fBopen\fP(2) によって返される)。 +.PP +拡張属性の名前 \fIname\fP は普通の NULL 終端された文字列である。 名前には、名前空間を表す接頭辞 (prefix) が含まれる; 個々の +inode に対して、互いに独立な名前空間が複数あってもよい。 拡張属性の値は、ある一定の長さの任意のテキスト・データまたは +バイナリ・データの集合である。 +.PP +\fIsize\fP に 0 を指定して空のバッファをこれらのシステムコールに渡すことができ、 この場合には指定された名前の拡張属性の現在のサイズが返される。 +この方法は、拡張属性の値を保持するのに十分な大きさのバッファ・サイズを 見積もるのに使うことができる、 +.PP +このシステムコール・インタフェースは、初期バッファのサイズの推測をしたり、 与えられたバッファが小さすぎたことを返り値で知らせることでバッファを大きく +したりできるように設計されている。 +.SH 返り値 +成功した場合、拡張属性の値の長さを表す正の数が返される。 失敗した場合、 \-1 が返され、 \fIerrno\fP に適切な値がセットされる。 +.SH エラー +.TP +\fBENOATTR\fP +指定された名前の属性が存在しない、またはプロセスがその属性にアクセスする権限がない (\fBENOATTR\fP は +\fI\fP で \fBENODATA\fP の同義語として定義されている)。 +.TP +\fBENOTSUP\fP +拡張属性がそのファイルシステムでサポートされていない、 もしくは無効になっている。 +.TP +\fBERANGE\fP +\fIvalue\fP バッファの大きさ \fIsize\fP が結果を保持するのに十分な大きさでなかった。 +.PP +上記に加えて、 \fBstat\fP(2) に書かれているエラーが発生する場合もある。 +.SH バージョン +これらのシステムコールはカーネル 2.4 以降の Linux で利用できる。 glibc でのサポートはバージョン 2.3 以降で行われている。 +.SH 準拠 +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +これらのシステムコールは Linux 独自である。 +.SH 関連項目 +\fBgetfattr\fP(1), \fBsetfattr\fP(1), \fBlistxattr\fP(2), \fBopen\fP(2), +\fBremovexattr\fP(2), \fBsetxattr\fP(2), \fBstat\fP(2), \fBattr\fP(5), \fBsymlink\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/inotify_init.2 b/manual/LDP_man-pages/draft/man2/inotify_init.2 new file mode 100644 index 00000000..73b4734e --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/inotify_init.2 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2005 Robert Love +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, minor changes +.\" 2008-10-10 mtk: add description of inotify_init1() +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH INOTIFY_INIT 2 2012\-05\-04 Linux "Linux Programmer's Manual" +.SH 名前 +inotify_init, inotify_init1 \- inotify インスタンスを初期化する +.SH 書式 +.nf +\fB#include \fP +.sp +\fBint inotify_init(void);\fP +\fBint inotify_init1(int \fP\fIflags\fP\fB);\fP +.fi +.SH 説明 +\fBinotify_init\fP() は、新規の inotify インスタンスを初期化し、作成された inotify イベントキュー +に対応するファイルディスクリプタを返す。 + +\fBinotify_init1\fP() は、 \fIflags\fP が 0 の場合、 \fBinotify_init\fP() と同じである。 \fIflags\fP +に以下の値をビット毎の論理和 (OR) で指定することで、 異なる動作をさせることができる。 +.TP 12 +\fBIN_NONBLOCK\fP +新しく生成されるオープンファイル記述 (open file description) の BR O_NONBLOCK +ファイルステータスフラグをセットする。 このフラグを使うことで、 \fBO_NONBLOCK\fP をセットするために \fBfcntl\fP(2) +を追加で呼び出す必要がなくなる。 +.TP +\fBIN_CLOEXEC\fP +新しいファイル・ディスクリプターに対して close\-on\-exec (\fBFD_CLOEXEC\fP) フラグをセットする。 +このフラグが役に立つ理由については、 \fBopen\fP(2) の \fBO_CLOEXEC\fP フラグの説明を参照のこと。 +.SH 返り値 +成功すると、これらのシステムコールは新しいファイルディスクリプタを返す。 エラーの場合、\-1 を返し、 \fIerrno\fP をエラーを示す値に設定する。 +.SH エラー +.TP +\fBEINVAL\fP +(\fBinotify_init1\fP()) 無効な値が \fIflags\fP に指定された。 +.TP +\fBEMFILE\fP +inotify インスタンスの総数がユーザ単位の上限に達していた。 +.TP +\fBENFILE\fP +inotify インスタンスの総数がシステムの上限に達していた。 +.TP +\fBENOMEM\fP +カーネルメモリが十分になかった。 +.SH バージョン +\fBinotify_init\fP() は Linux 2.6.13 で初めて登場し、 +ライブラリによるサポートは glibc バージョン 2.4 で追加された。 +\fBinotify_init1\fP() は Linux 2.6.27 で追加され、 +ライブラリによるサポートは glibc バージョン 2.9 で追加された。 +.SH 準拠 +これらのシステムコールは Linux 独自である。 +.SH 関連項目 +\fBinotify_add_watch\fP(2), \fBinotify_rm_watch\fP(2), \fBinotify\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/listxattr.2 b/manual/LDP_man-pages/draft/man2/listxattr.2 new file mode 100644 index 00000000..ff491e56 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/listxattr.2 @@ -0,0 +1,113 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH LISTXATTR 2 2013\-01\-27 Linux "Linux Programmer's Manual" +.SH 名前 +listxattr, llistxattr, flistxattr \- 拡張属性の名前リストを得る +.SH 書式 +.fam C +.nf +\fB#include \fP +\fB#include \fP +.sp +\fBssize_t listxattr(const char\ *\fP\fIpath\fP\fB, char\ *\fP\fIlist\fP\fB, size_t \fP\fIsize\fP\fB);\fP +\fBssize_t llistxattr(const char\ *\fP\fIpath\fP\fB, char\ *\fP\fIlist\fP\fB, size_t \fP\fIsize\fP\fB);\fP +\fBssize_t flistxattr(int \fP\fIfd\fP\fB, char\ *\fP\fIlist\fP\fB, size_t \fP\fIsize\fP\fB);\fP +.fi +.fam T +.SH 説明 +拡張属性は、inode (ファイル、ディレクトリ、シンボリックリンク等) に 関連付けられた \fIname\fP:\fIvalue\fP の対である。 +これらは、システム上のすべての inode に関連付けられた通常の属性 (\fBstat\fP(2) が返すデータ) を拡張するものである。 +拡張属性のコンセプトは \fBattr\fP(5) に書かれている。 +.PP +\fBlistxattr\fP() は、ファイルシステム内の指定された \fIpath\fP に対応する拡張属性の名前リストを取得する。 リストは名前の集合で、 +NULL 終端された文字列が連続して並んでいる。 呼び出したプロセスがアクセスする権限のない拡張属性の名前は、 リストに含まれない。拡張属性の名前の +\fIlist\fP の長さが返される。 +.PP +\fBllistxattr\fP() は \fBlistxattr\fP() と同じだが、シンボリックリンクの場合に、リンクが参照しているファイル +ではなく、リンクそのものの拡張属性の名前リストを取得する点だけが異なる。 +.PP +\fBflistxattr\fP() は \fBlistxattr\fP() と同じだが、 \fIpath\fP の代わりに \fIfd\fP +で参照されたオープン済みファイルの情報だけを取得する点が異なる (\fIfiledes\fP は \fBopen\fP(2) によって返される)。 +.PP +個々の拡張属性の \fIname\fP は普通の NULL 終端された文字列である。 名前には、名前空間を表す接頭辞 (prefix) が含まれる; 個々の +inode に対して、互いに独立な名前空間が複数あってもよい。 +.PP +\fIsize\fP に 0 を指定して空のバッファをこれらのシステムコールに渡すことができ、 この場合には拡張属性の名前リストの現在のサイズが返される。 +この方法は名前リストを保持するのに十分な大きさのバッファ・サイズを 見積もるのに使うことができる、 +.SS Example +返される名前の \fIlist\fP は、 NULL 終端された文字列の配列 (属性名は NULL バイト (\(aq\e0\(aq) で区切られている) +で、各要素は整列されている訳ではない。 以下に例を示す: +.fam C +.RS +.nf + +user.name1\e0system.name1\e0user.name2\e0 +.fi +.RE +.fam T +.P +拡張属性を使って POSIX ACL を実装している ext2、ext3、XFS のようなファイル システムでは、返される \fIlist\fP +は以下のようになることだろう: +.fam C +.RS +.nf + +system.posix_acl_access\e0system.posix_acl_default\e0 +.fi +.RE +.fam T +.SH 返り値 +成功した場合、拡張属性の名前リストの長さを表す非負の数が返される。 失敗した場合、 \-1 が返され、 \fIerrno\fP に適切な値がセットされる。 +.SH エラー +.TP +\fBENOTSUP\fP +拡張属性がそのファイルシステムでサポートされていない、 もしくは無効になっている。 +.TP +\fBERANGE\fP +\fIlist\fP バッファの大きさ \fIsize\fP が結果を保持するのに十分な大きさでなかった。 +.PP +上記に加えて、 \fBstat\fP(2) に書かれているエラーが発生する場合もある。 +.SH バージョン +これらのシステムコールはカーネル 2.4 以降の Linux で利用できる。 glibc でのサポートはバージョン 2.3 以降で行われている。 +.SH 準拠 +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +これらのシステムコールは Linux 独自である。 +.SH 関連項目 +\fBgetfattr\fP(1), \fBsetfattr\fP(1), \fBgetxattr\fP(2), \fBopen\fP(2), +\fBremovexattr\fP(2), \fBsetxattr\fP(2), \fBstat\fP(2), \fBattr\fP(5), \fBsymlink\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/poll.2 b/manual/LDP_man-pages/draft/man2/poll.2 new file mode 100644 index 00000000..ba04914b --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/poll.2 @@ -0,0 +1,231 @@ +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Additions from Richard Gooch and aeb, 971207 +.\" 2006-03-13, mtk, Added ppoll() + various other rewordings +.\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and +.\" formatting changes. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH POLL 2 2012\-08\-17 Linux "Linux Programmer's Manual" +.SH 名前 +poll, ppoll \- ファイルディスクリプタにおけるイベントを待つ +.SH 書式 +.nf +\fB#include \fP +.sp +\fBint poll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB, int \fP\fItimeout\fP\fB);\fP +.sp +\fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */ +\fB#include \fP +.sp +\fBint ppoll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB, \fP +\fB const struct timespec *\fP\fItimeout_ts\fP\fB, const sigset_t *\fP\fIsigmask\fP\fB);\fP +.fi +.SH 説明 +\fBpoll\fP() は \fBselect\fP(2) と同様の仕事を行う、つまり、ファイルディスクリプタ集合のいずれか一つが I/O +を実行可能な状態になるのを待つ。 + +監視するファイルディスクリプタ集合は、 \fIfds\fP 引き数で指定する。 \fIfds\fP は、以下の型の構造体の配列である。 +.in +4n +.nf + +struct pollfd { + int fd; /* file descriptor */ + short events; /* requested events */ + short revents; /* returned events */ +}; +.in +.fi +.PP +\fInfds\fP には、 \fIfds\fP 配列の要素数を指定する。 + +\fIfd\fP フィールドには、オープンされたファイルのファイルディスクリプタが入る。 +このフィールドが負の場合、対応する \fIevents\fP フィールドは無視され、 +\fIrevents\fP には 0 が返される。(この機能により、一つの \fBpoll\fP() の呼び出しで +簡単にあるファイルディスクリプタを無視することができる。 +単に \fIfd\fP フィールドの符号を反転するだけでよい。) + +構造体の \fIevents\fP 要素は入力パラメータで、 +ファイルディスクリプタ \fIfd\fP に関して、 +アプリケーションが興味を持っているイベントのビットマスクを指定する。 +このフィールドに 0 が指定された場合は、\fIfd\fP の全てのイベントが無視され、 +\fIrevents\fP には 0 が返される。 + +\fIrevents\fP 要素は出力パラメータで、実際に起こったイベントがカーネルにより設定される。 \fIrevents\fP で返されるビット列には、 +\fIevents\fP で指定したもののどれか、もしくは \fBPOLLERR\fP, \fBPOLLHUP\fP, \fBPOLLNVAL\fP のうちの一つが含まれる +(\fBPOLLERR\fP, \fBPOLLHUP\fP, \fBPOLLNVAL\fP の 3つのビットは \fIevents\fP +に指定しても意味がなく、対応した状態が真の場合に \fIrevents\fP に設定される)。 + +どのファイルディスクリプタにも要求したイベントが発生しておらず、 エラーも起こらない場合、 \fBpoll\fP() +はイベントのうちいずれか一つが発生するまで停止 (block) する。 + +\fItimeout\fP 引き数は、 \fBpoll\fP() が停止する最小時間をミリ秒で指定する +(この停止時間はシステムクロックの粒度に切り上げられ、カーネルの +スケジューリング遅延により少しだけ長くなる可能性がある)。 +\fItimeout\fP に負の値を指定した場合、タイムアウト時間が無限大を意味する。 +\fItimeout\fP を 0 に指定した場合、I/O 可能なファイルディスクリプタが +ない場合であっても、 \fBpoll\fP() はすぐに返る。 + +\fIevents\fP に指定したり、 \fIrevents\fP で返されるビットは \fI\fP で定義されている: +.RS +.TP +\fBPOLLIN\fP +読み出し可能なデータがある。 +.TP +\fBPOLLPRI\fP +読み出し可能な緊急データ (urgent data) がある (例えば、TCP ソケットの帯域外 (out\-of\-band data) +データを受信した場合や、 パケットモードの擬似端末のマスタがスレーブ側の変化を見つけたとき)。 +.TP +\fBPOLLOUT\fP +書き込みが停止 (block) しない状態である。 +.TP +\fBPOLLRDHUP\fP (Linux 2.6.17 以降) +ストリームソケットの他端が、コネクションを close したか、 コネクションの書き込み側を shutdown した。 この定義を有効にするには、 +(「どの」ヘッダファイルをインクルードするよりも前に) \fB_GNU_SOURCE\fP 機能検査マクロを定義しなければならない。 +.TP +\fBPOLLERR\fP +エラー状態 (出力の場合のみ)。 +.TP +\fBPOLLHUP\fP +ハングアップした (出力の場合のみ)。 +.TP +\fBPOLLNVAL\fP +不正な要求: \fIfd\fP がオープンされていない (出力の場合のみ)。 +.RE +.PP +\fB_XOPEN_SOURCE\fP を定義してコンパイルした場合には、以下の定義も行われる。 +ただし、上記のリストにあるビット以上の情報が得られる訳ではない。 +.RS +.TP +\fBPOLLRDNORM\fP +\fBPOLLIN\fP と同じ。 +.TP +\fBPOLLRDBAND\fP +.\" POLLRDBAND is used in the DECnet protocol. +優先帯域データ (priority band data) が読み出し可能である (普通は Linux では使用されない)。 +.TP +\fBPOLLWRNORM\fP +\fBPOLLOUT\fP と同じ。 +.TP +\fBPOLLWRBAND\fP +優先帯域データ (priority data) が書き込み可能である。 +.RE +.PP +Linux では \fBPOLLMSG\fP も定義されているが、使用されていない。 +.SS ppoll() +\fBpoll\fP() と \fBppoll\fP() の関係は \fBselect\fP(2) と \fBpselect\fP(2) の関係と同じようなものである: +\fBpselect\fP(2) と同様に、 \fBppoll\fP() を使うと、アプリケーションはファイルディスクリプタの状態変化 +もしくはシグナルの捕捉を安全に待つことができる。 +.PP +\fItimeout\fP 引き数の精度の違いを除くと、以下の \fBppoll\fP() の呼び出しは、 +.nf + + ready = ppoll(&fds, nfds, timeout_ts, &sigmask); + +.fi +次の呼び出しを \fIatomic\fP に実行するのと等価である。 +.nf + + sigset_t origmask; + int timeout; + + timeout = (timeout_ts == NULL) ? \-1 : + (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000); + sigprocmask(SIG_SETMASK, &sigmask, &origmask); + ready = poll(&fds, nfds, timeout); + sigprocmask(SIG_SETMASK, &origmask, NULL); +.fi +.PP +なぜ \fBppoll\fP() が必要なのかについての説明は \fBpselect\fP(2) の説明を参照のこと。 + +\fIsigmask\fP 引き数に NULL が指定された場合、シグナルマスクの操作は行われない (したがって、 \fBppoll\fP() の +\fBpoll\fP() との違いは \fItimeout\fP 引き数の精度だけとなる)。 + +\fItimeout\fP 引き数は \fBppoll\fP() が停止する時間の上限を指定するものである。 +この引き数には以下の型の構造体へのポインタを指定する。 +.in +4n +.nf + +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.fi +.in + +\fItimeout_ts\fP に NULL が指定された場合、 \fBppoll\fP は無限に停止することがあり得る。 +.SH 返り値 +成功した場合は正の数を返す。この数は 0 以外の \fIrevents\fP 要素を持つ構造体の数である (別の言い方をすると、これらのディスクリプタ +にはイベントかエラー報告がある)。 値 0 は、タイムアウトとなり、どのファイルディスクリプタでもイベントが 発生しなかったことを示す。エラーの場合は +\-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +.TP +\fBEFAULT\fP +引き数として指定した配列が、呼び出したプロセスのアドレス空間に 含まれていない。 +.TP +\fBEINTR\fP +要求されたイベントのどれかが起こる前にシグナルが発生した。 \fBsignal\fP(7) 参照。 +.TP +\fBEINVAL\fP +\fInfds\fP の値が \fBRLIMIT_NOFILE\fP を超えた。 +.TP +\fBENOMEM\fP +ファイルディスクリプタ・テーブルを確保するためのメモリがない。 +.SH バージョン +.\" library call was introduced in libc 5.4.28 +\fBpoll\fP() システムコールは Linux 2.1.23 で導入された。 +このシステムコールが存在しない古いカーネルでは、 +glibc (や古い Linux libc) は \fBselect\fP(2) を使用して \fBpoll\fP() +ラッパー関数のエミュレーションを行う。 + +\fBppoll\fP() システムコールは カーネル 2.6.16 で Linux に追加された。 \fBppoll\fP() ライブラリコールは glibc +2.4 に追加された。 +.SH 準拠 +.\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). +\fBpoll\fP() は POSIX.1\-2001 に準拠している。 \fBppoll\fP() は Linux 固有である。 +.SH 注意 +いくつかの実装では、値 \-1 を持った非標準の定数 \fBINFTIM\fP が定義されており、 \fBpoll\fP() の \fItimeout\fP +の指定に使用できる。 この定数は glibc では定義されていない。 + +\fBpoll\fP() で監視中のファイルディスクリプタが別のスレッドによってクローズされた場合に何が起こるかの議論については、 \fBselect\fP(2) +を参照してほしい。 +.SS "Linux での注意" +Linux の \fBppoll\fP() システムコールは \fItimeout_ts\fP 引き数を変更する。 しかし、glibc +のラッパー関数は、システムコールに渡す timeout 引き数 としてローカル変数を使うことでこの動作を隠蔽している。 このため、glibc の +\fBppoll\fP() 関数では \fItimeout_ts\fP 引き数は変更されない。 +.SH バグ +\fBselect\fP(2) の「バグ」の節に書かれている、誤った準備完了通知 (spurious readiness notifications) +についての議論を参照のこと。 +.SH 関連項目 +\fBselect\fP(2), \fBselect_tut\fP(2), \fBtime\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/readdir.2 b/manual/LDP_man-pages/draft/man2/readdir.2 new file mode 100644 index 00000000..dc43f92c --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/readdir.2 @@ -0,0 +1,100 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" In 1.3.X, returns only one entry each time; return value is different. +.\" Modified 2004-12-01, mtk, fixed headers listed in SYNOPSIS +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH READDIR 2 2012\-07\-13 Linux "Linux Programmer's Manual" +.SH 名前 +readdir \- ディレクトリ・エントリを読み込む +.SH 書式 +.nf +.sp +\fBint readdir(unsigned int \fP\fIfd\fP\fB, struct old_linux_dirent *\fP\fIdirp\fP\fB,\fP +\fB unsigned int \fP\fIcount\fP\fB);\fP +.fi + +\fI注\fP: このシステムコールに対する glibc のラッパー関数は用意されていない。「注意」の節を参照のこと。 +.SH 説明 +これはあなたの興味をもっている関数ではない。 POSIX 準拠の C ライブラリ・インターフェースについては \fBreaddir\fP(3) を見ること。 +このページは裸のカーネルのシステムコール・インターフェースについて 記述しているが、このインターフェースは \fBgetdents\fP(2) +によって取って代わられた。 +.PP +\fBreaddir\fP() は、ファイルディスクリプタ \fIfd\fP が参照しているディレクトリから \fIold_linux_dirent\fP +構造体を読み込み、 \fIdirp\fP で指されたバッファに格納する。 \fIcount\fP 引き数は(ほとんどの \fIold_linux_dirent\fP +構造体の読み込みにおいて)無視される +.PP +\fIold_linux_dirent\fP 構造体は以下のように宣言される: +.PP +.in +4n +.nf +struct old_linux_dirent { + long d_ino; /* inode number */ + off_t d_off; /* offset to this \fIold_linux_dirent\fP */ + unsigned short d_reclen; /* length of this \fId_name\fP */ + char d_name[NAME_MAX+1]; /* filename (null\-terminated) */ +} +.fi +.in +.PP +\fId_ino\fP は inode 番号である。 \fId_off\fP はディレクトリの最初からこの \fIold_linux_dirent\fP まで距離である。 +\fId_reclen\fP は \fId_name\fP の大きさで、終端のヌルバイト (null byte) を含まない。 \fId_name\fP +はヌルバイトで終わるファイル名である。 +.SH 返り値 +成功した場合は、1 が返される。 ディレクトリの最後では 0 が返される。 エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +.TP +\fBEBADF\fP +ファイルディスクリプタ \fIfd\fP が不正である。 +.TP +\fBEFAULT\fP +引き数が呼び出したプロセスのアドレス空間外を指している。 +.TP +\fBEINVAL\fP +結果用のバッファーが小さすぎる。 +.TP +\fBENOENT\fP +そのようなディレクトリは存在しない。 +.TP +\fBENOTDIR\fP +ファイルディスクリプタがディレクトリを参照していない。 +.SH 準拠 +このシステム・コールは Linux 特有である。 +.SH 注意 +glibc はこのシステムコールに対するラッパー関数を提供していない。 \fBsyscall\fP(2) を使って呼び出すこと。 +\fIold_linux_dirent\fP 構造体を自分自身で定義する必要がある。しかし、たいていはこのシステムコールではなく \fBreaddir\fP(3) +を使うべき場面のことが多い。 +.SH 関連項目 +\fBgetdents\fP(2), \fBreaddir\fP(3) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/uname.2 b/manual/LDP_man-pages/draft/man2/uname.2 new file mode 100644 index 00000000..160ef053 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/uname.2 @@ -0,0 +1,107 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-07-05 mtk: Added details on underlying system call interfaces +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH UNAME 2 2008\-12\-03 Linux "Linux Programmer's Manual" +.SH 名前 +uname \- 現在稼働中のカーネルについての名前と情報を得る +.SH 書式 +\fB#include \fP +.sp +\fBint uname(struct utsname *\fP\fIbuf\fP\fB);\fP +.SH 説明 +\fBuname\fP() は \fIbuf\fP で指される構造体にシステム情報を返す。 \fIutsname\fP 構造体は +\fI\fP で以下のように定義されている。 +.in +4n +.nf + +struct utsname { + char sysname[]; /* OS の名前 (例: "Linux") */ + char nodename[]; /* 「実装時に定義された、何らかの + ネットワーク」におけるマシン名 */ + char release[]; /* オペレーションシステムのリリース番号 (例: "2.6.28") */ + char version[]; /* オペレーティングシステムのバージョン */ + char machine[]; /* ハードウェア識別子 */ +#ifdef _GNU_SOURCE + char domainname[]; /* NIS や YP のドメイン名 */ +#endif +}; + +.fi +.in +\fIstruct utsname\fP にある配列の長さは指定されていない (「注意」の節を参照)。 フィールドは NULL バイト +(\(aq\e0\(aq) で終端される。 +.SH 返り値 +成功した場合は 0 が返される。エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +.TP +\fBEFAULT\fP +\fIbuf\fP が有効でない。 +.SH 準拠 +SVr4, POSIX.1\-2001. 4.3BSD には \fBuname\fP() コールがない。 +.PP +\fIdomainname\fP メンバー (NIS または YP ドメイン名) は GNU の拡張である。 +.SH 注意 +これはシステムコールであり、OS は名前・リリース・バージョンなどを たぶん分かっているだろう。 +さらにそれが稼働しているハードウェアも分かっているだろう。 よって構造体の 4 つのフィールドには意味がある。 一方、\fInodename\fP +フィールドには意味がない: このフィールドは現在のマシンの (定義されていない) どこかのネットワークにおける名前を与えるが、 +通常マシンは複数のネットワークに属し、複数の名前を持つ。 さらに、カーネルはこのような情報を知る術を持たないので、 +ここでの答えは前もって教えてやらなければならない。 これは追加フィールドである \fIdomainname\fP についても同様である。 +.LP +このため Linux ではシステムコール \fBsethostname\fP(2) と \fBsetdomainname\fP(2) が使われる。 +「\fBsethostname\fP(2) で設定されるホスト名は、 \fBuname\fP() で返される構造体の \fInodename\fP +フィールドと同じ文字列である」 と規定している標準規格はない (実際、256 バイトのホスト名と 8 バイトのノード名を許可しているシステムもある)。 +しかし、Linux では同じ文字列が返される。 \fBsetdomainname\fP(2) と \fIdomainname\fP +フィールドについても同じことが成り立つ。 +.LP +構造体のフィールドの長さはさまざまである。 OS やライブラリの中には、 ハードコードされた 9, 33, 65, 257 +などの値を使っているものもある。 また \fBSYS_NMLN\fP, \fB_SYS_NMLN\fP, \fBUTSLEN\fP, \fB_UTSNAME_LENGTH\fP +などを使っているシステムもある。 はっきり言って、これらの定数を使うのは悪い考え方であり、 sizeof(...) を使うべきである。 +インターネットホスト名で使う領域を持たせるために、 257 が選ばれることが多い。 +.LP +utsname の情報は、 \fI/proc/sys/kernel/\fP{\fIostype\fP, \fIhostname\fP, \fIosrelease\fP, +\fIversion\fP, \fIdomainname\fP} を使ってアクセスすることもできる。 +.SS 背後のカーネル・インタフェース +.LP +.\" That was back before Linux 1.0 +.\" That was also back before Linux 1.0 +時間の経過とともに、 \fIutsname\fP 構造体のサイズが大きくなり、この影響で \fBuname\fP() には 3つのバージョンが存在する: +\fIsys_olduname\fP() (スロットは \fI__NR_oldolduname\fP)、 \fIsys_uname\fP() (スロットは +\fI__NR_olduname\fP)、 \fIsys_newuname\fP() (スロットは \fI__NR_uname\fP)。 +\fIsys_olduname\fP() はすべてのフィールドが長さ 9 を使っていた。 \fIsys_uname\fP() は長さ 65 を使っていた。 +\fIsys_newuname\fP() も長さ 65 を使っているが、 \fIdomainname\fP フィールドが追加されている。 glibc の +\fBuname\fP() ラッパー関数は、これらの詳細をアプリケーションから隠蔽し、 +カーネルが提供しているシステムコールのうち最新のバージョンを起動する。 +.SH 関連項目 +\fBuname\fP(1), \fBgetdomainname\fP(2), \fBgethostname\fP(2) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/vfork.2 b/manual/LDP_man-pages/draft/man2/vfork.2 new file mode 100644 index 00000000..28fbdc60 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/vfork.2 @@ -0,0 +1,171 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl), 1 Nov 1999 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 1999-11-10: Merged text taken from the page contributed by +.\" Reed H. Petty (rhp@draper.net) +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH VFORK 2 2012\-08\-05 Linux "Linux Programmer's Manual" +.SH 名前 +vfork \- 子プロセスを生成し親プロセスを停止させる +.SH 書式 +\fB#include \fP +.br +\fB#include \fP +.sp +\fBpid_t vfork(void);\fP +.sp +.in -4n +glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): +.in +.sp +\fBvfork\fP(): +.ad l +.RS 4 +.PD 0 +.TP 4 +glibc 2.12 以降: +.nf +_BSD_SOURCE || + (_XOPEN_SOURCE\ >=\ 500 || + _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) && + !(_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700) +.TP 4 +.fi +glibc 2.12 より前: _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH 説明 +.SS 規格の説明 +(POSIX.1 より引用) \fBvfork\fP() 関数は \fBfork\fP(2) と同じ働きをするが、 \fBvfork\fP() +で作成されたプロセスが \fBvfork\fP() からの返り値を格納している \fIpid_t\fP 型の変数以外を変更したり、 \fBvfork\fP() +を呼び出している関数から return したり、 \fB_exit\fP(2) や \fBexec\fP(3) +族の関数をコールする前に他の関数をコールした場合の動作が 未定義であるという点が異なる。 +.SS "LINUX での説明" +\fBvfork\fP() は \fBfork\fP(2) と全く同じように呼び出したプロセスの子プロセスを生成する。 詳しい説明と返り値、エラーについては +\fBfork\fP(2) を参照すること。 +.PP +\fBvfork\fP() は \fBclone\fP(2) の特殊な場合である。 親プロセスのページテーブルのコピーを行わずに新しいプロセスを +作成するために使用する。これは性能に敏感なアプリケーションにおいて 子プロセスを生成してすぐに \fBexecve\fP(2) する場合に有用かもしれない。 +.PP +\fBvfork\fP() は \fBfork\fP(2) と違い、子プロセスが終了するか、 +\fBexecve\fP(2) をコールするまで呼び出し元のスレッドを停止 (suspend) させる。 +子プロセスの終了は、\fB_exit\fP(2) の呼び出しによる通常終了、致命的なシグナルの +配送後の異常終了の二つのケースがある。 +この時点までは、子プロセスはスタックを含む全てのメモリを親プロセスと共有する。 +子プロセスは現在の関数から return してはならず、 +\fBexit\fP(3) もコールしてはならないが、\fB_exit\fP(2) ならばコールしてもよい。 + +\fBfork\fP(2) と同様に、 \fBvfork\fP() で作成された子プロセスは、 +(ファイルディスクリプタ、シグナル配送定義、カレントワーキングディレクトリなどの) +呼び出し元のプロセスの各種の属性を継承する。 +\fBvfork\fP() では、上で説明した仮想アドレス空間の扱いだけが異なる。 + +親プロセスへ送られたシグナルは、子プロセスが親プロセスのメモリを解放した後 +(すなわち、子プロセスが終了するか \fBexecve\fP(2) を呼んだ後) に到着する。 +.SS 歴史的な説明 +Linux において \fBfork\fP(2) は書き込み時コピー (copy\-on\-write) ページを使用して実装されている。 そのため +\fBfork\fP(2) を使用することによって被る損害は親プロセスのページ・テーブルを 複製するために必要な時間とメモリだけである。 +しかしながら、忌しき昔には \fBfork\fP(2) は呼び出したプロセスのデータ空間の全てのコピーしていたが、 +これはしばしば不必要であった。なぜなら、たいていはすぐ後に \fBexec\fP(3) を実行していたからである。 この場合の効率を上げるために BSD は +\fBvfork\fP() システムコールを導入して親プロセスのアドレス空間を完全にコピー するかわりに、 \fBexecve\fP(2) をコールするか +exit が起きるまで親プロセスのメモリと制御スレッド を借りるようにした。 親プロセスは子プロセスがその資源を使用している間は停止された。 +\fBvfork\fP() は使いにくいものであった: 例えば、親プロセスの変数を変更しな いようにするためにはどの変数がレジスタに保持されているかを知らな +ければならなかった。 +.SH 準拠 +4.3BSD; POSIX.1\-2001 (廃止予定とされている)。 +POSIX.1\-2008 では \fBvfork\fP() の規定が削除されている。 + +.\" In AIXv3.1 vfork is equivalent to fork. +\fBvfork\fP() コールは他のオペレーティング・システムの同名のコールと ちょっと似 +ているかもしれない。規格が \fBvfork\fP() に要求していることは、 \fBfork\fP(2) に要 +求していることよりは弱い。したがって、 両者を同じものとして実装しても、規格に +準拠していることになる。 特にプログラマーは、子プロセスが終了するか +\fBexecve\fP(2) を呼び出すまで親プロセスが停止していることや、メモリを共有するこ +とによる特殊な動作をあてにすべきではない。 +.SH 注意 +.PP +\fBvfork\fP() の動作は構造的な欠陥と考える人もいるだろうし、 +BSD のマニュアルには、「このシステムコールは妥当なシステム共有機構が実装さ +れた場合には削除される。ユーザは \fBvfork\fP() のメモリ共有機能に依存するべき +ではない。何故ならば、このシステムコール が削除された場合には、それは +\fBfork\fP(2) の同義語とされるからである。」と書かれている。しかしながら、 +最近のメモリ管理ハードウェアにより \fBfork\fP(2) と \fBvfork\fP() の間の性能差が +減ったとはいえ、 Linux や他のシステムで \fBvfork\fP() が残されているのには +いくつか理由がある: +.IP * 3 +性能に厳しいアプリケーションでは、 \fBvfork\fP() により得られる +小さな性能上のメリットが必要な場合がある。 +.IP * +.\" http://stackoverflow.com/questions/4259629/what-is-the-difference-between-fork-and-vfork +.\" http://developers.sun.com/solaris/articles/subprocess/subprocess.html +.\" http://mailman.uclinux.org/pipermail/uclinux-dev/2009-April/000684.html +\fBvfork\fP() はメモリ管理ユニット (MMU) を持たないシステムでも実装すること +ができるが、そのようなシステムで \fBfork\fP(2) を実装することはできない。 +(POSIX.1\-2008 では \fBvfork\fP() が標準から削除された。 +\fBposix_spawn\fP(3) 関数の POSIX の原理 (rationale) には、 +\fBfork\fP(2)+\fBexec\fP(3) と等価な機能を提供する \fBposix_spawn\fP(3) は、 +MMU を持たないシステムでも実装できるように設計されたとの注記がある。) +.SS "Linux での注意" +\fBpthread_atfork\fP(3) を使って設定された fork ハンドラは NPTL +スレッドライブラリコールを採用したマルチスレッドプログラムでは 呼び出されない。一方、LinuxThreads スレッドライブラリを使った +プログラムでは、fork ハンドラは呼び出される。 (Linux のスレッドライブラリの説明は \fBpthreads\fP(7) を参照。) + +\fBvfork\fP() の呼び出しは、以下の \fIflags\fP を指定して \fBclone\fP(2) を呼び出す +のと等価である。 + + CLONE_VM | CLONE_VFORK | SIGCHLD +.SS 歴史 +.\" In the release notes for 4.2BSD Sam Leffler wrote: `vfork: Is still +.\" present, but definitely on its way out'. +\fBvfork\fP() システムコールは 3.0BSD に現われた。 4.4BSD において \fBfork\fP(2) の同義語となったが、NetBSD +では再び導入された。 +.UR http://www.netbsd.org\:/Documentation\:/kernel\:/vfork.html +.UE +を参照。 +Linux では 2.2.0\-pre6 あたりまでは \fBfork\fP(2) と等価であった。(i386 では) 2.2.0\-pre9 から +(他のアーキテクチャでは 少し遅れて) 独立したシステムコールとなった。 glibc でのサポートは glibc\-2.0.112 で追加された。 +.SH バグ +.PP +.\" +.\" As far as I can tell, the following is not true in 2.6.19: +.\" Currently (Linux 2.3.25), +.\" .BR strace (1) +.\" cannot follow +.\" .BR vfork () +.\" and requires a kernel patch. +シグナルの扱いの詳細は不明瞭でシステムごとに異っている。 BSD のマニュアルには、 「デッドロック状態になる可能性があるので \fBvfork\fP() +の途中の子プロセスに \fBSIGTTOU\fP や \fBSIGTTIN\fP シグナルを送信してはならない; さらに出力や \fIioctl\fP +は許されるが、入力を試みた場合には結果はファイル終端 (EOF) になる。」 と書かれている。 +.SH 関連項目 +\fBclone\fP(2), \fBexecve\fP(2), \fBfork\fP(2), \fBunshare\fP(2), \fBwait\fP(2) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man2/vhangup.2 b/manual/LDP_man-pages/draft/man2/vhangup.2 new file mode 100644 index 00000000..4f0ed9f3 --- /dev/null +++ b/manual/LDP_man-pages/draft/man2/vhangup.2 @@ -0,0 +1,65 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH VHANGUP 2 2007\-07\-26 Linux "Linux Programmer's Manual" +.SH 名前 +vhangup \- 現在の端末を仮想的に (virtualy) ハングアップ (hangup) させる +.SH 書式 +\fB#include \fP +.sp +\fBint vhangup(void);\fP +.sp +.in -4n +glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): +.in +.sp +.ad l +\fBvhangup\fP(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.ad b +.SH 説明 +\fBvhangup\fP() は現在の端末 (terminal) でハングアップをシミュレートする。このコールは他のユーザーがログインした時に綺麗 +(clean) な端末を得ることができるよう手配する。 +.SH 返り値 +成功した場合は 0 が返される。エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +.TP +\fBEPERM\fP +呼び出し元プロセスに \fBvhangup\fP() を呼び出すための十分な特権がない。 \fBCAP_SYS_TTY_CONFIG\fP ケーパビリティ +(capability) が必要である。 +.SH 準拠 +このコールは Linux 特有であり、移植を意図したプログラムで 使用してはいけない。 +.SH 関連項目 +\fBcapabilities\fP(7), \fBinit\fP(8) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man3/euidaccess.3 b/manual/LDP_man-pages/draft/man3/euidaccess.3 new file mode 100644 index 00000000..a49f8554 --- /dev/null +++ b/manual/LDP_man-pages/draft/man3/euidaccess.3 @@ -0,0 +1,79 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH EUIDACCESS 3 2010\-11\-01 "" "Linux Programmer's Manual" +.SH 名前 +euidaccess, eaccess \- ファイルへのアクセス権を実効ユーザでチェックする +.SH 書式 +.nf +\fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */ +\fB#include \fP +.sp +\fBint euidaccess(const char *\fP\fIpathname\fP\fB, int \fP\fImode\fP\fB);\fP +\fBint eaccess(const char *\fP\fIpathname\fP\fB, int \fP\fImode\fP\fB);\fP +.fi +.SH 説明 +\fBaccess\fP(2) と同様、 \fBeuidaccess\fP() は引き数 \fIpathname\fP で指定されたファイルの許可 +(permission) と存在のチェックを行う。 \fBaccess\fP(2) はプロセスの実 (real) ユーザID / 実グループID +を用いてチェックを行うのに対し、 \fBeuidaccess\fP() は実効 (effective) ID を用いる。 + +\fImode\fP は \fBR_OK\fP, \fBW_OK\fP, \fBX_OK\fP, \fBF_OK\fP の一つ以上から構成されるマスクである。 \fBR_OK\fP, +\fBW_OK\fP, \fBX_OK\fP, \fBF_OK\fP は \fBaccess\fP(2) と同じ意味を持つ。 + +\fBeaccess\fP() は \fBeuidaccess\fP() の同義語であり、他のいくつかのシステムとの互換性のために提供されている。 +.SH 返り値 +成功した場合 (要求した全てについて許可が得られたら)、ゼロが返される。 エラーの場合 (\fImode\fP +の少なくとも一つのビットで要求した許可がなかった場合や、 他のエラーが起こった場合)、\-1 が返され、 \fIerrno\fP が適切に設定される。 +.SH エラー +\fBaccess\fP(2) と同じ。 +.SH バージョン +\fBeaccess\fP() 関数は glibc のバージョン 2.4 で追加された。 +.SH 準拠 +.\" e.g., FreeBSD 6.1. +これらの関数は非標準である。 他のいくつかのシステムには \fBeaccess\fP() 関数がある。 +.SH 注意 +\fI警告\fP: +ある操作を実行する前にこの関数を使ってファイルに対するプロセスのアクセス許可を +確認してから、その情報に基づいて操作を行うと、競合条件が発生する可能性がある。 +これは二つの操作の間でファイルのアクセス許可が変化する場合があるからである。 +一般的には、必要な操作のみを行い、その際に発生したアクセス許可に関するエラーを +処理する方が安全である。 + +この関数は常にシンボリックリンクの展開を行う。 +シンボリックリンクのアクセス許可を確認する必要がある場合は、 +フラグ \fBAT_EACCESS\fP と \fBAT_SYMLINK_NOFOLLOW\fP を付けて +\fBfaccessat\fP(2) を使うこと。 +.SH 関連項目 +\fBaccess\fP(2), \fBchmod\fP(2), \fBchown\fP(2), \fBfaccessat\fP(2), \fBopen\fP(2), +\fBsetgid\fP(2), \fBsetuid\fP(2), \fBstat\fP(2), \fBcredentials\fP(7), +\fBpath_resolution\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man3/exec.3 b/manual/LDP_man-pages/draft/man3/exec.3 new file mode 100644 index 00000000..03cedd95 --- /dev/null +++ b/manual/LDP_man-pages/draft/man3/exec.3 @@ -0,0 +1,142 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)exec.3 6.4 (Berkeley) 4/19/91 +.\" +.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu +.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com +.\" Modified, 24 Jun 2004, Michael Kerrisk +.\" Added note on casting NULL +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH EXEC 3 2010\-09\-25 GNU "Linux Programmer's Manual" +.SH 名前 +execl, execlp, execle, execv, execvp, execvpe \- ファイルを実行する +.SH 書式 +\fB#include \fP +.sp +\fBextern char **environ;\fP +.sp +\fBint execl(const char *\fP\fIpath\fP\fB, const char *\fP\fIarg\fP\fB, ...);\fP +.br +\fBint execlp(const char *\fP\fIfile\fP\fB, const char *\fP\fIarg\fP\fB, ...);\fP +.br +\fBint execle(const char *\fP\fIpath\fP\fB, const char *\fP\fIarg\fP\fB,\fP +.br +\fB ..., char * const \fP\fIenvp\fP\fB[]);\fP +.br +\fBint execv(const char *\fP\fIpath\fP\fB, char *const \fP\fIargv\fP\fB[]);\fP +.br +\fBint execvp(const char *\fP\fIfile\fP\fB, char *const \fP\fIargv\fP\fB[]);\fP +.br +\fBint execvpe(const char *\fP\fIfile\fP\fB, char *const \fP\fIargv\fP\fB[],\fP +.br +\fB char *const \fP\fIenvp\fP\fB[]);\fP +.sp +.in -4n +glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): +.in +.sp +\fBexecvpe\fP(): _GNU_SOURCE +.SH 説明 +\fBexec\fP() ファミリーの関数は現在のプロセスイメージを新しいプロセスイメージで置き 換える。このマニュアルで説明されている関数は +\fBexecve\fP(2) のフロントエンドである。 (現在のプロセスイメージの置き換えについての詳細は \fBexecve\fP(2) +のマニュアルを参照) +.PP +これらの関数の最初の引き数は、実行されるファイルの名前である。 +.PP +関数 \fBexecl\fP(), \fBexeclp\fP(), \fBexecle\fP() の \fIconst char *arg\fP とそれに続く省略部分は +\fIarg0\fP, \fIarg1\fP, \&..., \fIargn\fP とみなされる。 これらには、実行されるプログラムで利用可能な引き数のリストを指定する +(引き数のリストは NULL で終端された文字列へのポインタから構成される)。 慣習として、最初の引き数は、実行されるファイル名 +へのポインタにする。引き数のリストは必ず NULL で終わらなければならず、これらの関数は可変長引き数関数なので、 このポインタは \fI(char *) +NULL\fP とキャストしなければならない。 +.PP +関数 \fBexecv\fP(), \fBexecvp\fP(), \fBexecvpe\fP() は、利用可能な引き数リスト (NULL で終端された文字列への +ポインタの配列) を新しいプログラムに渡す。 慣習として、最初の引き数は実行されるファイル名へ のポインタにする。ポインタの配列は必ず NULL +で終わらなければならない。 +.PP +関数 \fBexecle\fP(), \fBexecvpe\fP() では、呼び出し元が引き数 \fIenvp\fP +経由実行されるプログラムの環境を指定することができる。 \fIenvp\fP 引き数は、NULL で終端された文字列へのポインタの配列であり、 NULL +ポインタで終わらなければならない。 他の関数では、呼び出し元のプロセスの外部変数 \fBenviron\fP から新しいプロセス用の環境を与える。 +.SS "execlp() と execvp() の特別な動作" +.PP +関数 \fBexeclp\fP(), \fBexecvp\fP(), \fBexecvpe\fP() は、指定されたファイル名がスラッシュ (/) を含んでいない場合、 +シェルと同じ動作で実行可能なファイルを探索する。 ファイルの検索は、環境変数 \fBPATH\fP +で指定されたコロン区切りのディレクトリのパス名のリストを対象に行われる。 この変数が定義されていない場合、パス名のリストのデフォルト値として、 +カレントディレクトリの後ろに、 \fIconfstr(_CS_PATH)\fP が返すディレクトリのリストをつなげた値が使用される (この +\fBconfstr\fP(3) の呼び出しでは通常 "/bin:/usr/bin" が返される)。 + +指定されたファイル名がスラッシュを含む場合、 \fBPATH\fP は無視され、指定されたパス名のファイルが実行される。 + +さらに、いくつかのエラーは特別に処理される。 + +ファイルが実行ファイルでない場合 (このとき呼び出そうとした \fBexecve\fP(2) はエラー \fBEACCES\fP +で失敗する)、これらの関数は残りの検索パスの検索を続ける。 他にファイルが見つからなくなった場合 \fIerrno\fP に \fBEACCES\fP +を設定し復帰する。 + +ファイルのヘッダが実行形式として認識できない場合 (このとき呼び出そうとした \fBexecve\fP(2) はエラー \fBENOEXEC\fP +で失敗する)、これらの関数はそのファイルを最初の引き数としたシェル (\fI/bin/sh\fP) を実行する +(これにも失敗した場合、これ以上の検索は行われない)。 +.SH 返り値 +\fBexec\fP() 群の関数が復帰するのは、エラーが発生した場合のみである。 返り値は \-1 で、 \fIerrno\fP にエラーの内容がセットされる。 +.SH エラー +これら全ての関数は失敗する場合がある。その場合、 \fBexecve\fP(2) に対して規定されたエラーが \fIerrno\fP に設定される。 +.SH バージョン +\fBexecvpe\fP() 関数は glibc 2.11 で初めて登場した。 +.SH 準拠 +POSIX.1\-2001, POSIX.1\-2008. + +\fBexecvpe\fP() 関数は GNU による拡張である。 +.SH 注意 +Linux 以外のシステムには、 (環境変数 \fBPATH\fP が定義されていないときの) デフォルトのパスにおいて、カレント・ディレクトリが +\fI/bin\fP と \fI/usr/bin\fP の後ろに配置されるものもある。 これはトロイの木馬対策のためである。 Linux +では、デフォルトのパスに、昔ながらの「現在のディレクトリを 先に探索」というルールを使っている。 +.PP +ファイルを実行しようとしている間にエラーが発生した時の \fBexeclp\fP() と \fBexecvp\fP() +のふるまいについて歴史的な慣習はあるが、伝統的に文書として記載されておらず、 POSIX 標準でも規定されていない。BSD (またおそらく他のシステム) +では、 \fBETXTBSY\fP が発生した場合、自動的に中断 (sleep) し再試行を行う。 Linux +はそれをハードエラーとして取り扱い即座に復帰する。 +.PP +伝統的に、関数 \fBexeclp\fP() と \fBexecvp\fP() は、上で説明したエラーと、これら 2 つの関数自身が返す \fBENOMEM\fP と +\fBE2BIG\fP 以外の全てのエラーを無視していたが、 今では、上で説明した以外のエラーが発生した場合でも、 返ってくるよう変更された。 +.SH 関連項目 +\fBsh\fP(1), \fBexecve\fP(2), \fBfork\fP(2), \fBptrace\fP(2), \fBfexecve\fP(3), +\fBenviron\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man3/getutent.3 b/manual/LDP_man-pages/draft/man3/getutent.3 new file mode 100644 index 00000000..2d8608fb --- /dev/null +++ b/manual/LDP_man-pages/draft/man3/getutent.3 @@ -0,0 +1,216 @@ +.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Solaris manpages +.\" +.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt +.\" +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH GETUTENT 3 2008\-06\-29 "" "Linux Programmer's Manual" +.SH 名前 +getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- utmp +ファイルのエントリにアクセスする +.SH 書式 +\fB#include \fP +.sp +\fBstruct utmp *getutent(void);\fP +.br +\fBstruct utmp *getutid(struct utmp *\fP\fIut\fP\fB);\fP +.br +\fBstruct utmp *getutline(struct utmp *\fP\fIut\fP\fB);\fP +.sp +\fBstruct utmp *pututline(struct utmp *\fP\fIut\fP\fB);\fP +.sp +\fBvoid setutent(void);\fP +.br +\fBvoid endutent(void);\fP +.sp +\fBint utmpname(const char *\fP\fIfile\fP\fB);\fP +.SH 説明 +新しいアプリケーションでは、これらの関数の "utmpx" 版を使用すべきである。 これらは POSIX.1 で規定されている。「準拠」の節を参照。 + +\fButmpname\fP() は、他の utmp 関数がアクセスする (utmp フォーマットの) ファイルの名前を指定する。他の関数を使う前に +\fButmpname\fP() を使って ファイル名の指定を行わなかった場合は、 \fI\fP で 定義されている +\fB_PATH_UTMP\fP がファイル名とみなされる。 +.PP +\fBsetutent\fP() は、ファイルポインタを utmp ファイルの先頭に移動する。 +一般的には、他の関数を使う前にこの関数を呼び出しておくと良いだろう。 +.PP +\fBendutent\fP() は utmp ファイルをクローズする。ユーザーコードで +他の関数を使ってこのファイルにアクセスを行った時は、最後にこの関数を 呼び出すべきである。 +.PP +\fBgetutent\fP() は utmp ファイルの現在のファイル位置から一行読み込み、 行の各フィールドの内容を収めた構造体へのポインタを返す。 +この構造体の定義は \fButmp\fP(5) に書かれている。 +.PP +\fBgetutid\fP() は、 utmp ファイル中の現在の位置から順方向 (末尾に向かう方向) へ \fIut\fP に基く検索を行う。 +\fIut\fP\->ut_type が \fBRUN_LVL\fP, \fBBOOT_TIME\fP, \fBNEW_TIME\fP, \fBOLD_TIME\fP の +いずれかなら、 \fBgetutid\fP() は \fBut_type\fP フィールドが \fIut\fP\->ut_type +に一致する最初のエントリを探す。 \fIut\fP\->ut_type が \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, +\fBUSER_PROCESS\fP, \fBDEAD_PROCESS\fP のいずれかなら、 \fBgetutid\fP() は \fIut_id\fP フィールドが +\fIut\fP\->ut_id に 一致する最初のエントリを探す。 +.PP +\fBgetutline\fP() は、 utmp ファイルの現在の位置から末尾に向かって検索を行う。 \fIut_type\fP が +\fBUSER_PROCESS\fP または \fBLOGIN_PROCESS\fP で、 \fIut_line\fP フィールドが \fIut\fP\->ut_line +にマッチする最初の行を返す。 +.PP +\fBpututline\fP() は \fIutmp\fP 構造体 \fIut\fP の内容を utmp ファイルに書き出す。 \fBpututline\fP() は +\fBgetutid\fP() を用いて、新たなエントリを 挿入するのにふさわしい場所を探す。 \fIut\fP を挿入するふさわしい場所が +見つからない場合は、新たなエントリをファイルの末尾に追加する。 +.SH 返り値 +\fBgetutent\fP(), \fBgetutid\fP(), \fBgetutline\fP() は、成功すると \fIstruct utmp\fP +へのポインタを返す。 失敗すると NULL を返す (レコードが見つからなかった場合も失敗となる)。 この \fIstruct utmp\fP +は静的な記憶領域に確保され、次にこれらの関数を 呼び出した際に上書きされるかもしれない。 + +\fBpututline\fP() は成功すると \fIut\fP を返す。失敗すると NULL を返す。 + +\fButmpname\fP() は、新しい名前の格納に成功すると 0 を返し、失敗すると \-1 を返す。 +.SH エラー +.TP +\fBENOMEM\fP +メモリ不足。 +.TP +\fBESRCH\fP +レコードが見つからなかった。 +.PP +関数 \fBsetutent\fP(), \fBpututline\fP(), \fBgetut*\fP() は \fBopen\fP(2) +に書かれている理由でも失敗することがある。 +.SH ファイル +/var/run/utmp 現在ログイン中のユーザーのデータベース +.br +/var/log/wtmp 過去のユーザーログインのデータベース +.SH 準拠 +XPG2, SVr4. +.LP +XPG2 と SVID 2 では、 \fBpututline\fP() 関数は値を返さないとされており、 (AIX, HP\-UX, Linux libc5 +などの) 多くのシステムではそうなっている。 HP\-UX では、上述の \fBpututline\fP() と同じプロトタイプを持つ 新しい関数 +\fB_pututline\fP() が導入されている (この関数は Linux libc5 にもある)。 +.LP +現在では、Linux 以外のシステムでは、これらの関数は全て廃止されている。 SUSv1 の後に出てきた POSIX.1\-2001 +では、もはやこれらの関数はなく、 代わりに以下のものを使う。 +.sp +\fB#include \fP +.sp +\fBstruct utmpx *getutxent(void);\fP +.br +\fBstruct utmpx *getutxid(const struct utmpx *);\fP +.br +\fBstruct utmpx *getutxline(const struct utmpx *);\fP +.br +\fBstruct utmpx *pututxline(const struct utmpx *);\fP +.br +\fBvoid setutxent(void);\fP +.br +\fBvoid endutxent(void);\fP +.PP +これらの関数は glibc により提供されており、 "x" がない関数と同じ処理を行うが、 \fIstruct utmpx\fP を使用する。 Linux +では、この構造体の定義は \fIstruct utmp\fP と同じになっている。 完全を期すために、glibc では \fButmpxname\fP() +も提供している。この関数は POSIX.1 では規定されていない。 +.PP +Linux 以外のシステムでは、 \fIutmpx\fP 構造体は \fIutmp\fP 構造体の上位集合 (superset) になっていて、 +追加のフィールドがあったり、既存のフィールドのサイズが大きくなっていたり するものもある。複数のファイルが使用されている場合もあり、多くの場合 +\fI/var/*/utmpx\fP と \fI/var/*/wtmpx\fP というファイルが使われる。 +.LP +一方、 Linux glibc では複数の \fIutmpx\fP ファイル は使われていない。 +\fIutmp\fP 構造体が十分に大きいからである。 +上記の名前に "x" が付いた関数は "x" が付いていない対応する関数の別名と +なっている (例えば \fIgetutxent\fP() は \fIgetutent\fP() の別名である)。 +.SH 注意 +.SS "glibc での注意" +上記の関数群はスレッド・セーフではない。 glibc にはリエントラント版 (reentrant) が追加されている。 +.sp +.nf +\fB#define _GNU_SOURCE\fP /* or _SVID_SOURCE or _BSD_SOURCE; +\& \fBfeature_test_macros\fP(7) 参照 */ +\fB#include \fP +.sp +\fBint getutent_r(struct utmp *\fP\fIubuf\fP\fB, struct utmp **\fP\fIubufp\fP\fB);\fP +.sp +\fBint getutid_r(struct utmp *\fP\fIut\fP\fB,\fP +\fB struct utmp *\fP\fIubuf\fP\fB, struct utmp **\fP\fIubufp\fP\fB);\fP +.sp +\fBint getutline_r(struct utmp *\fP\fIut\fP\fB,\fP +\fB struct utmp *\fP\fIubuf\fP\fB, struct utmp **\fP\fIubufp\fP\fB);\fP +.fi +.sp +これらの関数は GNU での拡張であり、末尾の _r をとった名前の関数と 同様の機能を持つ。 \fIubuf\fP +パラメータは結果を格納する場所を指定する。 成功すると 0 を返し、結果へのポインタを \fI*ubufp\fP に書き込む。エラーの場合 \-1 を返す。 +上記の関数に対応する utmpx 版は存在しない (POSIX.1 ではこれらの関数を規定されていない)。 +.SH 例 +以下の例では、 utmp のレコードの追加・削除を行っている。このコードは、 擬似端末 (pseudo terminal) +から実行されることを想定している。 実際のアプリケーションでは \fBgetpwuid\fP(3) と \fBttyname\fP(3) +の戻り値を検査するべきである。 +.PP +.nf +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct utmp entry; + + system("echo before adding entry:;who"); + + entry.ut_type = USER_PROCESS; + entry.ut_pid = getpid(); + strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/")); + /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ + strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty")); + time(&entry.ut_time); + strcpy(entry.ut_user, getpwuid(getuid())\->pw_name); + memset(entry.ut_host, 0, UT_HOSTSIZE); + entry.ut_addr = 0; + setutent(); + pututline(&entry); + + system("echo after adding entry:;who"); + + entry.ut_type = DEAD_PROCESS; + memset(entry.ut_line, 0, UT_LINESIZE); + entry.ut_time = 0; + memset(entry.ut_user, 0, UT_NAMESIZE); + setutent(); + pututline(&entry); + + system("echo after removing entry:;who"); + + endutent(); + exit(EXIT_SUCCESS); +} +.fi +.SH 関連項目 +\fBgetutmp\fP(3), \fButmp\fP(5) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man3/login.3 b/manual/LDP_man-pages/draft/man3/login.3 new file mode 100644 index 00000000..65caa1b8 --- /dev/null +++ b/manual/LDP_man-pages/draft/man3/login.3 @@ -0,0 +1,78 @@ +.\" Derived from text written by Martin Schulze (or taken from glibc.info) +.\" and text written by Paul Thompson - both copyright 2002. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH LOGIN 3 2004\-05\-06 GNU "Linux Programmer's Manual" +.SH 名前 +login, logout \- utmp と wtmp エントリを書き込む +.SH 書式 +\fB#include \fP +.sp +\fBvoid login(const struct utmp *\fP\fIut\fP\fB);\fP +.sp +\fBint logout(const char *\fP\fIut_line\fP\fB);\fP +.sp +\fI\-lutil\fP でリンクする。 +.SH 説明 +utmp ファイルは現在システムを使用しているユーザを記録する。 wtmp ファイルはすべてのログインとログアウトを記録する。 \fButmp\fP(5) +を参照すること。 +.LP +関数 \fBlogin\fP() は与えられた \fIstruct utmp\fP \fIut\fP を utmp と wtmp ファイルの両方に書き込む。 +.LP +関数 \fBlogout\fP() は utmp ファイルにあるエントリをクリアする。 +.SS "GNU 版の詳細" +より正確には、 \fBlogin\fP() は引き数 \fIut\fP 構造体をとり、(もし存在するならば) フィールド \fIut\->ut_type\fP を +\fBUSER_PROCESS\fP という値にし、(もし存在するならば) フィールド \fIut\->ut_pid\fP を呼び出し元プロセスのプロセス +ID の値にする。 次にフィールド \fIut\->ut_line\fP の値を設定しようとする。 +この関数は、標準入力・標準出力・標準エラー出力の中から端末である最初のものをとり、対応するパス名から先頭の \fI/dev/\fP を引いたものを +このフィールドに格納して、この構造体を utmp ファイルに書き込む。 一方、端末名が見つからない場合は、このフィールドは "???" とされて、 +この構造体は utmp ファイルに書き込まれない。 その後にこの構造体は wtmp ファイルに書き込まれる。 +.LP +\fBlogout\fP() 関数は utmp ファイルから \fIut_line\fP 引き数にマッチするエントリを探す。 レコードが見つかった場合、 +\fIut_name\fP と \fIut_host\fP フィールドをクリアして、 \fIut_tv\fP タイムスタンプフィールドを更新し、 (もし存在するならば) +\fIut_type\fP フィールドを \fBDEAD_PROCESS\fP に更新する。 +.SH 返り値 +エントリをデータベースに書き込むのに成功した場合、 \fBlogout\fP() 関数は 1 を返す。 またエラーが起こった場合、0 を返す。 +.SH ファイル +.TP +\fI/var/run/utmp\fP +ユーザアカウントデータベース。 \fI\fP における \fB_PATH_UTMP\fP で設定されている。 +.TP +\fI/var/log/wtmp\fP +ユーザアカウントログファイル。 \fI\fP における \fB_PATH_WTMP\fP で設定されている。 +.SH 準拠 +POSIX.1\-2001 にはない。 BSD 系に存在する。 +.SH 注意 +\fIstruct utmp\fP のメンバ \fIut_user\fP は、BSD では \fIut_name\fP という名前である点に注意すること。 そのため +\fIut_name\fP は \fI\fP において \fIut_user\fP のエイリアスとして定義されている。 +.SH 関連項目 +\fBgetutent\fP(3), \fButmp\fP(5) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man3/readdir.3 b/manual/LDP_man-pages/draft/man3/readdir.3 new file mode 100644 index 00000000..10246ce4 --- /dev/null +++ b/manual/LDP_man-pages/draft/man3/readdir.3 @@ -0,0 +1,175 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper , mtk: +.\" Rework discussion of nonstandard structure fields. +.\" 2008-09-11, mtk, Document readdir_r(). +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH READDIR 3 2012\-07\-07 "" "Linux Programmer's Manual" +.SH 名前 +readdir, readdir_r \- ディレクトリを読み込む +.SH 書式 +.nf +\fB#include \fP +.sp +\fBstruct dirent *readdir(DIR *\fP\fIdirp\fP\fB);\fP +.sp +\fBint readdir_r(DIR *\fP\fIdirp\fP\fB, struct dirent *\fP\fIentry\fP\fB, struct dirent **\fP\fIresult\fP\fB);\fP +.fi +.sp +.in -4n +glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照): +.ad l +.in +.sp +\fBreaddir_r\fP(): +.RS 4 +_POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE +|| _POSIX_SOURCE +.RE +.ad b +.SH 説明 +\fBreaddir\fP() 関数は、\fIdirp\fP が指すディレクトリストリームの中で、 次のディレクトリエントリを表す \fIdirent\fP +構造体へのポインタを返す。 ディレクトリストリームの末尾に達した場合や、 エラーが発生した場合は、 NULL を返す。 +.PP +Linux では \fIdirent\fP 構造体は以下のように定義されている。 +.PP +.in +4n +.nf +struct dirent { + ino_t d_ino; /* inode 番号 */ + off_t d_off; /* 次の dirent へのオフセット */ + unsigned short d_reclen; /* このレコードの長さ */ + unsigned char d_type; /* ファイル種別。全ファイルシステム */ + でサポートされているわけではない */ + char d_name[256]; /* ファイル名 */ +}; +.fi +.in +.PP +\fIdirent\fP 構造体のフィールドで POSIX.1 で要求されているのは、 \fId_name\fP[] と (XSI 拡張での) \fId_ino\fP +だけである。 \fId_name\fP[] はその大きさも規定されておらず、 このフィールドには最大で \fBNAME_MAX\fP 個の文字と、それに続く終端の +NULL バイトが格納される。 他のフィールドは非標準であり、全てのシステムに存在するわけではない。 詳細については、下記の「注意」を参照のこと。 +.PP +\fBreaddir\fP() によって返されるデータは、それ以降の同じストリームに対する \fBreaddir\fP() +の呼び出しによって上書きされる可能性がある。 + +\fBreaddir_r\fP() 関数は \fBreaddir\fP() のリエントラント版である。 この関数はディレクトリストリーム \fIdirp\fP +から次のディレクトリエントリを読み込み、 \fIentry\fP が指す呼び出し元が割り当てたバッファにそのエントリを格納して返す +(このバッファの割り当てについては「注意」の節を参照のこと)。 返されるエントリへのポインタが \fI*result\fP +に格納される。ディレクトリストリームの末尾に達した場合は、 NULL が \fI*result\fP に格納される。 +.SH 返り値 +成功すると、 \fBreaddir\fP() は \fIdirent\fP 構造体へのポインタを返す。 (この構造体は静的に割り当てられているかもしれない。 +このポインタを \fBfree\fP(3) しようとしないこと。) ディレクトリストリームの末尾に達した場合には、NULL が返され、 \fIerrno\fP +は変化しない。 エラーが発生した場合、NULL が返され、 \fIerrno\fP が適切に設定される。 + +成功すると、 \fBreaddir_r\fP() 関数は 0 を返す。 エラーの場合、(「エラー」の節のリストに載っている) 正のエラー番号を返す。 +ディレクトリストリームの末尾に達した場合、 \fBreaddir_r\fP() は返り値として 0 を返し、 \fI*result\fP に NULL +を格納する。 +.SH エラー +.TP +\fBEBADF\fP +ディレクトリストリームディスクリプタ \fIdirp\fP が無効である。 +.SH 準拠 +SVr4, 4.3BSD, POSIX.1\-2001. +.SH 注意 +フィールド \fId_name\fP と \fId_ino\fP だけが POSIX.1\-2001 で規定されている。 +残りのフィールドは多くのシステムに存在するが、全てのシステムに 存在するわけではない。 glibc では、プログラムが POSIX.1 +で定義されていないフィールドが 利用できるかをチェックすることができる。 チェックするには、マクロ \fB_DIRENT_HAVE_D_NAMLEN\fP, +\fB_DIRENT_HAVE_D_RECLEN\fP, \fB_DIRENT_HAVE_D_OFF\fP, \fB_DIRENT_HAVE_D_TYPE\fP +が定義されているかをテストすればよい。 + +\fId_type\fP フィールドは、Linux 以外では、 主に BSD 系のシステムにだけ存在する。 このフィールドを使うと、 +その後の動作がファイルの種別により決まる場合に、 \fBlstat\fP(2) を呼び出すコストを避けることができる。 機能検査マクロ +\fB_BSD_SOURCE\fP が定義された場合、glibc は \fId_type\fP で返される値として以下のマクロ定数を定義する。 +.TP 12 +\fBDT_BLK\fP +ブロックデバイスである。 +.TP +\fBDT_CHR\fP +キャラクタデバイスである。 +.TP +\fBDT_DIR\fP +ディレクトリである。 +.TP +\fBDT_FIFO\fP +名前付きパイプ (FIFO) である。 +.TP +\fBDT_LNK\fP +シンボリックリンクである。 +.TP +\fBDT_REG\fP +通常のファイルである。 +.TP +\fBDT_SOCK\fP +UNIX ドメインソケットである。 +.TP +\fBDT_UNKNOWN\fP +.\" The glibc manual says that on some systems this is the only +.\" value returned +ファイルタイプが不明である。 +.PP +ファイル種別を決定できなかった場合には、 \fId_type\fP に \fBDT_UNKNOWN\fP が入る。 + +.\" kernel 2.6.27 +.\" The same sentence is in getdents.2 +現在のところ、 \fId_type\fP でファイルタイプを返す機能が完全にサポートされているのは、 いくつかのファイルシステムにおいてのみである +(Btrfs, ext2, ext3, ext4 はサポートしている)。 どのアプリケーションも、 \fBDT_UNKNOWN\fP +が返された際に適切に処理できなければならない。 + +POSIX.1 では \fId_name\fP フィールドのサイズは規定されておらず、 \fIdirent\fP 構造体の \fId_name\fP +の後ろに他の非標準のフィールドがあるかもしれないので、 移植性が必要なアプリケーションで \fBreaddir_r\fP() を使う場合は \fIentry\fP +に渡すバッファを次のようにして割り当てるべきである。 +.in +4n +.nf + +name_max = pathconf(dirpath, _PC_NAME_MAX); +if (name_max == \-1) /* 上限が定義されていない、またはエラー */ + name_max = 255; /* 適当な値を入れる */ +len = offsetof(struct dirent, d_name) + name_max + 1; +entryp = malloc(len); + +.fi +.in +(POSIX.1 では \fIstruct dirent\fP の最後のフィールドが \fId_name\fP であることを要求している。) +.SH 関連項目 +\fBgetdents\fP(2), \fBread\fP(2), \fBclosedir\fP(3), \fBdirfd\fP(3), \fBftw\fP(3), +\fBoffsetof\fP(3), \fBopendir\fP(3), \fBrewinddir\fP(3), \fBscandir\fP(3), +\fBseekdir\fP(3), \fBtelldir\fP(3) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man5/shells.5 b/manual/LDP_man-pages/draft/man5/shells.5 new file mode 100644 index 00000000..93a51318 --- /dev/null +++ b/manual/LDP_man-pages/draft/man5/shells.5 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Thu May 20 20:45:48 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt +.\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu) +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH SHELLS 5 2012\-12\-31 "" "Linux Programmer's Manual" +.SH 名前 +shells \- ログインシェルとして有効なファイルのパス名 +.SH 説明 +\fI/etc/shells\fP はログインシェルとして有効なファイルのフルパスが書かれた テキストファイルである。 \fBchsh\fP(1) +はこのファイルを参照する。 他のプログラムもこのファイルを参照できる。 +.PP +注意して欲しいのだが、プログラムによっては、 ユーザーが通常のユーザーかどうかを判断する際に、このファイルの内容を参考にすることがある。例えば FTP +デーモンは、ログインシェルがこのファイルに書かれていないユーザーからのアクセスを許さないのが以前から一般的である。 +.SH ファイル +\fI/etc/shells\fP +.SH 例 +\fI/etc/shells\fP には以下のようなパスが含まれているだろう。 +.sp +.RS +\fI/bin/sh\fP +.br +\fI/bin/bash\fP +.br +\fI/bin/csh\fP +.RE +.SH 関連項目 +\fBchsh\fP(1), \fBgetusershell\fP(3) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man5/utmp.5 b/manual/LDP_man-pages/draft/man5/utmp.5 new file mode 100644 index 00000000..8e3e49d6 --- /dev/null +++ b/manual/LDP_man-pages/draft/man5/utmp.5 @@ -0,0 +1,233 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-02-26 by Michael Haardt +.\" Modified 1996-07-20 by Michael Haardt +.\" Modified 1997-07-02 by Nicolás Lichtmaier +.\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH UTMP 5 2013\-02\-11 Linux "Linux Programmer's Manual" +.SH 名前 +utmp, wtmp \- ログイン記録 +.SH 書式 +\fB#include \fP +.SH 説明 +\fIutmp\fP ファイルを見ることで、現在誰がシステムを使っているかという情報 が得られる。ただすべてのプログラムが utmp ファイルを +更新しているわけではないので、実際にはそれ以上のユーザーが システムを使っている可能性がある。 +.PP +\fB警告:\fP (愚かにも) 多くのシステムプログラムがその整合性に依存しているので、 \fIutmp\fP ファイルは "other" +に分類されるユーザに対して 書き込み可能にしてはならない。 ファイルの所有者とグループオーナー以外のユーザに対して \fIutmp\fP +ファイルを書き込み可能な状態にしておくと、 システムのログファイルを偽造されたり、システムファイルの 改ざんを受けるといったリスクを犯すことになる。 +.PP +このファイルは \fIutmp\fP 構造体の繰り返しで構成される。 この構造体は \fI\fP で以下のように定義されている +(ここに記述してあるのは幾つかの大まかな定義のみで、 詳細は libc のバージョンにより変わることに注意が必要である)。 +.in +4n +.nf +.sp +/* Values for ut_type field, below */ + +#define EMPTY 0 /* Record does not contain valid info + (formerly known as UT_UNKNOWN on Linux) */ +#define RUN_LVL 1 /* Change in system run\-level (see + \fBinit\fP(8)) */ +#define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */ +#define NEW_TIME 3 /* Time after system clock change + (in \fIut_tv\fP) */ +#define OLD_TIME 4 /* Time before system clock change + (in \fIut_tv\fP) */ +#define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(8) */ +#define LOGIN_PROCESS 6 /* Session leader process for user login */ +#define USER_PROCESS 7 /* Normal process */ +#define DEAD_PROCESS 8 /* Terminated process */ +#define ACCOUNTING 9 /* Not implemented */ + +#define UT_LINESIZE 32 +#define UT_NAMESIZE 32 +#define UT_HOSTSIZE 256 + +struct exit_status { /* Type for ut_exit, below */ + short int e_termination; /* Process termination status */ + short int e_exit; /* Process exit status */ +}; + +struct utmp { + short ut_type; /* Type of record */ + pid_t ut_pid; /* PID of login process */ + char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */ + char ut_id[4]; /* Terminal name suffix, + or inittab(5) ID */ + char ut_user[UT_NAMESIZE]; /* Username */ + char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or + kernel version for run\-level + messages */ + struct exit_status ut_exit; /* Exit status of a process + marked as DEAD_PROCESS; not + used by Linux init(8) */ + /* ut_session と ut_tv フィールドは、32ビットでコンパイルされた場合と + 64ビットでコンパイルされた場合で同じサイズでなければならない。 + こうすることで、32ビットと64ビットのアプリケーションで、 + データファイルと共有メモリを共有することができるようになる。 */ +#if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32 + int32_t ut_session; /* Session ID (\fBgetsid\fP(2)), + used for windowing */ + struct { + int32_t tv_sec; /* Seconds */ + int32_t tv_usec; /* Microseconds */ + } ut_tv; /* Time entry was made */ +#else + long ut_session; /* Session ID */ + struct timeval ut_tv; /* Time entry was made */ +#endif + + int32_t ut_addr_v6[4]; /* Internet address of remote + host; IPv4 address uses + just ut_addr_v6[0] */ + char __unused[20]; /* Reserved for future use */ +}; + +/* Backward compatibility hacks */ +#define ut_name ut_user +#ifndef _NO_UT_TIME +#define ut_time ut_tv.tv_sec +#endif +#define ut_xtime ut_tv.tv_sec +#define ut_addr ut_addr_v6[0] +.sp +.fi +.in +この構造体からユーザーの使っている端末のスペシャルファイル名、 ユーザーのログイン名、 (\fBtime\fP(2) +形式での)ログイン時刻がわかる。文字列フィールドは、 フィールドの長さより文字列が短い場合には、 NULL バイト (\(aq\e0\(aq) +によって終端される。 +.PP +最初のエントリは \fBinit\fP(8) コマンドが \fBinittab\fP(5) を処理することで作られる。 あるエントリを処理する前に、 +\fBinit\fP(8) は \fIut_type\fP を \fBDEAD_PROCESS\fP に初期化する。 レコードの \fIut_type\fP が +\fBDEAD_PROCESS\fP と \fBRUN_LVL\fP のいずれでもなく、 かつ PID が \fIut_pid\fP +であるプロセスがいない場合は、\fIut_user\fP, \fIut_host\fP, \fIut_time\fP をヌルバイトでクリアして初期化を行う。 必要な +\fIut_id\fP を持つ空のレコードを見つけられなかった場合、 \fBinit\fP(8) は新しいレコードを作る。inittab から \fIut_id\fP +を設定し、 \fIut_pid\fP および \fIut_time\fP を現在値に、 \fIut_type\fP を \fBINIT_PROCESS\fP に設定する。 +.PP +\fBmingetty\fP(8) (または \fBagetty\fP(8)) は pid でエントリを特定し、 \fIut_type\fP を +\fBLOGIN_PROCESS\fP に変更し、 \fIut_time\fP を更新し、\fIut_line\fPを設定した後、接続が確立されるのを待つ。 +\fBlogin\fP(1) はユーザー認証が終了すると、 \fIut_type\fP を \fBUSER_PROCESS\fP に変更し、 \fIut_time\fP +を更新し、\fIut_host\fP と \fIut_addr\fPを設定する。 \fBmingetty\fP(8) (または \fBagetty\fP(8)) と +\fBlogin\fP(1) により異なるが、 \fIut_pid\fP の代わりに \fIut_line\fP を使ってレコードの特定が行われることもある +(\fIut_pid\fP を使う方が望ましい) 。 +.PP +\fBinit\fP(8) はプロセスの終了を検出した場合、 \fIut_pid\fP をキーとして utmp のエントリを特定し、 \fIut_type\fP を +\fBDEAD_PROCESS\fP に設定し、 \fIut_user\fP, \fIut_host\fP, \fIut_time\fP をヌルバイトでクリアする。 +.PP +\fBxterm\fP(1) コマンドや他の端末エミュレータは 直接 \fBUSER_PROCESS\fP のレコードを作り、 端末名のサフィックス文字列 +(\fI/dev/[pt]ty\fP に続く文字列) を使って \fIut_id\fP の値を生成する。 この id を持つエントリが +\fBDEAD_PROCESS\fP であった場合には再利用し、 それ以外の場合には新しいエントリが作られる。 可能な場合にはプロセス終了時に +\fBDEAD_PROCESS\fP と設定し、 さらに \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, \fIut_host\fP +をヌルバイトでクリアすることが奨励されている。 +.PP +\fBtelnetd\fP(8) は \fBLOGIN_PROCESS\fP を設定するだけでよく、 残りの処理は通常通り \fBlogin\fP(1) +に任せればよい。 telnet のセッションが終了した後、前述のように \fBtelnetd\fP(8) が utmp のエントリを初期化する。 +.PP +\fIwtmp\fP ファイルには、すべてのログインとログアウトが記録される。 そのフォーマットは、ログアウト済の端末でユーザー名がヌルとなること以外は +\fIutmp\fP とまったく同じである。 ユーザー名が \fBshutdown\fP もしくは \fBreboot\fP である 端末名 \fB~\fP はシステムの停止 +(shutdown) または再起動 (reboot) を意味する。またその端末名が \fB|\fP と \fB}\fP の対は \fBdate\fP(1) +コマンドで変更した新／旧のシステム時刻を記録している。 \fIwtmp\fP ファイルは \fBlogin\fP(1), \fBinit\fP(8) +やいくつかのバージョンの \fBgetty\fP(8) (\fBmingetty\fP(8) または \fBagetty\fP(8)) により管理されている。 +これらのプログラムはどれもファイルを新たに作成しないので、 ファイルを削除することで情報の記録 (record\-keeping) を止めることができる。 +.SH ファイル +/var/run/utmp +.br +/var/log/wtmp +.SH 準拠 +.PP +POSIX.1 では、 \fIutmp\fP 構造体ではなく、 \fIutmpx\fP 構造体を規定している。 \fIutmpx\fP +構造体で規定されているのは、フィールド \fIut_type\fP, \fIut_pid\fP, \fIut_line\fP, \fIut_id\fP, \fIut_user\fP, +\fIut_tv\fP である。 POSIX.1 では、フィールド \fIut_line\fP と \fIut_user\fP の長さは規定されていない。 + +Linux では、 \fIutmpx\fP 構造体の定義は \fIutmp\fP 構造体と同じである。 +.SS 過去のシステムとの比較 +Linux での utmp のエントリは v7/BSD や System V のいずれにも準拠しておらず、 その両方が混在したものである。 + +v7/BSD ではより少しの項目しかない; もっとも重要なことは、\fIut_type\fP が無いことである。 そのため v7/BSD 系のプログラムでは +(たとえば) 死んだ状態のエントリや ログイン状態のエントリまで表示されてしまうことになった。 +さらにセッション用のスロットを割り当てるための設定ファイルがない。 BSD に設定ファイルがあるのは \fIut_id\fP がないからである。 + +Linux (System V 系)では、設定ファイルを必要とせず セッション用のスロットを割り当てるので、一旦設定 されてしまうとレコードの +\fIut_id\fP は決して変更されない。 \fIut_id\fP をクリアすると競合状態におちいり、 utmp +のエントリを壊したり、潜在的なセキュリティホールになる可能性がある。 上述のフィールドを NULL バイトで埋めてクリアしておくのは、 System V +での取り決めでは必要とはされていないが、 BSD での取り決めを前提としていて、かつ utmp を更新しない多くのプログラムが +動作するようにするためである。 Linux ではここまで記述してきたように、行内容の表示は BSD の慣例に従っている。 +.PP +.\" mtk: What is the referrent of "them" in the following sentence? +.\" System V only uses the type field to mark them and logs +.\" informative messages such as \fB"new time"\fP in the line field. +\fBUT_UNKNOWN\fP は Linux で作られたもののようである。 System V には \fIut_host\fP も \fIut_addr_v6\fP +も存在しない。 +.SH 注意 +.PP +ファイルを削除することで utmp への記録を止められる 他の様々なシステムとは違い、Linux では utmp ファイルを必ずおいて おく必要がある。 +\fBwho\fP(1) コマンドが機能しないようにしたい場合には、 utmp ファイルの全ユーザーに対する読み取り許可を設定しないようにする。 +.PP +ファイルのフォーマットはマシンに依存するので、ファイルが作られた マシンもしくは同一アーキテクチャのマシン上でのみ処理することを推奨する。 +.PP +注意すべき点としては、 \fIbiarch\fP なプラットフォーム、つまり 32ビットと 64ビットの両方の アプリケーションを実行できるシステム +(x86\-64, ppc64, s390x など) では、 \fIut_tv\fP のサイズは 32ビットモードと 64ビットモードで同じである。 +\fIut_session\fP と \fIut_time\fP も、存在する場合には同様に同じサイズ である。これにより、32ビットアプリケーションと +64ビットアプリケーション の間でデータファイルと共有メモリを共有することが可能になる。 そのためには、 \fIut_session\fP を +\fIint32_t\fP 型に、 \fIut_tv\fP を 2つの \fIint32_t\fP 型のフィールド \fItv_sec\fP, \fItv_usec\fP +を持つ構造体に変更すればよい \fIut_tv\fP は \fIstruct timeval\fP と同じサイズとは限らないので、 +.in +4n +.nf +.sp +gettimeofday((struct timeval *) &ut.ut_tv, NULL); +.fi +.in + +のような呼び出しをするのではなく、 以下のように各フィールドを設定する方法が推奨される: +.in +4n +.nf +.sp +struct utmp ut; +struct timeval tv; + +gettimeofday(&tv, NULL); +ut.ut_tv.tv_sec = tv.tv_sec; +ut.ut_tv.tv_usec = tv.tv_usec; +.fi +.in +.PP +utmp 構造体は libc5 から libc6 で変更された。そのため昔の libc5 の構造体 を使ったプログラムは +\fI/var/run/utmp\fP や \fI/var/log/wtmp\fP ファイルを壊してしまう。 +.SH バグ +この man ページは libc5 に基づいて作られていて、 最新のものでは違っているかもしれない。 +.SH 関連項目 +\fBac\fP(1), \fBdate\fP(1), \fBlast\fP(1), \fBlogin\fP(1), \fButmpdump\fP(1), \fBwho\fP(1), +\fBgetutent\fP(3), \fBgetutmp\fP(3), \fBlogin\fP(3), \fBlogout\fP(3), \fBlogwtmp\fP(3), +\fBupdwtmp\fP(3), \fBinit\fP(8) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man7/epoll.7 b/manual/LDP_man-pages/draft/man7/epoll.7 new file mode 100644 index 00000000..bebca990 --- /dev/null +++ b/manual/LDP_man-pages/draft/man7/epoll.7 @@ -0,0 +1,313 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Davide Libenzi +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH EPOLL 7 2012\-04\-17 Linux "Linux Programmer's Manual" +.SH 名前 +epoll \- I/O イベント通知機能 +.SH 書式 +\fB#include \fP +.SH 説明 +\fBepoll\fP API は \fBpoll\fP(2) と同様の処理を行う、つまり、複数のファイルディスク +リプタを監視し、その中のいずれかが入出力可能な状態であるかを確認する。 +\fBepoll\fP API は、エッジトリガインタフェースとレベルトリガインタフェースの +いずれとしても使用することができ、監視するファイルディスクリプタの数が多い +場合にも使用できる。 \fBepoll\fP インスタンスの作成や管理を行うために +以下のシステムコールが提供されている: +.IP * 3 +\fBepoll_create\fP(2) は \fBepoll\fP インスタンスを作成し、そのインスタンスを参照する +ファイルディスクリプタを返す。(もっと新しい \fBepoll_create1\fP(2) では、 +\fBepoll_create\fP(2) の機能が拡張されている)。 +.IP * +特定のファイルディスクリプタに対する監視内容を \fBepoll_ctl\fP(2) で登録する。 \fBepoll\fP +インスタンスに現在登録されているファイルディスクリプタの集合は \fIepoll\fP 集合と呼ばれることもある。 +.IP * +\fBepoll_wait\fP(2) は I/O イベントを待つ。 +現在利用可能な状態のイベントがなければ、呼び出したスレッドを停止する。 +.SS レベルトリガとエッジトリガ +\fBepoll\fP イベント配送 (distribution) インタフェースは、 エッジトリガ (ET) としてもレベルトリガ (LT) +としても動作させることができる。 二つの配送機構の違いは、次のように説明できる。 このようなシナリオが起こったとしよう: +.IP 1. 3 +パイプの読み込み側を表すファイルディスクリプタ (\fIrfd\fP) が \fBepoll\fP インスタンスに登録される。 +.IP 2. +パイプへ書き込むプログラムが 2 kB のデータをパイプの書き込み側へ書き込む。 +.IP 3. +\fBepoll_wait\fP(2) を呼び出すと、読み込み可能 (ready) なファイルディスクリプタとして \fIrfd\fP が返る。 +.IP 4. +パイプから読み出すプログラムが、1 kB のデータを \fIrfd\fP から読み出す。 +.IP 5. +\fBepoll_wait\fP(2) の呼び出しが行われる。 +.PP +\fIrfd\fP ファイルディスクリプタが \fBEPOLLET\fP フラグ (エッジトリガ) を使って \fBepoll\fP に追加されていると、 +利用可能なデータがファイル入力バッファにまだ存在するにもかかわらず ステップ \fB5\fP の \fBepoll_wait\fP(2) +の呼び出しでハングする可能性がある。 その一方で、リモートの接続先 (peer) は既に送られたデータに 基づいて応答を期待しているかもしれない。 +このようなことが起こる理由は、エッジトリガイベント配送では、 モニタしているファイルでイベントが起ったときにのみイベントが 配送されるためである。 +したがって、ステップ \fB5\fP では、呼び出し側は結果的に 入力バッファ内にすで存在するデータを待つことになるかもしれない。 上記の例では、 \fB2\fP +で行われた書き込みによって \fIrfd\fP に関するイベントが生成され、 \fB3\fP でイベントが消費 (consume) される。 \fB4\fP +で行われる読み込み操作では、全部のバッファデータを消費しないので、 ステップ \fB5\fP で行われる \fBepoll_wait\fP(2) の呼び出しが +無期限に停止 (block) するかもしれない。 + +\fBEPOLLET\fP フラグを採用するアプリケーションでは、 インタフェースはブロックしない (nonblocking) ファイルディスクリプタを +使うべきである。 これは、ブロックされる読み込みや書き込みによって、 複数のファイルディスクリプタを扱うタスクが 停止してしまうのを避けるためである。 +\fBepoll\fP をエッジトリガ (\fBEPOLLET\fP) インタフェースとして使うために提案される方法は以下の通りである。 +.RS +.TP 4 +\fBi\fP +ブロックしないファイルディスクリプタと共に使う。 +.TP +\fBii\fP +\fBread\fP(2) または \fBwrite\fP(2) が \fBEAGAIN\fP を返した後でのみ、イベントを待つ。 +.RE +.PP +一方、レベルトリガインタフェースとして使う場合 + (こちらがデフォルトである、 +\fBEPOLLET\fP が指定されなかった場合)、 +\fBepoll\fP は単に高速な \fBpoll\fP(2) であり、使い方が同じなので、 +\fBpoll\fP(2) が使われているところではどこでも使用することができる。 + +エッジトリガを使った場合でも、複数のデータを受信すると複数の \fBepoll\fP イベントが生成されるので、 呼び出し側には +\fBEPOLLONESHOT\fP フラグを指定するオプションがある。 このフラグは \fBepoll\fP に対して、 \fBepoll_wait\fP(2) +によるイベントを受信した後で、関連するファイルディスクリプタを無効にさせる。 \fBEPOLLONESHOT\fP フラグが指定された場合、 +\fBepoll_ctl\fP(2) に \fBEPOLL_CTL_MOD\fP を指定してファイルディスクリプタを再度使用できるようにするのは、 +呼び出し側の責任である。 +.SS "/proc インタフェース" +.\" Following was added in 2.6.28, but them removed in 2.6.29 +.\" .TP +.\" .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)" +.\" This specifies an upper limit on the number of epoll instances +.\" that can be created per real user ID. +epoll が消費するカーネルメモリの量を制限するために、 以下のインタフェースを使用することができる。 +.TP +\fI/proc/sys/fs/epoll/max_user_watches\fP (Linux 2.6.28 以降) +.\" 2.6.29 (in 2.6.28, the default was 1/32 of lowmem) +このファイルは、あるユーザがシステム上の全ての epoll インスタンスに 登録できるファイルディスクリプタの総数の上限を規定する。 この上限は実ユーザ +ID 単位である。 登録されたファイルディスクリプタ 1 つが消費するメモリ量は、 32 ビットカーネルでおよそ 90 バイト、 64 +ビットカーネルでおよそ 160 バイトである。 現在のところ、 \fImax_user_watches\fP のデフォルト値は、利用可能なメモリ下限の +1/25 (4%) であり、 登録で消費されるメモリ量 (バイト単位) で割った値となる。 +.SS おすすめな使用例 +レベルトリガインタフェースとして使用するときの \fBepoll\fP の使い方は \fBpoll\fP(2) と同じである。 +しかしエッジトリガとして使う場合は、 アプリケーションのイベントループでストール (stall) しないように、 使い方をより明確にしておく必要がある。 +この例では、リスナはブロックしないソケットであり、 \fBlisten\fP(2) が呼ばれている。 関数 \fIdo_use_fd()\fP は、 +\fBread\fP(2) または \fBwrite\fP(2) によって \fBEAGAIN\fP が返されるまでは、新しい準備済みのファイルディスクリプタを使う。 +イベント駆動ステートマシンアプリケーションは、 \fBEAGAIN\fP を受信した後、カレントの状態を記録しておくべきである。 これにより、次の +\fIdo_use_fd()\fP 呼び出しのときに、以前に停止したところから \fBread\fP(2) または \fBwrite\fP(2) +を継続することができる。 + +.in +4n +.nf +#define MAX_EVENTS 10 +struct epoll_event ev, events[MAX_EVENTS]; +int listen_sock, conn_sock, nfds, epollfd; + +/* Set up listening socket, \(aqlisten_sock\(aq (socket(), + bind(), listen()) */ + +epollfd = epoll_create(10); +if (epollfd == \-1) { + perror("epoll_create"); + exit(EXIT_FAILURE); +} + +ev.events = EPOLLIN; +ev.data.fd = listen_sock; +if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == \-1) { + perror("epoll_ctl: listen_sock"); + exit(EXIT_FAILURE); +} + +for (;;) { + nfds = epoll_wait(epollfd, events, MAX_EVENTS, \-1); + if (nfds == \-1) { + perror("epoll_pwait"); + exit(EXIT_FAILURE); + } + + for (n = 0; n < nfds; ++n) { + if (events[n].data.fd == listen_sock) { + conn_sock = accept(listen_sock, + (struct sockaddr *) &local, &addrlen); + if (conn_sock == \-1) { + perror("accept"); + exit(EXIT_FAILURE); + } + setnonblocking(conn_sock); + ev.events = EPOLLIN | EPOLLET; + ev.data.fd = conn_sock; + if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock, + &ev) == \-1) { + perror("epoll_ctl: conn_sock"); + exit(EXIT_FAILURE); + } + } else { + do_use_fd(events[n].data.fd); + } + } +} +.fi +.in + +エッジトリガインタフェースとして使う場合、性能上の理由により、 一度 (\fBEPOLLIN\fP|\fBEPOLLOUT\fP) を指定してから +(\fBEPOLL_CTL_ADD\fP で) ファイルディスクリプタを \fBepoll\fP インタフェースに追加することができる。 これにより、 +\fBepoll_ctl\fP(2) に \fBEPOLL_CTL_MOD\fP を指定して呼び出すことで \fBEPOLLIN\fP と \fBEPOLLOUT\fP +の連続的な切り替えが避けられる。 +.SS 質問と解答 +.TP 4 +\fBQ0\fP +\fBepoll\fP 集合内の登録されたファイルディスクリプタを区別するには、 何をキーとして使えばよいか？ +.TP +\fBA0\fP +キーはファイルディスクリプタ番号とオープンファイル記述 (open file description) の組である (オープンファイル記述は "open +file handle" とも 呼ばれ、オープンされたファイルのカーネルの内部表現である)。 +.TP +\fBQ1\fP +1 つの \fBepoll\fP インスタンスに同じファイルディスクリプタを 2 回登録するとどうなるか？ +.TP +\fBA1\fP +.\" But a descriptor duplicated by fork(2) can't be added to the +.\" set, because the [file *, fd] pair is already in the epoll set. +.\" That is a somewhat ugly inconsistency. On the one hand, a child process +.\" cannot add the duplicate file descriptor to the epoll set. (In every +.\" other case that I can think of, descriptors duplicated by fork have +.\" similar semantics to descriptors duplicated by dup() and friends.) On +.\" the other hand, the very fact that the child has a duplicate of the +.\" descriptor means that even if the parent closes its descriptor, then +.\" epoll_wait() in the parent will continue to receive notifications for +.\" that descriptor because of the duplicated descriptor in the child. +.\" +.\" See http://thread.gmane.org/gmane.linux.kernel/596462/ +.\" "epoll design problems with common fork/exec patterns" +.\" +.\" mtk, Feb 2008 +たぶん \fBEEXIST\fP を受け取るだろう。 しかしながら、同じ \fBepoll\fP +インスタンスに対して複製されたディスクリプタを追加することは可能である (\fBdup\fP(2), \fBdup2\fP(2), \fBfcntl\fP(2) +\fBF_DUPFD\fP など)。 複製したファイルディスクリプタを異なる \fIevents\fP マスクで登録すれば、イベントをフィルタリングするのに +この機能は有用な手法である。 +.TP +\fBQ2\fP +2 つの \fBepoll\fP インスタンスが同じファイルディスクリプタを待ち受けることは可能か？ もし可能であれば、イベントは両方の \fBepoll\fP +ファイルディスクリプタに報告されるか？ +.TP +\fBA2\fP +イベントは両方に報告される。 しかしながら、これを正しく扱うには注意深くプログラミングする必要が あるかもしれない。 +.TP +\fBQ3\fP +\fBepoll\fP ファイルディスクリプタ自身は poll/epoll/select が可能か？ +.TP +\fBA3\fP +可能である。 \fBepoll\fP ファイルディスクリプタに処理待ちのイベントがある場合は、 読み出し可能だと通知されることだろう。 +.TP +\fBQ4\fP +\fBepoll\fP ファイルディスクリプタを自身のファイルディスクリプタ集合に 入れようとするとどうなるか？ +.TP +\fBA4\fP +\fBepoll_ctl\fP(2) の呼び出しは (\fBEINVAL\fP で) 失敗するだろう。 ただし \fBepoll\fP ファイルディスクリプタを他の +\fBepoll\fP ファイルディスクリプタ集合の内部に追加することは可能である。 +.TP +\fBQ5\fP +\fBepoll\fP ファイルディスクリプタを UNIX ドメインソケットで他のプロセスに送ることは可能か？ +.TP +\fBA5\fP +可能だが、これをすることに意味はない。 なぜなら、受信側のプロセスが \fBepoll\fP 集合内のファイルディスクリプタのコピーを持っていないからである。 +.TP +\fBQ6\fP +ファイルディスクリプタをクローズすると、そのファイルディスクリプタは全ての \fBepoll\fP 集合から自動的に削除されるか？ +.TP +\fBA6\fP +削除されるが、以下の点に注意が必要である。 ファイルディスクリプタはオープンファイル記述 (\fBopen\fP(2) 参照) への参照である。 +ディスクリプタの複製を \fBdup\fP(2), \fBdup2\fP(2), \fBfcntl\fP(2) の \fBF_DUPFD\fP や \fBfork\fP(2) +経由で行う度に、同じオープンファイル記述を参照する新規のファイル ディスクリプタが生成される。 +オープンファイル記述自体は、自身を参照する全てのファイルディスクリプタ がクローズされるまで存在し続ける。 ファイルディスクリプタが \fBepoll\fP +集合から削除されるのは、対応するオープンファイル記述を参照している 全てのファイルディスクリプタがクローズされた後である +(\fBepoll_ctl\fP(2) \fBEPOLL_CTL_DEL\fP を使ってそのディスクリプタを明示的に削除した場合にも削除される)。 このことは、 +\fBepoll\fP 集合に属しているあるファイルディスクリプタをクローズした後であっても、 +同じファイル記述を参照する他のファイルディスクリプタがオープンされている間は、 クローズしたファイルディスクリプタ宛にイベントが報告される可能性があると +いうことを意味する。 +.TP +\fBQ7\fP +2 つ以上のイベントが \fBepoll_wait\fP(2) コールの間に発生した場合、それらはまとめて報告されるか、 それとも別々に報告されるか？ +.TP +\fBA7\fP +まとめて報告されるだろう。 +.TP +\fBQ8\fP +ファイルディスクリプタに対する操作は、 既に集められているがまだ報告されていないイベントに影響するか？ +.TP +\fBA8\fP +既存のファイルディスクリプタに対して 2 つの操作を行うことができる。 この場合、削除には意味がない。 変更すると、使用可能な I/O +が再び読み込まれる。 +.TP +\fBQ9\fP +\fBEPOLLET\fP フラグ (エッジトリガ動作) を使っている場合、 \fBEAGAIN\fP を受け取るまで、 +継続してファイルディスクリプタを読み書きする必要があるか？ +.TP +\fBA9\fP +\fBepoll_wait\fP(2) からイベントを受け取ることは、 そのファイルディスクリプタが要求された I/O 操作に対して準備済みである、 +ということをユーザに示すものである。 次の (ブロックしない) read/write で \fBEAGAIN\fP +を受け取るまではファイルディスクリプタは準備済みであると 考えなければならない。 そのファイルディスクリプタをいつどのように使うかは、 +全くユーザに任されてる。 +.sp +パケット指向やトークン指向のファイル (例えば、データグラムソケット、 canonical モードの端末) では、 読み込み用 / 書き込み用の I/O +空間の末尾を検知する唯一の方法は \fBEAGAIN\fP になるまで read/write を行うことである。 +.sp +ストリーム指向のファイル (例えば、パイプ、FIFO、ストリームソケット) では、 読み込み用 / 書き込み用の I/O 空間が使い尽くされた状態は、 +対象となるファイルディスクリプタから読み込んだデータ量または 書き込んだデータ量をチェックすることでも検知できる。 +例えば、ある特定の量のデータを読み込むために \fBread\fP(2) を呼んだときに、 \fBread\fP(2) +が返したバイト数がそれより少なかった場合、 そのファイルディスクリプタの読み込み用 I/O 空間が 使い尽くされたことが分かる。 \fBwrite\fP(2) +を使って書き込みをするときも、同じことが言える (監視しているファイルディスクリプタが常にストリーム指向のファイルを +参照していることを保証できない場合には、後者の手法の使用を避けること)。 +.SS ありがちな落とし穴と回避方法 +.TP +\fBo 飢餓 (starvation) (エッジトリガ)\fP +.PP +大きな I/O 空間がある場合、 その I/O 空間のデータを全て処理 (drain) しようとすると、 +他のファイルが処理されず、飢餓を発生させることがある (この問題は \fBepoll\fP に固有のものではない)。 +.PP +この問題の解決法は、準備済み状態のリストを管理して、 関連する data 構造体の中でファイルディスクリプタが 利用可能であるとマークすることである。 +それによって、利用可能なすべてのファイルの中で どのファイルを処理する必要があるかを憶えることができ、 しかも順番に処理 (round robin) +することができる。 既に利用可能であるファイルディスクリプタに対して それ以後に受け取るイベントを無視することもできる。 +.TP +\fBo イベントキャッシュを使っている場合\fP +.PP +イベントキャッシュを使っている場合、 または \fBepoll_wait\fP(2) から返された全てのファイルディスクリプタを格納している場合、 +クローズされたことを動的にマークする (つまり前のイベントの処理によってマークされる) 方法を提供すべきである。 \fBepoll_wait\fP(2) +から 100 個のイベントを受け取り、 イベント #47 ではある条件でイベント #13 が閉じられると仮定する。 イベント #13 +の構造体を削除しファイルディスクリプタを \fBclose\fP(2) すると、イベントキャッシュはそのファイルディスクリプタを待つイベントが +存在するといって、混乱が起きる。 +.PP +この問題を解決する 1 つの方法は、イベント 47 の処理をしている間に、 ファイルディスクリプタ 13 を削除して \fBclose\fP(2) +するために \fBepoll_ctl\fP(\fBEPOLL_CTL_DEL\fP) を呼び出し、関連付けられた data 構造体を削除済みとマークして、 +クリーンアップリストにリンクすることである。 バッチ処理の中でファイルディスクリプタ 13 についての 他のイベントを見つけた場合、 +そのファイルディスクリプタが以前に削除されたものであると分かるので、 混乱は起きない。 +.SH バージョン +.\" Its interface should be finalized in Linux kernel 2.5.66. +\fBepoll\fP API は Linux カーネル 2.5.44 に導入された。 glibc でのサポートはバージョン 2.3.2 で追加された。 +.SH 準拠 +\fBepoll\fP API は Linux 固有である。 他のシステムでも同様の機構が提供されている場合がある。 例えば、FreeBSD の +\fIkqueue\fP や Solaris の \fI/dev/poll\fP などである。 +.SH 関連項目 +\fBepoll_create\fP(2), \fBepoll_create1\fP(2), \fBepoll_ctl\fP(2), \fBepoll_wait\fP(2) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/manual/LDP_man-pages/draft/man7/inotify.7 b/manual/LDP_man-pages/draft/man7/inotify.7 new file mode 100644 index 00000000..f23ede58 --- /dev/null +++ b/manual/LDP_man-pages/draft/man7/inotify.7 @@ -0,0 +1,288 @@ +.\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.TH INOTIFY 7 2013\-02\-25 Linux "Linux Programmer's Manual" +.SH 名前 +inotify \- ファイルシステムイベントを監視する +.SH 説明 +\fIinotify\fP API はファイルシステムイベントを監視するための機構を提供する。 inotify +は個々のファイルやディレクトリを監視するのに使える。 ディレクトリを監視する場合、inotify はディレクトリ自身と +ディレクトリ内のファイルのイベントを返す。 + +以下のシステムコールがこの API と共に使用される: \fBinotify_init\fP(2) (や \fBinotify_init1\fP(2)), +\fBinotify_add_watch\fP(2), \fBinotify_rm_watch\fP(2), \fBread\fP(2), \fBclose\fP(2). + +\fBinotify_init\fP(2) は inotify インスタンスを作成し、inotify インスタンスを参照する ファイルディスクリプタを返す。 +もっと新しい \fBinotify_init1\fP(2) も \fBinotify_init\fP(2) と同様だが、いくつかの追加の機能が提供されている。 + +\fBinotify_add_watch\fP(2) は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。 +監視対象リストの各アイテム ("watch") は、 ファイルまたはディレクトリのパス名と、 そのパス名で参照されるファイルに対して +カーネルが監視する複数のイベントの集合を指定する。 \fBinotify_add_watch\fP(2) +は新しい監視アイテムの作成や既存の監視対象の変更ができる。 各監視対象は一意の「監視対象ディスクリプタ」を持つ。 これは監視対象を作成したときに +\fBinotify_add_watch\fP(2) から返される整数である。 + +\fBinotify_rm_watch\fP(2) は inotify の監視対象リストからアイテムを削除する。 + +inotify インスタンスを指している 全てのファイルディスクリプタがクローズされた場合、 その下層にあるオブジェクトとそのリソースは、 +カーネルで再利用するために解放される。 関連が切られた監視対象は自動的に解放される。 + +どのようなイベントが起こっていたかを知るには、 アプリケーションで inotify ファイルディスクリプタを \fBread\fP(2) すればよい。 +これまでに何もイベントが起こっていない場合、 停止 (blocking) モードのファイルディスクリプタであれば、 少なくとも 1 +つのイベントが起こるまで \fBread\fP(2) は停止する (シグナルにより割り込まれなかった場合。 +シグナルによる割り込みがあった場合、呼び出しはエラー \fBEINTR\fP で失敗する。 \fBsignal\fP(7) 参照)。 + +\fBread\fP(2) が成功すると、以下の構造体を 1 つ以上含むバッファが返される: +.in +4n +.nf + +.\" FIXME . The type of the 'wd' field should probably be "int32_t". +.\" I submitted a patch to fix this. See the LKML thread +.\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008 +.\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040 +struct inotify_event { + int wd; /* 監視対象ディスクリプタ */ + uint32_t mask; /* イベントのマスク */ + uint32_t cookie; /* 関連するイベント群を関連づける + 一意なクッキー (rename(2) 用) */ + uint32_t len; /* \(aqname\(aq フィールドのサイズ */ + char name[]; /* NULL で終端された任意の名前 */ +}; +.fi +.in + +\fIwd\fP はイベント発生の監視対象を指定する。 これは、前もって行われた \fBinotify_add_watch\fP(2) +呼び出しで返された監視対象ディスクリプタのうちの 1 つである。 + +\fImask\fP には発生したイベント (下記参照) を記述するためのビットが含まれる。 + +\fIcookie\fP は関連するイベントを関連づけるための一意な整数である。 +現在のところ、この値は rename イベントに対してのみ使われており、 +結果のペアである \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP イベントを +アプリケーションで関連づけることができる。 +他のイベント種別の場合には、 \fIcookie\fP は 0 に設定する。 + +\fIname\fP フィールドは監視しているディレクトリ内のファイルに対して イベントが返される場合のためにだけ存在する。 +監視するディレクトリからのファイルの相対パス名を表す。 このパス名は NULL で終端され、 その後の読み込みで適切なアドレス境界に調整するために、 +さらに NULL バイトが含まれる場合もある。 + +\fIlen\fP フィールドは NULL バイトを含む \fIname\fP の全てのバイト数を表す。 +よって、 \fIinotify_event\fP 構造体のサイズは +\fIsizeof(struct inotify_event)+len\fP である。 + +\fBread\fP(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せ +ない場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカー +ネルでは、 \fBread\fP(2) は 0 を返す。 2.6.21 以降のカーネルでは、 +\fBread\fP(2) はエラー \fBEINVAL\fP で失敗する。 +バッファサイズとして + + sizeof(struct inotify_event) + NAME_MAX + 1 + +を指定すれば、少なくとも 1 イベントで読み出しを行うには十分である。 +.SS "inotify イベント" +\fBinotify_add_watch\fP(2) の \fImask\fP 引き数と、inotify ファイル構造体を \fBread\fP(2) +したときに返される \fIinotify_event\fP 構造体の \fImask\fP フィールドは、ともに inotify イベントを識別するための +ビットマスクである。 以下のビットが \fBinotify_add_watch\fP(2) を呼ぶときの \fImask\fP に指定可能であり、 +\fBread\fP(2) で返される \fImask\fP フィールドで返される: +.RS 4 +.sp +.PD 0 +.TP 18 +\fBIN_ACCESS\fP +ファイルがアクセス (read) された。(*) +.TP +\fBIN_ATTRIB\fP +メタデータが変更された。 メタデータとは、例えば、許可 (permission)、タイムスタンプ、拡張属性、 リンクカウント (Linux 2.6.25 +以降)、UID、GID などである。(*) +.TP +\fBIN_CLOSE_WRITE\fP +書き込みのためにオープンされたファイルがクローズされた。(*) +.TP +\fBIN_CLOSE_NOWRITE\fP +書き込み以外のためにオープンされたファイルがクローズされた。(*) +.TP +\fBIN_CREATE\fP +監視対象ディレクトリ内でファイルやディレクトリが作成された。(*) +.TP +\fBIN_DELETE\fP +監視対象ディレクトリ内でファイルやディレクトリが削除された。(*) +.TP +\fBIN_DELETE_SELF\fP +監視対象のディレクトリまたはファイル自身が削除された。 +.TP +\fBIN_MODIFY\fP +ファイルが修正された。(*) +.TP +\fBIN_MOVE_SELF\fP +監視対象のディレクトリまたはファイル自身が移動された。 +.TP +\fBIN_MOVED_FROM\fP +ファイルが監視対象ディレクトリ外へ移動された。(*) +.TP +\fBIN_MOVED_TO\fP +ファイルが監視対象ディレクトリ内へ移動された。(*) +.TP +\fBIN_OPEN\fP +ファイルがオープンされた。(*) +.PD +.RE +.PP +ディレクトリを監視する場合、 上記でアスタリスク (*) を付けたイベントは、 そのディレクトリ内のファイルに対して発生する。 このとき +\fIinotify_event\fP 構造体で返される \fIname\fP フィールドは、ディレクトリ内のファイル名を表す。 +.PP +\fBIN_ALL_EVENTS\fP マクロは上記のイベント全てのマスクとして定義される。 このマクロは \fBinotify_add_watch\fP(2) +を呼び出すときの \fImask\fP 引き数として使える。 + +さらに 2 つの便利なマクロがある。 +\fBIN_MOVE\fP は IN_MOVED_FROM|IN_MOVED_TO と同じで、 +\fBIN_CLOSE\fP は IN_CLOSE_WRITE|IN_CLOSE_NOWRITE と同じである。 +.PP +その他にも以下のビットを \fBinotify_add_watch\fP(2) を呼ぶときの \fImask\fP に指定できる: +.RS 4 +.sp +.PD 0 +.TP 18 +\fBIN_DONT_FOLLOW\fP +\fIpathname\fP がシンボリックリンクである場合に辿らない。 (Linux 2.6.15 以降) +.TP +\fBIN_EXCL_UNLINK\fP (Linux 2.6.36 以降) +.\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6 +デフォルトでは、あるディレクトリの子ファイルに関するイベントを監視 (watch) +した際、ディレクトリからその子ファイルが削除 (unlink) された場合であっても +その子ファイルに対してイベントが生成される。このことは、アプリケーションに +よってはあまり興味のないイベントが大量に発生することにつながる (例えば、\fI/tmp\fP +を監視している場合、たくさんのアプリケーションが、すぐにその名前が削除される +一時ファイルをそのディレクトリにに作成する)。 \fBIN_EXCL_UNLINK\fP を指定すると +このデフォルトの動作を変更でき、監視対象のディレクトリから子ファイルが削除 +された後に子ファイルに関するイベントが生成されなくなる。 +.TP +\fBIN_MASK_ADD\fP +\fIpathname\fP に対する監視マスクが既に存在する場合、 (マスクの置き換えではなく) イベントを追加 (OR) する。 +.TP +\fBIN_ONESHOT\fP +1 つのイベントについて \fIpathname\fP を監視し、 イベントが発生したら監視対象リストから削除する。 +.TP +\fBIN_ONLYDIR\fP (Linux 2.6.15 以降) +\fIpathname\fP がディレクトリの場合にのみ監視する。 +.PD +.RE +.PP +以下のビットが \fBread\fP(2) で返される \fImask\fP フィールドに設定される: +.RS 4 +.sp +.PD 0 +.TP 18 +\fBIN_IGNORED\fP +監視対象が (\fBinotify_rm_watch\fP(2) により) 明示的に 削除された。もしくは (ファイルの削除、またはファイル +システムのアンマウントにより) 自動的に削除された。 +.TP +\fBIN_ISDIR\fP +このイベントの対象がディレクトリである。 +.TP +\fBIN_Q_OVERFLOW\fP +イベントキューが溢れた (このイベントの場合、\fIwd\fP は \-1 である)。 +.TP +\fBIN_UNMOUNT\fP +監視対象オブジェクトを含むファイルシステムがアンマウントされた。 +.PD +.RE +.SS "/proc インターフェース" +以下のインターフェースは、inotify で消費される カーネルメモリの総量を制限するのに使用できる: +.TP +\fI/proc/sys/fs/inotify/max_queued_events\fP +このファイルの値は、アプリケーションが \fBinotify_init\fP(2) を呼び出すときに使用され、対応する inotify インスタンスについて +キューに入れられるイベントの数の上限を設定する。 この制限を超えたイベントは破棄されるが、 \fBIN_Q_OVERFLOW\fP イベントが常に生成される。 +.TP +\fI/proc/sys/fs/inotify/max_user_instances\fP +1 つの実ユーザ ID に対して生成できる inotify インスタンスの数の上限を指定する。 +.TP +\fI/proc/sys/fs/inotify/max_user_watches\fP +作成可能な監視対象の数の実 UID 単位の上限を指定する。 +.SH バージョン +inotify は 2.6.13 の Linux カーネルに組込まれた。 これに必要なライブラリのインターフェースは、 glibc のバージョン 2.4 +に追加された (\fBIN_DONT_FOLLOW\fP, \fBIN_MASK_ADD\fP, \fBIN_ONLYDIR\fP だけはバージョン 2.5 +で追加された)。 +.SH 準拠 +inotify API は Linux 独自のものである。 +.SH 注意 +inotify ファイルディスクリプタは \fBselect\fP(2), \fBpoll\fP(2), \fBepoll\fP(7) を使って監視できる。 +イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。 + +Linux 2.6.25 以降では、シグナル駆動 (signal\-driven) I/O の通知が inotify +ファイルディスクリプタについて利用可能である。 \fBfcntl\fP(2) に書かれている (\fBO_ASYNC\fP フラグを設定するための) +\fBF_SETFL\fP, \fBF_SETOWN\fP, \fBF_SETSIG\fP の議論を参照のこと。 シグナルハンドラに渡される \fIsiginfo_t\fP +構造体は、以下のフィールドが設定される (\fIsiginfo_t\fP は \fBsigaction\fP(2) で説明されている)。 \fIsi_fd\fP には +inotify ファイルディスクリプタ番号が、 \fIsi_signo\fP にはシグナル番号が、 \fIsi_code\fP には \fBPOLL_IN\fP が、 +\fIsi_band\fP には \fBPOLLIN\fP が設定される。 + +inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (\fIwd\fP, \fImask\fP, +\fIcookie\fP, \fIname\fP が等しい場合)、 前のイベントがまだ読み込まれていなければ、 連続するイベントが 1 つのイベントにまとめられる +(ただし「バグ」の節も参照のこと)。 + +inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。 +従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で +イベントが生成されることが保証される。 + +\fBFIONREAD\fP \fBioctl\fP(2) は inotify ファイルディスクリプタから何バイト読み込めるかを返す。 +.SS 制限と警告 +inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下の +サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。 +大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。 + +inotify API では、inotify イベントが発生するきっかけとなったユーザやプロセスに関する情報は提供されない。とりわけ、inotify +経由でイベントを監視しているプロセスが、自分自身がきっかけとなったイベントと他のプロセスがきっかけとなったイベントを区別する簡単な手段はない。 + +イベントキューは溢れる場合があることに注意すること。この場合にはイベントは +失われてしまう。堅牢性が必要なアプリケーションでは、イベントが失われる可能性 +を適切に扱う必要がある。 + +inotify API では影響が受けるファイルをファイル名で特定する。 +しかしながら、アプリケーションが inotify イベントを処理する時点では、 +そのファイル名がすでに削除されたり変更されたりしている可能性がある。 + +ディレクトリツリー全体を監視していて、そのツリー内に新しいサブディレクトリが +作成される場合、新しいサブディレクトリに対する watch を作成するまでに、 +新しいファイルがそのサブディレクトリ内にすでに作成されている場合がある点に +注意すること。したがって、watch を追加した直後にサブディレクトリの内容を +スキャンしたいと思う場合もあるだろう。 +.SH バグ +2.6.16 以前のカーネルでは \fBIN_ONESHOT\fP \fImask\fP フラグが働かない。 + +カーネル 2.6.25 より前では、 連続する同一のイベントを一つにまとめることを意図したコード (古い方のイベントがまだ読み込まれていない場合に、 +最新の 2 つのイベントを一つにまとめられる可能性がある) が、 最新のイベントが「最も古い」読み込まれていないイベントとまとめられるか +をチェックするようになっていた。 +.SH 関連項目 +\fBinotify_add_watch\fP(2), \fBinotify_init\fP(2), \fBinotify_init1\fP(2), +\fBinotify_rm_watch\fP(2), \fBread\fP(2), \fBstat\fP(2) + +Linux カーネルソース内の \fIDocumentation/filesystems/inotify.txt\fP +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 -- 2.11.0