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_importtcpsocket.rst | 70 ++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/nspr/reference/pr_importtcpsocket.rst (limited to 'docs/nspr/reference/pr_importtcpsocket.rst') 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. -- cgit v1.2.3