Sets or clears the socket option.
When set to, UDP packets may be sent to a local interface's broadcast address.
Note: All references to scope in this section are referring to IPv6 Zone Indices, which are defined by
In string form, an IP with a scope index is written as where scope is an interface name or interface number.
Sets the default outgoing multicast interface of the socket to a chosen interface or back to system interface selection.
The must be a valid string representation of an IP from the socket's family.
For IPv4 sockets, this should be the IP configured for the desired physical interface. All packets sent to multicast on the socket will be sent on the interface determined by the most recent successful use of this call.
For IPv6 sockets, should include a scope to indicate the interface as in the examples that follow.
In IPv6, individual calls can also use explicit scope in addresses, so only packets sent to a multicast address without specifying an explicit scope are affected by the most recent successful use of this call.
On most systems, where scope format uses the interface name:
On Windows, where scope format uses an interface number:
All systems use an IP of the host on the desired physical interface:
A call on a socket that is not ready to send or no longer open may throw a Not running
If can not be parsed into an IP then an is thrown.
On IPv4, if is a valid address but does not match any interface, or if the address does not match the family then a such as or is thrown.
On IPv6, most errors with specifying or omitting scope will result in the socket continuing to use (or returning to) the system's default interface selection.
A socket's address family's ANY address can be used to return control of the sockets default outgoing interface to the system for future multicast packets.
When set to multicast packets will also be received on the local interface.
While TTL generally stands for "Time to Live", in this context it specifies the number of IP hops that a packet is allowed to travel through, specifically for multicast traffic. Each router or gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.
The argument passed to is a number of hops between 0 and 255.
The default on most systems is but can vary.
Sets the maximum socket receive buffer in bytes.
Each router or gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. Changing TTL values is typically done for network probes or when multicasting.
By default, binding a socket will cause it to block the Node.js process from exiting as long as the socket is open.
The method can be used to exclude the socket from the reference counting that keeps the Node.js process active, allowing the process to exit even if the socket is still listening.
Calling multiple times will have no addition effect.
The method returns a reference to the socket so calls can be chained.
Change to asynchronous behavior
As of Node.js v0.10, changed to an asynchronous execution model.
Legacy code that assumes synchronous behavior, as in the following example:
Must be changed to pass a callback function to the function:
Available options are:
When will reuse the address, even if another process has already bound a socket on it.
Sets the socket value.
Custom lookup function.
Attached as a listener for events.
Creates a object.
Once the socket is created, calling will instruct the socket to begin listening for datagram messages.
When and are not passed to the method will bind the socket to the "all interfaces" address on a random port (it does the right thing for both and sockets).
The bound address and port can be retrieved using and
An optional function can be passed which is added as a listener for events.
About this Documentation
The goal of this documentation is to comprehensively explain the Node.js API, both from a reference as well as a conceptual point of view. Each section describes a built-in module or high-level concept.
Where appropriate, property types, method arguments, and the arguments provided to event handlers are detailed in a list underneath the topic heading.
If errors are found in this documentation, please submit an issue or see the contributing guide for directions on how to submit a patch.
Every file is generated based on the corresponding file in the folder in Node.js's source tree.
The documentation is generated using the program.
An HTML template is located at
Throughout the documentation are indications of a section's stability. The Node.js API is still somewhat changing, and as it matures, certain parts are more reliable than others. Some are so proven, and so relied upon, that they are unlikely to ever change at all. Others are brand new and experimental, or known to be hazardous and in the process of being redesigned.
The stability indices are as follows:
Stability: 0 - Deprecated. This feature is known to be problematic, and changes may be planned. Do not rely on it. Use of the feature may cause warnings to be emitted. Backwards compatibility across major versions should not be expected.
Stability: 1 - Experimental. This feature is still under active development and subject to non-backwards compatible changes, or even removal, in any future version. Use of the feature is not recommended in production environments. Experimental features are not subject to the Node.js Semantic Versioning model.
Stability: 2 - Stable. The API has proven satisfactory. Compatibility with the npm ecosystem is a high priority, and will not be broken unless absolutely necessary.
Caution must be used when making use of features, particularly within modules that may be used as dependencies (or dependencies of dependencies) within a Node.js application.
End users may not be aware that experimental features are being used, and therefore may experience unexpected failures or behavior changes when API modifications occur.
To help avoid such surprises, features may require a command-line flag to explicitly enable them, or may cause a process warning to be emitted.
By default, such warnings are printed to and may be handled by attaching a listener to the event.
Every document has a corresponding document presenting the same information in a structured manner.
This feature is experimental, and added for the benefit of IDEs and other utilities that wish to do programmatic things with the documentation.
Syscalls and man pages
System calls like and define the interface between user programs and the underlying operating system.
Node.js functions which simply wrap a syscall, like, will document that.
The docs link to the corresponding man pages (short for manual pages) which describe how the syscalls work.
Some syscalls, like, are BSD-specific.
That means, for example, that only works on macOS and other BSD-derived systems, and is not available on Linux.
Most Unix syscalls have Windows equivalents, but behavior may differ on Windows relative to Linux and macOS.
For an example of the subtle ways in which it's sometimes impossible to replace Unix syscall semantics on Windows, see