Node.js v0.11.11 マニュアル & ドキュメンテーション

Index | View on single page | View as JSON

net#

Stability: 3 - Stable

net モジュールは非同期なネットワークのラッパーを提供します。それはサーバとクライアントの両方 (ストリームと呼ばれます) を作成するための方法を含みます。このモジュールはrequire("net");によって取り込むことができます。

net.createServer([options], [connectionListener])#

新しい TCP サーバを作成します。 connectionListener 引数は 'connection' イベントに対するリスナーとして自動的に加えられます。

options は以下のデフォルト値を持つオブジェクトです:

{ allowHalfOpen: false
}

allowHalfOpen が true だと、反対側のソケットが FIN パケットを送信してきても自動的に FIN を送信しなくなります。ソケットは読み込み可能ではなくなりますが、書き込み可能のままです。明示的に end() を呼び出す必要があります。 'end' イベントにより多くの情報があります。

8124 番のポートへの接続を待ち受けるエコーサーバの例:

var net = require('net');
var server = net.createServer(function(c) { //'connection' listener
  console.log('server connected');
  c.on('end', function() {
    console.log('server disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.listen(8124, function() { //'listening' listener
  console.log('server bound');
});

telnet を使ってテストします:

telnet localhost 8124

'/tmp/echo.sock' へのソケットを待ち受けるには、最後から三行目をこのように変更します。

server.listen('/tmp/echo.sock', function() { //'listening' listener

nc を使って UNIX ドメインソケットサーバへ接続します:

nc -U /tmp/echo.sock

net.connect(options, [connectionListener])#

net.createConnection(options, [connectionListener])#

新しいソケットオブジェクトを構築し、与えられたロケーションへのソケットをオープンします。ソケットが確立されると、'connect' イベントが生成されます。

TCP ソケットの場合、options 引数は以下を指定したオブジェクトです。

port: クライアントが接続するポート番号です (必須)。
host: クライアントが接続するホストです。デフォルトは localhost です。
localAddress: ネットワーク接続をバインドするローカルインタフェースです。
family : IP スタックのバージョン。デフォルトは 4 です。

ローカルドメインソケットの場合、options 引数は以下を指定したオブジェクトです。

path: クライアントが接続するパスです (必須)。

共通のオプション:

allowHalfOpen: true の場合、反対側のソケットが FIN パケットを送信してきても自動的に FIN を送信しなくなります。デフォルトは false です。 'end' イベントにより多くの情報があります。

connectListener 引数は 'connect' イベントのリスナとして追加されます。

前述のエコーサーバに接続するクライアントの例:

var net = require('net');
var client = net.connect({port: 8124},
    function() { //'connect' listener
  console.log('client connected');
  client.write('world!\r\n');
});
client.on('data', function(data) {
  console.log(data.toString());
  client.end();
});
client.on('end', function() {
  console.log('client disconnected');
});

'/tmp/echo.sock' へのソケットに接続するには、2 行目をこのように変更します。

var client = net.connect({path: '/tmp/echo.sock'});

net.connect(port, [host], [connectListener])#

net.createConnection(port, [host], [connectListener])#

host 上の port に対する TCP コネクションを作成します。 host が省略されると localhost が仮定されます。 connectListener 引数は 'connect' イベントのリスナとして追加されます。

net.connect(path, [connectListener])#

net.createConnection(path, [connectListener])#

path に対する UNIX ドメインソケットを作成します。 connectListener 引数は 'connect' イベントのリスナとして追加されます。

Class: net.Server#

このクラスは TCP またはローカルのサーバを作成するために使われます。

server.listen(port, [host], [backlog], [callback])#

指定された port と host でコネクションの受け入れを開始します。 host が省略されると、サーバはどんな IPv4 アドレスへの接続も受け入れます (INADDR_ANY)。ポート番号に 0 を指定すると、ランダムなポートが割り当てられます。

バックログは保留された接続のキューの最大長です。実際の長さは Linux では tcp_max_syn_backlog や somaxconn など、 sysctl の設定を通じて OS によって決定されます。このパラメータのデフォルト値は 511 (512 ではありません) です。

この関数は非同期です。サーバがバインドされると、'listening' イベントが生成されます。最後の引数 callback は 'listening' のリスナとして加えられます。

一部のユーザが陥る問題の一つは、EADDRINUSE エラーです。これは、他のサーバが要求されたポートを使っていることを意味します。これに対照する方法の一つは、1秒待機してからリトライすることです。これは次のようになります

server.on('error', function (e) {
  if (e.code == 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(function () {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

注意: Node の全てのソケットは SO_REUSEADDR が設定されます)

server.listen(path, [callback])#

path String
callback Function

与えられた path へのコネクションを待ち受けるするローカルドメインソケットのサーバを開始します。

UNIX では、ローカルドメインは通常 UNIX ドメインとして知られています。パスはファイルシステムのパス名です。それはファイルが作成されるのと同様に命名規則と認可のチェックが行われ、ファイルシステム上で見ることが出来て、アンリンクされるまで持続されます。

Windows では、ローカルドメインは名前付きパイプを使って実装されます。パスは \\?\pipe\ または \\.\pipe\ のエントリを参照しなければ なりません。 どんな文字も許されていますが、後者は .. のシーケンスを解決するなど、パイプ名を処理する必要があるかも知れません。見た目と異なり、パイプの名前空間はフラットです。パイプは 持続的ではなく、最後の参照がクローズされると削除されます。 JavaScript の文字列では、パスを指定するためにバックスラッシュを重ねてエスケープする必要があることを忘れないでください。

net.createServer().listen(
    path.join('\\\\?\\pipe', process.cwd(), 'myctl'))

server.listen(handle, [callback])#

handle Object
callback Function

handle オブジェクトには、サーバまたはソケット (下層の _handle メンバならなんでも) または、 {fd: <n>} オブジェクトを設定することができます。

これによりサーバは指定したハンドルへの接続を受け付けることになりますが、ファイル記述子またはハンドルは既にポートまたはドメインソケットにバインドされているものと見なされます。

ファイル記述子へのリスニングは Windows ではサポートされません。

server.close([callback])#

サーバが新しい接続を受け付けるのを終了しますが、既存の接続は維持します。この関数は非同期で、サーバは最終的に全ての接続が閉じられると 'close' イベントを生成してクローズされます。オプションとして、'close' イベントに対するリスナを渡すことができます。

server.address()#

オペレーティングシステムから報告された、サーバにバインドされたアドレスとアドレスファミリ名、ポートを返します。 OSによって割り当てられたアドレスが渡された時に、どのポートに割り当てられたものかを調べるのに便利です。返されるオブジェクトは 3 つのプロパティを持ちます。例: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

例:

var server = net.createServer(function (socket) {
  socket.end("goodbye\n");
});

// grab a random port.
server.listen(function() {
  address = server.address();
  console.log("opened server on %j", address);
});

'listening' イベントが生成される前に server.address() を呼び出してはいけません。

server.unref()#

イベントシステムにおいて、このサーバだけがアクティブな場合にプログラムを終了することができるように、unref を呼び出します。既に unref されたサーバで再び unref が呼び出されても影響はありません。

server.ref()#

unref とは逆に、以前に unref されたサーバが唯一残ったサーバになっても、プログラムが終了 (デフォルトの動作です) しないように、ref を呼び出します。既に ref されたサーバで再び ref が呼び出されても影響はありません。

server.maxConnections#

サーバの接続数が大きくなった時に接続を拒否するためにこのプロパティを設定します。

child_process.fork() によって子プロセスに送られたソケットに対してこのオプションを使用することは推奨されません。

server.connections#

この関数は 廃止予定 です; 代わりに [server.getConnections()][] を使ってください。

このサーバ上の並行コネクションの数です。

ソケットが child_process.fork() によって子プロセスに送られると、これは null になります。 fork した子プロセスにポーリングして現在のアクティブな接続を得る代わりに、非同期の server.getConnections を使用してください。

net.Server は以下のイベントを持つ EventEmitter です:

server.getConnections(callback)#

サーバ上の並行コネクオションの数を非同期に取得します。ソケットが fork した子プロセスに送られても動作します。

コールバックは err と count の二つの引数を取るべきです。

Event: 'listening'#

server.listen() が呼ばれた後、サーバがバインドされると生成されます。

Event: 'connection'#

Socket object The connection object

新しいコネクションが作成されると生成されます。 socket は net.Socket のインスタンスです。

Event: 'close'#

サーバがクローズした時に生成されます。もし接続が存在すると、このイベントは全ての接続が閉じられるまで生成されないことに注意してください。

Event: 'error'#

Error Object

エラーが発生すると生成されます。このイベントに続いて 'close' イベントが直接生成される場合があります。 server.listen() の例を参照してください。

Class: net.Socket#

このオブジェクトは TCP またはローカルのソケットを抽象化したものです。 net.Socket のインスタンスは双方向のストリームインタフェースを実装します。それらはユーザによって (connect() によって) 作成されてクライアントとして使われるか、 Node によって作成されてサーバの 'connection' イベントを通じてユーザに渡されます。

new net.Socket([options])#

新しいソケットオブジェクトを構築します。

options は以下のデフォルト値を持つオブジェクトです。

{ fd: null
  allowHalfOpen: false,
  readable: false,
  writable: false
}

fd に既存のソケットのファイル記述子を指定することができます。 readable および writable に true を設定すると、ソケットへの読み込みまたは書き込みが可能になります (注意: fd が渡された場合のみ作用します)。 allowHalfOpen については createServer() および 'end' イベントを参照してください。

socket.connect(port, [host], [connectListener])#

socket.connect(path, [connectListener])#

与えられたソケットでコネクションをオープンします。 port と host が与えられた場合、ソケットは TCP ソケットとしてオープンされます。 host が省略された場合は localhost が仮定されます。 path が与えられた場合は、ソケットはそのパスへの UNIX ドメインソケットとしてオープンされます。

通常このメソッドは必要なく、net.createConnection でソケットをオープンします。これを使うのは、カスタマイズされたソケットを実装している場合だけです。

この関数は非同期です。ソケットが確立されると 'connect' イベントが生成されます。接続で問題があった場合は 'connect' イベントは生成されず、例外とともに 'error' イベントが生成されます。

connectListener 引数は 'connect' イベントのリスナに加えられます。

socket.bufferSize#

net.Socket には、socket.write() と常に協調するプロパティがあります。これはユーザが実行速度を向上させる手助けになります。コンピュータは、ソケットに書き込まれるデータ量についていくことはできません。 - ネットワーク接続は、単純に遅すぎます。 Node は、ソケットに書き込まれるデータを内部のキューに入れ、可能になった時にワイヤ上に送信します (内部ではソケットのファイル記述子が書き込み可能になるのをポーリングします)。

内部的なバッファリングの結果、メモリ消費が増大するかもしれません。このプロパティは、現在書き込みのためにバッファリングされている文字数を示します。 (文字数は書き込まれるバイト数とほぼ同じですが、バッファが文字列を含んでいる場合、文字列は遅延的にエンコードされるため、正確なバイト数は分かっていません)

大きな、あるいは増大する bufferSize を体験したユーザは、そのプログラムで pause() および resume() を使ってデータフローを「抑えよう」としなければなりません。

socket.setEncoding([encoding])#

ソケットを入力ストリームとしてエンコーディングを設定します。詳細は stream.setEncoding() を参照してください。

socket.write(data, [encoding], [callback])#

ソケットにデータを送信します。文字列の場合、第 2 引数はエンコーディングを指定します－デフォルトは UTF-8 です。

データ全体のカーネルバッファへのフラッシュが成功すると true を返します。データ全体または一部がユーザメモリ内のキューに入れられた場合は false を返します。再びバッファが空いた場合は 'drain' イベントが生成されます。

オプションの callback 引数はデータが最終的に出力された時に実行されます－これはすぐには起きないでしょう。

socket.end([data], [encoding])#

ソケットをハーフクローズします。例えば FIN パケットを送信します。サーバはまだデータを送り続けてくることができます。

data が指定された場合は、 socket.write(data, encoding) に続けて socket.end() を呼び出すのと等価です。

socket.destroy()#

このソケット上でどんな I/O も起こらないことを保証します。 (パースエラーなどの) エラーの場合にだけ必要です。

socket.pause()#

データの読み込みを中断します。つまり、'data' イベントは生成されません。アップロード速度を落とすために便利です。

socket.resume()#

pause() を呼び出した後で読み込みを再開します。

socket.setTimeout(timeout, [callback])#

このソケットが非アクティブになってから timeout ミリ秒後にタイムアウトするように設定します。デフォルトでは net.Socket はタイムアウトしません。

アイドルタイムアウトが引き起こされると、ソケットは 'timeout' イベントを受信しますが、コネクションは切断されません。ユーザは手動で end() または destroy() を呼び出す必要があります。

timeout が 0 の場合、アイドルタイムアウトは無効にされます。

オプションの callback 引数は、timeouot イベントの一回限りのリスナを追加します。

socket.setNoDelay([noDelay])#

Nagle アルゴリズムを無効にします。デフォルトでは TCP コネクションは Nagle アルゴリズムを使用し、データを送信する前にバッファリングします。 noDelay に true を設定すると、データは socket.write() を呼び出す度に即座に送信されます。デフォルトは true です。

socket.setKeepAlive([enable], [initialDelay])#

キープアライブ機能を有効/無効にします。オプションで最初の keepalive probe がアイドルソケットに送信されるまでの初期遅延を設定します。 enable のデフォルトは false です。

initialDelay (ミリ秒) が設定されると、最後にデータパケットを受信してから最初の keepalive probe までの遅延が設定されます。初期遅延に 0 が設定されると、デフォルト設定から値を変更されないようにします。デフォルトは 0 です。

socket.address()#

オペレーティングシステムから報告された、ソケットにバインドされたアドレスとアドレスファミリ名、ポートを返します。返されるオブジェクトは 3 つのプロパティを持ちます。例: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.unref()#

イベントシステムにおいて、このソケットだけがアクティブな場合にプログラムを終了することができるように、unref を呼び出します。既に unref されたソケットで再び unref が呼び出されても影響はありません。

socket.ref()#

unref とは逆に、以前に unref されたソケットが唯一残ったソケットになっても、プログラムが終了 (デフォルトの動作です) しないように、ref を呼び出します。既に ref されたソケットで再び ref が呼び出されても影響はありません。

socket.remoteAddress#

リモートの IP アドレスを表現する文字列です。例えば、'74.125.127.100' あるいは '2001:4860:a005::68'。

このメンバはサーバサイドのコネクションにのみ与えられます。

socket.remotePort#

リモートポートの数値表現です。たとえば、80 や 21。

socket.localAddress#

リモートクライアントが接続しているローカル IP アドレスを表現する文字列です。たとえば、 '0.0.0.0' をリッスンしていて、クライアントが '192.168.1.1' に接続した場合、この値は '192.168.1.1' になります。

socket.localPort#

ローカルポートの数値表現です。たとえば、80 や 21。

socket.bytesRead#

受信したバイトの合計です。

socket.bytesWritten#

送信したバイトの合計です。

net.Socket のインスタンスは以下のイベントを持つ EventEmitter です:

Event: 'lookup'#

ホスト名を解決した後、ただし接続の前に生成されます。 UNIX ソケットには適用されません。

err {Error | Null} エラーオブジェクト。 dns.lookup() 参照。
address {String} IP アドレス。
family {String | Null} アドレスファミリ。 dns.lookup() 参照。

Event: 'connect'#

ソケットコネクションの確立が成功した場合に生成されます。 connect() を参照してください。

Event: 'data'#

Buffer object

データを受信した場合に生成されます。 data 引数は Buffer または String です。データのエンコーディングは socket.setEncoding() で設定されます。 (より詳しい情報は Readable Stream を参照してください)。

Socket が 'data' イベントを生成した時にリスナが存在しなければ、 データは失われることに注意してください。

Event: 'end'#

ソケットの相手側が FIN パケットを送信した場合に生成されます。

デフォルト (allowHalfOpen == false) では、保留されていた書き込みキューが出力されるとソケットはファイル識別子を破棄します。しかし、allowHalfOpen == true が設定されていると、ユーザがデータを書き込めるようにしておくために、ソケットは自動的に end() を呼び出さないので、ユーザが end() を呼び出す必要があります。

Event: 'timeout'#

ソケットがタイムアウトして非アクティブになった場合に生成されます。これはソケットがアイドルになったことを通知するだけです。利用者は手動でコネクションをクローズする必要があります。

socket.setTimeout() を参照してください。

Event: 'drain'#

書き込みバッファが空になった場合に生成されます。アップロード速度を落とすために使うことができます。

socket.write() の戻り値を参照してください。

Event: 'error'#

Error object

エラーが発生した場合に生成されます。'close' イベントはこのイベントの後に直接呼び出されます。

Event: 'close'#

had_error {Boolean} ソケットで転送エラーが発生した場合は true です。

ソケットが完全にクローズした場合に生成されます。引数 had_error は boolean で、ソケットが転送エラーでクローズされたのかどうかを示します。

net.isIP(input)#

input が IP アドレスかテストします。不正な文字列だと 0、IP バージョン 4 アドレスだと 4，IP バージョン 6 アドレスだと 6 が返されます。

net.isIPv4(input)#

input がバージョン 4 の IP アドレスなら true、そうでなければ false を返します。

net.isIPv6(input)#

input がバージョン 6 の IP アドレスなら true、そうでなければ false を返します。

Table of Contents

net#

net.createServer([options], [connectionListener])#

net.connect(options, [connectionListener])#

net.createConnection(options, [connectionListener])#

net.connect(port, [host], [connectListener])#

net.createConnection(port, [host], [connectListener])#

net.connect(path, [connectListener])#

net.createConnection(path, [connectListener])#

Class: net.Server#

server.listen(port, [host], [backlog], [callback])#

server.listen(path, [callback])#

server.listen(handle, [callback])#

server.close([callback])#

server.address()#

server.unref()#

server.ref()#

server.maxConnections#

server.connections#

server.getConnections(callback)#

Event: 'listening'#

Event: 'connection'#

Event: 'close'#

Event: 'error'#

Class: net.Socket#

new net.Socket([options])#

socket.connect(port, [host], [connectListener])#

socket.connect(path, [connectListener])#

socket.bufferSize#

socket.setEncoding([encoding])#

socket.write(data, [encoding], [callback])#

socket.end([data], [encoding])#

socket.destroy()#

socket.pause()#

socket.resume()#

socket.setTimeout(timeout, [callback])#

socket.setNoDelay([noDelay])#

socket.setKeepAlive([enable], [initialDelay])#

socket.address()#

socket.unref()#

socket.ref()#

socket.remoteAddress#

socket.remotePort#

socket.localAddress#

socket.localPort#

socket.bytesRead#

socket.bytesWritten#

Event: 'lookup'#

Event: 'connect'#

Event: 'data'#

Event: 'end'#

Event: 'timeout'#

Event: 'drain'#

Event: 'error'#

Event: 'close'#

net.isIP(input)#

net.isIPv4(input)#

net.isIPv6(input)#