X-Git-Url: http://git.osdn.net/view?p=linuxjm%2FLDP_man-pages.git;a=blobdiff_plain;f=draft%2Fman7%2Funix.7;fp=draft%2Fman7%2Funix.7;h=0000000000000000000000000000000000000000;hp=407e632e59a196fda962c2fc3310ac563e6f2f3d;hb=2460a0b8024ceb8570acdbc9208713d79458efcb;hpb=83f9e5d087c3464d5131604d3c9893479e6228eb diff --git a/draft/man7/unix.7 b/draft/man7/unix.7 deleted file mode 100644 index 407e632e..00000000 --- a/draft/man7/unix.7 +++ /dev/null @@ -1,371 +0,0 @@ -.\" This man page is Copyright (C) 1999 Andi Kleen . -.\" and Copyright (C) 2008-2014, Michael Kerrisk -.\" -.\" %%%LICENSE_START(VERBATIM_ONE_PARA) -.\" and Copyright (C) 2008, 2012 Michael Kerrisk -.\" Permission is granted to distribute possibly modified copies -.\" of this page provided the header is included verbatim, -.\" and in case of nontrivial modification author and date -.\" of the modification is added to the header. -.\" %%%LICENSE_END -.\" -.\" Modified, 2003-12-02, Michael Kerrisk, -.\" Modified, 2003-09-23, Adam Langley -.\" Modified, 2004-05-27, Michael Kerrisk, -.\" Added SOCK_SEQPACKET -.\" 2008-05-27, mtk, Provide a clear description of the three types of -.\" address that can appear in the sockaddr_un structure: pathname, -.\" unnamed, and abstract. -.\" -.\"******************************************************************* -.\" -.\" This file was generated with po4a. Translate the source file. -.\" -.\"******************************************************************* -.\" -.\" Japanese Version Copyright (c) 1999 Shouichi Saito and -.\" NAKANO Takeo all rights reserved. -.\" Translated 1999-12-06, NAKANO Takeo -.\" based on the work by Shouichi Saito -.\" Updated 2003-01-07, Akihiro MOTOKI -.\" Updated 2005-02-21, Akihiro MOTOKI -.\" Updated 2005-12-26, Akihiro MOTOKI -.\" Updated 2008-08-08, Akihiro MOTOKI, LDP v3.05 -.\" -.TH UNIX 7 2014\-12\-31 Linux "Linux Programmer's Manual" -.SH 名前 -unix \- ローカルな プロセス間通信用のソケット -.SH 書式 -\fB#include \fP -.br -\fB#include \fP - -\fIunix_socket\fP\fB = socket(AF_UNIX, type, 0);\fP -.br -\fIerror\fP\fB = socketpair(AF_UNIX, type, 0, int *\fP\fIsv\fP\fB);\fP -.SH 説明 -\fBAF_UNIX\fP (\fBAF_LOCAL\fP とも言われる) ソケットファミリーは、同じマシン上で -プロセス同士が 効率的に通信するために用いられる。伝統的に、UNIX ドメイン -ソケットは、名前なしにもできるし、 (ソケット型であると印のついた) ファイル -システムのパス名に 結び付けることもできる。さらに Linux では、ファイル -システムに依存しない抽象名前空間 (abstract namespace) もサポートしている。 - -UNIX ドメインに指定できるソケットタイプは以下の通りである。 \fBSOCK_STREAM\fP は、 ストリーム指向のソケットで有効である。 -\fBSOCK_DGRAM\fP は、 メッセージ境界を保存するデータグラム指向のソケットで有効である (ほとんどの UNIX の実装では、 UNIX -ドメインデータグラムソケットは常に信頼でき、 データグラムの並び替えは行わない)。 \fBSOCK_SEQPACKET\fP は、 -メッセージ境界を保存し送信された順序でメッセージを届ける接続指向ソケットで有効である (Linux 2.6.4 以降で利用できる)。 - -UNIX ドメインソケットでは、補助データを使って ファイルディスクリプターや -プロセスの信任状 (credential) を 送受信することもできる。 -.SS アドレスのフォーマット -UNIX ドメインソケットのアドレスは以下の構造体で表現される。 -.in +4n -.nf - -#define UNIX_PATH_MAX 108 - -struct sockaddr_un { - sa_family_t sun_family; /* AF_UNIX */ - char sun_path[UNIX_PATH_MAX]; /* pathname */ -}; -.fi -.in -.PP -\fIsun_family\fP フィールドには必ず \fBAF_UNIX\fP が入っている。 - -様々なシステムコール (例えば \fBbind\fP(2), \fBconnect\fP(2), \fBsendto\fP(2)) は入力として -\fIsockaddr_un\fP 引き数を取る。 他のいくつかのシステムコール (例えば \fBgetsockname\fP(2), -\fBgetpeername\fP(2), \fBrecvfrom\fP(2), \fBaccept\fP(2)) はこの型の引き数を返す。 - -\fIsockaddr_un\fP 構造体では 3 種類のアドレスが区別される。 -.IP * 3 -\fIpathname (パス名)\fP: \fBbind\fP(2) を使って、UNIX ドメインソケットを、 -ヌル終端されたファイルシステム上のパス名に結び付けることができる。 (上述のいずれかのシステムコールにより) ソケットのアドレスが返される際、 -その長さは - - offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 - -であり、 \fIsun_path\fP にはヌル終端されたパス名が格納される。 (Linux では、上記の \fBoffsetof\fP() 式は -\fIsizeof(sa_family_t)\fP の値と同じだが、 他の実装では \fIsun_path\fP の前に他のフィールドが含まれる場合もある。 -そのため、 \fBoffsetof\fP() 式を使う方がより移植性のある方法でアドレス構造体のサイズを知ることができる。) -.IP -パス名ソケットの詳細については、後で説明する。 -.IP * -.\" There is quite some variation across implementations: FreeBSD -.\" says the length is 16 bytes, HP-UX 11 says it's zero bytes. -\fIunnamed (名前なし)\fP: \fBbind\fP(2) を使ってパス名に結び付けることができないストリーム型のソケットは 名前を持たない。同様に、 -\fBsocketpair\fP(2) で作成される 2 つのソケットも名前を持たない。 名前なしのソケットのアドレスを返す際には、 その長さは -\fIsizeof(sa_family_t)\fP であり、 \fIsun_path\fP は検査すべきではない。 -.IP * -\fIabstract (抽象)\fP: 抽象ソケットアドレスは、 \fIsun_path[0]\fP がヌルバイト (\(aq\e0\(aq) であることから -(パス名ソケットから) 区別できる。 この名前空間におけるソケットのアドレスは、 \fIsun_path\fP の残りのバイトの、 -アドレス構造体の指定された長さの範囲で表される (名前中のヌルバイトには特別な意味はない)。 この名前はファイルシステムのパス名とは何の関係もない。 -抽象ソケットのアドレスを返される際には、 返される \fIaddrlen\fP は \fIsizeof(sa_family_t)\fP より大きく (つまり 2 -より大きく)、 ソケットの名前は \fIsun_path\fP の最初の \fI(addrlen \- sizeof(sa_family_t))\fP -バイトに格納される。 ソケットの抽象名前空間は Linux による拡張であり、移植性はない。 -.SS パス名ソケット -ソケットにパス名を結びつける際に、 最大限の移植性を持たせ、コーディングを簡単にするためのルールがいくつかある。 -.IP * 3 -\fIsun_path\fP のパス名はヌル終端すべきである。 -.IP * -終端のヌルバイトを含めたパス名の長さは \fIsun_path\fP の大きさを超えないようにすべきである。 -.IP * -\fIsockaddr_un\fP 構造体の終わりを示す \fIaddrlen\fP 引き数は最低でも以下の値を持つべきである。 - -.nf - offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 -.fi -.IP -もしくは、もっと簡単には、 \fIaddrlen\fP に \fIsizeof(struct sockaddr_un)\fP を指定することもできる。 -.PP -.\" Linux does this, including for the case where the supplied path -.\" is 108 bytes -UNIX ドメインソケットアドレスの扱いが上記のルールに従っていない実装もいくつかある。 (全部ではないが) いくつかの実装では、 -\fIsun_path\fP に文字列終端の NULL がなかった場合に終端の NULL が追加される。 - -.\" HP-UX -.\" Modern BSDs generally have 104, Tru64 and AIX have 104, -.\" Solaris and Irix have 108 -移植性があるアプリケーションを作成する際には、 いくつかの実装では \fIsun_path\fP は 92 バイトしかないという点にも留意しておくとよい。 - -様々なシステムコール (\fBaccept\fP(2), \fBrecvfrom\fP(2), \fBgetsockname\fP(2), -\fBgetpeername\fP(2)) がソケットアドレス構造体を返す。 これらのシステムコールが UNIX ドメインソケットに対して呼ばれた際には、 -これらの呼び出しに渡す \fIaddrlen\fP 引き数は上記の説明のように初期化すべきである。 -リターン時には、この引き数にはアドレス構造体の「実際の」サイズが設定される。 呼び出し側ではこの引き数で返された値を確認すべきである。 -返された値が入力値よりも大きい場合、 \fIsun_path\fP に終端の NULL バイトが存在する保証はない (「バグ」を参照)。 -.SS ソケットオプション -歴史的な理由により、これらのオプションは たとえ \fBAF_UNIX\fP 固有のオプションであっても \fBSOL_SOCKET\fP 型で指定する。 -ソケットファミリーとして \fBSOL_SOCKET\fP を指定すると、 \fBsetsockopt\fP(2) でオプションが設定でき、 -\fBgetsockopt\fP(2) で取得ができる。 -.TP -\fBSO_PASSCRED\fP -送信プロセスの補助メッセージで信任状を受信できるようにする。このオプションが -セットされていて、まだソケットが接続されていないと、抽象名前空間に他と重なら -ない名前が自動的に生成される。ブール整数値のフラグを取る。 -.SS "自動バインド (autobind) 機能" -.\" i.e., sizeof(short) -\fBbind\fP(2) 呼び出しで \fIsizeof(sa_family_t)\fP として \fIaddrlen\fP を指定するか、 -アドレスに明示的にバインドされていないソケットに対して -\fBSO_PASSCRED\fP ソケットオプションが指定されていた場合、 -そのソケットは抽象アドレスに自動的にバインドされる。 -このアドレスは、1 個のヌルバイトの後に、文字集合 \fI[0\-9a\-f]\fP のバイトが -5 個続く形式である。したがって、自動的にバインドされるアドレス数には -2^20 個という上限が存在する。 -(Linux 2.1.15 以降で、自動バインド機能が追加されたときには、 -8 バイトが使われており、自動バインドアドレス数の上限は 2^32 であった。 -Linux 2.3.15 で 5 バイトに変更された。) -.SS "ソケット API" -この節では、Linux の UNIX ドメインソケットでの、ドメイン固有の詳細仕様と -ソケット API でサポートされていない機能について説明する。 - -UNIX ドメインソケットでは、帯域外データ (out\-of\-band data) の 送信 -(\fBsend\fP(2) と \fBrecv\fP(2) の \fBMSG_OOB\fP フラグ) はサポートされていない。 - -\fBsend\fP(2) \fBMSG_MORE\fP フラグは UNIX ドメインソケットではサポートされていない。 - -\fBrecv\fP(2) の \fIflags\fP 引き数での \fBMSG_TRUNC\fP の使用は UNIX ドメイン -ソケットではサポートされていない。 - -\fBSO_SNDBUF\fP ソケットオプションは UNIX ドメインソケットで効果を持つが、 -\fBSO_RCVBUF\fP は効果がない。 データグラムソケットでは、 \fBSO_SNDBUF\fP の値が -出力データグラムの上限サイズとなる。 実際の上限値は、 \fBSO_SNDBUF\fP オプション -として設定された値の 2倍 (\fBsocket\fP(7) 参照) からオーバヘッドとして使用される -32 バイトを引いた値となる。 -.SS 補助メッセージ -補助データを送受するには、 \fBsendmsg\fP(2) や \fBrecvmsg\fP(2) を使用する。 -歴史的な理由により、以下に示す補助メッセージの型は たとえ \fBAF_UNIX\fP 固有のものであっても \fBSOL_SOCKET\fP 型で指定する。 -これらを送るには、構造体 \fIcmsghdr\fP の \fIcmsg_level\fP フィールドに \fBSOL_SOCKET\fP をセットし、 -\fIcmsg_type\fP フィールドにタイプをセットする。 詳細は \fBcmsg\fP(3) を見よ。 -.TP -\fBSCM_RIGHTS\fP -他のプロセスでオープンされたファイルディスクリプターのセットを送受信する。 データ部分にファイルディスクリプターの整数配列が入っている。 -渡されたファイルディスクリプターは、あたかも \fBdup\fP(2) で生成されたかのように振る舞う。 -.TP -\fBSCM_CREDENTIALS\fP -UNIX 信任状を送受信する。これは認証に用いることができる。 -信任状は \fIstruct ucred\fP の補助メッセージとして渡される。 -この構造体は \fI\fP で以下のように定義されている。 - -.in +4n -.nf -struct ucred { - pid_t pid; /* process ID of the sending process */ - uid_t uid; /* user ID of the sending process */ - gid_t gid; /* group ID of the sending process */ -}; -.fi -.in - -glibc 2.8 以降では、この構造体の定義を得るためには -(\fIどの\fPヘッダーファイルをインクルードするよりも前に) -機能検査マクロ \fB_GNU_SOURCE\fP を定義しなければならない。 - -送信側が指定した信任状は、カーネルがチェックする。 実効ユーザー ID が 0 のプロセスには、 自分自身以外の値を指定する事が許される。 -送信側は以下の 3 つを指定しなければならない。 1) 自分自身のプロセス ID (\fBCAP_SYS_ADMIN\fP 権限を持っていない場合)、 2) -自分自身のユーザー ID あるいは実効ユーザー ID か保存 set\-user\-ID (\fBCAP_SETUID\fP 権限を持っていない場合)、 3) -自分自身のグループ ID あるいは実行グループ ID か保存 set\-group\-ID (\fBCAP_SETGID\fP を持っていない場合)。 -\fIstruct ucred\fP メッセージを受信するためには、ソケットに対し \fBSO_PASSCRED\fP オプションを有効にしなくてはならない。 -.SS ioctl -以下の \fBioctl\fP(2) 呼び出しは \fIvalue\fP に情報を入れて返す。 -正しい書式は以下の通り。 -.PP -.RS -.nf -\fBint\fP\fI value\fP\fB;\fP -\fIerror\fP\fB = ioctl(\fP\fIunix_socket\fP\fB, \fP\fIioctl_type\fP\fB, &\fP\fIvalue\fP\fB);\fP -.fi -.RE -.PP -\fIioctl_type\fP には以下を指定できる: -.TP -\fBSIOCINQ\fP -.\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002, -.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers -.\" SIOCOUTQ also has an effect for UNIX domain sockets, but not -.\" quite what userland might expect. It seems to return the number -.\" of bytes allocated for buffers containing pending output. -.\" That number is normally larger than the number of bytes of pending -.\" output. Since this info is, from userland's point of view, imprecise, -.\" and it may well change, probably best not to document this now. -受信バッファーのキューにある、まだ読んでいないデータの量を返す。ソケットは -LISTEN 状態にあってはならず、さもないとエラー (\fBEINVAL\fP) が返る。 -\fBSIOCINQ\fP は \fI\fP で定義されている。 -代わりに、\fI\fP で定義されている、同義語の \fBFIONREAD\fP -を使うこともできる。 -.SH エラー -.TP -\fBEADDRINUSE\fP -指定したローカルアドレスが既に使用されているか、ファイルシステムの -ソケットオブジェクトが既に存在している。 -.TP -\fBECONNREFUSED\fP -\fBconnect\fP(2) により指定されたリモートアドレスが接続待ちソケットではなかった。 -このエラーはターゲットのパス名がソケットでなかった場合にも発生する。 -.TP -\fBECONNRESET\fP -リモートソケットが予期しないかたちでクローズされた。 -.TP -\fBEFAULT\fP -ユーザーメモリーアドレスが不正。 -.TP -\fBEINVAL\fP -渡した引数が不正。よくある原因としては、渡したアドレスの \fIsun_type\fP フィール -ドに \fBAF_UNIX\fP が指定されていなかった、行おうとした操作に対してソケットが有 -効な状態ではなかった、など。 -.TP -\fBEISCONN\fP -既に接続されているソケットに対して \fBconnect\fP(2) が呼ばれた。または、指定したターゲットアドレスが 既に接続済みのソケットだった。 -.TP -\fBENOENT\fP -\fBconnect\fP(2) に指定されたリモートアドレスのパス名が存在しなかった。 -.TP -\fBENOMEM\fP -メモリーが足りない。 -.TP -\fBENOTCONN\fP -ソケット操作にターゲットアドレスが必要だが、 このソケットは接続されていない。 -.TP -\fBEOPNOTSUPP\fP -ストリーム指向でないソケットに対してストリーム操作が呼び出された。 または帯域外データオプションを用いようとした。 -.TP -\fBEPERM\fP -送信者が \fIstruct ucred\fP に不正な信任状を渡した。 -.TP -\fBEPIPE\fP -リモートソケットがストリームソケット上でクローズされた。 可能な場合は \fBSIGPIPE\fP も同時に送られる。これを避けるには -\fBMSG_NOSIGNAL\fP フラグを \fBsendmsg\fP(2) や \fBrecvmsg\fP(2) に渡す。 -.TP -\fBEPROTONOSUPPORT\fP -渡されたプロトコルが \fBAF_UNIX\fP でない。 -.TP -\fBEPROTOTYPE\fP -リモートソケットとローカルソケットのタイプが一致していなかった (\fBSOCK_DGRAM\fP と \fBSOCK_STREAM\fP)。 -.TP -\fBESOCKTNOSUPPORT\fP -未知のソケットタイプ。 -.PP -他にも汎用のソケット層でエラーが起こったり、 ファイルシステム上にソケットオブジェクトを作ろうとした場合に ファイルシステムのエラーが起こることがある。 -それぞれの詳細は適切な man ページを参照すること。 -.SH バージョン -\fBSCM_CREDENTIALS\fP と抽象名前空間は、Linux 2.2 で導入された。 移植性が必要なプログラムでは使うべきではない。 (BSD -由来のシステムの中にも信任状の送受信をサポートしているものがあるが、 その実装の詳細はシステムによって異なる) -.SH 注意 -Linux の実装では、 ファイルシステム上から見えるソケットは、 それらが置かれているディレクトリのパーミッションに従う。 ソケットの所有者、 -グループ、 パーミッションは変更できる。 新しいソケットを作るとき、 作ろうとするディレクトリに対して プロセスが書き込みと検索 (実行) -権限を持っていなければ、 作成に失敗する。 ソケットオブジェクトに接続するには、 read/write 権限が必要である。 この動作は、 多くの BSD -由来のシステムとは異なっている (BSD では UNIX ドメインソケットに対してはパーミッションを無視する)。 -移植性の必要なプログラムでは、セキュリティをこの仕様に依存してはならない。 - -ファイル名を指定してソケットにバインドすると、ファイルシステムにソケットが -生成される。これは必要なくなったときに呼びだしたユーザーが削除しなければ -ならない (\fBunlink\fP(2) を用いる)。 UNIX で通常使われる「背後で閉じる方式」 -が適用される。ソケットはいつでも unlink することができ、最後の参照が -クローズされたときにファイルシステムから削除される。 - -\fBSOCK_STREAM\fP 上でファイルディスクリプターや信任状を渡すためには、同じ \fBsendmsg\fP(2) や \fBrecvmsg\fP(2) -コールで補助データ以外のデータを少なくとも 1 バイト送信/受信する必要がある。 - -.\" -UNIX ドメインのストリームソケットでは、 帯域外データの概念はサポートされない。 -.SH バグ -.\" The behavior on Solaris is quite similar. -ソケットをアドレスに結びつける際、 Linux は終端の NULL が \fIsun_path\fP になかった場合に追加する実装の一つである。 -ほとんどの場合、 これは問題にならない。 ソケットアドレスが取得された際、ソケットをバインドしたときに指定したものより 1 バイト長くなるだけである。 -しかしながら、紛らわしい動作が起こる場合が一つある。 ソケットをバインドした際に 108 個の NULL でないバイトを指定した場合、 終端の NULL -が追加されるとパス名の長さが \fIsizeof(sun_path)\fP を超えてしまう。 結果として、(例えば \fBaccept\fP(2) で) -ソケットアドレスを取得した際に、 値を取得する呼び出しの入力の \fIaddress\fP 引き数に \fIsizeof(struct -sockaddr_un)\fP を指定したとすると、 返されるアドレス構造体は \fIsun_path\fP に終端の NULL を「含まない」ことになる。 - -.\" i.e., traditional BSD -さらに、 いくつかの実装では、ソケットをバインドする際に終端の NULL が必要ではなく (\fIaddrlen\fP 引き数を使って \fIsun_path\fP -の長さが判定される)、 このような実装でソケットアドレスを取得する際には、 \fIsun_path\fP に終端の NULL は存在しない。 - -ソケットアドレスを取得するアプリケーションでは、 \fIsun_path\fP に終端の NULL が存在しないという移植性の問題を、 -パス名の有効なバイト数が以下のようになると事実を考慮することで取り扱うことができる。 - -.\" The following patch to amend kernel behavior was rejected: -.\" http://thread.gmane.org/gmane.linux.kernel.api/2437 -.\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path -.\" 2012-04-17 -.\" And there was a related discussion in the Austin list: -.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735 -.\" Subject: Having a sun_path with no null terminator -.\" 2012-04-18 -.\" -.\" FIXME . Track http://austingroupbugs.net/view.php?id=561 - strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) - -他の方法としては、 アプリケーションがソケットアドレスを取得する際、 取得の呼び出しを行う前に、 大きさが \fIsizeof(struct -sockaddr_un)+1\fP のバッファーを割り当てることもできる。 取得の呼び出しでは \fIaddrlen\fP に \fIsizeof(struct -sockaddr_un)\fP を指定すると、 余分な一つの 0 バイトにより \fIsun_path\fP で返される文字列に終端の NULL -が含まれることが保証される。 - -.nf -.in +3 -void *addrp; - -addrlen = sizeof(struct sockaddr_un); -addrp = malloc(addrlen + 1); -if (addrp == NULL) - /* Handle error */ ; -memset(addrp, 0, addrlen + 1); - -if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) - /* handle error */ ; - -printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); -.in -.fi - -アプリケーションが「パス名ソケット」の節で説明したルールにしたがってパス名を「作成」していれば、 このような分かりにくさは避けることができる。 -.SH 例 -\fBbind\fP(2) 参照。 - -\fBSCM_RIGHTS\fP の使用例については \fBcmsg\fP(3) を参照。 -.SH 関連項目 -\fBrecvmsg\fP(2), \fBsendmsg\fP(2), \fBsocket\fP(2), \fBsocketpair\fP(2), \fBcmsg\fP(3), -\fBcapabilities\fP(7), \fBcredentials\fP(7), \fBsocket\fP(7) -.SH この文書について -この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部 -である。プロジェクトの説明とバグ報告に関する情報は -http://www.kernel.org/doc/man\-pages/ に書かれている。