From 6bf0a5cb5034a7e684dcc3500e841785237ce2dd Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sun, 7 Apr 2024 19:32:43 +0200
Subject: Adding upstream version 1:115.7.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 docs/nspr/reference/pr_initializenetaddr.rst | 80 ++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/nspr/reference/pr_initializenetaddr.rst

(limited to 'docs/nspr/reference/pr_initializenetaddr.rst')

diff --git a/docs/nspr/reference/pr_initializenetaddr.rst b/docs/nspr/reference/pr_initializenetaddr.rst
new file mode 100644
index 0000000000..c701334990
--- /dev/null
+++ b/docs/nspr/reference/pr_initializenetaddr.rst
@@ -0,0 +1,80 @@
+PR_InitializeNetAddr
+====================
+
+Initializes or reinitializes a network address. The storage for the
+network address structure is allocated by, and remains the
+responsibility of, the calling client.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prnetdb.h>
+
+   PRStatus PR_InitializeNetAddr(
+     PRNetAddrValue val,
+     PRUint16 port,
+     PRNetAddr *addr);
+
+
+Parameters
+~~~~~~~~~~
+
+The function has the following parameters:
+
+``val``
+   The value to be assigned to the IP Address portion of the network
+   address. This must be ``PR_IpAddrNull``, ``PR_IpAddrAny``, or
+   ``PR_IpAddrLoopback``.
+``port``
+   The port number to be assigned in the network address structure. The
+   value is specified in host byte order.
+``addr``
+   A pointer to the :ref:`PRNetAddr` structure to be manipulated.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+-  If successful, ``PR_SUCCESS``.
+-  If unsuccessful, ``PR_FAILURE``. This may occur, for example, if the
+   value of val is not within the ranges defined by ``PRNetAddrValue``.
+   You can retrieve the reason for the failure by calling
+   :ref:`PR_GetError`.
+
+
+Description
+-----------
+
+:ref:`PR_InitializeNetAddr` allows the assignment of special network
+address values and the port number, while also setting the state that
+indicates the version of the address being used.
+
+The special network address values are identified by the enum
+``PRNetAddrValue``:
+
+.. code::
+
+   typedef enum PRNetAddrValue{
+     PR_IpAddrNull,
+     PR_IpAddrAny,
+     PR_IpAddrLoopback
+   } PRNetAddrValue;
+
+The enum has the following enumerators:
+
+``PR_IpAddrNull``
+   Do not overwrite the IP address. This allows the caller to change the
+   network address' port number assignment without affecting the host
+   address.
+``PR_IpAddrAny``
+   Assign logical ``PR_INADDR_ANY`` to IP address. This wildcard value
+   is typically used to establish a socket on which to listen for
+   incoming connection requests.
+``PR_IpAddrLoopback``
+   Assign logical ``PR_INADDR_LOOPBACK``. A client can use this value to
+   connect to itself without knowing the host's network address.
-- 
cgit v1.2.3