UDP/データグラムソケット

[安定版: 2 - 安定]

安定版: 2 安定度: 2 - 安定

ソースコード: lib/dgram.js

node:dgram モジュールは、UDP データグラムソケットの実装を提供します。

ESM

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`サーバーエラー:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`サーバーが受信: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`サーバーリスニング ${address.address}:${address.port}`)
})

server.bind(41234)
// 出力: サーバーリスニング 0.0.0.0:41234

CJS

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`サーバーエラー:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`サーバーが受信: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`サーバーリスニング ${address.address}:${address.port}`)
})

server.bind(41234)
// 出力: サーバーリスニング 0.0.0.0:41234

クラス: dgram.Socket

追加: v0.1.99

• 拡張: <EventEmitter>

データグラム機能をカプセル化します。

dgram.Socket の新しいインスタンスは、dgram.createSocket() を使用して作成されます。 dgram.Socket インスタンスを作成するために new キーワードを使用しないでください。

イベント: 'close'

追加: v0.1.99

'close' イベントは、close() でソケットが閉じられた後に発行されます。一度トリガーされると、このソケットで新しい 'message' イベントは発行されません。

イベント: 'connect'

追加: v12.0.0

'connect' イベントは、connect() 呼び出しが成功した結果として、ソケットがリモートアドレスに関連付けられた後に発行されます。

イベント: 'error'

追加: v0.1.99

• exception <Error>

'error' イベントは、何らかのエラーが発生するたびに発生します。イベントハンドラー関数には、単一の Error オブジェクトが渡されます。

イベント: 'listening'

追加: v0.1.99

'listening' イベントは、dgram.Socket がアドレス可能になり、データを受信できるようになったときに一度だけ発生します。これは、socket.bind() で明示的に行うか、socket.send() を使用して最初にデータを送信するときに暗黙的に行われます。dgram.Socket がリッスンするまで、基盤となるシステムリソースは存在せず、socket.address() や socket.setTTL() などの呼び出しは失敗します。

イベント: 'message'

[履歴]

バージョン	変更点
v18.4.0	family プロパティが数値ではなく文字列を返すようになりました。
v18.0.0	family プロパティが文字列ではなく数値を返すようになりました。
v0.1.99	追加: v0.1.99

'message' イベントは、新しいデータグラムがソケットで利用可能になったときに発生します。イベントハンドラー関数には、msg と rinfo の 2 つの引数が渡されます。

• msg <Buffer> メッセージ。
• rinfo <Object> リモートアドレス情報。
  • address <string> 送信元アドレス。
  • family <string> アドレスファミリ ('IPv4' または 'IPv6')。
  • port <number> 送信元ポート。
  • size <number> メッセージサイズ。

受信パケットの送信元アドレスが IPv6 リンクローカルアドレスの場合、インターフェース名が address に追加されます。たとえば、en0 インターフェースで受信したパケットは、アドレスフィールドが 'fe80::2618:1234:ab11:3b9c%en0' に設定されている場合があります。ここで、'%en0' はゾーン ID サフィックスとしてのインターフェース名です。

socket.addMembership(multicastAddress[, multicastInterface])

追加: v0.6.9

• multicastAddress <string>
• multicastInterface <string>

カーネルに、IP_ADD_MEMBERSHIP ソケットオプションを使用して、指定された multicastAddress および multicastInterface でマルチキャストグループに参加するように指示します。 multicastInterface 引数が指定されていない場合、オペレーティングシステムは 1 つのインターフェースを選択し、それにメンバーシップを追加します。利用可能なすべてのインターフェースにメンバーシップを追加するには、インターフェースごとに 1 回、addMembership を複数回呼び出します。

バインドされていないソケットで呼び出された場合、このメソッドは暗黙的にランダムなポートにバインドし、すべてのインターフェースをリッスンします。

複数の cluster ワーカー間で UDP ソケットを共有する場合、socket.addMembership() 関数は 1 回のみ呼び出す必要があります。そうしないと、EADDRINUSE エラーが発生します。

ESM

import cluster from 'node:cluster'
import dgram from 'node:dgram'

if (cluster.isPrimary) {
  cluster.fork() // 正常に動作します。
  cluster.fork() // EADDRINUSE で失敗します。
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

CJS

const cluster = require('node:cluster')
const dgram = require('node:dgram')

if (cluster.isPrimary) {
  cluster.fork() // 正常に動作します。
  cluster.fork() // EADDRINUSE で失敗します。
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])

追加: v13.1.0, v12.16.0

• sourceAddress <string>
• groupAddress <string>
• multicastInterface <string>

カーネルに、IP_ADD_SOURCE_MEMBERSHIP ソケットオプションを使用して、指定された sourceAddress および groupAddress でソース固有のマルチキャストチャネルに参加するように指示します。 multicastInterface 引数が指定されていない場合、オペレーティングシステムは 1 つのインターフェースを選択し、それにメンバーシップを追加します。利用可能なすべてのインターフェースにメンバーシップを追加するには、インターフェースごとに 1 回、socket.addSourceSpecificMembership() を複数回呼び出します。

バインドされていないソケットで呼び出された場合、このメソッドは暗黙的にランダムなポートにバインドし、すべてのインターフェースをリッスンします。

socket.address()

追加: v0.1.99

• 戻り値: <Object>

ソケットのアドレス情報を含むオブジェクトを返します。UDP ソケットの場合、このオブジェクトにはaddress、family、およびportプロパティが含まれます。

バインドされていないソケットで呼び出された場合、このメソッドはEBADFをスローします。

socket.bind([port][, address][, callback])

[履歴]

バージョン	変更点
v0.9.1	メソッドが非同期実行モデルに変更されました。レガシーコードは、メソッド呼び出しにコールバック関数を渡すように変更する必要があります。
v0.1.99	追加: v0.1.99

• port <integer>
• address <string>
• callback <Function> パラメーターなし。バインドが完了したときに呼び出されます。

UDP ソケットの場合、dgram.Socketが指定されたportとオプションのaddressでデータグラムメッセージをリッスンするようにします。 portが指定されていないか0の場合、オペレーティングシステムはランダムなポートへのバインドを試みます。addressが指定されていない場合、オペレーティングシステムはすべてのアドレスでリッスンしようとします。バインドが完了すると、'listening'イベントが発行され、オプションのcallback関数が呼び出されます。

'listening'イベントリスナーを指定し、socket.bind()メソッドにcallbackを渡すことは有害ではありませんが、あまり役に立ちません。

バインドされたデータグラムソケットは、データグラムメッセージを受信するために Node.js プロセスを実行し続けます。

バインドに失敗すると、'error'イベントが生成されます。まれに（例えば、クローズされたソケットでバインドを試みる場合）、Errorがスローされることがあります。

ポート 41234 でリッスンする UDP サーバーの例：

ESM

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`server error:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server listening ${address.address}:${address.port}`)
})

server.bind(41234)
// Prints: server listening 0.0.0.0:41234

CJS

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`server error:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server listening ${address.address}:${address.port}`)
})

server.bind(41234)
// Prints: server listening 0.0.0.0:41234

socket.bind(options[, callback])

追加: v0.11.14

• options <Object> 必須。以下のプロパティをサポートします。

  • port <integer>
  • address <string>
  • exclusive <boolean>
  • fd <integer>

• callback <Function>

UDP ソケットの場合、dgram.Socketが、最初の引数として渡されるoptionsオブジェクトのプロパティとして渡される指定されたportとオプションのaddressでデータグラムメッセージをリッスンするようにします。portが指定されていないか、0の場合、オペレーティングシステムはランダムなポートへのバインドを試みます。addressが指定されていない場合、オペレーティングシステムはすべてのアドレスでリッスンしようとします。バインドが完了すると、'listening'イベントが発行され、オプションのcallback関数が呼び出されます。

optionsオブジェクトにはfdプロパティを含めることができます。fdが0より大きい値に設定されている場合、指定されたファイルディスクリプターを持つ既存のソケットをラップします。この場合、portとaddressのプロパティは無視されます。

'listening'イベントリスナーを指定し、socket.bind()メソッドにcallbackを渡すことは有害ではありませんが、あまり有用ではありません。

optionsオブジェクトには、clusterモジュールでdgram.Socketオブジェクトを使用する場合に使用される追加のexclusiveプロパティを含めることができます。exclusiveがfalse（デフォルト）に設定されている場合、クラスタワーカーは同じ基盤となるソケットハンドルを使用し、接続処理の義務を共有できます。ただし、exclusiveがtrueの場合、ハンドルは共有されず、ポートの共有を試みるとエラーが発生します。reusePortオプションがtrueに設定されたdgram.Socketを作成すると、socket.bind()が呼び出されたときに常にexclusiveがtrueになります。

バインドされたデータグラムソケットは、Node.js プロセスをデータグラムメッセージを受信するために実行し続けます。

バインドに失敗すると、'error'イベントが生成されます。まれに（例えば、クローズされたソケットでバインドしようとする場合）、Errorがスローされることがあります。

排他的なポートでリッスンしているソケットの例を以下に示します。

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true,
})

socket.close([callback])

追加: v0.1.99

• callback <Function> ソケットが閉じられたときに呼び出されます。

基になるソケットを閉じ、そのソケットでのデータのリッスンを停止します。callback が提供されている場合は、'close' イベントのリスナーとして追加されます。

socket[Symbol.asyncDispose]()

追加: v20.5.0, v18.18.0

[安定: 1 - 試験的]

安定: 1 安定性: 1 - 試験的

socket.close() を呼び出し、ソケットが閉じたときに解決される Promise を返します。

socket.connect(port[, address][, callback])

追加: v12.0.0

• port <integer>
• address <string>
• callback <Function> 接続が完了したとき、またはエラーが発生したときに呼び出されます。

dgram.Socket をリモートアドレスとポートに関連付けます。このハンドルによって送信されるすべてのメッセージは、自動的にその宛先に送信されます。また、ソケットはそのリモートピアからのメッセージのみを受信します。既に接続されているソケットで connect() を呼び出そうとすると、ERR_SOCKET_DGRAM_IS_CONNECTED 例外が発生します。address が指定されていない場合は、'127.0.0.1' (udp4 ソケットの場合) または '::1' (udp6 ソケットの場合) がデフォルトで使用されます。接続が完了すると、'connect' イベントが発行され、オプションの callback 関数が呼び出されます。失敗した場合は、callback が呼び出されるか、これが失敗した場合は 'error' イベントが発行されます。

socket.disconnect()

追加: v12.0.0

接続された dgram.Socket をそのリモートアドレスから関連付け解除する同期関数です。バインドされていない、または既に接続解除されているソケットで disconnect() を呼び出そうとすると、ERR_SOCKET_DGRAM_NOT_CONNECTED 例外が発生します。

socket.dropMembership(multicastAddress[, multicastInterface])

追加: v0.6.9

• multicastAddress <string>
• multicastInterface <string>

IP_DROP_MEMBERSHIPソケットオプションを使用して、multicastAddress でマルチキャストグループから離脱するようにカーネルに指示します。このメソッドは、ソケットが閉じられたり、プロセスが終了したりすると、カーネルによって自動的に呼び出されるため、ほとんどのアプリではこれを呼び出す理由はありません。

multicastInterface が指定されていない場合、オペレーティングシステムは、すべての有効なインターフェースでメンバーシップを削除しようとします。

socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])

追加: v13.1.0, v12.16.0

• sourceAddress <string>
• groupAddress <string>
• multicastInterface <string>

IP_DROP_SOURCE_MEMBERSHIPソケットオプションを使用して、指定された sourceAddress と groupAddress でソース固有のマルチキャストチャネルから離脱するようにカーネルに指示します。このメソッドは、ソケットが閉じられたり、プロセスが終了したりすると、カーネルによって自動的に呼び出されるため、ほとんどのアプリではこれを呼び出す理由はありません。

multicastInterface が指定されていない場合、オペレーティングシステムは、すべての有効なインターフェースでメンバーシップを削除しようとします。

socket.getRecvBufferSize()

追加: v8.7.0

• 戻り値: <number> バイト単位の SO_RCVBUF ソケット受信バッファサイズ。

このメソッドは、バインドされていないソケットで呼び出された場合、ERR_SOCKET_BUFFER_SIZE をスローします。

socket.getSendBufferSize()

追加: v8.7.0

• 戻り値: <number> バイト単位の SO_SNDBUF ソケット送信バッファサイズ。

このメソッドは、バインドされていないソケットで呼び出された場合、ERR_SOCKET_BUFFER_SIZE をスローします。

socket.getSendQueueSize()

追加: v18.8.0, v16.19.0

• 戻り値: <number> 送信待ちのキューに入っているバイト数。

socket.getSendQueueCount()

追加: v18.8.0, v16.19.0

• 戻り値: <number> 現在キューに入っており、処理を待っている送信リクエストの数。

socket.ref()

追加: v0.9.1

• 戻り値: <dgram.Socket>

デフォルトでは、ソケットをバインドすると、ソケットが開いている限り、Node.js プロセスが終了するのをブロックします。socket.unref() メソッドを使用すると、Node.js プロセスをアクティブに保つ参照カウントからソケットを除外できます。socket.ref() メソッドは、ソケットを参照カウントに戻し、デフォルトの動作を復元します。

socket.ref() を複数回呼び出しても、追加の効果はありません。

socket.ref() メソッドはソケットへの参照を返すため、呼び出しをチェーンできます。

socket.remoteAddress()

追加: v12.0.0

• 戻り値: <Object>

リモートエンドポイントの address、family、および port を含むオブジェクトを返します。ソケットが接続されていない場合、このメソッドは ERR_SOCKET_DGRAM_NOT_CONNECTED 例外をスローします。

socket.send(msg[, offset, length][, port][, address][, callback])

[履歴]

バージョン	変更点
v17.0.0	address パラメーターは string、null、または undefined のみを受け入れるようになりました。
v14.5.0, v12.19.0	msg パラメーターは、任意の TypedArray または DataView になりました。
v12.0.0	接続されたソケットでのデータ送信のサポートが追加されました。
v8.0.0	msg パラメーターは Uint8Array になりました。
v8.0.0	address パラメーターは常にオプションになりました。
v6.0.0	成功した場合、callback は 0 ではなく null の error 引数で呼び出されるようになりました。
v5.7.0	msg パラメーターは配列になりました。また、offset および length パラメーターはオプションになりました。
v0.1.99	追加: v0.1.99

• msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> 送信するメッセージ。
• offset <integer> メッセージが始まるバッファー内のオフセット。
• length <integer> メッセージ内のバイト数。
• port <integer> 宛先ポート。
• address <string> 宛先ホスト名または IP アドレス。
• callback <Function> メッセージが送信されたときに呼び出されます。

ソケットでデータグラムをブロードキャストします。コネクションレスソケットの場合、宛先 port と address を指定する必要があります。一方、接続されたソケットは、関連付けられたリモートエンドポイントを使用するため、port 引数と address 引数は設定しないでください。

msg 引数には、送信するメッセージが含まれます。その型に応じて、異なる動作が適用される場合があります。msg が Buffer、任意の TypedArray、または DataView の場合、offset と length は、メッセージが始まる Buffer 内のオフセットと、メッセージ内のバイト数をそれぞれ指定します。msg が String の場合、'utf8' エンコーディングで Buffer に自動的に変換されます。マルチバイト文字を含むメッセージの場合、offset と length は、文字位置ではなく バイト長 に関して計算されます。msg が配列の場合、offset と length は指定しないでください。

address 引数は文字列です。address の値がホスト名の場合、DNS が使用されてホストのアドレスが解決されます。address が指定されていないか、nullish の場合、デフォルトで '127.0.0.1' (udp4 ソケットの場合) または '::1' (udp6 ソケットの場合) が使用されます。

ソケットが bind の呼び出しによって以前にバインドされていない場合、ソケットにはランダムなポート番号が割り当てられ、「すべてのインターフェース」アドレス ('0.0.0.0' ( udp4 ソケットの場合)、'::0' ( udp6 ソケットの場合)) にバインドされます。

オプションの callback 関数は、DNS エラーを報告したり、buf オブジェクトを再利用しても安全な時期を判断したりする方法として指定できます。DNS ルックアップは、Node.js イベントループの少なくとも 1 つのティックに対して送信時間を遅延させます。

データグラムが送信されたことを確実に知る唯一の方法は、callback を使用することです。エラーが発生し、callback が指定されている場合、エラーは callback の最初の引数として渡されます。callback が指定されていない場合、エラーは socket オブジェクトで 'error' イベントとして発生します。

オフセットと長さはオプションですが、使用する場合は両方とも必ず設定する必要があります。これらは、最初の引数が Buffer、TypedArray、または DataView の場合にのみサポートされます。

このメソッドは、バインドされていないソケットで呼び出された場合、ERR_SOCKET_BAD_PORT をスローします。

localhost のポートに UDP パケットを送信する例を次に示します。

ESM

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

CJS

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

複数のバッファーで構成された UDP パケットを 127.0.0.1 のポートに送信する例を次に示します。

ESM

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

CJS

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

複数のバッファーの送信は、アプリケーションとオペレーティングシステムに応じて高速または低速になる可能性があります。ケースバイケースで最適な戦略を決定するには、ベンチマークを実行してください。ただし、一般的に言って、複数のバッファーを送信する方が高速です。

localhost のポートに接続されたソケットを使用して UDP パケットを送信する例を次に示します。

ESM

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

CJS

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

UDP データグラムサイズに関する注意

IPv4/v6 データグラムの最大サイズは、MTU（最大伝送ユニット）とペイロード長フィールドのサイズに依存します。

• ペイロード長フィールドは 16 ビット幅であり、インターネットヘッダーとデータを含む通常のペイロードは 64K オクテットを超えることはできません（65,507 バイト = 65,535 − 8 バイトの UDP ヘッダー − 20 バイトの IP ヘッダー）。これは一般的にループバックインターフェースに当てはまりますが、このような長いデータグラムメッセージは、ほとんどのホストやネットワークでは実用的ではありません。
• MTUは、特定のリンク層テクノロジーがデータグラムメッセージでサポートできる最大サイズです。どのリンクについても、IPv4 は最小MTUを 68 オクテットと規定していますが、IPv4 の推奨MTUは 576 です（通常、ダイヤルアップタイプのアプリケーションのMTUとして推奨されています）。これらは全体で到着する場合も、断片で到着する場合もあります。 IPv6 の場合、最小MTUは 1280 オクテットです。ただし、必須の最小フラグメント再構成バッファーサイズは 1500 オクテットです。 68 オクテットの値は非常に小さく、イーサネットのような現在のほとんどのリンク層テクノロジーでは、最小MTUは 1500 です。

パケットが通過する可能性のある各リンクの MTU を事前に知ることはできません。受信側のMTUよりも大きいデータグラムを送信すると、パケットは意図した受信者にデータが到達しなかったことを送信元に通知することなく、静かに破棄されるため、機能しません。

socket.setBroadcast(flag)

追加: v0.6.9

• flag <boolean>

SO_BROADCASTソケットオプションを設定またはクリアします。 trueに設定すると、UDP パケットをローカルインターフェースのブロードキャストアドレスに送信できます。

このメソッドは、バインドされていないソケットで呼び出されるとEBADFをスローします。

socket.setMulticastInterface(multicastInterface)

追加: v8.6.0

• multicastInterface <string>

このセクションのスコープへのすべての参照は、 IPv6 ゾーンインデックスを参照しています。これは、RFC 4007で定義されています。文字列形式では、スコープインデックス付きの IP は'IP%scope'として記述され、スコープはインターフェース名またはインターフェース番号です。

ソケットのデフォルトの送信マルチキャストインターフェースを選択したインターフェースに設定するか、システムインターフェース選択に戻します。 multicastInterfaceは、ソケットのファミリーからの IP の有効な文字列表現である必要があります。

IPv4 ソケットの場合、これは目的の物理インターフェース用に構成された IP である必要があります。ソケットでマルチキャストに送信されたすべてのパケットは、この呼び出しの最新の成功使用によって決定されたインターフェースで送信されます。

IPv6 ソケットの場合、multicastInterfaceには、後続の例のようにインターフェースを示すスコープを含める必要があります。 IPv6 では、個々のsend呼び出しでもアドレスに明示的なスコープを使用できるため、明示的なスコープを指定せずにマルチキャストアドレスに送信されたパケットのみが、この呼び出しの最新の成功使用の影響を受けます。

このメソッドは、バインドされていないソケットで呼び出されるとEBADFをスローします。

例: IPv6 発信マルチキャストインターフェース

ほとんどのシステムでは、スコープ形式はインターフェース名を使用します。

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%eth1')
})

Windows では、スコープ形式はインターフェース番号を使用します。

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%2')
})

例: IPv4 発信マルチキャストインターフェース

すべてのシステムは、目的の物理インターフェース上のホストの IP を使用します。

const socket = dgram.createSocket('udp4')

socket.bind(1234, () => {
  socket.setMulticastInterface('10.0.0.2')
})

呼び出し結果

送信準備ができていないソケット、または開いていないソケットでの呼び出しは、Not running Error をスローする可能性があります。

multicastInterface が IP に解析できない場合、EINVAL System Error がスローされます。

IPv4 では、multicastInterface が有効なアドレスであっても、どのインターフェースとも一致しない場合、またはアドレスがファミリと一致しない場合は、EADDRNOTAVAIL や EPROTONOSUP などのSystem Error がスローされます。

IPv6 では、スコープの指定または省略に関するほとんどのエラーは、ソケットがシステムのデフォルトのインターフェース選択を使用し続ける（または戻る）結果になります。

ソケットのアドレスファミリの ANY アドレス（IPv4 '0.0.0.0' または IPv6 '::'）を使用して、将来のマルチキャストパケットのために、ソケットのデフォルトの発信インターフェースの制御をシステムに戻すことができます。

socket.setMulticastLoopback(flag)

追加: v0.3.8

• flag <boolean>

IP_MULTICAST_LOOP ソケットオプションを設定またはクリアします。true に設定すると、マルチキャストパケットはローカルインターフェースでも受信されます。

このメソッドは、バインドされていないソケットで呼び出された場合、EBADF をスローします。

socket.setMulticastTTL(ttl)

追加: v0.3.8

• ttl <integer>

IP_MULTICAST_TTL ソケットオプションを設定します。TTL は一般的に "Time to Live" を意味しますが、このコンテキストでは、特にマルチキャストトラフィックの場合、パケットが通過できる IP ホップ数を指定します。パケットを転送する各ルーターまたはゲートウェイは、TTL をデクリメントします。TTL がルーターによって 0 にデクリメントされた場合、転送されません。

ttl 引数は 0 から 255 の範囲で指定できます。ほとんどのシステムでのデフォルトは 1 です。

このメソッドは、バインドされていないソケットで呼び出された場合、EBADF をスローします。

socket.setRecvBufferSize(size)

追加: v8.7.0

• size <integer>

SO_RCVBUF ソケットオプションを設定します。ソケットの最大受信バッファをバイト単位で設定します。

このメソッドは、バインドされていないソケットで呼び出された場合、ERR_SOCKET_BUFFER_SIZE をスローします。

socket.setSendBufferSize(size)

追加: v8.7.0

• size <integer>

SO_SNDBUF ソケットオプションを設定します。ソケットの最大送信バッファをバイト単位で設定します。

このメソッドは、バインドされていないソケットで呼び出された場合、ERR_SOCKET_BUFFER_SIZE をスローします。

socket.setTTL(ttl)

追加: v0.1.101

• ttl <integer>

IP_TTL ソケットオプションを設定します。TTL は一般に「Time to Live（生存時間）」を意味しますが、このコンテキストでは、パケットが通過できる IP ホップ数を指定します。パケットを転送する各ルータまたはゲートウェイは TTL をデクリメントします。ルータによって TTL が 0 にデクリメントされた場合、パケットは転送されません。TTL 値の変更は、通常、ネットワークプローブまたはマルチキャスト時に行われます。

ttl 引数は 1 から 255 の間で指定できます。ほとんどのシステムでのデフォルトは 64 です。

このメソッドは、バインドされていないソケットで呼び出された場合、EBADF をスローします。

socket.unref()

追加: v0.9.1

• 戻り値: <dgram.Socket>

デフォルトでは、ソケットをバインドすると、ソケットが開いている限り、Node.js プロセスが終了するのをブロックします。socket.unref() メソッドを使用すると、ソケットが Node.js プロセスをアクティブに保つ参照カウントから除外でき、ソケットがまだリッスンしている場合でもプロセスを終了させることができます。

socket.unref() を複数回呼び出しても、追加の効果はありません。

socket.unref() メソッドは、呼び出しをチェーンできるようにソケットへの参照を返します。

node:dgram モジュール関数

dgram.createSocket(options[, callback])

[履歴]

バージョン	変更点
v23.1.0	reusePort オプションがサポートされました。
v15.8.0	AbortSignal のサポートが追加されました。
v11.4.0	ipv6Only オプションがサポートされました。
v8.7.0	recvBufferSize および sendBufferSize オプションがサポートされました。
v8.6.0	lookup オプションがサポートされました。
v0.11.13	追加: v0.11.13

• options <Object> 利用可能なオプションは次のとおりです。

  • type <string> ソケットのファミリー。'udp4' または 'udp6' のいずれかでなければなりません。必須です。
  • reuseAddr <boolean> true の場合、socket.bind() は、別のプロセスがすでにソケットをバインドしている場合でも、アドレスを再利用しますが、データを受信できるのは 1 つのソケットのみです。デフォルト: false。
  • reusePort <boolean> true の場合、socket.bind() は、別のプロセスがすでにソケットをバインドしている場合でも、ポートを再利用します。着信データグラムは、リスニングソケットに配信されます。このオプションは、Linux 3.9+、DragonFlyBSD 3.6+、FreeBSD 12.0+、Solaris 11.4、AIX 7.2.5+ など、一部のプラットフォームでのみ使用できます。サポートされていないプラットフォームでは、ソケットがバインドされると、このオプションでエラーが発生します。デフォルト: false。
  • ipv6Only <boolean> ipv6Only を true に設定すると、デュアルスタックのサポートが無効になります。つまり、アドレス :: にバインドしても、0.0.0.0 がバインドされることはありません。デフォルト: false。
  • recvBufferSize <number> SO_RCVBUF ソケット値を設定します。
  • sendBufferSize <number> SO_SNDBUF ソケット値を設定します。
  • lookup <Function> カスタムルックアップ関数。デフォルト: dns.lookup()。
  • signal <AbortSignal> ソケットを閉じるために使用できる AbortSignal。
  • receiveBlockList <net.BlockList> receiveBlockList は、特定の IP アドレス、IP 範囲、または IP サブネットへの着信データグラムを破棄するために使用できます。サーバーがリバースプロキシ、NAT などの背後にある場合、ブロックリストに対してチェックされるアドレスはプロキシのアドレス、または NAT で指定されたアドレスであるため、これは機能しません。
  • sendBlockList <net.BlockList> sendBlockList は、特定の IP アドレス、IP 範囲、または IP サブネットへのアウトバウンドアクセスを無効にするために使用できます。

• callback <Function> 'message' イベントのリスナーとしてアタッチされます。オプション。

• 戻り値: <dgram.Socket>

dgram.Socket オブジェクトを作成します。ソケットが作成されたら、socket.bind() を呼び出すと、ソケットがデータグラムメッセージのリスニングを開始するように指示されます。address および port が socket.bind() に渡されない場合、このメソッドはランダムなポート上の「すべてのインターフェース」アドレスにソケットをバインドします (udp4 と udp6 の両方のソケットに対して正しい処理を行います)。バインドされたアドレスとポートは、socket.address().address および socket.address().port を使用して取得できます。

signal オプションが有効になっている場合、対応する AbortController で .abort() を呼び出すことは、ソケットで .close() を呼び出すのと似ています。

const controller = new AbortController()
const { signal } = controller
const server = dgram.createSocket({ type: 'udp4', signal })
server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})
// 後で、サーバーを閉じたい場合。
controller.abort()

dgram.createSocket(type[, callback])

追加: v0.1.99

• type <string> 'udp4' または 'udp6' のいずれか。
• callback <Function> 'message' イベントのリスナーとしてアタッチされます。
• 戻り値: <dgram.Socket>

指定された type の dgram.Socket オブジェクトを作成します。

ソケットが作成されると、socket.bind() を呼び出すと、ソケットがデータグラムメッセージの受信を開始するように指示されます。address と port が socket.bind() に渡されない場合、メソッドはランダムなポートで「すべてのインターフェース」アドレスにソケットをバインドします（udp4 および udp6 ソケットの両方で正しい処理を行います）。バインドされたアドレスとポートは、socket.address().address と socket.address().port を使用して取得できます。