diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
commit | 36d22d82aa202bb199967e9512281e9a53db42c9 (patch) | |
tree | 105e8c98ddea1c1e4784a60a5a6410fa416be2de /docs/nspr/reference/pr_connect.rst | |
parent | Initial commit. (diff) | |
download | firefox-esr-upstream.tar.xz firefox-esr-upstream.zip |
Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | docs/nspr/reference/pr_connect.rst | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/nspr/reference/pr_connect.rst b/docs/nspr/reference/pr_connect.rst new file mode 100644 index 0000000000..10978df792 --- /dev/null +++ b/docs/nspr/reference/pr_connect.rst @@ -0,0 +1,67 @@ +PR_Connect +========== + +Initiates a connection on a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Connect( + PRFileDesc *fd, + const PRNetAddr *addr, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``addr`` + A pointer to the address of the peer to which the socket is to be + connected. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the connect operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion of connection setup, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. Further information can be obtained + by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Connect` is usually invoked on a TCP socket, but it may also be +invoked on a UDP socket. Both cases are discussed here. + +If the socket is a TCP socket, :ref:`PR_Connect` establishes a TCP +connection to the peer. If the socket is not bound, it will be bound to +an arbitrary local address. + +:ref:`PR_Connect` blocks until either the connection is successfully +established or an error occurs. The function uses the lesser of the +provided timeout and the OS's connect timeout. In particular, if you +specify ``PR_INTERVAL_NO_TIMEOUT`` as the timeout, the OS's connection +time limit will be used. + +If the socket is a UDP socket, there is no connection setup to speak of, +since UDP is connectionless. If :ref:`PR_Connect` is invoked on a UDP +socket, it has an overloaded meaning: :ref:`PR_Connect` merely saves the +specified address as the default peer address for the socket, so that +subsequently one can send and receive datagrams from the socket using +:ref:`PR_Send` and :ref:`PR_Recv` instead of the usual :ref:`PR_SendTo` and +:ref:`PR_RecvFrom`. |