1 files changed, 87 insertions, 0 deletions
diff --git a/docs/nspr/reference/pr_pushiolayer.rst b/docs/nspr/reference/pr_pushiolayer.rst
new file mode 100644
index 0000000000..067370108f
--- /dev/null
+++ b/docs/nspr/reference/pr_pushiolayer.rst
@@ -0,0 +1,87 @@
+PR_PushIOLayer
+==============
+
+Adds a layer onto the stack.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prio.h>
+
+   PRStatus PR_PushIOLayer(
+     PRFileDesc *stack,
+     PRDescIdentity id,
+     PRFileDesc *layer);
+
+
+Parameters
+~~~~~~~~~~
+
+The function has the following parameters:
+
+``stack``
+   A pointer to a :ref:`PRFileDesc` object representing the stack.
+``id``
+   A :ref:`PRDescIdentity` object for the layer on the stack above which
+   the new layer is to be added.
+``layer``
+   A pointer to a :ref:`PRFileDesc` object representing the new layer to be
+   added to the stack.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+-  If the layer is successfully pushed onto the stack, ``PR_SUCCESS``.
+-  If the layer is not successfully pushed onto the stack,
+   ``PR_FAILURE``. Use :ref:`PR_GetError` to get additional information
+   regarding the reason for the failure.
+
+
+Description
+-----------
+
+A file descriptor for a layer (possibly allocated using
+:ref:`PR_CreateIOLayerStub`) may be pushed onto an existing stack of file
+descriptors at any time. The new layer is inserted into the stack just
+above the layer with the identity specified by ``id``.
+
+Even if the ``id`` parameter indicates the topmost layer of the stack,
+the value of the file descriptor describing the original stack will not
+change. In other words, ``stack`` continues to point to the top of the
+stack after the function returns.
+
+Caution
+-------
+
+Keeping the pointer to the stack even as layers are pushed onto the top
+of the stack is accomplished by swapping the contents of the file
+descriptor being pushed and the stack's current top layer file
+descriptor.
+
+The intent is that the pointer to the stack remain the stack's identity
+even if someone (perhaps covertly) has pushed other layers. Some subtle
+ramifications:
+
+-  The ownership of the storage pointed to by the caller's layer
+   argument is relinquished to the runtime. Accessing the object via the
+   pointer is not permitted while the runtime has ownership. The correct
+   mechanism to access the object is to get a pointer to it by calling
+   :ref:`PR_GetIdentitiesLayer`.
+
+-  The contents of the caller's object are swapped into another
+   container, including the reference to the object's destructor. If the
+   original container was allocated using a different mechanism than
+   used by the runtime, the default calling of the layer's destructor by
+   the runtime will fail :ref:`PR_CreateIOLayerStub` is provided to
+   allocate layer objects and template implementations). The destructor
+   will be called on all layers when the stack is closed (see
+   :ref:`PR_Close`). If the containers are allocated by some method other
+   than :ref:`PR_CreateIOLayerStub`, it may be required that the stack have
+   the layers popped off (in reverse order that they were pushed) before
+   calling :ref:`PR_Close`.