release/man2/setns.2

   1 .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
   2 .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gamil.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2_ONELINE)
   5 .\" Licensed under the GPLv2
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\"*******************************************************************
   9 .\"
  10 .\" This file was generated with po4a. Translate the source file.
  11 .\"
  12 .\"*******************************************************************
  13 .TH SETNS 2 2013\-01\-01 Linux "Linux Programmer's Manual"
  14 .SH 名前
  15 setns \- スレッドに名前空間を関連付けしなおす
  16 .SH 書式
  17 .nf
  18 \fB#define _GNU_SOURCE\fP             /* feature_test_macros(7) 参照 */
  19 \fB#include <sched.h>\fP
  20 .sp
  21 \fBint setns(int \fP\fIfd\fP\fB, int \fP\fInstype\fP\fB);\fP
  22 .fi
  23 .SH 説明
  24 名前空間を参照するファイルディスクリプタを指定すると、
  25 呼び出したスレッドにその名前空間を関連付けしなおす。
  26
  27 \fIfd\fP 引き数は、 \fI/proc/[pid]/ns/\fP ディレクトリ内の名前空間エントリ
  28 のいずれかを参照するファイルディスクリプタである。
  29 \fI/proc/[pid]/ns/\fP の詳細は \fBproc\fP(5) を参照。
  30 \fInstype\fP 引き数で指定された制限の範囲内で、
  31 呼び出したスレッドに \fIfd\fP に対応する名前空間を関連付けしなおす。
  32
  33 \fInstype\fP 引き数は、呼び出したスレッドがどのタイプの名前空間を
  34 関連付けしなおすことができるかを指定する。
  35 この引き数には以下のいずれかの値を指定できる。
  36 .TP
  37 \fB0\fP
  38 どのタイプの名前空間も関連付けることができる。
  39 .TP
  40 \fBCLONE_NEWIPC\fP
  41 \fIfd\fP は IPC 名前空間を参照していなければならない。
  42 .TP
  43 \fBCLONE_NEWNET\fP
  44 \fIfd\fP はネットワーク名前空間を参照していなければならない。
  45 .TP
  46 \fBCLONE_NEWUTS\fP
  47 \fIfd\fP は UTS 名前空間を参照していなければならない。
  48 .PP
  49 呼び出し側が \fIfd\fP がどのタイプの名前空間を参照しているかを知っている
  50 (もしくは気にする必要がない) 場合には、 \fInstype\fP に 0 を指定すれば十分
  51 である。呼び出し側が \fIfd\fP がどのタイプの名前空間を参照しているかを
  52 知っておらず、かつ、特定のタイプの名前空間であることを保証したい場合、
  53 \fInstype\fP に 0 以外の値を指定するとよい。 (ファイルディスクリプタが別の
  54 プロセスによりオープンされ、例えば、UNIX ドメインソケット経由で呼び出し
  55 側に渡された場合などでは、呼び出し側が \fIfd\fP がどのタイプの名前空間を
  56 参照しているかを知らない可能性がある。)
  57 .SH 返り値
  58 成功すると \fIsetns\fP() は 0 を返す。
  59 失敗すると、 \-1 が返され、 \fIerrno\fP にエラーを示す値が設定される。
  60 .SH エラー
  61 .TP
  62 \fBEBADF\fP
  63 \fIfd\fP が有効なファイルディスクリプタではない。
  64 .TP
  65 \fBEINVAL\fP
  66 \fIfd\fP が \fInstype\fP で指定されたタイプと一致しない名前空間を参照している。
  67 または、指定された名前空間をそのスレッドに関連付けし直す際に問題
  68 があった。
  69 .TP
  70 \fBENOMEM\fP
  71 指定された名前空間に変更するのに必要なメモリが割り当てられない。
  72 .TP
  73 \fBEPERM\fP
  74 呼び出したスレッドがこの操作を行うのに必要な特権 (\fBCAP_SYS_ADMIN\fP) を
  75 持っていなかった。
  76 .SH バージョン
  77 \fBsetns\fP() システムコールはカーネル 3.0 で Linux に初めて登場した。
  78 ライブラリによるサポートは glibc バージョン 2.14 を追加された。
  79 .SH 準拠
  80 \fBsetns\fP() システムコールは Linux 固有である。
  81 .SH 注意
  82 新しいスレッドが \fBclone\fP(2) を使って作成された際に共有できる全ての属性を、
  83 \fBsetns\fP() を使って変更できるわけではない。
  84 .SH EXAMPLE
  85 The program below takes two or more arguments.  The first argument specifies
  86 the pathname of a namespace file in an existing \fI/proc/[pid]/ns/\fP
  87 directory.  The remaining arguments specify a command and its arguments.
  88 The program opens the namespace file, joins that namespace using \fBsetns\fP(),
  89 and executes the specified command inside that namespace.
  90
  91 The following shell session demonstrates the use of this program (compiled
  92 as a binary named \fIns_exec\fP)  in conjunction with the \fBCLONE_NEWUTS\fP
  93 example program in the \fBclone\fP(2)  man page (complied as a binary named
  94 \fInewuts\fP).
  95
  96 We begin by executing the example program in \fBclone\fP(2)  in the
  97 background.  That program creates a child in a separate UTS namespace.  The
  98 child changes the hostname in its namespace, and then both processes display
  99 the hostnames in their UTS namespaces, so that we can see that they are
 100 different.
 101
 102 .nf
 103 .in +4n
 104 $ \fBsu\fP                   # Need privilege for namespace operations
 105 Password:
 106 # \fB./newuts bizarro &\fP
 107 [1] 3549
 108 clone() returned 3550
 109 uts.nodename in child:  bizarro
 110 uts.nodename in parent: antero
 111 # \fBuname \-n\fP             # Verify hostname in the shell
 112 antero
 113 .in
 114 .fi
 115
 116 We then run the program shown below, using it to execute a shell.  Inside
 117 that shell, we verify that the hostname is the one set by the child created
 118 by the first program:
 119
 120 .nf
 121 .in +4n
 122 # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP
 123 # \fBuname \-n\fP             # Executed in shell started by ns_exec
 124 bizarro
 125 .in
 126 .fi
 127 .SS プログラムのソース
 128 .nf
 129 #define _GNU_SOURCE
 130 #include <fcntl.h>
 131 #include <sched.h>
 132 #include <unistd.h>
 133 #include <stdlib.h>
 134 #include <stdio.h>
 135
 136 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 137                         } while (0)
 138
 139 int
 140 main(int argc, char *argv[])
 141 {
 142     int fd;
 143
 144     if (argc < 3) {
 145         fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\en", argv[0]);
 146         exit(EXIT_FAILURE);
 147     }
 148
 149     fd = open(argv[1], O_RDONLY);   /* Get descriptor for namespace */
 150     if (fd == \-1)
 151         errExit("open");
 152
 153     if (setns(fd, 0) == \-1)         /* Join that namespace */
 154         errExit("setns");
 155
 156     execvp(argv[2], &argv[2]);      /* Execute a command in namespace */
 157     errExit("execvp");
 158 }
 159 .fi
 160 .SH 関連項目
 161 \fBclone\fP(2), \fBfork\fP(2), \fBvfork\fP(2), \fBproc\fP(5), \fBunix\fP(7)
 162 .SH この文書について
 163 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 164 である。プロジェクトの説明とバグ報告に関する情報は
 165 http://www.kernel.org/doc/man\-pages/ に書かれている。