From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- docs/nspr/reference/pr_writev.rst | 79 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/nspr/reference/pr_writev.rst (limited to 'docs/nspr/reference/pr_writev.rst') diff --git a/docs/nspr/reference/pr_writev.rst b/docs/nspr/reference/pr_writev.rst new file mode 100644 index 0000000000..0100b72afc --- /dev/null +++ b/docs/nspr/reference/pr_writev.rst @@ -0,0 +1,79 @@ +PR_Writev +========= + +Writes data to a socket from multiple buffers. + + +Syntax +------ + +.. code:: + + #include + + PRInt32 PR_Writev( + PRFileDesc *fd, + PRIOVec *iov, + PRInt32 size, + PRIntervalTime timeout); + + #define PR_MAX_IOVECTOR_SIZE 16 + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object for a socket. +``iov`` + An array of ``PRIOVec`` structures that describe the buffers to write + from. +``size`` + Number of ``PRIOVec`` structures in the ``iov`` array. The value of + this parameter must not be greater than ``PR_MAX_IOVECTOR_SIZE``. If + it is, the function will fail and the error will be set to + ``PR_BUFFER_OVERFLOW_ERROR``. +``timeout`` + A value of type :ref:`PRIntervalTime` describing the time limit for + completion of the entire write operation. + + +Returns +~~~~~~~ + +One of the following values: + +- A positive number indicates the number of bytes successfully written. +- The value -1 indicates that the operation failed. The reason for the + failure can be obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +The thread calling :ref:`PR_Writev` blocks until all the data is written or +the write operation fails. Therefore, the return value is equal to +either the sum of all the buffer lengths (on success) or -1 (on +failure). Note that if :ref:`PR_Writev` returns -1, part of the data may +have been written before an error occurred. If the timeout parameter is +not ``PR_INTERVAL_NO_TIMEOUT`` and all the data cannot be written in the +specified interval, :ref:`PR_Writev` returns -1 with the error code +``PR_IO_TIMEOUT_ERROR``. + +This is the type definition for ``PRIOVec``: + +.. code:: + + typedef struct PRIOVec { + char *iov_base; + int iov_len; + } PRIOVec; + +The ``PRIOVec`` structure has the following fields: + +``iov_base`` + A pointer to the beginning of the buffer. +``iov_len`` + The size of the buffer. -- cgit v1.2.3