Add extra documentation to SendZc

io-uring-test/src/tests/net.rs

@@ -1662,10 +1662,12 @@ pub fn test_udp_sendzc_with_dest<S: squeue::EntryMarker, C: cqueue::EntryMarker>
                 // First SendZc notification
                 11 => {
                     assert_eq!(cqueue::more(cqe.flags()), true);
+                    assert_eq!(cqueue::notif(cqe.flags()), false);
                 }
                 // Last SendZc notification
                 0 => {
                     assert_eq!(cqueue::more(cqe.flags()), false);
+                    assert_eq!(cqueue::notif(cqe.flags()), true);
                 }
                 _ => panic!("wrong result for notification"),
             },

src/opcode.rs

@@ -1662,6 +1662,21 @@ opcode! {
     ///
     /// A fixed (pre-mapped) buffer can optionally be used from pre-mapped buffers that have been
     /// previously registered with [`Submitter::register_buffers`](crate::Submitter::register_buffers).
+    ///
+    /// This operation might result in two completion queue entries. The flags field of the first
+    /// cqe may likely contain [`IORING_CQE_F_MORE`](crate::cqueue::more), which means that there
+    /// will be a second completion event (notification) for the request, with the `user_data`
+    /// field set to the same value. The user must not modify the data buffer until the
+    /// notification is posted. The first cqe follows the usual rules and so its `res` field will
+    /// contain the number of bytes sent or a negative error code. The notification's `res` field
+    /// will be set to zero and the flags field will contain
+    /// [`IORING_CQE_F_NOTIF`](crate::cqueue::notif). The two step model is needed because the
+    /// kernel may hold on to buffers for a long time, e.g. waiting for a TCP ACK, and having a
+    /// separate cqe for request completions allows userspace to push more data without extra
+    /// delays. Note, notifications are only responsible for controlling the lifetime of the
+    /// buffers, and as such don't mean anything about whether the data has atually been sent out
+    /// or received by the other end. Even errored requests may generate a notification, and the
+    /// user must use [notif](crate::cqueue::notif) rather than relying on the result.
     pub struct SendZc {
         fd: { impl sealed::UseFixed },
         buf: { *const u8 },