Update draft based on LDP v3.75 po4a files

[linuxjm/LDP_man-pages.git] / draft / man7 / unix.7

.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\" and Copyright (C) 2008-2014, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
.\" and Copyright (C) 2008, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
.\" 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, <mtk.manpages@gmail.com>
.\" Modified, 2003-09-23, Adam Langley
.\" Modified, 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com>
.\"     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 <nakano@apm.seikei.ac.jp>
.\"     based on the work by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
.\" Updated 2003-01-07, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" 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\-10\-15 Linux "Linux Programmer's Manual"
.SH 名前
unix \- ローカルな プロセス間通信用のソケット
.SH 書式
\fB#include <sys/socket.h>\fP
.br
\fB#include <sys/un.h>\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 が入っている。

Various systems calls (for example, \fBbind\fP(2), \fBconnect\fP(2), and
\fBsendto\fP(2))  take a \fIsockaddr_un\fP argument as input.  Some other system
calls (for example, \fBgetsockname\fP(2), \fBgetpeername\fP(2), \fBrecvfrom\fP(2),
and \fBaccept\fP(2))  return an argument of this type.

\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
For further details of pathname sockets, see below.
.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 パス名ソケット
When binding a socket to a pathname, a few rules should be observed for
maximum portability and ease of coding:
.IP * 3
\fIsun_path\fP のパス名はヌル終端すべきである。
.IP *
終端のヌルバイトを含めたパス名の長さは \fIsun_path\fP の大きさを超えないようにすべきである。
.IP *
The \fIaddrlen\fP argument that describes the enclosing \fIsockaddr_un\fP
structure should have a value of at least:

.nf
    offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1
.fi
.IP
or, more simply, \fIaddrlen\fP can be specified as \fIsizeof(struct
sockaddr_un)\fP.
.PP
.\" Linux does this, including for the case where the supplied path
.\" is 108 bytes
There is some variation in how implementations handle UNIX domain socket
addresses that do not follow the above rules.  For example, some (but not
all) implementations append a null terminator if none is present in the
supplied \fIsun_path\fP.

.\" HP-UX
.\" Modern BSDs generally have 104, Tru64 and AIX have 104,
.\" Solaris and Irix have 108
When coding portable applications, keep in mind that some implementations
have \fIsun_path\fP as short as 92 bytes.

Various system calls (\fBaccept\fP(2), \fBrecvfrom\fP(2), \fBgetsockname\fP(2),
\fBgetpeername\fP(2))  return socket address structures.  When applied to UNIX
domain sockets, the value\-result \fIaddrlen\fP argument supplied to the call
should be initialized as above.  Upon return, the argument is set to
indicate the \fIactual\fP size of the address structure.  The caller should
check the value returned in this argument: if the output value exceeds the
input value, then there is no guarantee that a null terminator is present in
\fIsun_path\fP.  (See BUGS.)
.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<sys/socket.h>\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<linux/sockios.h>\fP で定義されている。
代わりに、\fI<sys/ioctl.h>\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.
When binding a socket to an address, Linux is one of the implementations
that appends a null terminator if none is supplied in \fIsun_path\fP.  In most
cases this is unproblematic: when the socket address is retrieved, it will
be one byte longer than that supplied when the socket was bound.  However,
there is one case where confusing behavior can result: if 108 non\-null bytes
are supplied when a socket is bound, then the addition of the null
terminator takes the length of the pathname beyond \fIsizeof(sun_path)\fP.
Consequently, when retrieving the socket address (for example, via
\fBaccept\fP(2)), if the input \fIaddrlen\fP argument for the retrieving call is
specified as \fIsizeof(struct sockaddr_un)\fP, then the returned address
structure \fIwon't\fP have a null terminator in \fIsun_path\fP.

.\" i.e., traditional BSD
In addition, some implementations don't require a null terminator when
binding a socket (the \fIaddrlen\fP argument is used to determine the length of
\fIsun_path\fP)  and when the socket address is retrieved on these
implementations, there is no null terminator in \fIsun_path\fP.

Applications that retrieve socket addresses can (portably) code to handle
the possibility that there is no null terminator in \fIsun_path\fP by
respecting the fact that the number of valid bytes in the pathname is:

.\" 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))

Alternatively, an application can retrieve the socket address by allocating
a buffer of size \fIsizeof(struct sockaddr_un)+1\fP that is zeroed out before
the retrieval.  The retrieving call can specify \fIaddrlen\fP as
\fIsizeof(struct sockaddr_un)\fP, and the extra zero byte ensures that there
will be a null terminator for the string returned in \fIsun_path\fP:

.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

This sort of messiness can be avoided if it is guaranteed that the
applications that \fIcreate\fP pathname sockets follow the rules outlined above
under \fIPathname sockets\fP.
.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.75 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。