###### (This function is part of SDL_net, a separate library from SDL.)
# NET_CreateDatagramSocket

Create and bind a new datagram socket.

## Header File

Defined in [<SDL3_net/SDL_net.h>](https://github.com/libsdl-org/SDL_net/blob/main/include/SDL3_net/SDL_net.h)

## Syntax

```c
NET_DatagramSocket * NET_CreateDatagramSocket(NET_Address *addr, Uint16 port, SDL_PropertiesID props);


#define NET_PROP_DATAGRAM_SOCKET_REUSEADDR_BOOLEAN         "NET.datagram_socket.reuseaddr"
#define NET_PROP_DATAGRAM_SOCKET_ALLOW_BROADCAST_BOOLEAN   "NET.datagram_socket.allow_broadcast"
```

## Function Parameters

|                              |           |                                                                                                     |
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------- |
| [NET_Address](NET_Address) * | **addr**  | the local address to listen for connections on, or NULL to listen on all available local addresses. |
| Uint16                       | **port**  | the port on the local address to listen for connections on, or zero for the system to decide.       |
| SDL_PropertiesID             | **props** | properties of the new socket. Specify zero for defaults.                                            |

## Return Value

([NET_DatagramSocket](NET_DatagramSocket) *) Returns a new
[NET_DatagramSocket](NET_DatagramSocket), or NULL on error; call
SDL_GetError() for details.

## Remarks

Datagram sockets follow different rules than stream sockets. They are not a
reliable stream of bytes but rather packets, they are not limited to
talking to a single other remote system, they do not maintain a single
"connection" that can be dropped, and they are more nimble about network
failures at the expense of being more complex to use. What makes sense for
your app depends entirely on what your app is trying to accomplish.

Generally the idea of a datagram socket is that you send data one chunk
("packet") at a time to any address you want, and it arrives whenever it
gets there, even if later packets get there first, and maybe it doesn't get
there at all, and you don't know when anything of this happens by default.

This function creates a new datagram socket.

This function does not block, and is not asynchronous, as the system can
decide immediately if it can create a socket or not. If this returns
success, you can immediately start talking to the network.

You can specify an address to listen for connections on; this address must
be local to the system, and probably one returned by
[NET_GetLocalAddresses](NET_GetLocalAddresses)(), but almost always you
just want to specify NULL here, to listen on any address available to the
app.

If you need to bind to a specific port (like a server), you should specify
it in the `port` argument; datagram servers should do this, so they can be
reached at a well-known port. If you only plan to initiate communications
(like a client), you should specify 0 and let the system pick an unused
port. Only one process can bind to a specific port at a time, so if you
aren't acting as a server, you should choose 0. Datagram sockets can send
individual packets to any port, so this just declares where data will
arrive for your socket.

Datagram sockets don't employ any protocol (above the UDP level), so they
can talk to apps that aren't using SDL_net, but if you want to speak any
protocol beyond arbitrary packets of bytes, such as WebRTC, you'll have to
implement that yourself on top of the stream socket.

Unlike BSD sockets or WinSock, you specify the port as a normal integer;
you do not have to byteswap it into "network order," as the library will
handle that for you.

The caller may supply properties to customize behavior. This is optional,
and a value of zero for `props` will request defaults for all properties.

These are the supported properties:

- [`NET_PROP_DATAGRAM_SOCKET_REUSEADDR_BOOLEAN`](NET_PROP_DATAGRAM_SOCKET_REUSEADDR_BOOLEAN):
  true if the socket should be created even if a previous socket has
  recently used this address. For various reasons, networks prefer that
  there be some delay between apps reusing the same address, but this can
  be problematic when iterating quickly, for software development purposes
  or just restarting a crashed service. This property defaults to true
  (although it should be noted that, at the operating system level, this
  defaults to false!). If this property is false and the OS feels that not
  enough time has elapsed, socket creation will fail and this function will
  report an error.
- [`NET_PROP_DATAGRAM_SOCKET_ALLOW_BROADCAST_BOOLEAN`](NET_PROP_DATAGRAM_SOCKET_ALLOW_BROADCAST_BOOLEAN):
  true if the socket should allow broadcasting. At the lower level, this
  will set `SO_BROADCAST` for IPv4 sockets, to allow sending to the
  subnet's broadcast address at the OS level. For IPv6, it'll join the
  all-nodes link-local multicast group, ff02::1, allowing sending and
  receiving there, more or less simulating the usual IPv4 broadcast
  semantics. Other protocols take similar approaches. If you do not intend
  to send or receive broadcast packets on this socket, set this property to
  false, or omit it, as it defaults to false. Note: IPv4 will still be able
  to receive broadcast packets without this option, but IPv6 will not. Also
  see notes about sending to a broadcast address in
  [NET_SendDatagram](NET_SendDatagram)().

## Thread Safety

It is safe to call this function from any thread.

## Version

This function is available since SDL_net 3.0.0.

## See Also

- [NET_GetLocalAddresses](NET_GetLocalAddresses)
- [NET_DestroyDatagramSocket](NET_DestroyDatagramSocket)

----
[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategorySDLNet](CategorySDLNet)

