docs/nspr/reference/i_o_functions.rst

   1 I/O functions
   2 =============
   3
   4 This chapter describes the NSPR functions used to perform operations
   5 such as system access, normal file I/O, and socket (network) I/O.
   6
   7 For sample code that illustrates basic I/O operations, see :ref:`Introduction_to_NSPR>`.
   8 For information about the types most
   9 commonly used with the functions described in this chapter, see `I/O
  10 Types <I%2fO_Types>`__.
  11
  12 -  `Functions that Operate on
  13    Pathnames <#Functions_that_Operate_on_Pathnames>`__
  14 -  `Functions that Act on File
  15    Descriptors <#Functions_that_Act_on_File_Descriptors>`__
  16 -  `Directory I/O Functions <#Directory_I/O_Functions>`__
  17 -  `Socket Manipulation Functions <#Socket_Manipulation_Functions>`__
  18 -  `Converting Between Host and Network
  19    Addresses <#Converting_Between_Host_and_Network_Addresses>`__
  20 -  `Memory-Mapped I/O Functions <#Memory-Mapped_I/O_Functions>`__
  21 -  `Anonymous Pipe Function <#Anonymous_Pipe_Function>`__
  22 -  `Polling Functions <#Polling_Functions>`__
  23 -  `Pollable Events <#Pollable_Events>`__
  24 -  `Manipulating Layers <#Manipulating_Layers>`__
  25
  26 .. _Functions_that_Operate_on_Pathnames:
  27
  28 Functions that Operate on Pathnames
  29 -----------------------------------
  30
  31 A file or directory in a file system is specified by its pathname. NSPR
  32 uses Unix-style pathnames, which are null-terminated character strings.
  33 Only the ASCII character set is supported. The forward slash (/)
  34 separates the directories in a pathname. NSPR converts the slashes in a
  35 pathname to the directory separator of the native OS--for example,
  36 backslash (\) on Windows and colon (:) on Mac OS--before passing it to
  37 the native system calls.
  38
  39 Some file systems also differentiate drives or volumes.
  40
  41 -  :ref:`PR_Open`
  42 -  :ref:`PR_Delete`
  43 -  :ref:`PR_GetFileInfo`
  44 -  :ref:`PR_GetFileInfo64`
  45 -  :ref:`PR_Rename`
  46 -  :ref:`PR_Access`
  47
  48    -  type :ref:`PRAccessHow`
  49
  50 .. _Functions_that_Act_on_File_Descriptors:
  51
  52 Functions that Act on File Descriptors
  53 --------------------------------------
  54
  55 -  :ref:`PR_Close`
  56 -  :ref:`PR_Read`
  57 -  :ref:`PR_Write`
  58 -  :ref:`PR_Writev`
  59 -  :ref:`PR_GetOpenFileInfo`
  60 -  :ref:`PR_GetOpenFileInfo64`
  61 -  :ref:`PR_Seek`
  62 -  :ref:`PR_Seek64`
  63 -  :ref:`PR_Available`
  64 -  :ref:`PR_Available64`
  65 -  :ref:`PR_Sync`
  66 -  :ref:`PR_GetDescType`
  67 -  :ref:`PR_GetSpecialFD`
  68 -  :ref:`PR_CreatePipe`
  69
  70 .. _Directory_I.2FO_Functions:
  71
  72 Directory I/O Functions
  73 -----------------------
  74
  75 -  :ref:`PR_OpenDir`
  76 -  :ref:`PR_ReadDir`
  77 -  :ref:`PR_CloseDir`
  78 -  :ref:`PR_MkDir`
  79 -  :ref:`PR_RmDir`
  80
  81 .. _Socket_Manipulation_Functions:
  82
  83 Socket Manipulation Functions
  84 -----------------------------
  85
  86 The network programming interface presented here is a socket API modeled
  87 after the popular Berkeley sockets. Differences include the following:
  88
  89 -  The blocking socket functions in NSPR take a timeout parameter.
  90 -  Two new functions, :ref:`PR_TransmitFile` and :ref:`PR_AcceptRead`, can
  91    exploit the new system calls of some operating systems for higher
  92    performance.
  93
  94 List of functions:
  95
  96 -  :ref:`PR_OpenUDPSocket`
  97 -  :ref:`PR_NewUDPSocket`
  98 -  :ref:`PR_OpenTCPSocket`
  99 -  :ref:`PR_NewTCPSocket`
 100 -  :ref:`PR_ImportTCPSocket`
 101 -  :ref:`PR_Connect`
 102 -  :ref:`PR_ConnectContinue`
 103 -  :ref:`PR_Accept`
 104 -  :ref:`PR_Bind`
 105 -  :ref:`PR_Listen`
 106 -  :ref:`PR_Shutdown`
 107 -  :ref:`PR_Recv`
 108 -  :ref:`PR_Send`
 109 -  :ref:`PR_RecvFrom`
 110 -  :ref:`PR_SendTo`
 111 -  :ref:`PR_TransmitFile`
 112 -  :ref:`PR_AcceptRead`
 113 -  :ref:`PR_GetSockName`
 114 -  :ref:`PR_GetPeerName`
 115 -  :ref:`PR_GetSocketOption`
 116 -  :ref:`PR_SetSocketOption`
 117
 118 .. _Converting_Between_Host_and_Network_Addresses:
 119
 120 Converting Between Host and Network Addresses
 121 ---------------------------------------------
 122
 123 -  :ref:`PR_ntohs`
 124 -  :ref:`PR_ntohl`
 125 -  :ref:`PR_htons`
 126 -  :ref:`PR_htonl`
 127 -  :ref:`PR_FamilyInet`
 128
 129 .. _Memory-Mapped_I.2FO_Functions:
 130
 131 Memory-Mapped I/O Functions
 132 ---------------------------
 133
 134 The memory-mapped I/O functions allow sections of a file to be mapped to
 135 memory regions, allowing read-write accesses to the file to be
 136 accomplished by normal memory accesses.
 137
 138 Memory-mapped I/O functions are currently implemented for Unix, Linux,
 139 Mac OS X, and Win32 only.
 140
 141 -  :ref:`PR_CreateFileMap`
 142 -  :ref:`PR_MemMap`
 143 -  :ref:`PR_MemUnmap`
 144 -  :ref:`PR_CloseFileMap`
 145
 146 .. _Anonymous_Pipe_Function:
 147
 148 Anonymous Pipe Function
 149 -----------------------
 150
 151 -  :ref:`PR_CreatePipe`
 152
 153 .. _Polling_Functions:
 154
 155 Polling Functions
 156 -----------------
 157
 158 This section describes two of the most important polling functions
 159 provided by NSPR:
 160
 161 -  :ref:`PR_Poll`
 162 -  :ref:`PR_GetConnectStatus`
 163
 164 .. _Pollable_Events:
 165
 166 Pollable Events
 167 ---------------
 168
 169 A pollable event is a special kind of file descriptor. The only I/O
 170 operation you can perform on a pollable event is to poll it with the
 171 :ref:`PR_POLL_READ` flag. You cannot read from or write to a pollable
 172 event.
 173
 174 The purpose of a pollable event is to combine event waiting with I/O
 175 waiting in a single :ref:`PR_Poll` call. Pollable events are implemented
 176 using a pipe or a pair of TCP sockets connected via the loopback
 177 address, therefore setting and/or waiting for pollable events are
 178 expensive operating system calls. Do not use pollable events for general
 179 thread synchronization; use condition variables instead.
 180
 181 A pollable event has two states: set and unset. Events are not queued,
 182 so there is no notion of an event count. A pollable event is either set
 183 or unset.
 184
 185 -  :ref:`PR_NewPollableEvent`
 186 -  :ref:`PR_DestroyPollableEvent`
 187 -  :ref:`PR_SetPollableEvent`
 188 -  :ref:`PR_WaitForPollableEvent`
 189
 190 One can call :ref:`PR_Poll` with the :ref:`PR_POLL_READ` flag on a pollable
 191 event. When the pollable event is set, :ref:`PR_Poll` returns the the
 192 :ref:`PR_POLL_READ` flag set in the out_flags.
 193
 194 .. _Manipulating_Layers:
 195
 196 Manipulating Layers
 197 -------------------
 198
 199 File descriptors may be layered. For example, SSL is a layer on top of a
 200 reliable bytestream layer such as TCP.
 201
 202 Each type of layer has a unique identity, which is allocated by the
 203 runtime. The layer implementer should associate the identity with all
 204 layers of that type. It is then possible to scan the chain of layers and
 205 find a layer that one recognizes and therefore predict that it will
 206 implement a desired protocol.
 207
 208 A layer can be pushed onto or popped from an existing stack of layers.
 209 The file descriptor of the top layer can be passed to NSPR I/O
 210 functions, which invoke the appropriate version of the I/O methods
 211 polymorphically.
 212
 213 NSPR defines three identities:
 214
 215 .. code::
 216
 217    #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
 218    #define PR_TOP_IO_LAYER (PRDescIdentity)-2
 219    #define PR_NSPR_IO_LAYER (PRDescIdentity)0
 220
 221 -  :ref:`PR_INVALID_IO_LAYER`: An invalid layer identify (for error
 222    return).
 223 -  :ref:`PR_TOP_IO_LAYER`: The identity of the top of the stack.
 224 -  :ref:`PR_NSPR_IO_LAYER`: The identity for the layer implemented by NSPR.
 225
 226 :ref:`PR_TOP_IO_LAYER` may be used as a shorthand for identifying the
 227 topmost layer of an existing stack. For example, the following lines of
 228 code are equivalent:
 229
 230 | ``rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);``
 231 | ``rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer);``
 232
 233 -  :ref:`PR_GetUniqueIdentity`
 234 -  :ref:`PR_GetNameForIdentity`
 235 -  :ref:`PR_GetLayersIdentity`
 236 -  :ref:`PR_GetIdentitiesLayer`
 237 -  :ref:`PR_GetDefaultIOMethods`
 238 -  :ref:`PR_CreateIOLayerStub`
 239 -  :ref:`PR_PushIOLayer`
 240 -  :ref:`PR_PopIOLayer`