14.3.2 UDP

For information about UDP in general, see TCP/IP Illustrated, Volume 1 by W. Richard Stevens.

If family-hostname or family-port-no is not #f, then the socket’s protocol family is determined from these arguments. The socket is not bound to the hostname or port number. For example, the arguments might be the hostname and port to which messages will be sent through the socket, which ensures that the socket’s protocol family is consistent with the destination. Alternately, the arguments might be the same as for a future call to udp-bind!, which ensures that the socket’s protocol family is consistent with the binding. If neither family-hostname nor family-port-no is non-#f, then the socket’s protocol family is IPv4.

If hostname-string is #f, then the socket accepts connections to all of the listening machine’s IP addresses at port-no. Otherwise, the socket accepts connections only at the IP address associated with the given name. For example, providing "127.0.0.1" as hostname-string typically creates a listener that accepts only connections to "127.0.0.1" from the local machine.

A socket cannot receive datagrams until it is bound to a local address and port. If a socket is not bound before it is used with a sending procedure udp-send, udp-send-to, etc., the sending procedure binds the socket to a random local port. Similarly, if an event from udp-send-evt or udp-send-to-evt is chosen for a synchronization (see Events), the socket is bound; if the event is not chosen, the socket may or may not become bound.

The binding of a bound socket cannot be changed, with one exception: on some systems, if the socket is bound automatically when sending, if the socket is disconnected via udp-connect!, and if the socket is later used again in a send, then the later send may change the socket’s automatic binding.

If udp-socket is already bound or closed, the exn:fail:network exception is raised.

If the reuse? argument is true, then udp-bind! will set the SO_REUSEADDR socket option before binding, permitting the sharing of access to a UDP port between many processes on a single machine when using UDP multicast.

If hostname-string is #f, then port-no also must be #f, and the port is disconnected (if connected). If one of hostname-string or port-no is #f and the other is not, the exn:fail:contract exception is raised.

A connected socket can be used with udp-send (not udp-send-to), and it accepts datagrams only from the connected address and port. A socket need not be connected to receive datagrams. A socket can be connected, re-connected, and disconnected any number of times.

If udp-socket is closed, the exn:fail:network exception is raised.

If start-pos is greater than the length of bstr, or if end-pos is less than start-pos or greater than the length of bstr, the exn:fail:contract exception is raised.

If udp-socket is closed or connected, the exn:fail:network exception is raised.

Three values are returned: the number of received bytes (between 0 and end-pos-start-pos, a hostname string indicating the source address of the datagram, and an integer indicating the source port of the datagram. If the received datagram is longer than end-pos-start-pos bytes, the remainder is discarded.

If start-pos is greater than the length of bstr, or if end-pos is less than start-pos or greater than the length of bstr, the exn:fail:contract exception is raised.

If port-numbers? is true, then four results are returned: a string for the local machine’s address, an exact integer between 1 and 65535 for the local machine’s port number or 0 if the socket is unbound, a string for the remote machine’s address, and an exact integer between 1 and 65535 for the remote machine’s port number or 0 if the socket is unconnected.

If the given port has been closed, the exn:fail:network exception is raised.

The multicast-addr argument must be a valid IPv4 multicast IP address; for example, "224.0.0.251" is the appropriate address for the mDNS protocol. The hostname argument selects the interface that the socket uses to receive (not send) multicast datagrams; if hostname is #f or "0.0.0.0", the kernel selects an interface automatically.

Leaving a group requires the same multicast-addr and hostname arguments that were used to join the group.

Sets or checks whether udp-socket receives its own multicast datagrams: a #t result or a true value for loopback? indicates that self-receipt is enabled, and #f indicates that self-receipt is disabled.

Sets or retrieves the current time-to-live setting of udp-socket.

The time-to-live setting should almost always be 1, and it is important that this number is as low as possible. In fact, these functions seldom should be used at all. See the documentation for your platform’s IP stack.