tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

pr_connect.rst (1902B)

      1 PR_Connect
      2 ==========
      3 
      4 Initiates a connection on a specified socket.
      5 
      6 
      7 Syntax
      8 ------
      9 
     10 .. code::
     11 
     12   #include <prio.h>
     13 
     14   PRStatus PR_Connect(
     15     PRFileDesc *fd,
     16     const PRNetAddr *addr,
     17     PRIntervalTime timeout);
     18 
     19 
     20 Parameters
     21 ~~~~~~~~~~
     22 
     23 The function has the following parameters:
     24 
     25 ``fd``
     26   A pointer to a :ref:`PRFileDesc` object representing a socket.
     27 ``addr``
     28   A pointer to the address of the peer to which the socket is to be
     29   connected.
     30 ``timeout``
     31   A value of type :ref:`PRIntervalTime` specifying the time limit for
     32   completion of the connect operation.
     33 
     34 
     35 Returns
     36 ~~~~~~~
     37 
     38 The function returns one of the following values:
     39 
     40 -  Upon successful completion of connection setup, ``PR_SUCCESS``.
     41 -  If unsuccessful, ``PR_FAILURE``. Further information can be obtained
     42   by calling :ref:`PR_GetError`.
     43 
     44 
     45 Description
     46 -----------
     47 
     48 :ref:`PR_Connect` is usually invoked on a TCP socket, but it may also be
     49 invoked on a UDP socket. Both cases are discussed here.
     50 
     51 If the socket is a TCP socket, :ref:`PR_Connect` establishes a TCP
     52 connection to the peer. If the socket is not bound, it will be bound to
     53 an arbitrary local address.
     54 
     55 :ref:`PR_Connect` blocks until either the connection is successfully
     56 established or an error occurs. The function uses the lesser of the
     57 provided timeout and the OS's connect timeout. In particular, if you
     58 specify ``PR_INTERVAL_NO_TIMEOUT`` as the timeout, the OS's connection
     59 time limit will be used.
     60 
     61 If the socket is a UDP socket, there is no connection setup to speak of,
     62 since UDP is connectionless. If :ref:`PR_Connect` is invoked on a UDP
     63 socket, it has an overloaded meaning: :ref:`PR_Connect` merely saves the
     64 specified address as the default peer address for the socket, so that
     65 subsequently one can send and receive datagrams from the socket using
     66 :ref:`PR_Send` and :ref:`PR_Recv` instead of the usual :ref:`PR_SendTo` and
     67 :ref:`PR_RecvFrom`.