summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/i_o_functions.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:22:09 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:22:09 +0000
commit43a97878ce14b72f0981164f87f2e35e14151312 (patch)
tree620249daf56c0258faa40cbdcf9cfba06de2a846 /docs/nspr/reference/i_o_functions.rst
parentInitial commit. (diff)
downloadfirefox-43a97878ce14b72f0981164f87f2e35e14151312.tar.xz
firefox-43a97878ce14b72f0981164f87f2e35e14151312.zip
Adding upstream version 110.0.1.upstream/110.0.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/nspr/reference/i_o_functions.rst')
-rw-r--r--docs/nspr/reference/i_o_functions.rst240
1 files changed, 240 insertions, 0 deletions
diff --git a/docs/nspr/reference/i_o_functions.rst b/docs/nspr/reference/i_o_functions.rst
new file mode 100644
index 0000000000..a13d0b3b74
--- /dev/null
+++ b/docs/nspr/reference/i_o_functions.rst
@@ -0,0 +1,240 @@
+I/O functions
+=============
+
+This chapter describes the NSPR functions used to perform operations
+such as system access, normal file I/O, and socket (network) I/O.
+
+For sample code that illustrates basic I/O operations, see :ref:`Introduction_to_NSPR>`.
+For information about the types most
+commonly used with the functions described in this chapter, see `I/O
+Types <I%2fO_Types>`__.
+
+- `Functions that Operate on
+ Pathnames <#Functions_that_Operate_on_Pathnames>`__
+- `Functions that Act on File
+ Descriptors <#Functions_that_Act_on_File_Descriptors>`__
+- `Directory I/O Functions <#Directory_I/O_Functions>`__
+- `Socket Manipulation Functions <#Socket_Manipulation_Functions>`__
+- `Converting Between Host and Network
+ Addresses <#Converting_Between_Host_and_Network_Addresses>`__
+- `Memory-Mapped I/O Functions <#Memory-Mapped_I/O_Functions>`__
+- `Anonymous Pipe Function <#Anonymous_Pipe_Function>`__
+- `Polling Functions <#Polling_Functions>`__
+- `Pollable Events <#Pollable_Events>`__
+- `Manipulating Layers <#Manipulating_Layers>`__
+
+.. _Functions_that_Operate_on_Pathnames:
+
+Functions that Operate on Pathnames
+-----------------------------------
+
+A file or directory in a file system is specified by its pathname. NSPR
+uses Unix-style pathnames, which are null-terminated character strings.
+Only the ASCII character set is supported. The forward slash (/)
+separates the directories in a pathname. NSPR converts the slashes in a
+pathname to the directory separator of the native OS--for example,
+backslash (\) on Windows and colon (:) on Mac OS--before passing it to
+the native system calls.
+
+Some file systems also differentiate drives or volumes.
+
+- :ref:`PR_Open`
+- :ref:`PR_Delete`
+- :ref:`PR_GetFileInfo`
+- :ref:`PR_GetFileInfo64`
+- :ref:`PR_Rename`
+- :ref:`PR_Access`
+
+ - type :ref:`PRAccessHow`
+
+.. _Functions_that_Act_on_File_Descriptors:
+
+Functions that Act on File Descriptors
+--------------------------------------
+
+- :ref:`PR_Close`
+- :ref:`PR_Read`
+- :ref:`PR_Write`
+- :ref:`PR_Writev`
+- :ref:`PR_GetOpenFileInfo`
+- :ref:`PR_GetOpenFileInfo64`
+- :ref:`PR_Seek`
+- :ref:`PR_Seek64`
+- :ref:`PR_Available`
+- :ref:`PR_Available64`
+- :ref:`PR_Sync`
+- :ref:`PR_GetDescType`
+- :ref:`PR_GetSpecialFD`
+- :ref:`PR_CreatePipe`
+
+.. _Directory_I.2FO_Functions:
+
+Directory I/O Functions
+-----------------------
+
+- :ref:`PR_OpenDir`
+- :ref:`PR_ReadDir`
+- :ref:`PR_CloseDir`
+- :ref:`PR_MkDir`
+- :ref:`PR_RmDir`
+
+.. _Socket_Manipulation_Functions:
+
+Socket Manipulation Functions
+-----------------------------
+
+The network programming interface presented here is a socket API modeled
+after the popular Berkeley sockets. Differences include the following:
+
+- The blocking socket functions in NSPR take a timeout parameter.
+- Two new functions, :ref:`PR_TransmitFile` and :ref:`PR_AcceptRead`, can
+ exploit the new system calls of some operating systems for higher
+ performance.
+
+List of functions:
+
+- :ref:`PR_OpenUDPSocket`
+- :ref:`PR_NewUDPSocket`
+- :ref:`PR_OpenTCPSocket`
+- :ref:`PR_NewTCPSocket`
+- :ref:`PR_ImportTCPSocket`
+- :ref:`PR_Connect`
+- :ref:`PR_ConnectContinue`
+- :ref:`PR_Accept`
+- :ref:`PR_Bind`
+- :ref:`PR_Listen`
+- :ref:`PR_Shutdown`
+- :ref:`PR_Recv`
+- :ref:`PR_Send`
+- :ref:`PR_RecvFrom`
+- :ref:`PR_SendTo`
+- :ref:`PR_TransmitFile`
+- :ref:`PR_AcceptRead`
+- :ref:`PR_GetSockName`
+- :ref:`PR_GetPeerName`
+- :ref:`PR_GetSocketOption`
+- :ref:`PR_SetSocketOption`
+
+.. _Converting_Between_Host_and_Network_Addresses:
+
+Converting Between Host and Network Addresses
+---------------------------------------------
+
+- :ref:`PR_ntohs`
+- :ref:`PR_ntohl`
+- :ref:`PR_htons`
+- :ref:`PR_htonl`
+- :ref:`PR_FamilyInet`
+
+.. _Memory-Mapped_I.2FO_Functions:
+
+Memory-Mapped I/O Functions
+---------------------------
+
+The memory-mapped I/O functions allow sections of a file to be mapped to
+memory regions, allowing read-write accesses to the file to be
+accomplished by normal memory accesses.
+
+Memory-mapped I/O functions are currently implemented for Unix, Linux,
+Mac OS X, and Win32 only.
+
+- :ref:`PR_CreateFileMap`
+- :ref:`PR_MemMap`
+- :ref:`PR_MemUnmap`
+- :ref:`PR_CloseFileMap`
+
+.. _Anonymous_Pipe_Function:
+
+Anonymous Pipe Function
+-----------------------
+
+- :ref:`PR_CreatePipe`
+
+.. _Polling_Functions:
+
+Polling Functions
+-----------------
+
+This section describes two of the most important polling functions
+provided by NSPR:
+
+- :ref:`PR_Poll`
+- :ref:`PR_GetConnectStatus`
+
+.. _Pollable_Events:
+
+Pollable Events
+---------------
+
+A pollable event is a special kind of file descriptor. The only I/O
+operation you can perform on a pollable event is to poll it with the
+:ref:`PR_POLL_READ` flag. You cannot read from or write to a pollable
+event.
+
+The purpose of a pollable event is to combine event waiting with I/O
+waiting in a single :ref:`PR_Poll` call. Pollable events are implemented
+using a pipe or a pair of TCP sockets connected via the loopback
+address, therefore setting and/or waiting for pollable events are
+expensive operating system calls. Do not use pollable events for general
+thread synchronization; use condition variables instead.
+
+A pollable event has two states: set and unset. Events are not queued,
+so there is no notion of an event count. A pollable event is either set
+or unset.
+
+- :ref:`PR_NewPollableEvent`
+- :ref:`PR_DestroyPollableEvent`
+- :ref:`PR_SetPollableEvent`
+- :ref:`PR_WaitForPollableEvent`
+
+One can call :ref:`PR_Poll` with the :ref:`PR_POLL_READ` flag on a pollable
+event. When the pollable event is set, :ref:`PR_Poll` returns the the
+:ref:`PR_POLL_READ` flag set in the out_flags.
+
+.. _Manipulating_Layers:
+
+Manipulating Layers
+-------------------
+
+File descriptors may be layered. For example, SSL is a layer on top of a
+reliable bytestream layer such as TCP.
+
+Each type of layer has a unique identity, which is allocated by the
+runtime. The layer implementor should associate the identity with all
+layers of that type. It is then possible to scan the chain of layers and
+find a layer that one recognizes and therefore predict that it will
+implement a desired protocol.
+
+A layer can be pushed onto or popped from an existing stack of layers.
+The file descriptor of the top layer can be passed to NSPR I/O
+functions, which invoke the appropriate version of the I/O methods
+polymorphically.
+
+NSPR defines three identities:
+
+.. code::
+
+ #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
+ #define PR_TOP_IO_LAYER (PRDescIdentity)-2
+ #define PR_NSPR_IO_LAYER (PRDescIdentity)0
+
+- :ref:`PR_INVALID_IO_LAYER`: An invalid layer identify (for error
+ return).
+- :ref:`PR_TOP_IO_LAYER`: The identity of the top of the stack.
+- :ref:`PR_NSPR_IO_LAYER`: The identity for the layer implemented by NSPR.
+
+:ref:`PR_TOP_IO_LAYER` may be used as a shorthand for identifying the
+topmost layer of an existing stack. For example, the following lines of
+code are equivalent:
+
+| ``rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);``
+| ``rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer);``
+
+- :ref:`PR_GetUniqueIdentity`
+- :ref:`PR_GetNameForIdentity`
+- :ref:`PR_GetLayersIdentity`
+- :ref:`PR_GetIdentitiesLayer`
+- :ref:`PR_GetDefaultIOMethods`
+- :ref:`PR_CreateIOLayerStub`
+- :ref:`PR_PushIOLayer`
+- :ref:`PR_PopIOLayer`