Adds a layer onto the stack.


#include <prio.h> 

PRStatus PR_PushIOLayer(
  PRFileDesc *stack, 
  PRDescIdentity id,
  PRFileDesc *layer);


The function has the following parameters:

A pointer to a PRFileDesc object representing the stack.
A PRDescIdentity object for the layer on the stack above which the new layer is to be added.
A pointer to a PRFileDesc object representing the new layer to be added to the stack.


The function returns one of the following values:


A file descriptor for a layer (possibly allocated using 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.


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: