io_uring_prep_send_zc(3)	 liburing Manual	io_uring_prep_send_zc(3)

NAME
     io_uring_prep_send_zc - prepare a zerocopy send request

SYNOPSIS
     #include <liburing.h>

     void io_uring_prep_send_zc(struct io_uring_sqe *sqe,
				int sockfd,
				const void *buf,
				size_t len,
				int flags,
				unsigned zc_flags);

     void io_uring_prep_send_zc_fixed(struct io_uring_sqe *sqe,
				      int sockfd,
				      const void *buf,
				      size_t len,
				      int flags,
				      unsigned zc_flags);
				      unsigned buf_index);

DESCRIPTION
     The io_uring_prep_send_zc(3) function prepares a zerocopy send request. The
     submission	 queue	entry  sqe is setup to use the file descriptor sockfd to
     start sending the data from buf of size len bytes with send modifier  flags
     flags and zerocopy modifier flags zc_flags.

     The io_uring_prep_send_zc_fixed(3) works just like io_uring_prep_send_zc(3)
     except it requires the use of buffers that have been registered with io_ur-
     ing_register_buffers(3).	The buf and len arguments must fall within a re-
     gion specified by buf_index in the previously registered buffer. The buffer
     need not be aligned with the start of the registered buffer.

     See io_uring_prep_send(3) for a description of flags that can be set in the
     SQE ioprio field. In addition to those, the zero-copy  send  also	supports
     setting  IORING_SEND_ZC_REPORT_USAGE  .   If  set, the notification CQE res
     field will report the number of bytes that were  copied  rather  than  sent
     with  zero copy. A value of 0 indicates success. If the value is IORING_NO-
     TIF_USAGE_ZC_COPIED , then data was copied.

     As opposed to non-zerocopy send requests, a zerocopy send will usually gen-
     erate two CQEs. The first CQE holds the result of the  send  operation  it-
     self,  and	 if  that  CQE has IORING_CQE_F_MORE set in the CQE flags field,
     then a second notification CQE will be posted for the operation. This  sec-
     ond  notification tells the application that the memory associated with the
     send is safe to get reused. The second CQE will have IORING_CQE_F_NOTIF set
     in the CQE flags field. Also see  the  io_uring_enter(2)  man  page  for  a
     fuller description of the notification CQE.

     Note  that	 using IOSQE_IO_LINK with this request type requires the setting
     of MSG_WAITALL in the flags argument, as a short send isn't  considered  an
     error condition without that being set.

     These  functions  prepare	an  async zerocopy send(2) request. See that man
     page for details. For details on the zerocopy  nature  of	it,  see  io_ur-
     ing_enter(2).


RETURN VALUE
     None

ERRORS
     The CQE res field will contain the result of the operation. See the related
     man page for details on possible values. Note that where synchronous system
     calls  will  return  -1 on failure and set errno to the actual error value,
     io_uring never uses errno.	 Instead it returns the negated	 errno	directly
     in the CQE res field. Some common error cases are:

     -ENOMEM
	    The	 ulimit(1)  -l setting is too low to support the size of the at-
	    tempted zero copy send.  Increasing the limit may help

     -ENOMEM
	    The kernel ran out of memory.

NOTES
     Despite accepting a size_t number of bytes, these functions can transfer at
     most INT_MAX bytes per call (the maximum for the underlying syscall  inter-
     face).

SEE ALSO
     io_uring_get_sqe(3),   io_uring_submit(3),	  io_uring_prep_send(3),  io_ur-
     ing_enter(2), send(2)

liburing-2.3			September 6, 2022	io_uring_prep_send_zc(3)