summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/prlinger.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/nspr/reference/prlinger.rst')
-rw-r--r--docs/nspr/reference/prlinger.rst56
1 files changed, 56 insertions, 0 deletions
diff --git a/docs/nspr/reference/prlinger.rst b/docs/nspr/reference/prlinger.rst
new file mode 100644
index 0000000000..9506dc0240
--- /dev/null
+++ b/docs/nspr/reference/prlinger.rst
@@ -0,0 +1,56 @@
+PRLinger
+========
+
+Structure used with the ``PR_SockOpt_Linger`` socket option to specify
+the time interval (in :ref:`PRIntervalTime` units) to linger on closing a
+socket if any data remain in the socket send buffer.
+
+
+Syntax
+~~~~~~
+
+.. code::
+
+ #include <prio.h>
+
+ typedef struct PRLinger {
+ PRBool polarity;
+ PRIntervalTime linger;
+ } PRLinger;
+
+
+Fields
+~~~~~~
+
+The structure has the following fields:
+
+``polarity``
+ Polarity of the option's setting: ``PR_FALSE`` means the option is
+ off, in which case the value of ``linger`` is ignored. ``PR_TRUE``
+ means the option is on, and the value of ``linger`` will be used to
+ determine how long :ref:`PR_Close` waits before returning.
+``linger``
+ Time (in :ref:`PRIntervalTime` units) to linger before closing if any
+ data remain in the socket send buffer.
+
+
+Description
+~~~~~~~~~~~
+
+By default, :ref:`PR_Close` returns immediately, but if there are any data
+remaining in the socket send buffer, the system attempts to deliver the
+data to the peer. The ``PR_SockOpt_Linger`` socket option, with a value
+represented by a structure of type :ref:`PRLinger`, makes it possible to
+change this default as follows:
+
+- If ``polarity`` is set to ``PR_FALSE``, :ref:`PR_Close` returns
+ immediately, but if there are any data remaining in the socket send
+ buffer, the runtime attempts to deliver the data to the peer.
+- If ``polarity`` is set to ``PR_TRUE`` and ``linger`` is set to 0
+ (``PR_INTERVAL_NO_WAIT``), the runtime aborts the connection when it
+ is closed and discards any data remaining in the socket send buffer.
+- If ``polarity`` is set to ``PR_TRUE`` and ``linger`` is nonzero, the
+ runtime *lingers* when the socket is closed. That is, if any data
+ remains in the socket send buffer, :ref:`PR_Close` blocks until either
+ all the data is sent and acknowledged by the peer or the interval
+ specified by ``linger`` expires.