From 5b83319c68d96fedd24a86698e4a7c199d16fc64 Mon Sep 17 00:00:00 2001
From: Sam Clark <3758302+goatgoose@users.noreply.github.com>
Date: Mon, 4 Mar 2024 15:18:09 -0500
Subject: [PATCH] docs: Specify the return value of S2N_FAILURE for IO APIs
 (#4446)

---
 api/s2n.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/api/s2n.h b/api/s2n.h
index 5c375f57491..6bce51c0342 100644
--- a/api/s2n.h
+++ b/api/s2n.h
@@ -2008,7 +2008,7 @@ S2N_API extern int s2n_negotiate(struct s2n_connection *conn, s2n_blocked_status
  * @param buf A pointer to a buffer that s2n will write data from
  * @param size The size of buf
  * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
- * @returns The number of bytes written, and may indicate a partial write
+ * @returns The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.
  */
 S2N_API extern ssize_t s2n_send(struct s2n_connection *conn, const void *buf, ssize_t size, s2n_blocked_status *blocked);
 
@@ -2021,7 +2021,7 @@ S2N_API extern ssize_t s2n_send(struct s2n_connection *conn, const void *buf, ss
  * @param bufs A pointer to a vector of buffers that s2n will write data from.
  * @param count The number of buffers in `bufs`
  * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
- * @returns The number of bytes written, and may indicate a partial write. 
+ * @returns The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.
  */
 S2N_API extern ssize_t s2n_sendv(struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, s2n_blocked_status *blocked);
 
@@ -2040,7 +2040,7 @@ S2N_API extern ssize_t s2n_sendv(struct s2n_connection *conn, const struct iovec
  * @param count The number of buffers in `bufs`
  * @param offs The write cursor offset. This should be updated as data is written. See the example code.
  * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
- * @returns The number of bytes written, and may indicate a partial write. 
+ * @returns The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.
  */
 S2N_API extern ssize_t s2n_sendv_with_offset(struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, ssize_t offs, s2n_blocked_status *blocked);
 
@@ -2057,7 +2057,7 @@ S2N_API extern ssize_t s2n_sendv_with_offset(struct s2n_connection *conn, const
  * @param buf A pointer to a buffer that s2n will place read data into.
  * @param size Size of `buf`
  * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
- * @returns number of bytes read. 0 if the connection was shutdown by peer.
+ * @returns The number of bytes read on success. 0 if the connection was shutdown by the peer. S2N_FAILURE on failure.
  */
 S2N_API extern ssize_t s2n_recv(struct s2n_connection *conn, void *buf, ssize_t size, s2n_blocked_status *blocked);