Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 70 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_importtcpsocket.rst b/docs/nspr/reference/pr_importtcpsocket.rst
new file mode 100644
index 0000000000..4722744b3d
--- /dev/null
+++ b/docs/nspr/reference/pr_importtcpsocket.rst
@@ -0,0 +1,70 @@
+PR_ImportTCPSocket
+==================
+
+Imports a native TCP socket into NSPR.
+
+
+Syntax
+------
+
+.. code::
+
+   #include "private/pprio.h"
+
+   PRFileDesc* PR_ImportTCPSocket(PROsfd osfd);
+
+
+Parameters
+~~~~~~~~~~
+
+The function has the following parameters:
+
+``osfd``
+   The native file descriptor for the TCP socket to import. On POSIX
+   systems, this is an ``int``. On Windows, this is a ``SOCKET``.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+-  Upon successful completion, a pointer to the :ref:`PRFileDesc` object
+   created for the newly imported native TCP socket.
+-  If the import of the native TCP socket failed, ``NULL``.
+
+
+Description
+-----------
+
+A native TCP socket ``osfd`` can be imported into NSPR with
+:ref:`PR_ImportTCPSocket`. The caller gives up control of the native TCP
+socket ``osfd`` and should use the ``PRFileDesc*`` returned by
+:ref:`PR_ImportTCPSocket` instead.
+
+Although :ref:`PR_ImportTCPSocket` is a supported function, it is declared
+in ``"private/pprio.h"`` to stress the fact that this function depends
+on the internals of the NSPR implementation. The caller needs to
+understand what NSPR will do to the native file descriptor and make sure
+that NSPR can use the native file descriptor successfully.
+
+For example, on POSIX systems, NSPR will put the native file descriptor
+(an ``int``) in non-blocking mode by calling ``fcntl`` to set the
+``O_NONBLOCK`` file status flag on the native file descriptor, and then
+NSPR will call socket functions such as ``recv``, ``send``, and ``poll``
+on the native file descriptor. The caller must not do anything to the
+native file descriptor before the :ref:`PR_ImportTCPSocket` call that will
+prevent the native file descriptor from working in non-blocking mode.
+
+Warning
+-------
+
+In theory, code that uses :ref:`PR_ImportTCPSocket` may break when NSPR's
+implementation changes. In practice, this is unlikely to happen because
+NSPR's implementation has been stable for years and because of NSPR's
+strong commitment to backward compatibility. Using
+:ref:`PR_ImportTCPSocket` is much more convenient than writing an NSPR I/O
+layer that wraps your native TCP sockets. Of course, it is best if you
+just use :ref:`PR_OpenTCPSocket` or :ref:`PR_NewTCPSocket`. If you are not
+sure whether :ref:`PR_ImportTCPSocket` is right for you, please ask in the
+mozilla.dev.tech.nspr newsgroup.