micropython · dpgeorge · Jun 3, 2025 · May 16, 2025 · May 16, 2025 · May 16, 2025
diff --git a/docs/library/socket.rst b/docs/library/socket.rst
@@ -227,22 +227,28 @@ Methods
    has the same "no short writes" policy for blocking sockets, and will return
    number of bytes sent on non-blocking sockets.
 
-.. method:: socket.recv(bufsize)
+.. method:: socket.recv(bufsize, [flags])
 
    Receive data from the socket. The return value is a bytes object representing the data
    received. The maximum amount of data to be received at once is specified by bufsize.
 
+   Most ports support the optional *flags* argument. Available *flags* are defined as constants
+   in the socket module and have the same meaning as in CPython. ``MSG_PEEK`` and ``MSG_DONTWAIT``
+   are supported on all ports which accept the *flags* argument.
+
 .. method:: socket.sendto(bytes, address)
 
    Send data to the socket. The socket should not be connected to a remote socket, since the
    destination socket is specified by *address*.
 
-.. method:: socket.recvfrom(bufsize)
+.. method:: socket.recvfrom(bufsize, [flags])
 
   Receive data from the socket. The return value is a pair *(bytes, address)* where *bytes* is a
   bytes object representing the data received and *address* is the address of the socket sending
   the data.
 
+  See the `recv` function for an explanation of the optional *flags* argument.
+
 .. method:: socket.setsockopt(level, optname, value)
 
    Set the value of the given socket option. The needed symbolic constants are defined in the

diff --git a/extmod/modlwip.c b/extmod/modlwip.c
@@ -70,6 +70,10 @@
 
 #define TCP_NODELAY TF_NODELAY
 
+// Socket flags
+#define MSG_PEEK     0x01
+#define MSG_DONTWAIT 0x02
+
 // For compatibilily with older lwIP versions.
 #ifndef ip_set_option
 #define ip_set_option(pcb, opt)   ((pcb)->so_options |= (opt))
@@ -673,13 +677,13 @@ static mp_uint_t lwip_raw_udp_send(lwip_socket_obj_t *socket, const byte *buf, m
 }
 
 // Helper function for recv/recvfrom to handle raw/UDP packets
-static mp_uint_t lwip_raw_udp_receive(lwip_socket_obj_t *socket, byte *buf, mp_uint_t len, ip_addr_t *ip, mp_uint_t *port, int *_errno) {
+static mp_uint_t lwip_raw_udp_receive(lwip_socket_obj_t *socket, byte *buf, mp_uint_t len, mp_int_t flags, ip_addr_t *ip, mp_uint_t *port, int *_errno) {
 
     lwip_incoming_packet_t *slot = &socket->incoming.udp_raw.array[socket->incoming.udp_raw.iget];
 
     if (slot->pbuf == NULL) {
-        if (socket->timeout == 0) {
-            // Non-blocking socket.
+        // Non-blocking socket or flag
+        if (socket->timeout == 0 || (flags & MSG_DONTWAIT)) {
             *_errno = MP_EAGAIN;
             return -1;
         }
@@ -705,9 +709,11 @@ static mp_uint_t lwip_raw_udp_receive(lwip_socket_obj_t *socket, byte *buf, mp_u
     MICROPY_PY_LWIP_ENTER
 
     u16_t result = pbuf_copy_partial(p, buf, ((p->tot_len > len) ? len : p->tot_len), 0);
-    pbuf_free(p);
-    slot->pbuf = NULL;
-    socket->incoming.udp_raw.iget = (socket->incoming.udp_raw.iget + 1) % LWIP_INCOMING_PACKET_QUEUE_LEN;
+    if ((flags & MSG_PEEK) == 0) {
+        pbuf_free(p);
+        slot->pbuf = NULL;
+        socket->incoming.udp_raw.iget = (socket->incoming.udp_raw.iget + 1) % LWIP_INCOMING_PACKET_QUEUE_LEN;
+    }
 
     MICROPY_PY_LWIP_EXIT
 
@@ -815,14 +821,14 @@ static mp_uint_t lwip_tcp_send(lwip_socket_obj_t *socket, const byte *buf, mp_ui
 }
 
 // Helper function for recv/recvfrom to handle TCP packets
-static mp_uint_t lwip_tcp_receive(lwip_socket_obj_t *socket, byte *buf, mp_uint_t len, int *_errno) {
+static mp_uint_t lwip_tcp_receive(lwip_socket_obj_t *socket, byte *buf, mp_uint_t len, mp_int_t flags, int *_errno) {
     // Check for any pending errors
     STREAM_ERROR_CHECK(socket);
 
     if (socket->incoming.tcp.pbuf == NULL) {
 
-        // Non-blocking socket
-        if (socket->timeout == 0) {
+        // Non-blocking socket or flag
+        if (socket->timeout == 0 || (flags & MSG_DONTWAIT)) {
             if (socket->state == STATE_PEER_CLOSED) {
                 return 0;
             }
@@ -867,19 +873,21 @@ static mp_uint_t lwip_tcp_receive(lwip_socket_obj_t *socket, byte *buf, mp_uint_
 
     memcpy(buf, (byte *)p->payload + socket->recv_offset, len);
 
-    remaining -= len;
-    if (remaining == 0) {
-        socket->incoming.tcp.pbuf = p->next;
-        // If we don't ref here, free() will free the entire chain,
-        // if we ref, it does what we need: frees 1st buf, and decrements
-        // next buf's refcount back to 1.
-        pbuf_ref(p->next);
-        pbuf_free(p);
-        socket->recv_offset = 0;
-    } else {
-        socket->recv_offset += len;
+    if ((flags & MSG_PEEK) == 0) {
+        remaining -= len;
+        if (remaining == 0) {
+            socket->incoming.tcp.pbuf = p->next;
+            // If we don't ref here, free() will free the entire chain,
+            // if we ref, it does what we need: frees 1st buf, and decrements
+            // next buf's refcount back to 1.
+            pbuf_ref(p->next);
+            pbuf_free(p);
+            socket->recv_offset = 0;
+        } else {
+            socket->recv_offset += len;
+        }
+        tcp_recved(socket->pcb.tcp, len);
     }
-    tcp_recved(socket->pcb.tcp, len);
 
     MICROPY_PY_LWIP_EXIT
 
@@ -1271,40 +1279,58 @@ static mp_obj_t lwip_socket_send(mp_obj_t self_in, mp_obj_t buf_in) {
 }
 static MP_DEFINE_CONST_FUN_OBJ_2(lwip_socket_send_obj, lwip_socket_send);
 
-static mp_obj_t lwip_socket_recv(mp_obj_t self_in, mp_obj_t len_in) {
-    lwip_socket_obj_t *socket = MP_OBJ_TO_PTR(self_in);
+// Common implementation for recv & recvfrom
+static mp_obj_t lwip_socket_recv_common(size_t n_args, const mp_obj_t *args, ip_addr_t *ip, mp_uint_t *port) {
+    lwip_socket_obj_t *socket = MP_OBJ_TO_PTR(args[0]);
+    mp_int_t len = mp_obj_get_int(args[1]);
+    mp_int_t flags = n_args > 2 ? mp_obj_get_int(args[2]) : 0;
     int _errno;
+    vstr_t vstr;
+    mp_uint_t ret = 0;
 
     lwip_socket_check_connected(socket);
 
-    mp_int_t len = mp_obj_get_int(len_in);
-    vstr_t vstr;
     vstr_init_len(&vstr, len);
 
-    mp_uint_t ret = 0;
     switch (socket->type) {
-        case MOD_NETWORK_SOCK_STREAM: {
-            ret = lwip_tcp_receive(socket, (byte *)vstr.buf, len, &_errno);
+        case MOD_NETWORK_SOCK_STREAM:
+            if (ip != NULL) {
+                *ip = socket->tcp_peer_addr;
+                *port = (mp_uint_t)socket->tcp_peer_port;
+            }
+            ret = lwip_tcp_receive(socket, (byte *)vstr.buf, len, flags, &_errno);
             break;
-        }
         case MOD_NETWORK_SOCK_DGRAM:
         #if MICROPY_PY_LWIP_SOCK_RAW
         case MOD_NETWORK_SOCK_RAW:
         #endif
-            ret = lwip_raw_udp_receive(socket, (byte *)vstr.buf, len, NULL, NULL, &_errno);
+            ret = lwip_raw_udp_receive(socket, (byte *)vstr.buf, len, flags, ip, port, &_errno);
             break;
     }
     if (ret == -1) {
         mp_raise_OSError(_errno);
     }
-
     if (ret == 0) {
         return mp_const_empty_bytes;
     }
     vstr.len = ret;
     return mp_obj_new_bytes_from_vstr(&vstr);
 }
-static MP_DEFINE_CONST_FUN_OBJ_2(lwip_socket_recv_obj, lwip_socket_recv);
+
+static mp_obj_t lwip_socket_recv(size_t n_args, const mp_obj_t *args) {
+    return lwip_socket_recv_common(n_args, args, NULL, NULL);
+}
+static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(lwip_socket_recv_obj, 2, 3, lwip_socket_recv);
+
+static mp_obj_t lwip_socket_recvfrom(size_t n_args, const mp_obj_t *args) {
+    ip_addr_t ip;
+    mp_uint_t port;
+    mp_obj_t tuple[2];
+    tuple[0] = lwip_socket_recv_common(n_args, args, &ip, &port);
+    tuple[1] = lwip_format_inet_addr(&ip, port);
+    return mp_obj_new_tuple(2, tuple);
+}
+static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(lwip_socket_recvfrom_obj, 2, 3, lwip_socket_recvfrom);
 
 static mp_obj_t lwip_socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_in) {
     lwip_socket_obj_t *socket = MP_OBJ_TO_PTR(self_in);
@@ -1339,50 +1365,6 @@ static mp_obj_t lwip_socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t
 }
 static MP_DEFINE_CONST_FUN_OBJ_3(lwip_socket_sendto_obj, lwip_socket_sendto);
 
-static mp_obj_t lwip_socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) {
-    lwip_socket_obj_t *socket = MP_OBJ_TO_PTR(self_in);
-    int _errno;
-
-    lwip_socket_check_connected(socket);
-
-    mp_int_t len = mp_obj_get_int(len_in);
-    vstr_t vstr;
-    vstr_init_len(&vstr, len);
-    ip_addr_t ip;
-    mp_uint_t port;
-
-    mp_uint_t ret = 0;
-    switch (socket->type) {
-        case MOD_NETWORK_SOCK_STREAM: {
-            ip = socket->tcp_peer_addr;
-            port = (mp_uint_t)socket->tcp_peer_port;
-            ret = lwip_tcp_receive(socket, (byte *)vstr.buf, len, &_errno);
-            break;
-        }
-        case MOD_NETWORK_SOCK_DGRAM:
-        #if MICROPY_PY_LWIP_SOCK_RAW
-        case MOD_NETWORK_SOCK_RAW:
-        #endif
-            ret = lwip_raw_udp_receive(socket, (byte *)vstr.buf, len, &ip, &port, &_errno);
-            break;
-    }
-    if (ret == -1) {
-        mp_raise_OSError(_errno);
-    }
-
-    mp_obj_t tuple[2];
-    if (ret == 0) {
-        tuple[0] = mp_const_empty_bytes;
-    } else {
-        vstr.len = ret;
-        tuple[0] = mp_obj_new_bytes_from_vstr(&vstr);
-    }
-    tuple[1] = lwip_format_inet_addr(&ip, port);
-
-    return mp_obj_new_tuple(2, tuple);
-}
-static MP_DEFINE_CONST_FUN_OBJ_2(lwip_socket_recvfrom_obj, lwip_socket_recvfrom);
-
 static mp_obj_t lwip_socket_sendall(mp_obj_t self_in, mp_obj_t buf_in) {
     lwip_socket_obj_t *socket = MP_OBJ_TO_PTR(self_in);
     lwip_socket_check_connected(socket);
@@ -1542,12 +1524,12 @@ static mp_uint_t lwip_socket_read(mp_obj_t self_in, void *buf, mp_uint_t size, i
 
     switch (socket->type) {
         case MOD_NETWORK_SOCK_STREAM:
-            return lwip_tcp_receive(socket, buf, size, errcode);
+            return lwip_tcp_receive(socket, buf, size, 0, errcode);
         case MOD_NETWORK_SOCK_DGRAM:
         #if MICROPY_PY_LWIP_SOCK_RAW
         case MOD_NETWORK_SOCK_RAW:
         #endif
-            return lwip_raw_udp_receive(socket, buf, size, NULL, NULL, errcode);
+            return lwip_raw_udp_receive(socket, buf, size, 0, NULL, NULL, errcode);
     }
     // Unreachable
     return MP_STREAM_ERROR;
@@ -1919,6 +1901,8 @@ static const mp_rom_map_elem_t mp_module_lwip_globals_table[] = {
 
     { MP_ROM_QSTR(MP_QSTR_IPPROTO_TCP), MP_ROM_INT(IP_PROTO_TCP) },
     { MP_ROM_QSTR(MP_QSTR_TCP_NODELAY), MP_ROM_INT(TCP_NODELAY) },
+    { MP_ROM_QSTR(MP_QSTR_MSG_PEEK), MP_ROM_INT(MSG_PEEK) },
+    { MP_ROM_QSTR(MP_QSTR_MSG_DONTWAIT), MP_ROM_INT(MSG_DONTWAIT) },
 };
 
 static MP_DEFINE_CONST_DICT(mp_module_lwip_globals, mp_module_lwip_globals_table);

diff --git a/ports/esp32/modsocket.c b/ports/esp32/modsocket.c
@@ -611,7 +611,7 @@ static MP_DEFINE_CONST_FUN_OBJ_2(socket_setblocking_obj, socket_setblocking);
 // XXX this can end up waiting a very long time if the content is dribbled in one character
 // at a time, as the timeout resets each time a recvfrom succeeds ... this is probably not
 // good behaviour.
-static mp_uint_t _socket_read_data(mp_obj_t self_in, void *buf, size_t size,
+static mp_uint_t _socket_read_data(mp_obj_t self_in, void *buf, size_t size, mp_int_t flags,
     struct sockaddr *from, socklen_t *from_len, int *errcode) {
     socket_obj_t *sock = MP_OBJ_TO_PTR(self_in);
 
@@ -645,7 +645,7 @@ static mp_uint_t _socket_read_data(mp_obj_t self_in, void *buf, size_t size,
         if (release_gil) {
             MP_THREAD_GIL_EXIT();
         }
-        int r = lwip_recvfrom(sock->fd, buf, size, 0, from, from_len);
+        int r = lwip_recvfrom(sock->fd, buf, size, flags, from, from_len);
         if (release_gil) {
             MP_THREAD_GIL_ENTER();
         }
@@ -655,7 +655,7 @@ static mp_uint_t _socket_read_data(mp_obj_t self_in, void *buf, size_t size,
         if (r >= 0) {
             return r;
         }
-        if (errno != EWOULDBLOCK) {
+        if (errno != EWOULDBLOCK || (flags & MSG_DONTWAIT)) {
             *errcode = errno;
             return MP_STREAM_ERROR;
         }
@@ -666,14 +666,17 @@ static mp_uint_t _socket_read_data(mp_obj_t self_in, void *buf, size_t size,
     return MP_STREAM_ERROR;
 }
 
-mp_obj_t _socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in,
+mp_obj_t _socket_recvfrom(size_t n_args, const mp_obj_t *args,
     struct sockaddr *from, socklen_t *from_len) {
-    size_t len = mp_obj_get_int(len_in);
+    mp_obj_t self_in = args[0];
+    size_t len = mp_obj_get_int(args[1]);
+    int flags = n_args > 2 ? mp_obj_get_int(args[2]) : 0;
+
     vstr_t vstr;
     vstr_init_len(&vstr, len);
 
     int errcode;
-    mp_uint_t ret = _socket_read_data(self_in, vstr.buf, len, from, from_len, &errcode);
+    mp_uint_t ret = _socket_read_data(self_in, vstr.buf, len, flags, from, from_len, &errcode);
     if (ret == MP_STREAM_ERROR) {
         mp_raise_OSError(errcode);
     }
@@ -682,25 +685,25 @@ mp_obj_t _socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in,
     return mp_obj_new_bytes_from_vstr(&vstr);
 }
 
-static mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) {
-    return _socket_recvfrom(self_in, len_in, NULL, NULL);
+static mp_obj_t socket_recv(size_t n_args, const mp_obj_t *args) {
+    return _socket_recvfrom(n_args, args, NULL, NULL);
 }
-static MP_DEFINE_CONST_FUN_OBJ_2(socket_recv_obj, socket_recv);
+static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_recv_obj, 2, 3, socket_recv);
 
-static mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) {
+static mp_obj_t socket_recvfrom(size_t n_args, const mp_obj_t *args) {
     struct sockaddr from;
     socklen_t fromlen = sizeof(from);
 
     mp_obj_t tuple[2];
-    tuple[0] = _socket_recvfrom(self_in, len_in, &from, &fromlen);
+    tuple[0] = _socket_recvfrom(n_args, args, &from, &fromlen);
 
     uint8_t *ip = (uint8_t *)&((struct sockaddr_in *)&from)->sin_addr;
     mp_uint_t port = lwip_ntohs(((struct sockaddr_in *)&from)->sin_port);
     tuple[1] = netutils_format_inet_addr(ip, port, NETUTILS_BIG);
 
     return mp_obj_new_tuple(2, tuple);
 }
-static MP_DEFINE_CONST_FUN_OBJ_2(socket_recvfrom_obj, socket_recvfrom);
+static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_recvfrom_obj, 2, 3, socket_recvfrom);
 
 int _socket_send(socket_obj_t *sock, const char *data, size_t datalen) {
     int sentlen = 0;
@@ -789,7 +792,7 @@ static mp_obj_t socket_makefile(size_t n_args, const mp_obj_t *args) {
 static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_makefile_obj, 1, 3, socket_makefile);
 
 static mp_uint_t socket_stream_read(mp_obj_t self_in, void *buf, mp_uint_t size, int *errcode) {
-    return _socket_read_data(self_in, buf, size, NULL, NULL, errcode);
+    return _socket_read_data(self_in, buf, size, 0, NULL, NULL, errcode);
 }
 
 static mp_uint_t socket_stream_write(mp_obj_t self_in, const void *buf, mp_uint_t size, int *errcode) {
@@ -1010,6 +1013,8 @@ static const mp_rom_map_elem_t mp_module_socket_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_SO_BINDTODEVICE), MP_ROM_INT(SO_BINDTODEVICE) },
     { MP_ROM_QSTR(MP_QSTR_IP_ADD_MEMBERSHIP), MP_ROM_INT(IP_ADD_MEMBERSHIP) },
     { MP_ROM_QSTR(MP_QSTR_TCP_NODELAY), MP_ROM_INT(TCP_NODELAY) },
+    { MP_ROM_QSTR(MP_QSTR_MSG_PEEK), MP_ROM_INT(MSG_PEEK) },
+    { MP_ROM_QSTR(MP_QSTR_MSG_DONTWAIT), MP_ROM_INT(MSG_DONTWAIT) },
 };
 
 static MP_DEFINE_CONST_DICT(mp_module_socket_globals, mp_module_socket_globals_table);

diff --git a/ports/unix/modsocket.c b/ports/unix/modsocket.c
@@ -701,6 +701,7 @@ static const mp_rom_map_elem_t mp_module_socket_globals_table[] = {
 
     C(MSG_DONTROUTE),
     C(MSG_DONTWAIT),
+    C(MSG_PEEK),
 
     C(SOL_SOCKET),
     C(SO_BROADCAST),