draft/man7/unix.7

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   4 .\" Permission is granted to distribute possibly modified copies
   5 .\" of this page provided the header is included verbatim,
   6 .\" and in case of nontrivial modification author and date
   7 .\" of the modification is added to the header.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" Modified, 2003-12-02, Michael Kerrisk, <mtk.manpages@gmail.com>
  11 .\" Modified, 2003-09-23, Adam Langley
  12 .\" Modified, 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com>
  13 .\"     Added SOCK_SEQPACKET
  14 .\" 2008-05-27, mtk, Provide a clear description of the three types of
  15 .\"     address that can appear in the sockaddr_un structure: pathname,
  16 .\"     unnamed, and abstract.
  17 .\"
  18 .\"*******************************************************************
  19 .\"
  20 .\" This file was generated with po4a. Translate the source file.
  21 .\"
  22 .\"*******************************************************************
  23 .\"
  24 .\" Japanese Version Copyright (c) 1999 Shouichi Saito and
  25 .\"     NAKANO Takeo all rights reserved.
  26 .\" Translated 1999-12-06, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  27 .\"     based on the work by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
  28 .\" Updated 2003-01-07, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  29 .\" Updated 2005-02-21, Akihiro MOTOKI
  30 .\" Updated 2005-12-26, Akihiro MOTOKI
  31 .\" Updated 2008-08-08, Akihiro MOTOKI, LDP v3.05
  32 .\"
  33 .TH UNIX 7 2012\-05\-10 Linux "Linux Programmer's Manual"
  34 .SH 名前
  35 unix \- ローカルな プロセス間通信用のソケット
  36 .SH 書式
  37 \fB#include <sys/socket.h>\fP
  38 .br
  39 \fB#include <sys/un.h>\fP
  40
  41 \fIunix_socket\fP\fB = socket(AF_UNIX, type, 0);\fP
  42 .br
  43 \fIerror\fP\fB = socketpair(AF_UNIX, type, 0, int *\fP\fIsv\fP\fB);\fP
  44 .SH 説明
  45 \fBAF_UNIX\fP (\fBAF_LOCAL\fP とも言われる) ソケットファミリーは、同じマシン上で
  46 プロセス同士が 効率的に通信するために用いられる。伝統的に、UNIX ドメイン
  47 ソケットは、名前なしにもできるし、 (ソケット型であると印のついた) ファイル
  48 システムのパス名に 結び付けることもできる。さらに Linux では、ファイル
  49 システムに依存しない抽象名前空間 (abstract namespace) もサポートしている。
  50
  51 有効なタイプを以下に示す。 \fBSOCK_STREAM\fP はストリーム指向のソケットである。
  52 \fBSOCK_DGRAM\fP はメッセージ境界を保存するデータグラム指向のソケットである
  53 (ほとんどの UNIX の実装では、UNIX ドメイン・データグラム・ソケットは 常に
  54 信頼でき、データグラムの並び替えは行わない)。
  55 \fBSOCK_SEQPACKET\fP はメッセージ境界を保存し、送信された順序でメッセージを
  56 届ける接続指向ソケット である (Linux 2.6.4 以降で利用できる)。
  57
  58 UNIX ドメインソケットでは、補助データを使って ファイルディスクリプタや
  59 プロセスの信任状 (credential) を 送受信することもできる。
  60 .SS アドレスのフォーマット
  61 UNIX ドメインソケットのアドレスは以下の構造体で表現される。
  62 .in +4n
  63 .nf
  64
  65 #define UNIX_PATH_MAX    108
  66
  67 struct sockaddr_un {
  68     sa_family_t sun_family;               /* AF_UNIX */
  69     char        sun_path[UNIX_PATH_MAX];  /* pathname */
  70 };
  71 .fi
  72 .in
  73 .PP
  74 \fIsun_family\fP には必ず \fBAF_UNIX\fP が入っている。
  75
  76 この構造体では 3 種類のアドレスが区別される。
  77 .IP * 3
  78 \fIpathname (パス名)\fP: \fBbind\fP(2) を使って、UNIX ドメインソケットを NULL 終端
  79 されたファイルシステム上の パス名に結び付けることができる。
  80 \fBgetsockname\fP(2), \fBgetpeername\fP(2), \fBaccept\fP(2) がソケットのアドレスを
  81 返す際には、その長さは
  82 \fIoffsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1\fP
  83 であり、 \fIsun_path\fP に NULL 終端されたパス名が格納される。
  84 .IP *
  85 .\" There is quite some variation across implementations: FreeBSD
  86 .\" says the length is 16 bytes, HP-UX 11 says it's zero bytes.
  87 \fIunnamed (名前なし)\fP: \fBbind\fP(2)  を使ってパス名に結び付けることができないストリーム型のソケットは 名前を持たない。同様に、
  88 \fBsocketpair\fP(2)  で作成される 2 つのソケットも名前を持たない。 \fBgetsockname\fP(2),
  89 \fBgetpeername\fP(2), \fBaccept\fP(2)  が名前なしのソケットのアドレスを返す際には、 その長さは
  90 \fIsizeof(sa_family_t)\fP であり、 \fIsun_path\fP は検査すべきではない。
  91 .IP *
  92 \fIabstract (抽象)\fP: 抽象ソケットアドレスは、 \fIsun_path[0]\fP が NULL バイト
  93 (\(aq\e0\(aq) であることで区別される。この名前空間におけるソケットのアドレス
  94 は、 \fIsun_path\fP の残りのバイトの、アドレス構造体の指定された長さの範囲で表さ
  95 れる (名前中の NULL バイトには特別な意味はない)。この名前はファイルシステムの
  96 パス名とは何の関係もない。 \fBgetsockname\fP(2), \fBgetpeername\fP(2),
  97 \fBaccept\fP(2) が抽象ソケットのアドレスを返す際には、返される \fIaddrlen\fP は
  98 \fIsizeof(sa_family_t)\fP より大きく (つまり 2 より大きく)、ソケットの名前は
  99 \fIsun_path\fP の最初の \fI(addrlen \- sizeof(sa_family_t))\fP バイトに格納される。
 100 ソケットの抽象名前空間は Linux による拡張であり、移植性はない。
 101 .SS ソケットオプション
 102 歴史的な理由により、これらのオプションは たとえ \fBAF_UNIX\fP 固有のオプションであっても \fBSOL_SOCKET\fP 型で指定する。
 103 ソケットファミリーとして \fBSOL_SOCKET\fP を指定すると、 \fBsetsockopt\fP(2)  でオプションが設定でき、
 104 \fBgetsockopt\fP(2)  で取得ができる。
 105 .TP
 106 \fBSO_PASSCRED\fP
 107 送信プロセスの補助メッセージで信任状を受信できるようにする。このオプションが
 108 セットされていて、まだソケットが接続されていないと、抽象名前空間に他と重なら
 109 ない名前が自動的に生成される。ブール整数値のフラグを取る。
 110 .SS "自動バインド (autobind) 機能"
 111 .\" i.e. sizeof(short)
 112 \fBbind\fP(2) 呼び出しで \fIsizeof(sa_family_t)\fP として \fIaddrlen\fP を指定するか、
 113 アドレスに明示的にバインドされていないソケットに対して
 114 \fBSO_PASSCRED\fP ソケットオプションが指定されていた場合、
 115 そのソケットは抽象アドレスに自動的にバインドされる。
 116 このアドレスは、1 個の NULL バイトの後に、文字集合 \fI[0\-9a\-f]\fP のバイトが
 117 5 個続く形式である。したがって、自動的にバインドされるアドレス数には
 118 2^20 個という上限が存在する。
 119 (Linux 2.1.15 以降で、自動バインド機能が追加されたときには、
 120 8 バイトが使われており、自動バインドアドレス数の上限は 2^32 であった。
 121 Linux 2.3.15 で 5 バイトに変更された。)
 122 .SS "ソケット API"
 123 この節では、Linux の UNIX ドメインソケットでの、ドメイン固有の詳細仕様と
 124 ソケット API でサポートされていない機能について説明する。
 125
 126 UNIX ドメインソケットでは、帯域外データ (out\-of\-band data) の 送信
 127 (\fBsend\fP(2) と \fBrecv\fP(2) の \fBMSG_OOB\fP フラグ) はサポートされていない。
 128
 129 \fBsend\fP(2) \fBMSG_MORE\fP フラグは UNIX ドメインソケットではサポートされていない。
 130
 131 \fBrecv\fP(2) の \fIflags\fP 引き数での \fBMSG_TRUNC\fP の使用は UNIX ドメイン
 132 ソケットではサポートされていない。
 133
 134 \fBSO_SNDBUF\fP ソケットオプションは UNIX ドメインソケットで効果を持つが、
 135 \fBSO_RCVBUF\fP は効果がない。 データグラム・ソケットでは、 \fBSO_SNDBUF\fP の値が
 136 出力データグラムの上限サイズとなる。 実際の上限値は、 \fBSO_SNDBUF\fP オプション
 137 として設定された値の 2倍 (\fBsocket\fP(7) 参照) からオーバヘッドとして使用される
 138 32 バイトを引いた値となる。
 139 .SS 補助メッセージ
 140 補助データを送受するには、 \fBsendmsg\fP(2)  や \fBrecvmsg\fP(2)  を使用する。
 141 歴史的な理由により、以下に示す補助メッセージの型は たとえ \fBAF_UNIX\fP 固有のものであっても \fBSOL_SOCKET\fP 型で指定する。
 142 これらを送るには、構造体 \fIcmsghdr\fP の \fIcmsg_level\fP フィールドに \fBSOL_SOCKET\fP をセットし、
 143 \fIcmsg_type\fP フィールドにタイプをセットする。 詳細は \fBcmsg\fP(3)  を見よ。
 144 .TP
 145 \fBSCM_RIGHTS\fP
 146 他のプロセスでオープンされたファイルディスクリプタのセットを送受信する。 データ部分にファイルディスクリプタの整数配列が入っている。
 147 渡されたファイルディスクリプタは、あたかも \fBdup\fP(2)  で生成されたかのように振る舞う。
 148 .TP
 149 \fBSCM_CREDENTIALS\fP
 150 UNIX 信任状を送受信する。これは認証に用いることができる。
 151 信任状は \fIstruct ucred\fP の補助メッセージとして渡される。
 152 この構造体は \fI<sys/socket.h>\fP で以下のように定義されている。
 153
 154 .in +4n
 155 .nf
 156 struct ucred {
 157     pid_t pid;    /* process ID of the sending process */
 158     uid_t uid;    /* user ID of the sending process */
 159     gid_t gid;    /* group ID of the sending process */
 160 };
 161 .fi
 162 .in
 163
 164 glibc 2.8 以降では、この構造体の定義を得るためには
 165 (\fIどの\fPヘッダファイルをインクルードするよりも前に)
 166 機能検査マクロ \fB_GNU_SOURCE\fP を定義しなければならない。
 167
 168 送信側が指定した信任状は、カーネルがチェックする。 実効ユーザー ID が 0 のプロセスには、 自分自身以外の値を指定する事が許される。
 169 送信側は以下の 3 つを指定しなければならない。 1) 自分自身のプロセス ID (\fBCAP_SYS_ADMIN\fP 権限を持っていない場合)、 2)
 170 自分自身のユーザー ID あるいは実効ユーザー ID か保存 set\-user\-ID (\fBCAP_SETUID\fP 権限を持っていない場合)、 3)
 171 自分自身のグループ ID あるいは実行グループ ID か保存 set\-group\-ID (\fBCAP_SETGID\fP を持っていない場合)。
 172 \fIstruct ucred\fP メッセージを受信するためには、ソケットに対し \fBSO_PASSCRED\fP オプションを有効にしなくてはならない。
 173 .SS ioctl
 174 以下の \fBioctl\fP(2) 呼び出しは \fIvalue\fP に情報を入れて返す。
 175 正しい書式は以下の通り。
 176 .PP
 177 .RS
 178 .nf
 179 \fBint\fP\fI value\fP\fB;\fP
 180 \fIerror\fP\fB = ioctl(\fP\fIunix_socket\fP\fB, \fP\fIioctl_type\fP\fB, &\fP\fIvalue\fP\fB);\fP
 181 .fi
 182 .RE
 183 .PP
 184 \fIioctl_type\fP には以下を指定できる:
 185 .TP
 186 \fBSIOCINQ\fP
 187 .\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002,
 188 .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
 189 .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not
 190 .\" quite what userland might expect. It seems to return the number
 191 .\" of bytes allocated for buffers containing pending output.
 192 .\" That number is normally larger than the number of bytes of pending
 193 .\" output. Since this info is, from userland's point of view, imprecise,
 194 .\" and it may well change, probably best not to document this now.
 195 受信バッファのキューにある、まだ読んでいないデータの量を返す。ソケットは
 196 LISTEN 状態にあってはならず、さもないとエラー (\fBEINVAL\fP) が返る。
 197 \fBSIOCINQ\fP は \fI<linux/sockios.h>\fP で定義されている。
 198 代わりに、\fI<sys/ioctl.h>\fP で定義されている、同義語の \fBFIONREAD\fP
 199 を使うこともできる。
 200 .SH エラー
 201 .TP
 202 \fBEADDRINUSE\fP
 203 指定したローカルアドレスが既に使用されているか、ファイルシステムの
 204 ソケットオブジェクトが既に存在している。
 205 .TP
 206 \fBECONNREFUSED\fP
 207 \fBconnect\fP(2) により指定されたリモートアドレスが接続待ちソケットではなかった。
 208 ターゲットアドレスがソケットではない場合にもこのエラーが発生する。
 209 .TP
 210 \fBECONNRESET\fP
 211 リモートソケットが予期しないかたちでクローズされた。
 212 .TP
 213 \fBEFAULT\fP
 214 ユーザーメモリアドレスが不正。
 215 .TP
 216 \fBEINVAL\fP
 217 渡した引数が不正。よくある原因としては、渡したアドレスの \fIsun_type\fP フィール
 218 ドに \fBAF_UNIX\fP が指定されていなかった、行おうとした操作に対してソケットが有
 219 効な状態ではなかった、など。
 220 .TP
 221 \fBEISCONN\fP
 222 既に接続されているソケットに対して \fBconnect\fP(2)  が呼ばれた。または、指定したターゲットアドレスが 既に接続済みのソケットだった。
 223 .TP
 224 \fBENOENT\fP
 225 \fBconnect\fP(2) に指定されたリモートアドレスのパス名が存在しなかった。
 226 .TP
 227 \fBENOMEM\fP
 228 メモリが足りない。
 229 .TP
 230 \fBENOTCONN\fP
 231 ソケット操作にターゲットアドレスが必要だが、 このソケットは接続されていない。
 232 .TP
 233 \fBEOPNOTSUPP\fP
 234 ストリーム指向でないソケットに対してストリーム操作が呼び出された。 または帯域外データオプションを用いようとした。
 235 .TP
 236 \fBEPERM\fP
 237 送信者が \fIstruct ucred\fP に不正な信任状を渡した。
 238 .TP
 239 \fBEPIPE\fP
 240 リモートソケットがストリームソケット上でクローズされた。 可能な場合は \fBSIGPIPE\fP も同時に送られる。これを避けるには
 241 \fBMSG_NOSIGNAL\fP フラグを \fBsendmsg\fP(2)  や \fBrecvmsg\fP(2)  に渡す。
 242 .TP
 243 \fBEPROTONOSUPPORT\fP
 244 渡されたプロトコルが \fBAF_UNIX\fP でない。
 245 .TP
 246 \fBEPROTOTYPE\fP
 247 リモートソケットとローカルソケットのタイプが一致していなかった (\fBSOCK_DGRAM\fP と \fBSOCK_STREAM\fP)。
 248 .TP
 249 \fBESOCKTNOSUPPORT\fP
 250 未知のソケットタイプ。
 251 .PP
 252 他にも汎用のソケット層でエラーが起こったり、 ファイルシステム上にソケットオブジェクトを作ろうとした場合に ファイルシステムのエラーが起こることがある。
 253 それぞれの詳細は適切な man ページを参照すること。
 254 .SH バージョン
 255 \fBSCM_CREDENTIALS\fP と抽象名前空間は、Linux 2.2 で導入された。 移植性が必要なプログラムでは使うべきではない。 (BSD
 256 由来のシステムの中にも信任状の送受信をサポートしているものがあるが、 その実装の詳細はシステムによって異なる)
 257 .SH 注意
 258 Linux の実装では、ファイルシステム上から見えるソケットは、それらが置かれてい
 259 るディレクトリのパーミッションに従う。ソケットの所有者、グループ、パーミッショ
 260 ンは変更できる。新しいソケットを作るとき、作ろうとするディレクトリに対して プ
 261 ロセスが書き込みと検索 (実行) 権限を持っていなければ、作成に失敗する。ソケッ
 262 トオブジェクトに接続するには、 read/write 権限が必要である。この動作は、多く
 263 の BSD 由来のシステムとは異なっている (BSD では UNIX ドメインソケットに対して
 264 はパーミッションを無視する)。 移植性の必要なプログラムでは、セキュリティをこ
 265 の仕様に依存してはならない。
 266
 267 ファイル名を指定してソケットにバインドすると、ファイルシステムにソケットが
 268 生成される。これは必要なくなったときに呼びだしたユーザーが削除しなければ
 269 ならない (\fBunlink\fP(2) を用いる)。 UNIX で通常使われる「背後で閉じる方式」
 270 が適用される。ソケットはいつでも unlink することができ、最後の参照が
 271 クローズされたときにファイルシステムから削除される。
 272
 273 \fBSOCK_STREAM\fP 上でファイルディスクリプタや信任状を渡すためには、同じ \fBsendmsg\fP(2)  や \fBrecvmsg\fP(2)
 274 コールで補助データ以外のデータを少なくとも 1 バイト送信/受信する必要がある。
 275
 276 UNIX ドメインのストリーム・ソケットでは、 帯域外データの概念はサポートされない。
 277 .SH 例
 278 \fBbind\fP(2)  参照。
 279
 280 \fBSCM_RIGHTS\fP の使用例については \fBcmsg\fP(3) を参照。
 281 .SH 関連項目
 282 \fBrecvmsg\fP(2), \fBsendmsg\fP(2), \fBsocket\fP(2), \fBsocketpair\fP(2), \fBcmsg\fP(3),
 283 \fBcapabilities\fP(7), \fBcredentials\fP(7), \fBsocket\fP(7)
 284 .SH この文書について
 285 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 286 である。プロジェクトの説明とバグ報告に関する情報は
 287 http://www.kernel.org/doc/man\-pages/ に書かれている。