diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
| commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
| tree | f435a8308119effd964b339f76abb83a57c29483 /docs/nspr/reference | |
| parent | Initial commit. (diff) | |
| download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip | |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/nspr/reference')
346 files changed, 15805 insertions, 0 deletions
diff --git a/docs/nspr/reference/anonymous_shared_memory.rst b/docs/nspr/reference/anonymous_shared_memory.rst new file mode 100644 index 0000000000..3daea2cbb0 --- /dev/null +++ b/docs/nspr/reference/anonymous_shared_memory.rst @@ -0,0 +1,118 @@ +Anonymous Shared Memory +======================= + +This chapter describes the NSPR API for anonymous shared memory. + +- `Anonymous Memory Protocol <#Anonymous_Memory_Protocol>`__ +- `Anonymous Shared Memory + Functions <#Anonymous_Shared_Memory_Functions>`__ + +.. _Anonymous_Memory_Protocol: + +Anonymous Memory Protocol +------------------------- + +NSPR provides an anonymous shared memory based on NSPR's :ref:`PRFileMap` +type. The anonymous file-mapped shared memory provides an inheritable +shared memory, as in: the child process inherits the shared memory. +Compare the file-mapped anonymous shared memory to to a named shared +memory described in prshm.h. The intent is to provide a shared memory +that is accessible only by parent and child processes. ... It's a +security thing. + +Depending on the underlying platform, the file-mapped shared memory may +be backed by a file. ... surprise! ... On some platforms, no real file +backs the shared memory. On platforms where the shared memory is backed +by a file, the file's name in the filesystem is visible to other +processes for only the duration of the creation of the file, hopefully a +very short time. This restricts processes that do not inherit the shared +memory from opening the file and reading or writing its contents. +Further, when all processes using an anonymous shared memory terminate, +the backing file is deleted. ... If you are not paranoid, you're not +paying attention. + +The file-mapped shared memory requires a protocol for the parent process +and child process to share the memory. NSPR provides two protocols. Use +one or the other; don't mix and match. + +In the first protocol, the job of passing the inheritable shared memory +is done via helper-functions with PR_CreateProcess. In the second +protocol, the parent process is responsible for creating the child +process; the parent and child are mutually responsible for passing a +``FileMap`` string. NSPR provides helper functions for extracting data +from the :ref:`PRFileMap` object. ... See the examples below. + +Both sides should adhere strictly to the protocol for proper operation. +The pseudo-code below shows the use of a file-mapped shared memory by a +parent and child processes. In the examples, the server creates the +file-mapped shared memory, the client attaches to it. + +.. _First_protocol: + +First protocol +~~~~~~~~~~~~~~ + +**Server:** + +.. code:: + + fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); + addr = PR_MemMap(fm); + attr = PR_NewProcessAttr(); + PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname ); + PR_CreateProcess(Client); + PR_DestroyProcessAttr(attr); + ... yadda ... + PR_MemUnmap( addr ); + PR_CloseFileMap(fm); + +**Client:** + +.. code:: + + ... started by server via PR_CreateProcess() + fm = PR_GetInheritedFileMap( shmname ); + addr = PR_MemMap(fm); + ... yadda ... + PR_MemUnmap(addr); + PR_CloseFileMap(fm); + +.. _Second_protocol: + +Second protocol +~~~~~~~~~~~~~~~ + +**Server:** + +.. code:: + + fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); + fmstring = PR_ExportFileMapAsString( fm ); + addr = PR_MemMap(fm); + ... application specific technique to pass fmstring to child + ... yadda ... Server uses his own magic to create child + PR_MemUnmap( addr ); + PR_CloseFileMap(fm); + +**Client:** + +.. code:: + + ... started by server via his own magic + ... application specific technique to find fmstring from parent + fm = PR_ImportFileMapFromString( fmstring ) + addr = PR_MemMap(fm); + ... yadda ... + PR_MemUnmap(addr); + PR_CloseFileMap(fm); + +.. _Anonymous_Shared_Memory_Functions: + +Anonymous Shared Memory Functions +--------------------------------- + +- :ref:`PR_OpenAnonFileMap` +- :ref:`PR_ProcessAttrSetInheritableFileMap` +- :ref:`PR_GetInheritedFileMap` +- :ref:`PR_ExportFileMapAsString` +- :ref:`PR_ImportFileMapFromString` diff --git a/docs/nspr/reference/atomic_operations.rst b/docs/nspr/reference/atomic_operations.rst new file mode 100644 index 0000000000..1599d39ce8 --- /dev/null +++ b/docs/nspr/reference/atomic_operations.rst @@ -0,0 +1,32 @@ +This chapter describes the global functions you use to perform atomic +operations. The functions define a portable API that may be reliably +used in any environment. Since not all operating environments provide +access to such functions, their performance may vary considerably. + +.. _Atomic_Operations_Functions: + +Atomic Operations Functions +--------------------------- + +The API defined for the atomic functions is consistent across all +supported platforms. However, the implementation may vary greatly, and +hence the performance. On systems that do not provide direct access to +atomic operators, NSPR emulates the capabilities by using its own +locking mechanisms. For such systems, NSPR performs atomic operations +just as efficiently as the client could. Therefore, to preserve +portability, it is recommended that clients use the NSPR API for atomic +operations. + +These functions operate on 32-bit integers: + +- :ref:`PR_AtomicIncrement` +- :ref:`PR_AtomicDecrement` +- :ref:`PR_AtomicSet` +- :ref:`PR_AtomicAdd` + +These functions implement a simple stack data structure: + +- :ref:`PR_CreateStack` +- :ref:`PR_StackPush` +- :ref:`PR_StackPop` +- :ref:`PR_DestroyStack` diff --git a/docs/nspr/reference/cached_monitors.rst b/docs/nspr/reference/cached_monitors.rst new file mode 100644 index 0000000000..647bdb1b54 --- /dev/null +++ b/docs/nspr/reference/cached_monitors.rst @@ -0,0 +1,37 @@ +This chapter describes the functions you use when you work with cached +monitors. Unlike a plain monitor, a cached monitor is associated with +the address of a protected object, and the association is maintained +only while the protection is needed. This arrangement allows a cached +monitor to be associated with another object without preallocating a +monitor for all objects. A hash table is used to quickly map addresses +to their respective monitors. The system automatically enlarges the hash +table as needed. + +Important +--------- + +Cached monitors are slower to use than their uncached counterparts. + +See `Monitors <Monitors>`__ for information about uncached monitors. + +.. _Cached_Monitors_Functions: + +Cached Monitors Functions +------------------------- + +Cached monitors allow the client to associate monitoring protection and +state change synchronization in a lazy fashion. The monitoring +capability is associated with the protected object only during the time +it is required, allowing the monitor object to be reused. This +additional flexibility comes at the cost of a small loss in performance. + + - :ref:`PR_CEnterMonitor` enters the lock associated with a cached + monitor. + - :ref:`PR_CExitMonitor` decrements the entry count associated with a + cached monitor. + - :ref:`PR_CWait` waits for a notification that a monitor's state has + changed. + - :ref:`PR_CNotify` notifies a thread waiting for a change in the state of + monitored data. + - :ref:`PR_CNotifyAll` notifies all the threads waiting for a change in + the state of monitored data. diff --git a/docs/nspr/reference/condition_variables.rst b/docs/nspr/reference/condition_variables.rst new file mode 100644 index 0000000000..b5a1b5abcb --- /dev/null +++ b/docs/nspr/reference/condition_variables.rst @@ -0,0 +1,50 @@ +This chapter describes the API for creating and destroying condition +variables, notifying condition variables of changes in monitored data, +and making a thread wait on such notification. + +- `Condition Variable Type <#Condition_Variable_Type>`__ +- `Condition Variable Functions <#Condition_Variable_Functions>`__ + +Conditions are closely associated with a single monitor, which typically +consists of a mutex, one or more condition variables, and the monitored +data. The association between a condition and a monitor is established +when a condition variable is created, and the association persists for +its life. In addition, a static association exists between the condition +and some data within the monitor. This data is what will be manipulated +by the program under the protection of the monitor. + +A call to :ref:`PR_WaitCondVar` causes a thread to block until a specified +condition variable receives notification of a change of state in its +associated monitored data. Other threads may notify the condition +variable when changes occur. + +For an introduction to NSPR thread synchronization, including locks and +condition variables, see `Introduction to +NSPR <Introduction_to_NSPR>`__. + +For reference information on NSPR locks, see +`Locks <NSPR_API_Reference/Locks>`__. + +NSPR provides a special type, :ref:`PRMonitor`, for use with Java. Unlike a +mutex of type :ref:`PRLock`, which can have multiple associated condition +variables of type :ref:`PRCondVar`, a mutex of type :ref:`PRMonitor` has a +single, implicitly associated condition variable. For information about +:ref:`PRMonitor`, see `Monitors <Monitors>`__. + +.. _Condition_Variable_Type: + +Condition Variable Type +----------------------- + + - :ref:`PRCondVar` + +.. _Condition_Variable_Functions: + +Condition Variable Functions +---------------------------- + + - :ref:`PR_NewCondVar` + - :ref:`PR_DestroyCondVar` + - :ref:`PR_WaitCondVar` + - :ref:`PR_NotifyCondVar` + - :ref:`PR_NotifyAllCondVar` diff --git a/docs/nspr/reference/date_and_time.rst b/docs/nspr/reference/date_and_time.rst new file mode 100644 index 0000000000..b86929b44e --- /dev/null +++ b/docs/nspr/reference/date_and_time.rst @@ -0,0 +1,83 @@ +This chapter describes the date and time functions in NSPR. + +NSPR represents time in two ways, absolute time and clock/calendar time. +NSPR provides types and constants for both representations, and +functions to convert time values between the two. + +- Absolute time representation treats time instants as points along the + time line. A time instant is represented by its position on the time + line relative to the origin, called the epoch. NSPR defines the epoch + to be midnight (00:00:00) 1 January 1970 UTC (Coordinated Universal + Time). In this form, time is just a point on the time line. There is + no notion of time zone. + +- Clock/calendar time, used for human interfaces, represents time in + the familiar year, month, day, hour, minute, second components. In + this form, the time zone information is important. For example, + without specifying the time zone, the time 8:00AM 1 May 1998 is + ambiguous. The NSPR data type for clock/calendar time, called an + exploded time, has the time zone information in it, so that its + corresponding point in absolute time is uniquely specified. + +Note that absolute and clock times are not normally used in timing +operations. For functions that deal with the measurement of elapsed time +and with timeouts, see `Interval Timing <Interval_Timing>`__. + +- `Macros for Time Unit + Conversion <#Macros_for_Time_Unit_Conversion>`__ +- `Types and Constants <#Types_and_Constants>`__ +- `Time Parameter Callback + Functions <#Time_Parameter_Callback_Functions>`__ +- `Functions <#Functions>`__ + +.. _Macros_for_Time_Unit_Conversion: + +Macros for Time Unit Conversion +------------------------------- + +Macros for converting between seconds, milliseconds, microseconds, and +nanoseconds. + +- :ref:`PR_MSEC_PER_SEC` +- :ref:`PR_USEC_PER_SEC` +- :ref:`PR_NSEC_PER_SEC` +- :ref:`PR_USEC_PER_MSEC` +- :ref:`PR_NSEC_PER_MSEC` + +.. _Types_and_Constants: + +Types and Constants +------------------- + +Types and constants defined for NSPR dates and times are: + +- :ref:`PRTime` +- :ref:`PRTimeParameters` +- :ref:`PRExplodedTime` + +.. _Time_Parameter_Callback_Functions: + +Time Parameter Callback Functions +--------------------------------- + +In some geographic locations, use of Daylight Saving Time (DST) and the +rule for determining the dates on which DST starts and ends have changed +a few times. Therefore, a callback function is used to determine time +zone information. + +You can define your own time parameter callback functions, which must +conform to the definition :ref:`PRTimeParamFn`. Two often-used callback +functions of this type are provided by NSPR: + +- :ref:`PRTimeParamFn` +- :ref:`PR_LocalTimeParameters` and :ref:`PR_GMTParameters` + +Functions +--------- + +The functions that create and manipulate time and date values are: + +- :ref:`PR_Now` +- :ref:`PR_ExplodeTime` +- :ref:`PR_ImplodeTime` +- :ref:`PR_NormalizeTime` diff --git a/docs/nspr/reference/dynamic_library_linking.rst b/docs/nspr/reference/dynamic_library_linking.rst new file mode 100644 index 0000000000..6ab8d33840 --- /dev/null +++ b/docs/nspr/reference/dynamic_library_linking.rst @@ -0,0 +1,114 @@ +Dynamic Library Search +====================== + +This section describes NSPR's programming interface to load, unload and +resolve symbols in dynamic libraries. It also provides a method by which +to condition symbols of statically linked code so that to other clients +it appears as though they are dynamically loaded. + +.. _Library_Linking_Types: + +Library Linking Types +--------------------- + +These data types are defined for dynamic library linking: + + - :ref:`PRLibrary` + - :ref:`PRStaticLinkTable` + +.. _Library_Linking_Functions: + +Library Linking Functions +------------------------- + +The library linking functions are: + + - :ref:`PR_SetLibraryPath` + - :ref:`PR_GetLibraryPath` + - :ref:`PR_GetLibraryName` + - :ref:`PR_FreeLibraryName` + - :ref:`PR_LoadLibrary` + - :ref:`PR_UnloadLibrary` + - :ref:`PR_FindSymbol` + - :ref:`PR_FindSymbolAndLibrary` + +.. _Finding_Symbols_Defined_in_the_Main_Executable_Program: + +Finding Symbols Defined in the Main Executable Program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`PR_LoadLibrary` cannot open a handle that references the main +executable program. (This is admittedly an omission that should be +fixed.) However, it is possible to look up symbols defined in the main +executable program as follows. + +.. code:: + + PRLibrary *lib; + void *funcPtr; + + funcPtr = PR_FindSymbolAndLibrary("FunctionName", &lib); + +When :ref:`PR_FindSymbolAndLibrary` returns, ``funcPtr`` is the value of +the function pointer you want to look up, and the variable lib +references the main executable program. You can then call +:ref:`PR_FindSymbol` on lib to look up other symbols defined in the main +program. Remember to call ``PR_UnloadLibrary(lib)`` to close the library +handle when you are done. + +.. _Platform_Notes: + +Platform Notes +-------------- + +To use the dynamic library loading functions on some platforms, certain +environment variables must be set at run time, and you may need to link +your executable programs using special linker options. + +This section summarizes these platform idiosyncrasies. For more +information, consult the man pages for ``ld`` and ``dlopen`` (or +``shl_load`` on HP-UX) for Unix, and the ``LoadLibrary`` documentation +for Win32. + +- `Dynamic Library Search Path <#Dynamic_Library_Search_Path>`__ +- `Exporting Symbols from the Main Executable + Program <#Exporting_Symbols_from_the_Main_Executable_Program>`__ + +Dynamic Library Search Path +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The dynamic library search path is the list of directories in which to +look for a dynamic library. Each platform has its own standard +directories in which to look for dynamic libraries, plus a customizable +list of directories specified by an environment variable. + +- On most Unix systems, this environment variable is + ``LD_LIBRARY_PATH``. These systems typically use ``dlopen`` to load a + dynamic library. +- HP-UX uses ``shl_load`` to load dynamic libraries, and the + environment variable specifying the dynamic library search path is + ``SHLIB_PATH``. Moreover, the executable program must be linked with + the +s option so that it will search for shared libraries in the + directories specified by ``SHLIB_PATH`` at run time. Alternatively, + you can enable the +s option as a postprocessing step using the + ``chatr`` tool. For example, link your executable program a.out + without the +s option, then execute the following: + +.. code:: + + chatr +s enable a.out + +- On Rhapsody, the environment variable is ``DYLD_LIBRARY_PATH``. +- On Win32, the environment variable is ``PATH``. The same search path + is used to search for executable programs and DLLs. + +.. _Exporting_Symbols_from_the_Main_Executable_Program: + +Exporting Symbols from the Main Executable Program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On some systems, symbols defined in the main executable program are not +exported by default. On HP-UX, you must link the executable program with +the -E linker option in order to export all symbols in the main program +to shared libraries. If you use the GNU compilers (on any platform), you +must also link the executable program with the -E option. diff --git a/docs/nspr/reference/floating_point_number_to_string_conversion.rst b/docs/nspr/reference/floating_point_number_to_string_conversion.rst new file mode 100644 index 0000000000..6c9b36003f --- /dev/null +++ b/docs/nspr/reference/floating_point_number_to_string_conversion.rst @@ -0,0 +1,24 @@ +NSPR provides functions that convert double-precision floating point +numbers to and from their character string representations. + +These conversion functions were originally written by David M. Gay of +AT&T. They use IEEE double-precision (not IEEE double-extended) +arithmetic. + +The header file ``prdtoa.h`` declares these functions. The functions +are: + + - :ref:`PR_strtod` + - :ref:`PR_dtoa` + - :ref:`PR_cnvtf` + +References +---------- + +Gay's implementation is inspired by these two papers. + +[1] William D. Clinger, "How to Read Floating Point Numbers Accurately," +Proc. ACM SIGPLAN '90, pp. 92-101. + +[2] Guy L. Steele, Jr. and Jon L. White, "How to Print Floating-Point +Numbers Accurately," Proc. ACM SIGPLAN '90, pp. 112-126. diff --git a/docs/nspr/reference/hash_tables.rst b/docs/nspr/reference/hash_tables.rst new file mode 100644 index 0000000000..bafef49c4b --- /dev/null +++ b/docs/nspr/reference/hash_tables.rst @@ -0,0 +1,42 @@ +This chapter describes the hash table functions in the plds (portable +library — data structures) library of NSPR. The hash table library +functions are declared in the header file ``plhash.h.`` + +.. warning:: + + **Warning**: The NSPR hash table library functions are not thread + safe. + +A hash table lookup may change the internal organization of the hash +table (to speed up future lookups). + +- `Hash Table Types and Constants <#Hash_Table_Types_and_Constants>`__ +- `Hash Table Functions <#Hash_Table_Functions>`__ + +.. _Hash_Table_Types_and_Constants: + +Hash Table Types and Constants +------------------------------ + + - :ref:`PLHashEntry` + - :ref:`PLHashTable` + - :ref:`PLHashNumber` + - :ref:`PLHashFunction` + - :ref:`PLHashComparator` + - :ref:`PLHashEnumerator` + - :ref:`PLHashAllocOps` + +.. _Hash_Table_Functions: + +Hash Table Functions +-------------------- + + - :ref:`PL_NewHashTable` + - :ref:`PL_HashTableDestroy` + - :ref:`PL_HashTableAdd` + - :ref:`PL_HashTableRemove` + - :ref:`PL_HashTableLookup` + - :ref:`PL_HashTableEnumerateEntries` + - :ref:`PL_HashString` + - :ref:`PL_CompareStrings` + - :ref:`PL_CompareValues` diff --git a/docs/nspr/reference/i_o_functions.rst b/docs/nspr/reference/i_o_functions.rst new file mode 100644 index 0000000000..667f05d06f --- /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 implementer 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` diff --git a/docs/nspr/reference/i_o_types.rst b/docs/nspr/reference/i_o_types.rst new file mode 100644 index 0000000000..16ec1bd705 --- /dev/null +++ b/docs/nspr/reference/i_o_types.rst @@ -0,0 +1,105 @@ +This chapter describes the most common NSPR types, enumerations, and +structures used with the functions described in `I/O +Functions <I%2f%2fO_Functions>`__ and `Network +Addresses <Network_Addresses>`__. These include the types used for +system access, normal file I/O, and socket (network) I/O. + +Types unique to a particular function are described with the function +itself. + +For sample code that illustrates basic I/O operations, see `Introduction +to NSPR <Introduction_to_NSPR>`__. + +- `Directory Type <#Directory_Type>`__ +- `File Descriptor Types <#File_Descriptor_Types>`__ +- `File Info Types <#File_Info_Types>`__ +- `Network Address Types <#Network_Address_Types>`__ +- `Types Used with Socket Options + Functions <#Types_Used_with_Socket_Options_Functions>`__ +- `Type Used with Memory-Mapped + I/O <#Type_Used_with_Memory-Mapped_I/O>`__ +- `Offset Interpretation for Seek + Functions <#Offset_Interpretation_for_Seek_Functions>`__ + +.. _Directory_Type: + +Directory Type +-------------- + + - :ref:`PRDir` + +.. _File_Descriptor_Types: + +File Descriptor Types +--------------------- + +NSPR represents I/O objects, such as open files and sockets, by file +descriptors of type :ref:`PRFileDesc`. This section introduces +:ref:`PRFileDesc` and related types. + + - :ref:`PRFileDesc` + - :ref:`PRIOMethods` + - :ref:`PRFilePrivate` + - :ref:`PRDescIdentity` + +Note that the NSPR documentation follows the Unix convention of using +the term\ *files* to refer to many kinds of I/O objects. To refer +specifically to the files in a file system (that is, disk files), this +documentation uses the term\ *normal files*. + +:ref:`PRFileDesc` has an object-oriented flavor. An I/O function on a +:ref:`PRFileDesc` structure is carried out by invoking the corresponding +"method" in the I/O methods table (a structure of type :ref:`PRIOMethods`) +of the :ref:`PRFileDesc` structure (the "object"). Different kinds of I/O +objects (such as files and sockets) have different I/O methods tables, +thus implementing different behavior in response to the same I/O +function call. + +NSPR supports the implementation of layered I/O. Each layer is +represented by a :ref:`PRFileDesc` structure, and the :ref:`PRFileDesc` +structures for the layers are chained together. Each :ref:`PRFileDesc` +structure has a field (of type :ref:`PRDescIdentity`) to identify itself in +the layers. For example, the Netscape implementation of the Secure +Sockets Layer (SSL) protocol is implemented as an I/O layer on top of +NSPR's socket layer. + +.. _File_Info_Types: + +File Info Types +--------------- + + - :ref:`PRFileInfo` + - :ref:`PRFileInfo64` + - :ref:`PRFileType` + +.. _Network_Address_Types: + +Network Address Types +--------------------- + + - :ref:`PRNetAddr` + - :ref:`PRIPv6Addr` + +.. _Types_Used_with_Socket_Options_Functions: + +Types Used with Socket Options Functions +---------------------------------------- + + - :ref:`PRSocketOptionData` + - :ref:`PRSockOption` + - :ref:`PRLinger` + - :ref:`PRMcastRequest` + +.. _Type_Used_with_Memory-Mapped_I.2FO: + +Type Used with Memory-Mapped I/O +-------------------------------- + + - :ref:`PRFileMap` + +.. _Offset_Interpretation_for_Seek_Functions: + +Offset Interpretation for Seek Functions +---------------------------------------- + + - :ref:`PRSeekWhence` diff --git a/docs/nspr/reference/index.rst b/docs/nspr/reference/index.rst new file mode 100644 index 0000000000..8502db1e33 --- /dev/null +++ b/docs/nspr/reference/index.rst @@ -0,0 +1,289 @@ +NSPR API Reference +================== + +.. toctree:: + :maxdepth: 2 + +Introduction to NSPR +-------------------- + +- :ref:`NSPR_Naming_Conventions` +- :ref:`NSPR_Threads` + + - :ref:`Thread_Scheduling` + + - :ref:`Setting_Thread_Priorities` + - :ref:`Preempting_Threads` + - :ref:`Interrupting_Threads` + +- :ref:`NSPR_Thread_Synchronization` + + - :ref:`Locks_and_Monitors` + - :ref:`Condition_Variables` + +- :ref:`NSPR_Sample_Code` + +NSPR Types +---------- + +- :ref:`Calling_Convention_Types` +- :ref:`Algebraic_Types` + + - :ref:`8-.2C_16-.2C_and_32-bit_Integer_Types` + + - :ref:`Signed_Integers` + - :ref:`Unsigned_Integers` + + - :ref:`64-bit_Integer_Types` + - :ref:`Floating-Point_Number_Type` + - :ref:`Native_OS_Integer_Types` + +- :ref:`Miscellaneous_Types` + + - :ref:`Size_Type` + - :ref:`Pointer_Difference_Types` + - :ref:`Boolean_Types` + - :ref:`Status_Type_for_Return_Values` + +Threads +------- + +- :ref:`Threading_Types_and_Constants` +- :ref:`Threading_Functions` + + - :ref:`Creating.2C_Joining.2C_and_Identifying_Threads` + - :ref:`Controlling_Thread_Priorities` + - :ref:`Controlling_Per-Thread_Private_Data` + - :ref:`Interrupting_and_Yielding` + - :ref:`Setting_Global_Thread_Concurrency` + - :ref:`Getting_a_Thread.27s_Scope` + +Process Initialization +---------------------- + +- :ref:`Identity_and_Versioning` + + - :ref:`Name_and_Version_Constants` + +- :ref:`Initialization_and_Cleanup` +- :ref:`Module_Initialization` + +Locks +----- + +- :ref:`Lock_Type` +- :ref:`Lock_Functions` + +Condition_Variables +------------------- + +- :ref:`Condition_Variable_Type` +- :ref:`Condition_Variable_Functions` + +Monitors +-------- + +- :ref:`Monitor_Type` +- :ref:`Monitor_Functions` + +Cached Monitors +--------------- + +- :ref:`Cached_Monitors_Functions` + +I/O Types +--------- + +- :ref:`Directory_Type` +- :ref:`File_Descriptor_Types` +- :ref:`File_Info_Types` +- :ref:`Network_Address_Types` +- :ref:`Types_Used_with_Socket_Options_Functions` +- :ref:`Type_Used_with_Memory-Mapped_I.2FO` +- :ref:`Offset_Interpretation_for_Seek_Functions` + +I/O Functions +------------- + +- :ref:`Functions_that_Operate_on_Pathnames` +- :ref:`Functions_that_Act_on_File_Descriptors` +- :ref:`Directory_I.2FO_Functions` +- :ref:`Socket_Manipulation_Functions` +- :ref:`Converting_Between_Host_and_Network_Addresses` +- :ref:`Memory-Mapped_I.2FO_Functions` +- :ref:`Anonymous_Pipe_Function` +- :ref:`Polling_Functions` +- :ref:`Pollable_Events` +- :ref:`Manipulating_Layers` + +Network Addresses +----------------- + +- :ref:`Network_Address_Types_and_Constants` +- :ref:`Network_Address_Functions` + +Atomic Operations +----------------- + +- :ref:`PR_AtomicIncrement` +- :ref:`PR_AtomicDecrement` +- :ref:`PR_AtomicSet` + +Interval Timing +--------------- + +- :ref:`Interval_Time_Type_and_Constants` +- :ref:`Interval_Functions` + +Date and Time +------------- + +- :ref:`Types_and_Constants` +- :ref:`Time_Parameter_Callback_Functions` +- :ref:`Functions` + +Memory_Management Operations +---------------------------- + +- :ref:`Memory_Allocation_Functions` +- :ref:`Memory_Allocation_Macros` + +String Operations +----------------- + +- :ref:`PL_strlen` +- :ref:`PL_strcpy` +- :ref:`PL_strdup` +- :ref:`PL_strfree` + +Floating Point Number to String Conversion +------------------------------------------ + +- :ref:`PR_strtod` +- :ref:`PR_dtoa` +- :ref:`PR_cnvtf` + +Linked Lists +------------ + +- :ref:`Linked_List_Types` + + - :ref:`PRCList` + +- :ref:`Linked_List_Macros` + + - :ref:`PR_INIT_CLIST` + - :ref:`PR_INIT_STATIC_CLIST` + - :ref:`PR_APPEND_LINK` + - :ref:`PR_INSERT_LINK` + - :ref:`PR_NEXT_LINK` + - :ref:`PR_PREV_LINK` + - :ref:`PR_REMOVE_LINK` + - :ref:`PR_REMOVE_AND_INIT_LINK` + - :ref:`PR_INSERT_BEFORE` + - :ref:`PR_INSERT_AFTER` + +Dynamic Library Linking +----------------------- + +- :ref:`Library_Linking_Types` + + - :ref:`PRLibrary` + - :ref:`PRStaticLinkTable` + +- :ref:`Library_Linking_Functions` + + - :ref:`PR_SetLibraryPath` + - :ref:`PR_GetLibraryPath` + - :ref:`PR_GetLibraryName` + - :ref:`PR_FreeLibraryName` + - :ref:`PR_LoadLibrary` + - :ref:`PR_UnloadLibrary` + - :ref:`PR_FindSymbol` + - :ref:`PR_FindSymbolAndLibrary` + - :ref:`Finding_Symbols_Defined_in_the_Main_Executable_Program` + +- :ref:`Platform_Notes` + + - :ref:`Dynamic_Library_Search_Path` + - :ref:`Exporting_Symbols_from_the_Main_Executable_Program` + +Process Management and Interprocess Communication +------------------------------------------------- + +- :ref:`Process_Management_Types_and_Constants` + + - :ref:`PRProcess` + - :ref:`PRProcessAttr` + +- :ref:`Process_Management_Functions` + + - :ref:`Setting_the_Attributes_of_a_New_Process` + - :ref:`Creating_and_Managing_Processes` + +Logging +------- + +- :ref:`Conditional_Compilation_and_Execution` +- :ref:`Log_Types_and_Variables` + + - :ref:`PRLogModuleInfo` + - :ref:`PRLogModuleLevel` + - :ref:`NSPR_LOG_MODULES` + - :ref:`NSPR_LOG_FILE` + +- :ref:`Logging_Functions_and_Macros` + + - :ref:`PR_NewLogModule` + - :ref:`PR_SetLogFile` + - :ref:`PR_SetLogBuffering` + - :ref:`PR_LogPrint` + - :ref:`PR_LogFlush` + - :ref:`PR_LOG_TEST` + - :ref:`PR_LOG` + - :ref:`PR_Assert` + - :ref:`PR_ASSERT` + - :ref:`PR_NOT_REACHED` + +- :ref:`Use_Example` + +Named Shared Memory +------------------- + +- :ref:`Shared_Memory_Protocol` +- :ref:`Named_Shared_Memory_Functions` + +Anonymous Shared_Memory +----------------------- + +- :ref:`Anonymous_Memory_Protocol` +- :ref:`Anonymous_Shared_Memory_Functions` + +IPC Semaphores +-------------- + +- :ref:`IPC_Semaphore_Functions` + +Thread Pools +------------ + +- :ref:`Thread_Pool_Types` +- :ref:`Thread_Pool_Functions` + +Random Number Generator +----------------------- + +- :ref:`Random_Number_Generator_Function` + +Hash Tables +----------- + +- :ref:`Hash_Table_Types_and_Constants` +- :ref:`Hash_Table_Functions` + +NSPR Error Handling +------------------- + +- :ref:`Error_Type` +- :ref:`Error_Functions` +- :ref:`Error_Codes` diff --git a/docs/nspr/reference/interval_timing.rst b/docs/nspr/reference/interval_timing.rst new file mode 100644 index 0000000000..2d19d6004b --- /dev/null +++ b/docs/nspr/reference/interval_timing.rst @@ -0,0 +1,72 @@ +NSPR defines a platform-dependent type, :ref:`PRIntervalTime`, for timing +intervals of fewer than approximately 6 hours. This chapter describes +:ref:`PRIntervalTime` and the functions that allow you to use it for timing +purposes: + +- `Interval Time Type and + Constants <#Interval_Time_Type_and_Constants>`__ +- `Interval Functions <#Interval_Functions>`__ + +.. _Interval_Time_Type_and_Constants: + +Interval Time Type and Constants +-------------------------------- + +All timed functions in NSPR require a parameter that depicts the amount +of time allowed to elapse before the operation is declared failed. The +type of such arguments is :ref:`PRIntervalTime`. Such parameters are common +in NSPR functions such as those used for I/O operations and operations +on condition variables. + +NSPR 2.0 provides interval times that are efficient in terms of +performance and storage requirements. Conceptually, they are based on +free-running counters that increment at a fixed rate without possibility +of outside influence (as might be observed if one was using a +time-of-day clock that gets reset due to some administrative action). +The counters have no fixed epoch and have a finite period. To make use +of these counters, the application must declare a point in time, the +epoch, and an amount of time elapsed since that **epoch**, the +**interval**. In almost all cases the epoch is defined as the value of +the interval timer at the time it was sampled. + + - :ref:`PRIntervalTime` + +.. _Interval_Functions: + +Interval Functions +------------------ + +Interval timing functions are divided into three groups: + +- `Getting the Current Interval and Ticks Per + Second <#Getting_the_Current_Interval_and_Ticks_Per_Second>`__ +- `Converting Standard Clock Units to Platform-Dependent + Intervals <#Converting_Standard_Clock_Units_to_Platform-Dependent_Intervals>`__ +- `Converting Platform-Dependent Intervals to Standard Clock + Units <#Converting_Platform-Dependent_Intervals_to_Standard_Clock_Units>`__ + +.. _Getting_the_Current_Interval_and_Ticks_Per_Second: + +Getting the Current Interval and Ticks Per Second +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_IntervalNow` + - :ref:`PR_TicksPerSecond` + +.. _Converting_Standard_Clock_Units_to_Platform-Dependent_Intervals: + +Converting Standard Clock Units to Platform-Dependent Intervals +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_SecondsToInterval` + - :ref:`PR_MillisecondsToInterval` + - :ref:`PR_MicrosecondsToInterval` + +.. _Converting_Platform-Dependent_Intervals_to_Standard_Clock_Units: + +Converting Platform-Dependent Intervals to Standard Clock Units +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_IntervalToSeconds` + - :ref:`PR_IntervalToMilliseconds` + - :ref:`PR_IntervalToMicroseconds` diff --git a/docs/nspr/reference/introduction_to_nspr.rst b/docs/nspr/reference/introduction_to_nspr.rst new file mode 100644 index 0000000000..72460157a7 --- /dev/null +++ b/docs/nspr/reference/introduction_to_nspr.rst @@ -0,0 +1,408 @@ +Introduction to NSPR +==================== + +The Netscape Portable Runtime (NSPR) API allows compliant applications +to use system facilities such as threads, thread synchronization, I/O, +interval timing, atomic operations, and several other low-level services +in a platform-independent manner. This chapter introduces key NSPR +programming concepts and illustrates them with sample code. + +NSPR does not provide a platform for porting existing code. It must be +used from the beginning of a software project. + +.. _NSPR_Naming_Conventions: + +NSPR Naming Conventions +----------------------- + +Naming of NSPR types, functions, and macros follows the following +conventions: + +- Types exported by NSPR begin with ``PR`` and are followed by + intercap-style declarations, like this: :ref:`PRInt`, :ref:`PRFileDesc` +- Function definitions begin with ``PR_`` and are followed by + intercap-style declarations, like this: :ref:`PR_Read``, + :ref:`PR_JoinThread`` +- Preprocessor macros begin with the letters ``PR`` and are followed by + all uppercase characters separated with the underscore character + (``_``), like this: :ref:`PR_BYTES_PER_SHORT`, :ref:`PR_EXTERN` + +.. _NSPR_Threads: + +NSPR Threads +------------ + +NSPR provides an execution environment that promotes the use of +lightweight threads. Each thread is an execution entity that is +scheduled independently from other threads in the same process. A thread +has a limited number of resources that it truly owns. These resources +include the thread stack and the CPU register set (including PC). + +To an NSPR client, a thread is represented by a pointer to an opaque +structure of type :ref:`PRThread``. A thread is created by an explicit +client request and remains a valid, independent execution entity until +it returns from its root function or the process abnormally terminates. +(:ref:`PRThread` and functions for creating and manipulating threads are +described in detail in `Threads <Threads>`__.) + +NSPR threads are lightweight in the sense that they are cheaper than +full-blown processes, but they are not free. They achieve the cost +reduction by relying on their containing process to manage most of the +resources that they access. This, and the fact that threads share an +address space with other threads in the same process, makes it important +to remember that *threads are not processes* . + +NSPR threads are scheduled in two separate domains: + +- **Local threads** are scheduled within a process only and are handled + entirely by NSPR, either by completely emulating threads on each host + operating system (OS) that doesn't support threads, or by using the + threading facilities of each host OS that does support threads to + emulate a relatively large number of local threads by using a + relatively small number of native threads. + +- **Global threads** are scheduled by the host OS--not by NSPR--either + within a process or across processes on the entire host. Global + threads correspond to native threads on the host OS. + +NSPR threads can also be either user threads or system threads. NSPR +provides a function, :ref:`PR_Cleanup`, that synchronizes process +termination. :ref:`PR_Cleanup` waits for the last user thread to exit +before returning, whereas it ignores system threads when determining +when a process should exit. This arrangement implies that a system +thread should not have volatile data that needs to be safely stored +away. + +Priorities for NSPR threads are based loosely on hints provided by the +client and sometimes constrained by the underlying operating system. +Therefore, priorities are not rigidly defined. For more information, see +`Thread Scheduling <#Thread_Scheduling>`__. + +In general, it's preferable to create local user threads with normal +priority and let NSPR take care of the details as appropriate for each +host OS. It's usually not necessary to create a global thread explicitly +unless you are planning to port your code only to platforms that provide +threading services with which you are familiar or unless the thread will +be executing code that might directly call blocking OS functions. + +Threads can also have "per-thread-data" attached to them. Each thread +has a built-in per-thread error number and error string that are updated +when NSPR operations fail. It's also possible for NSPR clients to define +their own per-thread-data. For details, see `Controlling Per-Thread +Private Data <Threads#Controlling_Per-Thread_Private_Data>`__. + +.. _Thread_Scheduling: + +Thread Scheduling +~~~~~~~~~~~~~~~~~ + +NSPR threads are scheduled by priority and can be preempted or +interrupted. The sections that follow briefly introduce the NSPR +approach to these three aspects of thread scheduling. + +- `Setting Thread Priorities <#Setting_Thread_Priorities>`__ +- `Preempting Threads <#Preempting_Threads>`__ +- `Interrupting Threads <#Interrupting_Threads>`__ + +For reference information on the NSPR API used for thread scheduling, +see `Threads <Threads>`__. + +.. _Setting_Thread_Priorities: + +Setting Thread Priorities +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The host operating systems supported by NSPR differ widely in the +mechanisms they use to support thread priorities. In general, an NSPR +thread of higher priority has a statistically better chance of running +relative to threads of lower priority. However, because of the multiple +strategies to provide execution vehicles for threads on various host +platforms, priorities are not a clearly defined abstraction in NSPR. At +best they are intended to specify a preference with respect to the +amount of CPU time that a higher-priority thread might expect relative +to a lower-priority thread. This preference is still subject to resource +availability, and must not be used in place of proper synchronization. +For more information on thread synchronization, see `NSPR Thread +Synchronization <#NSPR_Thread_Synchronization>`__. + +The issue is further muddied by inconsistent offerings from OS vendors +regarding the priority of their kernel-supported threads. NSPR assumes +that the priorities of global threads are not manageable, but that the +host OS will perform some sort of fair scheduling. It's usually +preferable to create local user threads with normal priority and let +NSPR and the host take care of the details. + +In some NSPR configurations, there may be an arbitrary (and perhaps +large) number of local threads being supported by a more limited number +of **virtual processors** (an internal application of global threads). +In such situations, each virtual processor will have some number of +local threads associated with it, though exactly which local threads and +how many may vary over time. NSPR guarantees that for each virtual +processor the highest-priority, schedulable local thread is the one +executing. This thread implementation strategy is referred to as the **M +x N model.** + +.. _Preempting_Threads: + +Preempting Threads +^^^^^^^^^^^^^^^^^^ + +Preemption is the act of taking control away from a ready thread at an +arbitrary point and giving control to another appropriate thread. It +might be viewed as taking the executing thread and adding it to the end +of the ready queue for its appropriate priority, then simply running the +scheduling algorithm to find the most appropriate thread. The chosen +thread may be of higher priority, of the same priority, or even the same +thread. It will not be a thread of lower priority. + +Some operating systems cannot be made preemptible (for example, Mac OS +and Win 16). This puts them at some risk in supporting arbitrary code, +even if the code is interpreted (Java). Other systems are not +thread-aware, and their runtime libraries not thread-safe (most versions +of Unix). These systems can support local level thread abstractions that +can be made preemptible, but run the risk of library corruption +(``libc``). Still other operating systems have a native notion of +threads, and their libraries are thread-aware and support locking. +However, if local threads are also present, and they are preemptible, +they are subject to deadlock. At this time, the only safe solutions are +to turn off preemption (a runtime decision) or to preempt global threads +only. + +.. _Interrupting_Threads: + +Interrupting Threads +^^^^^^^^^^^^^^^^^^^^ + +NSPR threads are interruptible, with some constraints and +inconsistencies. + +To interrupt a thread, the caller of :ref:`PR_Interrupt` must have the NSPR +reference to the target thread (:ref:`PRThread`). When the target is +interrupted, it is rescheduled from the point at which it was blocked, +with a status error indicating that it was interrupted. NSPR recognizes +only two areas where a thread may be interrupted: waiting on a condition +variable and waiting on I/O. In the latter case, interruption does +cancel the I/O operation. In neither case does being interrupted imply +the demise of the thread. + +.. _NSPR_Thread_Synchronization: + +NSPR Thread Synchronization +--------------------------- + +Thread synchronization has two aspects: locking and notification. +Locking prevents access to some resource, such as a piece of shared +data: that is, it enforces mutual exclusion. Notification involves +passing synchronization information among cooperating threads. + +In NSPR, a **mutual exclusion lock** (or **mutex**) of type :ref:`PRLock` +controls locking, and associated **condition variables** of type +:ref:`PRCondVar` communicate changes in state among threads. When a +programmer associates a mutex with an arbitrary collection of data, the +mutex provides a protective **monitor** around the data. + +.. _Locks_and_Monitors: + +Locks and Monitors +~~~~~~~~~~~~~~~~~~ + +In general, a monitor is a conceptual entity composed of a mutex, one or +more condition variables, and the monitored data. Monitors in this +generic sense should not be confused with the monitor type used in Java +programming. In addition to :ref:`PRLock`, NSPR provides another mutex +type, :ref:`PRMonitor`, which is reentrant and can have only one associated +condition variable. :ref:`PRMonitor` is intended for use with Java and +reflects the Java approach to thread synchronization. + +To access the data in the monitor, the thread performing the access must +hold the mutex, also described as being "in the monitor." Mutual +exclusion guarantees that only one thread can be in the monitor at a +time and that no thread may observe or modify the monitored data without +being in the monitor. + +Monitoring is about protecting data, not code. A **monitored invariant** +is a Boolean expression over the monitored data. The expression may be +false only when a thread is in the monitor (holding the monitor's +mutex). This requirement implies that when a thread first enters the +monitor, an evaluation of the invariant expression must yield a +``true``. The thread must also reinstate the monitored invariant before +exiting the monitor. Therefore, evaluation of the expression must also +yield a true at that point in execution. + +A trivial example might be as follows. Suppose an object has three +values, ``v1``, ``v2``, and ``sum``. The invariant is that the third +value is the sum of the other two. Expressed mathematically, the +invariant is ``sum = v1 + v2``. Any modification of ``v1`` or ``v2`` +requires modification of ``sum``. Since that is a complex operation, it +must be monitored. Furthermore, any type of access to ``sum`` must also +be monitored to ensure that neither ``v1`` nor ``v2`` are in flux. + +.. note:: + + Evaluation of the invariant expression is a conceptual + requirement and is rarely done in practice. It is valuable to + formally define the expression during design, write it down, and + adhere to it. It is also useful to implement the expression during + development and test it where appropriate. The thread makes an + absolute assertion of the expression's evaluation both on entering + and on exiting the monitor. + +Acquiring a lock is a synchronous operation. Once the lock primitive is +called, the thread returns only when it has acquired the lock. Should +another thread (or the same thread) already have the lock held, the +calling thread blocks, waiting for the situation to improve. That +blocked state is not interruptible, nor is it timed. + +.. _Condition_Variables: + +Condition Variables +~~~~~~~~~~~~~~~~~~~ + +Condition variables facilitate communication between threads. The +communication available is a semantic-free notification whose context +must be supplied by the programmer. Conditions are closely associated +with a single monitor. + +The association between a condition and a monitor is established when a +condition variable is created, and the association persists for the life +of the condition variable. In addition, a static association exists +between the condition and some data within the monitor. This data is +what will be manipulated by the program under the protection of the +monitor. A thread may wait on notification of a condition that signals +changes in the state of the associated data. Other threads may notify +the condition when changes occur. + +Condition variables are always monitored. The relevant operations on +conditions are always performed from within the monitor. They are used +to communicate changes in the state of the monitored data (though still +preserving the monitored invariant). Condition variables allow one or +more threads to wait for a predetermined condition to exist, and they +allow another thread to notify them when the condition occurs. Condition +variables themselves do not carry the semantics of the state change, but +simply provide a mechanism for indicating that something has changed. It +is the programmer's responsibility to associate a condition with the +state of the data. + +A thread may be designed to wait for a particular situation to exist in +some monitored data. Since the nature of the situation is not an +attribute of the condition, the program must test that itself. Since +this testing involves the monitored data, it must be done from within +the monitor. The wait operation atomically exits the monitor and blocks +the calling thread in a waiting condition state. When the thread is +resumed after the wait, it will have reentered the monitor, making +operations on the data safe. + +There is a subtle interaction between the thread(s) waiting on a +condition and those notifying it. The notification must take place +within a monitor--the same monitor that protects the data being +manipulated by the notifier. In pseudocode, the sequence looks like +this: + +.. code:: + + enter(monitor); + ... manipulate the monitored data + notify(condition); + exit(monitor); + +Notifications to a condition do not accumulate. Nor is it required that +any thread be waiting on a condition when the notification occurs. The +design of the code that waits on a condition must take these facts into +account. Therefore, the pseudocode for the waiting thread might look +like this: + +.. code:: + + enter(monitor) + while (!expression) wait(condition); + ... manipulate monitored data + exit(monitor); + +The need to evaluate the Boolean expression again after rescheduling +from a wait may appear unnecessary, but it is vital to the correct +execution of the program. The notification promotes a thread waiting on +a condition to a ready state. When that thread actually gets scheduled +is determined by the thread scheduler and cannot be predicted. If +multiple threads are actually processing the notifications, one or more +of them could be scheduled ahead of the one explicitly promoted by the +notification. One such thread could enter the monitor and perform the +work indicated by the notification, and exit. In this case the thread +would resume from the wait only to find that there's nothing to do. + +For example, suppose the defined rule of a function is that it should +wait until there is an object available and that it should return a +reference to that object. Writing the code as follows could potentially +return a null reference, violating the invariant of the function: + +.. code:: + + void *dequeue() + { + void *db; + enter(monitor); + if ((db = delink()) == null) + { + wait(condition); + db = delink(); + } + exit(monitor); + return db; + } + +The same function would be more appropriately written as follows: + +.. code:: + + void *dequeue() + { + void *db; + enter(monitor); + while ((db = delink()) == null) + wait(condition); + exit(monitor); + return db; + } + +.. note:: + + **Caution**: The semantics of :ref:`PR_WaitCondVar` assume that the + monitor is about to be exited. This assumption implies that the + monitored invariant must be reinstated before calling + :ref:`PR_WaitCondVar`. Failure to do this will cause subtle but painful + bugs. + +To modify monitored data safely, a thread must be in the monitor. Since +no other thread may modify or (in most cases) even observe the protected +data from outside the monitor, the thread can safely make any +modifications needed. When the changes have been completed, the thread +notifies the condition associated with the data and exits the monitor +using :ref:`PR_NotifyCondVar`. Logically, each such notification promotes +one thread that was waiting on the condition to a ready state. An +alternate form of notification (:ref:`PR_NotifyAllCondVar`) promotes all +threads waiting on a condition to the ready state. If no threads were +waiting, the notification is a no-op. + +Waiting on a condition variable is an interruptible operation. Another +thread could target the waiting thread and issue a :ref:`PR_Interrupt`, +causing a waiting thread to resume. In such cases the return from the +wait operation indicates a failure and definitively indicates that the +cause of the failure is an interrupt. + +A call to :ref:`PR_WaitCondVar` may also resume because the interval +specified on the wait call has expired. However, this fact cannot be +unambiguously delivered, so no attempt is made to do so. If the logic of +a program allows for timing of waits on conditions, then the clock must +be treated as part of the monitored data and the amount of time elapsed +re-asserted when the call returns. Philosophically, timeouts should be +treated as explicit notifications, and therefore require the testing of +the monitored data upon resumption. + +.. _NSPR_Sample_Code: + +NSPR Sample Code +---------------- + +The documents linked here present two sample programs, including +detailed annotations: ``layer.html`` and ``switch.html``. In addition to +these annotated HTML versions, the same samples are available in pure +source form. diff --git a/docs/nspr/reference/ipc_semaphores.rst b/docs/nspr/reference/ipc_semaphores.rst new file mode 100644 index 0000000000..2391346c9c --- /dev/null +++ b/docs/nspr/reference/ipc_semaphores.rst @@ -0,0 +1,23 @@ +This chapter describes the NSPR API for using interprocess communication +semaphores. + +NSPR provides an interprocess communication mechanism using a counting +semaphore model similar to that which is provided in Unix and Windows +platforms. + +.. note:: + + **Note:** See also `Named Shared Memory <Named_Shared_Memory>`__ + +- `IPC Semaphore Functions <#IPC_Semaphore_Functions>`__ + +.. _IPC_Semaphore_Functions: + +IPC Semaphore Functions +----------------------- + + - :ref:`PR_OpenSemaphore` + - :ref:`PR_WaitSemaphore` + - :ref:`PR_PostSemaphore` + - :ref:`PR_CloseSemaphore` + - :ref:`PR_DeleteSemaphore` diff --git a/docs/nspr/reference/linked_lists.rst b/docs/nspr/reference/linked_lists.rst new file mode 100644 index 0000000000..696d112cd7 --- /dev/null +++ b/docs/nspr/reference/linked_lists.rst @@ -0,0 +1,36 @@ +This chapter describes the NSPR API for managing linked lists. The API +is a set of macros for initializing a circular (doubly linked) list, +inserting and removing elements from the list. The macros are not thread +safe. The caller must provide for mutually-exclusive access to the list, +and for the nodes being added and removed from the list. + +- `Linked List Types <#Linked_List_Types>`__ +- `Linked List Macros <#Linked_List_Macros>`__ + +.. _Linked_List_Types: + +Linked List Types +----------------- + +The :ref:`PRCList` type represents a circular linked list. + +.. _Linked_List_Macros: + +Linked List Macros +------------------ + +Macros that create and operate on linked lists are: + + - :ref:`PR_INIT_CLIST` + - :ref:`PR_INIT_STATIC_CLIST` + - :ref:`PR_APPEND_LINK` + - :ref:`PR_INSERT_LINK` + - :ref:`PR_NEXT_LINK` + - :ref:`PR_PREV_LINK` + - :ref:`PR_REMOVE_LINK` + - :ref:`PR_REMOVE_AND_INIT_LINK` + - :ref:`PR_INSERT_BEFORE` + - :ref:`PR_INSERT_AFTER` + - :ref:`PR_CLIST_IS_EMPTY` + - :ref:`PR_LIST_HEAD` + - :ref:`PR_LIST_TAIL` diff --git a/docs/nspr/reference/locks.rst b/docs/nspr/reference/locks.rst new file mode 100644 index 0000000000..5ab57102c1 --- /dev/null +++ b/docs/nspr/reference/locks.rst @@ -0,0 +1,42 @@ +This chapter describes the NSPR API for creation and manipulation of a +mutex of type :ref:`PRLock`. + +- `Lock Type <#Lock_Type>`__ +- `Lock Functions <#Lock_Functions>`__ + +In NSPR, a mutex of type :ref:`PRLock` controls locking, and associated +condition variables communicate changes in state among threads. When a +programmer associates a mutex with an arbitrary collection of data, the +mutex provides a protective monitor around the data. + +In general, a monitor is a conceptual entity composed of a mutex, one or +more condition variables, and the monitored data. Monitors in this +generic sense should not be confused with monitors used in Java +programming. In addition to :ref:`PRLock`, NSPR provides another mutex +type, :ref:`PRMonitor`, which is reentrant and can have only one associated +condition variable. :ref:`PRMonitor` is intended for use with Java and +reflects the Java approach to thread synchronization. + +For an introduction to NSPR thread synchronization, including locks and +condition variables, see `Introduction to +NSPR <Introduction_to_NSPR>`__. + +For reference information on NSPR condition variables, see `Condition +Variables <Condition_Variables>`__. + +.. _Lock_Type: + +Lock Type +--------- + + - :ref:`PRLock` + +.. _Lock_Functions: + +Lock Functions +-------------- + + - :ref:`PR_NewLock` creates a new lock object. + - :ref:`PR_DestroyLock` destroys a specified lock object. + - :ref:`PR_Lock` locks a specified lock object. + - :ref:`PR_Unlock` unlocks a specified lock object. diff --git a/docs/nspr/reference/logging.rst b/docs/nspr/reference/logging.rst new file mode 100644 index 0000000000..ba91ad39a6 --- /dev/null +++ b/docs/nspr/reference/logging.rst @@ -0,0 +1,116 @@ +NSPR Logging +============ + +This chapter describes the global functions you use to perform logging. +NSPR provides a set of logging functions that conditionally write +``printf()`` style strings to the console or to a log file. NSPR uses +this facility itself for its own development debugging purposes. + +You can select events to be logged by module or level. A module is a +user-defined class of log events. A level is a numeric value that +indicates the seriousness of the event to be logged. You can combine +module and level criteria to get highly selective logging. + +NSPR also provides "assert"-style macros and functions to aid in +application debugging. + +- `Conditional Compilation and + Execution <#Conditional_Compilation_and_Execution>`__ +- `Log Types and Variables <#Log_Types_and_Variables>`__ +- `Logging Functions and Macros <#Logging_Functions_and_Macros>`__ +- `Use Example <#Use_Example>`__ + +.. _Conditional_Compilation_and_Execution: + +Conditional Compilation and Execution +------------------------------------- + +NSPR's logging facility is conditionally compiled in and enabled for +applications using it. These controls are platform dependent. Logging is +not compiled in for the Win16 platform. Logging is compiled into the +NSPR debug builds; logging is not compiled into the NSPR optimized +builds. The compile time ``#define`` values ``DEBUG`` or +``FORCE_PR_LOG`` enable NSPR logging for application programs. + +To enable NSPR logging and/or the debugging aids in your application, +compile using the NSPR debug build headers and runtime. Set one of the +compile-time defines when you build your application. + +Execution-time control of NSPR's logging uses two environment variables. +These variables control which modules and levels are logged as well as +the file name of the log file. By default, no logging is enabled at +execution time. + +.. _Log_Types_and_Variables: + +Log Types and Variables +----------------------- + +Two types supporting NSPR logging are exposed in the API: + + - :ref:`PRLogModuleInfo` + - :ref:`PRLogModuleLevel` + +Two environment variables control the behavior of logging at execution +time: + + - :ref:`NSPR_LOG_MODULES` + - :ref:`NSPR_LOG_FILE` + +.. _Logging_Functions_and_Macros: + +Logging Functions and Macros +---------------------------- + +The functions and macros for logging are: + + - :ref:`PR_NewLogModule` + - :ref:`PR_SetLogFile` + - :ref:`PR_SetLogBuffering` + - :ref:`PR_LogPrint` + - :ref:`PR_LogFlush` + - :ref:`PR_LOG_TEST` + - :ref:`PR_LOG` + - :ref:`PR_Assert` + - :ref:`PR_STATIC_ASSERT` (new in NSPR 4.6.6XXX this hasn't been released + yet; the number is a logical guess) + - :ref:`PR_NOT_REACHED` + +.. note:: + + The above documentation has not been ported to MDN yet, see + http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25338. + +.. _Use_Example: + +Use Example +----------- + +The following sample code fragment demonstrates use of the logging and +debugging aids. + +- Compile the program with DEBUG defined. +- Before running the compiled program, set the environment variable + NSPR_LOG_MODULES to userStuff:5 + +.. code:: + + static void UserLogStuff( void ) + { + PRLogModuleInfo *myLM; + PRIntn i; + + PR_STATIC_ASSERT(5 > 4); /* NSPR 4.6.6 or newer */ + + myLM = PR_NewLogModule( "userStuff" ); + PR_ASSERT( myLM ); + + PR_LOG( myLM, PR_LOG_NOTICE, ("Log a Notice %d\n", 999 )); + for (i = 0; i < 10 ; i++ ) + { + PR_LOG( myLM, PR_LOG_DEBUG, ("Log Debug number: %d\n", i)); + PR_Sleep( 500 ); + } + PR_LOG( myLM, PR_LOG_NOTICE, "That's all folks\n"); + + } /* end UserLogStuff() */ diff --git a/docs/nspr/reference/long_long_(64-bit)_integers.rst b/docs/nspr/reference/long_long_(64-bit)_integers.rst new file mode 100644 index 0000000000..d0a747e7ed --- /dev/null +++ b/docs/nspr/reference/long_long_(64-bit)_integers.rst @@ -0,0 +1,32 @@ +Long Long integers +================== + +This chapter describes the global functions you use to perform 64-bit +integer operations. The functions define a portable API that can be used +reliably in any environment. Where 64-bit integers are desired, use of +NSPR's implementation is recommended to ensure cross-platform +compatibility. + +Most of the 64-bit integer operations are implemented as macros. The +specific implementation of each macro depends on whether the compiler +for the target platform supports 64-bit integers. For a specific target +platform, if 64-bit integers are supported for that platform, define +``HAVE_LONG_LONG`` at compile time. + +.. _64-Bit_Integer_Types: + +64-Bit Integer Types +~~~~~~~~~~~~~~~~~~~~ + +NSPR provides two types to represent 64-bit integers: + +- :ref:`PRInt64` +- :ref:`PRUint64` + +.. _64-Bit_Integer_Functions: + +64-Bit Integer Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +The API defined for the 64-bit integer functions is consistent across +all supported platforms. diff --git a/docs/nspr/reference/memory_management_operations.rst b/docs/nspr/reference/memory_management_operations.rst new file mode 100644 index 0000000000..1f61020685 --- /dev/null +++ b/docs/nspr/reference/memory_management_operations.rst @@ -0,0 +1,49 @@ +This chapter describes the global functions and macros you use to +perform memory management. NSPR provides heap-based memory management +functions that map to the familiar ``malloc()``, ``calloc()``, +``realloc()``, and ``free()``. + +- `Memory Allocation Functions <#Memory_Allocation_Functions>`__ +- `Memory Allocation Macros <#Memory_Allocation_Macros>`__ + +.. _Memory_Allocation_Functions: + +Memory Allocation Functions +--------------------------- + +NSPR has its own heap, and these functions act on that heap. Libraries +built on top of NSPR, such as the Netscape security libraries, use these +functions to allocate and free memory. If you are allocating memory for +use by such libraries or freeing memory that was allocated by such +libraries, you must use these NSPR functions rather than the libc +equivalents. + +Memory allocation functions are: + + - :ref:`PR_Malloc` + - :ref:`PR_Calloc` + - :ref:`PR_Realloc` + - :ref:`PR_Free` + +``PR_Malloc()``, ``PR_Calloc()``, ``PR_Realloc()``, and ``PR_Free()`` +have the same signatures as their libc equivalents ``malloc()``, +``calloc()``, ``realloc()``, and ``free()``, and have the same +semantics. (Note that the argument type ``size_t`` is replaced by +:ref:`PRUint32`.) Memory allocated by ``PR_Malloc()``, ``PR_Calloc()``, or +``PR_Realloc()`` must be freed by ``PR_Free()``. + +.. _Memory_Allocation_Macros: + +Memory Allocation Macros +------------------------ + +Macro versions of the memory allocation functions are available, as well +as additional macros that provide programming convenience: + + - :ref:`PR_MALLOC` + - :ref:`PR_NEW` + - :ref:`PR_REALLOC` + - :ref:`PR_CALLOC` + - :ref:`PR_NEWZAP` + - :ref:`PR_DELETE` + - :ref:`PR_FREEIF` diff --git a/docs/nspr/reference/monitors.rst b/docs/nspr/reference/monitors.rst new file mode 100644 index 0000000000..63d43d595b --- /dev/null +++ b/docs/nspr/reference/monitors.rst @@ -0,0 +1,63 @@ +In addition to the mutex type :ref:`PRLock`, NSPR provides a special type, +:ref:`PRMonitor`, for use in Java programming. This chapter describes the +NSPR API for creation and manipulation of a mutex of type :ref:`PRMonitor`. + +- `Monitor Type <#Monitor_Type>`__ +- `Monitor Functions <#Monitor_Functions>`__ + +With a mutex of type :ref:`PRLock`, a single thread may enter the monitor +only once before it exits, and the mutex can have multiple associated +condition variables. + +With a mutex of type :ref:`PRMonitor`, a single thread may re-enter a +monitor as many times as it sees fit. The first time the thread enters a +monitor, it acquires the monitor's lock and the thread's entry count is +incremented to 1. Each subsequent time the thread successfully enters +the same monitor, the thread's entry count is incremented again, and +each time the thread exits the monitor, the thread's entry count is +decremented. When the entry count for a thread reaches zero, the thread +releases the monitor's lock, and other threads that were blocked while +trying to enter the monitor will be rescheduled. + +A call to :ref:`PR_Wait` temporarily returns the entry count to zero. When +the calling thread resumes, it has the same entry count it had before +the wait operation. + +Unlike a mutex of type :ref:`PRLock`, a mutex of type :ref:`PRMonitor` has a +single, implicitly associated condition variable that may be used to +facilitate synchronization of threads with the change in state of +monitored data. + +For an introduction to NSPR thread synchronization, including locks and +condition variables, see `Introduction to +NSPR <Introduction_to_NSPR>`__. + +.. _Monitor_Type: + +Monitor Type +------------ + +With the exception of :ref:`PR_NewMonitor`, which creates a new monitor +object, all monitor functions require a pointer to an opaque object of +type :ref:`PRMonitor`. + +.. _Monitor_Functions: + +Monitor Functions +----------------- + +All monitor functions are thread-safe. However, this safety does not +extend to protecting the monitor object from deletion. + + - :ref:`PR_NewMonitor` creates a new monitor. + - :ref:`PR_DestroyMonitor` destroys a monitor object. + - :ref:`PR_EnterMonitor` enters the lock associated with a specified + monitor. + - :ref:`PR_ExitMonitor` decrements the entry count associated with a + specified monitor. + - :ref:`PR_Wait` waits for a notify on a specified monitor's condition + variable. + - :ref:`PR_Notify` notifies a thread waiting on a specified monitor's + condition variable. + - :ref:`PR_NotifyAll` notifies all threads waiting on a specified + monitor's condition variable. diff --git a/docs/nspr/reference/named_shared_memory.rst b/docs/nspr/reference/named_shared_memory.rst new file mode 100644 index 0000000000..dff1275cc4 --- /dev/null +++ b/docs/nspr/reference/named_shared_memory.rst @@ -0,0 +1,95 @@ +The chapter describes the NSPR API for named shared memory. Shared +memory allows multiple processes to access one or more common shared +memory regions, using it as an interprocess communication channel. The +NSPR shared memory API provides a cross-platform named shared-memory +interface that is modeled on similar constructs in the Unix and Windows +operating systems. + +- `Shared Memory Protocol <#Shared_Memory_Protocol>`__ +- `Named Shared Memory Functions <#Named_Shared_Memory_Functions>`__ + +.. _Shared_Memory_Protocol: + +Shared Memory Protocol +---------------------- + +.. _Using_Named_Shared_Memory_Functions: + +Using Named Shared Memory Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`PR_OpenSharedMemory` creates the shared memory segment, if it does +not already exist, or opens a connection with the existing shared memory +segment if it already exists. + +:ref:`PR_AttachSharedMemory` should be called following +:ref:`PR_OpenSharedMemory` to map the memory segment to an address in the +application's address space. :ref:`PR_AttachSharedMemory` may also be +called to remap a shared memory segment after detaching the same +``PRSharedMemory`` object. Be sure to detach it when you're finished. + +:ref:`PR_DetachSharedMemory` should be called to unmap the shared memory +segment from the application's address space. + +:ref:`PR_CloseSharedMemory` should be called when no further use of the +``PRSharedMemory`` object is required within a process. Following a call +to :ref:`PR_CloseSharedMemory`, the ``PRSharedMemory`` object is invalid +and cannot be reused. + +:ref:`PR_DeleteSharedMemory` should be called before process termination. +After you call :ref:`PR_DeleteSharedMemory`, any further use of the shared +memory associated with the name may cause unpredictable results. + +Filenames +~~~~~~~~~ + +The name passed to :ref:`PR_OpenSharedMemory` should be a valid filename +for a Unix platform. :ref:`PR_OpenSharedMemory` creates file using the name +passed in. Some platforms may mangle the name before creating the file +and the shared memory. The Unix implementation may use SysV IPC shared +memory, Posix shared memory, or memory mapped files; the filename may be +used to define the namespace. On Windows, the name is significant, but +there is no file associated with the name. + +No assumptions about the persistence of data in the named file should be +made. Depending on platform, the shared memory may be mapped onto system +paging space and be discarded at process termination. + +All names provided to :ref:`PR_OpenSharedMemory` should be valid filename +syntax or name syntax for shared memory for the target platform. +Referenced directories should have permissions appropriate for writing. + +.. _Limits_on_Shared_Memory_Resources: + +Limits on Shared Memory Resources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Different platforms have limits on both the number and size of shared +memory resources. The default system limits on some platforms may be +smaller than your requirements. These limits may be adjusted on some +platforms either via boot-time options or by setting the size of the +system paging space to accommodate more and/or larger shared memory +segment(s). + +.. _Security_Considerations: + +Security Considerations +~~~~~~~~~~~~~~~~~~~~~~~ + +On Unix platforms, depending on implementation, contents of the backing +store for the shared memory can be exposed via the file system. Set +permissions and or access controls at create and attach time to ensure +you get the desired security. + +On Windows platforms, no special security measures are provided. + +.. _Named_Shared_Memory_Functions: + +Named Shared Memory Functions +----------------------------- + + - :ref:`PR_OpenSharedMemory` + - :ref:`PR_AttachSharedMemory` + - :ref:`PR_DetachSharedMemory` + - :ref:`PR_CloseSharedMemory` + - :ref:`PR_DeleteSharedMemory` diff --git a/docs/nspr/reference/network_addresses.rst b/docs/nspr/reference/network_addresses.rst new file mode 100644 index 0000000000..c6845e6efc --- /dev/null +++ b/docs/nspr/reference/network_addresses.rst @@ -0,0 +1,82 @@ +This chapter describes the NSPR types and functions used to manipulate +network addresses. + +- `Network Address Types and + Constants <#Network_Address_Types_and_Constants>`__ +- `Network Address Functions <#Network_Address_Functions>`__ + +The API described in this chapter recognizes the emergence of Internet +Protocol Version 6 (IPv6). To facilitate the transition to IPv6, it is +recommended that clients treat all structures containing network +addresses as transparent objects and use the functions documented here +to manipulate the information. + +If used consistently, this API also eliminates the need to deal with the +byte ordering of network addresses. Typically, the only numeric +declarations required are the well-known port numbers that are part of +the :ref:`PRNetAddr` structure. + +.. _Network_Address_Types_and_Constants: + +Network Address Types and Constants +----------------------------------- + + - :ref:`PRHostEnt` + - :ref:`PRProtoEnt` + - :ref:`PR_NETDB_BUF_SIZE` + +.. _Network_Address_Functions: + +Network address functions +------------------------- + +.. _Initializing_a_Network_Address: + +Initializing a network address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`PR_InitializeNetAddr` facilitates the use of :ref:`PRNetAddr`, the basic +network address structure, in a polymorphic manner. By using these +functions with other network address functions, clients can support +either version 4 or version 6 of the Internet Protocol transparently. + +All NSPR functions that require `PRNetAddr <PRNetAddr>`__ as an argument +accept either an IPv4 or IPv6 version of the address. + + - :ref:`PR_InitializeNetAddr` + +.. _Converting_Between_a_String_and_a_Network_Address: + +Converting between a string and a network address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_StringToNetAddr` + - :ref:`PR_NetAddrToString` + +.. _Converting_address_formats: + +Converting address formats +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_ConvertIPv4AddrToIPv6` + +.. _Getting_Host_Names_and_Addresses: + +Getting host names and addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_GetHostByName` + - :ref:`PR_GetHostByAddr` + - :ref:`PR_EnumerateHostEnt` + - :ref:`PR_GetAddrInfoByName` + - :ref:`PR_EnumerateAddrInfo` + - :ref:`PR_GetCanonNameFromAddrInfo` + - :ref:`PR_FreeAddrInfo` + +.. _Getting_Protocol_Entries: + +Getting protocol entries +~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_GetProtoByName` + - :ref:`PR_GetProtoByNumber` diff --git a/docs/nspr/reference/nspr_error_handling.rst b/docs/nspr/reference/nspr_error_handling.rst new file mode 100644 index 0000000000..df40678607 --- /dev/null +++ b/docs/nspr/reference/nspr_error_handling.rst @@ -0,0 +1,206 @@ +This chapter describes the functions for retrieving and setting errors +and the error codes set by NSPR. + +- `Error Type <#Error_Type>`__ +- `Error Functions <#Error_Functions>`__ +- `Error Codes <#Error_Codes>`__ + +For information on naming conventions for NSPR types, functions, and +macros, see `NSPR Naming +Conventions <Introduction_to_NSPR#NSPR_Naming_Conventions>`__. + +.. _Error_Type: + +Error Type +---------- + + - :ref:`PRErrorCode` + +.. _Error_Functions: + +Error Functions +--------------- + + - :ref:`PR_SetError` + - :ref:`PR_SetErrorText` + - :ref:`PR_GetError` + - :ref:`PR_GetOSError` + - :ref:`PR_GetErrorTextLength` + - :ref:`PR_GetErrorText` + +.. _Error_Codes: + +Error Codes +----------- + +Error codes defined in ``prerror.h``: + +``PR_OUT_OF_MEMORY_ERROR`` + Insufficient memory to perform request. +``PR_BAD_DESCRIPTOR_ERROR`` + The file descriptor used as an argument in the preceding function is + invalid. +``PR_WOULD_BLOCK_ERROR`` + The operation would have blocked, which conflicts with the semantics + that have been established. +``PR_ACCESS_FAULT_ERROR`` + One of the arguments of the preceding function specified an invalid + memory address. +``PR_INVALID_METHOD_ERROR`` + The preceding function is invalid for the type of file descriptor + used. +``PR_ILLEGAL_ACCESS_ERROR`` + One of the arguments of the preceding function specified an invalid + memory address. +``PR_UNKNOWN_ERROR`` + Some unknown error has occurred. +``PR_PENDING_INTERRUPT_ERROR`` + The operation terminated because another thread has interrupted it + with :ref:`PR_Interrupt`. +``PR_NOT_IMPLEMENTED_ERROR`` + The preceding function has not been implemented. +``PR_IO_ERROR`` + The preceding I/O function encountered some sort of an error, perhaps + an invalid device. +``PR_IO_TIMEOUT_ERROR`` + The I/O operation has not completed in the time specified for the + preceding function. +``PR_IO_PENDING_ERROR`` + An I/O operation has been attempted on a file descriptor that is + currently busy with another operation. +``PR_DIRECTORY_OPEN_ERROR`` + The directory could not be opened. +``PR_INVALID_ARGUMENT_ERROR`` + One or more of the arguments to the function is invalid. +``PR_ADDRESS_NOT_AVAILABLE_ERROR`` + The network address (:ref:`PRNetAddr`) is not available (probably in + use). +``PR_ADDRESS_NOT_SUPPORTED_ERROR`` + The type of network address specified is not supported. +``PR_IS_CONNECTED_ERROR`` + An attempt to connect on an already connected network file + descriptor. +``PR_BAD_ADDRESS_ERROR`` + The network address specified is invalid (as reported by the + network). +``PR_ADDRESS_IN_USE_ERROR`` + Network address specified (:ref:`PRNetAddr`) is in use. +``PR_CONNECT_REFUSED_ERROR`` + The peer has refused to allow the connection to be established. +``PR_NETWORK_UNREACHABLE_ERROR`` + The network address specifies a host that is unreachable (perhaps + temporary). +``PR_CONNECT_TIMEOUT_ERROR`` + The connection attempt did not complete in a reasonable period of + time. +``PR_NOT_CONNECTED_ERROR`` + The preceding function attempted to use connected semantics on a + network file descriptor that was not connected. +``PR_LOAD_LIBRARY_ERROR`` + Failure to load a dynamic library. +``PR_UNLOAD_LIBRARY_ERROR`` + Failure to unload a dynamic library. +``PR_FIND_SYMBOL_ERROR`` + Symbol could not be found in the specified library. +``PR_INSUFFICIENT_RESOURCES_ERROR`` + There are insufficient system resources to process the request. +``PR_DIRECTORY_LOOKUP_ERROR`` + A directory lookup on a network address has failed. +``PR_TPD_RANGE_ERROR`` + Attempt to access a thread-private data index that is out of range of + any index that has been allocated to the process. +``PR_PROC_DESC_TABLE_FULL_ERROR`` + The process' table for holding open file descriptors is full. +``PR_SYS_DESC_TABLE_FULL_ERROR`` + The system's table for holding open file descriptors has been + exceeded. +``PR_NOT_SOCKET_ERROR`` + An attempt to use a non-network file descriptor on a network-only + operation. +``PR_NOT_TCP_SOCKET_ERROR`` + Attempt to perform a TCP specific function on a non-TCP file + descriptor. +``PR_SOCKET_ADDRESS_IS_BOUND_ERRO`` + Attempt to bind an address to a TCP file descriptor that is already + bound. +``PR_NO_ACCESS_RIGHTS_ERROR`` + Calling thread does not have privilege to perform the operation + requested. +``PR_OPERATION_NOT_SUPPORTED_ERRO`` + The requested operation is not supported by the platform. +``PR_PROTOCOL_NOT_SUPPORTED_ERROR`` + The host operating system does not support the protocol requested. +``PR_REMOTE_FILE_ERROR`` + Access to the remote file has been severed. +``PR_BUFFER_OVERFLOW_ERROR`` + The value retrieved is too large to be stored in the buffer provided. +``PR_CONNECT_RESET_ERROR`` + The (TCP) connection has been reset by the peer. +``PR_RANGE_ERROR`` + Unused. +``PR_DEADLOCK_ERROR`` + Performing the requested operation would have caused a deadlock. The + deadlock was avoided. +``PR_FILE_IS_LOCKED_ERROR`` + An attempt to acquire a lock on a file has failed because the file is + already locked. +``PR_FILE_TOO_BIG_ERROR`` + Completing the write or seek operation would have resulted in a file + larger than the system could handle. +``PR_NO_DEVICE_SPACE_ERROR`` + The device for storing the file is full. +``PR_PIPE_ERROR`` + Unused. +``PR_NO_SEEK_DEVICE_ERROR`` + Unused. +``PR_IS_DIRECTORY_ERROR`` + Attempt to perform a normal file operation on a directory. +``PR_LOOP_ERROR`` + Symbolic link loop. +``PR_NAME_TOO_LONG_ERROR`` + Filename is longer than allowed by the host operating system. +``PR_FILE_NOT_FOUND_ERROR`` + The requested file was not found. +``PR_NOT_DIRECTORY_ERROR`` + Attempt to perform directory specific operations on a normal file. +``PR_READ_ONLY_FILESYSTEM_ERROR`` + Attempt to write to a read-only file system. +``PR_DIRECTORY_NOT_EMPTY_ERROR`` + Attempt to delete a directory that is not empty. +``PR_FILESYSTEM_MOUNTED_ERROR`` + Attempt to delete or rename a file object while the file system is + busy. +``PR_NOT_SAME_DEVICE_ERROR`` + Request to rename a file to a file system on another device. +``PR_DIRECTORY_CORRUPTED_ERROR`` + The directory object in the file system is corrupted. +``PR_FILE_EXISTS_ERROR`` + Attempt to create or rename a file when the new name is already being + used. +``PR_MAX_DIRECTORY_ENTRIES_ERROR`` + Attempt to add new filename to directory would exceed the limit + allowed. +``PR_INVALID_DEVICE_STATE_ERROR`` + The device was in an invalid state to complete the desired operation. +``PR_DEVICE_IS_LOCKED_ERROR`` + The device needed to perform the desired request is locked. +``PR_NO_MORE_FILES_ERROR`` + There are no more entries in the directory. +``PR_END_OF_FILE_ERROR`` + Unexpectedly encountered end of file (Mac OS only). +``PR_FILE_SEEK_ERROR`` + An unexpected seek error (Mac OS only). +``PR_FILE_IS_BUSY_ERROR`` + The file is busy and the operation cannot be performed. +``PR_IN_PROGRESS_ERROR`` + The operation is still in progress (probably a nonblocking connect). +``PR_ALREADY_INITIATED_ERROR`` + The (retried) operation has already been initiated (probably a + nonblocking connect). +``PR_GROUP_EMPTY_ERROR`` + The wait group is empty. +``PR_INVALID_STATE_ERROR`` + The attempted operation is on an object that was in an improper state + to perform the request. +``PR_MAX_ERROR`` + Placeholder for the end of the list. diff --git a/docs/nspr/reference/nspr_log_file.rst b/docs/nspr/reference/nspr_log_file.rst new file mode 100644 index 0000000000..0208d4bac4 --- /dev/null +++ b/docs/nspr/reference/nspr_log_file.rst @@ -0,0 +1,31 @@ +NSPR_LOG_FILE +============= + +This environment variable specifies the file to which log messages are +directed. + + +Syntax +------ + +:: + + filespec + +*filespec* is a filename. The exact syntax is platform specific. + + +Description +----------- + +Use this environment variable to specify a log file other than the +default. If :ref:`NSPR_LOG_FILE` is not in the environment, then log output +is written to ``stdout`` or ``stderr``, depending on the platform. Set +:ref:`NSPR_LOG_FILE` to the name of the log file you want to use. NSPR +logging, when enabled, writes to the file named in this environment +variable. + +For MS Windows systems, you can set :ref:`NSPR_LOG_FILE` to the special +(case-sensitive) value ``WinDebug``. This value causes logging output to +be written using the Windows function ``OutputDebugString()``, which +writes to the debugger window. diff --git a/docs/nspr/reference/nspr_log_modules.rst b/docs/nspr/reference/nspr_log_modules.rst new file mode 100644 index 0000000000..9f2986607f --- /dev/null +++ b/docs/nspr/reference/nspr_log_modules.rst @@ -0,0 +1,88 @@ +NSPR_LOG_MODULES +================ + +This environment variable specifies which log modules have logging +enabled. + + +Syntax +------ + +:: + + moduleName:level[, moduleName:level]* + +*moduleName* is the name specified in a +`:ref:`PR_NewLogModule` <http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25372>`__ +call or one of the handy magic names listed below. + +*level* is a numeric value between 0 and 5, with the values having the +following meanings: + +- 0 = PR_LOG_NONE: nothing should be logged +- 1 = PR_LOG_ALWAYS: important; intended to always be logged +- 2 = PR_LOG_ERROR: errors +- 3 = PR_LOG_WARNING: warnings +- 4 = PR_LOG_DEBUG: debug messages, notices +- 5: everything! + + +Description +----------- + +Specify a ``moduleName`` that is associated with the ``name`` argument +in a call to +`:ref:`PR_NewLogModule` <http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25372>`__ +and a non-zero ``level`` value to enable logging for the named +``moduleName``. + +Special log module names are provided for controlling NSPR's log service +at execution time. These controls should be set in the +:ref:`NSPR_LOG_MODULES` environment variable at execution time to affect +NSPR's log service for your application. + +- **all** The name ``all`` enables all log modules. To enable all log + module calls to + ```PR_LOG`` <http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25497>`__, + set the variable as follows: + + :: + + set NSPR_LOG_MODULES=all:5 + +- **timestamp** Including ``timestamp`` results in a timestamp of the + form "2015-01-15 21:24:26.049906 UTC - " prefixing every logged line. + +- **append** Including ``append`` results in log entries being appended + to the existing contents of the file referenced by NSPR_LOG_FILE. If + not specified, the existing contents of NSPR_LOG_FILE will be lost as + a new file is created with the same filename. + +- **sync** The name ``sync`` enables unbuffered logging. This ensures + that all log messages are flushed to the operating system as they are + written, but may slow the program down. + +- **bufsize:size** The name ``bufsize:``\ *size* sets the log buffer to + *size*. + +Examples +-------- + +Log everything from the Toolkit::Storage component that happens, +prefixing each line with the timestamp when it was logged to the file +/tmp/foo.log (which will be replaced each time the executable is run). + +:: + + set NSPR_LOG_MODULES=timestamp,mozStorage:5 + set NSPR_LOG_FILE=/tmp/foo.log + +.. _Logging_with_Try_Server: + +Logging with Try Server +----------------------- + +- For **mochitest**, edit variable :ref:`NSPR_LOG_MODULES` in + ``testing/mochitest/runtests.py`` before pushing to try. You would be + able to download the log file as an artifact from the Log viewer. +- (other tests?) diff --git a/docs/nspr/reference/nspr_types.rst b/docs/nspr/reference/nspr_types.rst new file mode 100644 index 0000000000..6e304f4eb5 --- /dev/null +++ b/docs/nspr/reference/nspr_types.rst @@ -0,0 +1,180 @@ +This chapter describes the most common NSPR types. Other chapters +describe more specialized types when describing the functions that use +them. + +- `Calling Convention Types <#Calling_Convention_Types>`__ are used for + externally visible functions and globals. +- `Algebraic Types <#Algebraic_Types>`__ of various lengths are used + for integer algebra. +- `Miscellaneous Types <#Miscellaneous_Types>`__ are used for + representing size, pointer difference, Boolean values, and return + values. + +For information on naming conventions for NSPR types, functions, and +macros, see `NSPR Naming +Conventions <Introduction_to_NSPR#NSPR_Naming_Conventions>`__. + +.. _Calling_Convention_Types: + +Calling Convention Types +------------------------ + +These types are used to support cross-platform declarations of +prototypes and implementations: + + - :ref:`PR_EXTERN` is used for declarations of external functions or + variables. + - :ref:`PR_IMPLEMENT` is used for definitions of external functions or + variables. + - :ref:`PR_CALLBACK` is used for definitions and declarations of functions + that are called via function pointers. A typical example is a + function implemented in an application but called from a shared + library. + +Here are some simple examples of the use of these types: + +.. container:: highlight + + In dowhim.h: + + .. code:: + + PR_EXTERN( void ) DoWhatIMean( void ); + + static void PR_CALLBACK RootFunction(void *arg); + +.. container:: highlight + + In dowhim.c: + + .. code:: + + PR_IMPLEMENT( void ) DoWhatIMean( void ) { return; }; + + PRThread *thread = PR_CreateThread(..., RootFunction, ...); + +.. _Algebraic_Types: + +Algebraic Types +--------------- + +NSPR provides the following type definitions with unambiguous bit widths +for algebraic operations: + +- `8-, 16-, and 32-bit Integer + Types <#8-,_16-,_and_32-bit_Integer_Types>`__ +- `64-bit Integer Types <#64-bit_Integer_Types>`__ +- `Floating-Point Number Type <#Floating-Point_Number_Type>`__ + +For convenience, NSPR also provides type definitions with +platform-dependent bit widths: + +- `Native OS Integer Types <#Native_OS_Integer_Types>`__ + +.. _8-.2C_16-.2C_and_32-bit_Integer_Types: + +8-, 16-, and 32-bit Integer Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _Signed_Integers: + +Signed Integers +^^^^^^^^^^^^^^^ + + - :ref:`PRInt8` + - :ref:`PRInt16` + - :ref:`PRInt32` + +.. _Unsigned_Integers: + +Unsigned Integers +^^^^^^^^^^^^^^^^^ + + - :ref:`PRUint8` + - :ref:`PRUint16` + - :ref:`PRUint32` + +.. _64-bit_Integer_Types: + +64-bit Integer Types +~~~~~~~~~~~~~~~~~~~~ + +Different platforms treat 64-bit numeric fields in different ways. Some +systems require emulation of 64-bit fields by using two 32-bit numeric +fields bound in a structure. Since the types (``long long`` versus +``struct LONGLONG``) are not type compatible, NSPR defines macros to +manipulate 64-bit numeric fields. These macros are defined in +``prlong.h``. Conscientious use of these macros ensures portability of +code to all the platforms supported by NSPR and still provides optimal +behavior on those systems that treat long long values directly. + + - :ref:`PRInt64` + - :ref:`PRUint64` + +.. _Floating-Point_Number_Type: + +Floating-Point Number Type +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The NSPR floating-point type is always 64 bits. + + - :ref:`PRFloat64` + +.. _Native_OS_Integer_Types: + +Native OS Integer Types +~~~~~~~~~~~~~~~~~~~~~~~ + +These types are most appropriate for automatic variables. They are +guaranteed to be at least 16 bits, though various architectures may +define them to be wider (for example, 32 or even 64 bits). These types +are never valid for fields of a structure. + + - :ref:`PRIntn` + - :ref:`PRUintn` + +.. _Miscellaneous_Types: + +Miscellaneous Types +------------------- + +- `Size Type <#Size_Type>`__ +- `Pointer Difference Types <#Pointer_Difference_Types>`__ +- `Boolean Types <#Boolean_Types>`__ +- `Status Type for Return Values <#Status_Type_for_Return_Values>`__ + +.. _Size_Type: + +Size Type +~~~~~~~~~ + + - :ref:`PRSize` + +.. _Pointer_Difference_Types: + +Pointer Difference Types +~~~~~~~~~~~~~~~~~~~~~~~~ + +Types for pointer difference. Variables of these types are suitable for +storing a pointer or pointer subtraction. These are the same as the +corresponding types in ``libc``. + + - :ref:`PRPtrdiff` + - :ref:`PRUptrdiff` + +.. _Boolean_Types: + +Boolean Types +~~~~~~~~~~~~~ + +Type and constants for Boolean values. + + - :ref:`PRBool` + - :ref:`PRPackedBool` + +.. _Status_Type_for_Return_Values: + +Status Type for Return Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PRStatus` diff --git a/docs/nspr/reference/pl_comparestrings.rst b/docs/nspr/reference/pl_comparestrings.rst new file mode 100644 index 0000000000..46050c74b2 --- /dev/null +++ b/docs/nspr/reference/pl_comparestrings.rst @@ -0,0 +1,27 @@ +PL_CompareStrings +================= + +Compares two character strings. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PRIntn PL_CompareStrings( + const void *v1, + const void *v2); + + +Description +----------- + +:ref:`PL_CompareStrings` compares ``v1`` and ``v2`` as character strings +using ``strcmp``. If the two strings are equal, it returns 1. If the two +strings are not equal, it returns 0. + +:ref:`PL_CompareStrings` can be used as the comparator function for +string-valued key or entry value. diff --git a/docs/nspr/reference/pl_comparevalues.rst b/docs/nspr/reference/pl_comparevalues.rst new file mode 100644 index 0000000000..9fef0b63f3 --- /dev/null +++ b/docs/nspr/reference/pl_comparevalues.rst @@ -0,0 +1,27 @@ +PL_CompareValues +================ + +Compares two ``void *`` values numerically. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PRIntn PL_CompareValues(const + void *v1, + const void *v2); + + +Description +----------- + +:ref:`PL_CompareValues` compares the two ``void *`` values ``v1`` and +``v2`` numerically, i.e., it returns the value of the expression ``v1`` +== ``v2``. + +:ref:`PL_CompareValues` can be used as the comparator function for integer +or pointer-valued key or entry value. diff --git a/docs/nspr/reference/pl_hashstring.rst b/docs/nspr/reference/pl_hashstring.rst new file mode 100644 index 0000000000..3c6b8cde5f --- /dev/null +++ b/docs/nspr/reference/pl_hashstring.rst @@ -0,0 +1,36 @@ +PL_HashString +============= + +A general-purpose hash function for character strings. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PLHashNumber PL_HashString(const void *key); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``key`` + A pointer to a character string. + + +Returns +~~~~~~~ + +The hash number for the specified key. + + +Description +----------- + +:ref:`PL_HashString` can be used as the key hash function for a hash table +if the key is a character string. diff --git a/docs/nspr/reference/pl_hashtableadd.rst b/docs/nspr/reference/pl_hashtableadd.rst new file mode 100644 index 0000000000..a4827d5c05 --- /dev/null +++ b/docs/nspr/reference/pl_hashtableadd.rst @@ -0,0 +1,52 @@ +PL_HashTableAdd +=============== + +Add a new entry with the specified key and value to the hash table. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PLHashEntry *PL_HashTableAdd( + PLHashTable *ht, + const void *key, + void *value); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``ht`` + A pointer to the the hash table to which to add the entry. +``key`` + A pointer to the key for the entry to be added. +``value`` + A pointer to the value for the entry to be added. + + +Returns +~~~~~~~ + +A pointer to the new entry. + + +Description +----------- + +Add a new entry with the specified key and value to the hash table. + +If an entry with the same key already exists in the table, the +``freeEntry`` function is invoked with the ``HT_FREE_VALUE`` flag. You +can write your ``freeEntry`` function to free the value of the specified +entry if the old value should be freed. The default ``freeEntry`` +function does not free the value of the entry. + +:ref:`PL_HashTableAdd` returns ``NULL`` if there is not enough memory to +create a new entry. It doubles the number of buckets if the table is +overloaded. diff --git a/docs/nspr/reference/pl_hashtabledestroy.rst b/docs/nspr/reference/pl_hashtabledestroy.rst new file mode 100644 index 0000000000..9b45e5a609 --- /dev/null +++ b/docs/nspr/reference/pl_hashtabledestroy.rst @@ -0,0 +1,32 @@ +PL_HashTableDestroy +=================== + +Frees the table and all the entries. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + void PL_HashTableDestroy(PLHashTable *ht); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``ht`` + A pointer to the hash table to be destroyed. + + +Description +----------- + +:ref:`PL_HashTableDestroy` frees all the entries in the table and the table +itself. The entries are freed by the ``freeEntry`` function (with the +``HT_FREE_ENTRY`` flag) in the ``allocOps`` structure supplied when the +table was created. diff --git a/docs/nspr/reference/pl_hashtableenumerateentries.rst b/docs/nspr/reference/pl_hashtableenumerateentries.rst new file mode 100644 index 0000000000..ce77c8aad7 --- /dev/null +++ b/docs/nspr/reference/pl_hashtableenumerateentries.rst @@ -0,0 +1,46 @@ +PL_HashTableEnumerateEntries +============================ + +Enumerates all the entries in the hash table, invoking a specified +function on each entry. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PRIntn PL_HashTableEnumerateEntries( + PLHashTable *ht, + PLHashEnumerator f, + void *arg); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``ht`` + A pointer to the hash table whose entries are to be enumerated. +``f`` + Function to be applied to each entry. +``arg`` + Argument for function ``f``. + + +Returns +~~~~~~~ + +The number of entries enumerated. + + +Description +----------- + +The entries are enumerated in an unspecified order. For each entry, the +enumerator function is invoked with the entry, the index (in the +sequence of enumeration, starting from 0) of the entry, and arg as +arguments. diff --git a/docs/nspr/reference/pl_hashtablelookup.rst b/docs/nspr/reference/pl_hashtablelookup.rst new file mode 100644 index 0000000000..236c08a874 --- /dev/null +++ b/docs/nspr/reference/pl_hashtablelookup.rst @@ -0,0 +1,45 @@ +PL_HashTableLookup +================== + +Looks up the entry with the specified key and return its value. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + void *PL_HashTableLookup( + PLHashTable *ht, + const void *key); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``ht`` + A pointer to the hash table in which to look up the entry specified + by ``key``. +``key`` + A pointer to the key for the entry to look up. + + +Returns +~~~~~~~ + +The value of the entry with the specified key, or ``NULL`` if there is +no such entry. + + +Description +----------- + +If there is no entry with the specified key, :ref:`PL_HashTableLookup` +returns ``NULL``. This means that one cannot tell whether a ``NULL`` +return value means the entry does not exist or the value of the entry is +``NULL``. Keep this ambiguity in mind if you want to store ``NULL`` +values in a hash table. diff --git a/docs/nspr/reference/pl_hashtableremove.rst b/docs/nspr/reference/pl_hashtableremove.rst new file mode 100644 index 0000000000..32c3662f63 --- /dev/null +++ b/docs/nspr/reference/pl_hashtableremove.rst @@ -0,0 +1,46 @@ +PL_HashTableRemove +================== + +Removes the entry with the specified key from the hash table. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PRBool PL_HashTableRemove( + PLHashTable *ht, + const void *key); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``ht`` + A pointer to the hash table from which to remove the entry. +``key`` + A pointer to the key for the entry to be removed. + + +Description +----------- + +If there is no entry in the table with the specified key, +:ref:`PL_HashTableRemove` returns ``PR_FALSE``. If the entry exists, +:ref:`PL_HashTableRemove` removes the entry from the table, invokes +``freeEntry`` with the ``HT_FREE_ENTRY`` flag to frees the entry, and +returns ``PR_TRUE``. + +If the table is underloaded, :ref:`PL_HashTableRemove` also shrinks the +number of buckets by half. + + +Remark +------ + +This function should return :ref:`PRStatus`. diff --git a/docs/nspr/reference/pl_newhashtable.rst b/docs/nspr/reference/pl_newhashtable.rst new file mode 100644 index 0000000000..d4479284c5 --- /dev/null +++ b/docs/nspr/reference/pl_newhashtable.rst @@ -0,0 +1,67 @@ +PL_NewHashTable +=============== + +Create a new hash table. + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + PLHashTable *PL_NewHashTable( + PRUint32 numBuckets, + PLHashFunction keyHash, + PLHashComparator keyCompare, + PLHashComparator valueCompare, + const PLHashAllocOps *allocOps, + void *allocPriv + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``numBuckets`` + The number of buckets in the hash table. +``keyHash`` + Hash function. +``keyCompare`` + Function used to compare keys of entries. +``valueCompare`` + Function used to compare keys of entries. +``allocOps`` + A pointer to a ``PLHashAllocOps`` structure that must exist + throughout the lifetime of the new hash table. +``allocPriv`` + Passed as the first argument (pool). + + +Returns +~~~~~~~ + +The new hash table. + + +Description +----------- + +:ref:`PL_NewHashTable` creates a new hash table. The table has at least 16 +buckets. You can pass a value of 0 as ``numBuckets`` to create the +default number of buckets in the new table. The arguments ``keyCompare`` +and ``valueCompare`` are functions of type :ref:`PLHashComparator` that the +hash table library functions use to compare the keys and the values of +entries. + +The argument ``allocOps`` points to a ``PLHashAllocOps`` structure that +must exist throughout the lifetime of the new hash table. The hash table +library functions do not make a copy of this structure. When the +allocation functions in ``allocOps`` are invoked, the allocation private +data allocPriv is passed as the first argument (pool). You can specify a +``NULL`` value for ``allocOps`` to use the default allocation functions. +If ``allocOps`` is ``NULL``, ``allocPriv`` is ignored. Note that the +default ``freeEntry`` function does not free the value of the entry. diff --git a/docs/nspr/reference/pl_strcpy.rst b/docs/nspr/reference/pl_strcpy.rst new file mode 100644 index 0000000000..addd05b824 --- /dev/null +++ b/docs/nspr/reference/pl_strcpy.rst @@ -0,0 +1,40 @@ +PL_strcpy +========= + + +Copies a string, up to and including the trailing ``'\0'``, into a +destination buffer. + + +Syntax +~~~~~~ + +.. code:: + + char * PL_strcpy(char *dest, const char *src); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``dest`` + Pointer to a buffer. On output, the buffer contains a copy of the + string passed in src. +``src`` + Pointer to the string to be copied. + + +Returns +~~~~~~~ + +The function returns a pointer to the buffer specified by the ``dest`` +parameter. + + +Description +~~~~~~~~~~~ + +If the string specified by ``src`` is longer than the buffer specified +by ``dest``, the buffer will not be null-terminated. diff --git a/docs/nspr/reference/pl_strdup.rst b/docs/nspr/reference/pl_strdup.rst new file mode 100644 index 0000000000..fcced90ec4 --- /dev/null +++ b/docs/nspr/reference/pl_strdup.rst @@ -0,0 +1,48 @@ +PL_strdup +========= + +Returns a pointer to a new memory node in the NSPR heap containing a +copy of a specified string. + + +Syntax +~~~~~~ + +.. code:: + + #include <plstr.h> + + char *PL_strdup(const char *s); + + +Parameter +~~~~~~~~~ + +The function has a single parameter: + +``s`` + The string to copy, may be ``NULL``. + + +Returns +~~~~~~~ + +The function returns one of these values: + +- If successful, a pointer to a copy of the specified string. +- If the memory allocation fails, ``NULL``. + + +Description +~~~~~~~~~~~ + +To accommodate the terminator, the size of the allocated memory is one +greater than the length of the string being copied. A ``NULL`` argument, +like a zero-length argument, results in a pointer to a one-byte block of +memory containing the null value. + +Notes +~~~~~ + +The memory allocated by :ref:`PL_strdup` should be freed with +`PL_strfree </en/PL_strfree>`__. diff --git a/docs/nspr/reference/pl_strfree.rst b/docs/nspr/reference/pl_strfree.rst new file mode 100644 index 0000000000..e17c0c34cf --- /dev/null +++ b/docs/nspr/reference/pl_strfree.rst @@ -0,0 +1,21 @@ +PL_strfree +========== + +Frees memory allocated by :ref:`PL_strdup` + + +Syntax +~~~~~~ + +.. code:: + + void PL_strfree(char *s); + + +Parameter +~~~~~~~~~ + +The function has these parameter: + +``s`` + Pointer to the string to be freed. diff --git a/docs/nspr/reference/pl_strlen.rst b/docs/nspr/reference/pl_strlen.rst new file mode 100644 index 0000000000..edd1ecd129 --- /dev/null +++ b/docs/nspr/reference/pl_strlen.rst @@ -0,0 +1,28 @@ +PL_strlen +========= + +Returns the length of a specified string (not including the trailing +``'\0'``) + + +Syntax +~~~~~~ + +.. code:: + + PRUint32 PL_strlen(const char *str); + + +Parameter +~~~~~~~~~ + +The function has these parameter: + +``str`` + Size in bytes of item to be allocated. + + +Returns +~~~~~~~ + +If successful, the function returns length of the specified string. diff --git a/docs/nspr/reference/plhashallocops.rst b/docs/nspr/reference/plhashallocops.rst new file mode 100644 index 0000000000..02cceb9c2b --- /dev/null +++ b/docs/nspr/reference/plhashallocops.rst @@ -0,0 +1,40 @@ + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef struct PLHashAllocOps { + void *(PR_CALLBACK *allocTable)(void *pool, PRSize size); + void (PR_CALLBACK *freeTable)(void *pool, void *item); + PLHashEntry *(PR_CALLBACK *allocEntry)(void *pool, const void *key); + void (PR_CALLBACK *freeEntry)(void *pool, PLHashEntry *he, PRUintn flag); + } PLHashAllocOps; + + #define HT_FREE_VALUE 0 /* just free the entry's value */ + #define HT_FREE_ENTRY 1 /* free value and entire entry */ + + +Description +----------- + +Users of the hash table functions can provide their own memory +allocation functions. A pair of functions is used to allocate and tree +the table, and another pair of functions is used to allocate and free +the table entries. + +The first argument, pool, for all four functions is a void \* pointer +that is a piece of data for the memory allocator. Typically pool points +to a memory pool used by the memory allocator. + +The ``freeEntry`` function does not need to free the value of the entry. +If flag is ``HT_FREE_ENTRY``, the function frees the entry. + + +Remark +------ + +The ``key`` argument for the ``allocEntry`` function does not seem to be +useful. It is unused in the default ``allocEntry`` function. diff --git a/docs/nspr/reference/plhashcomparator.rst b/docs/nspr/reference/plhashcomparator.rst new file mode 100644 index 0000000000..1310a6f37d --- /dev/null +++ b/docs/nspr/reference/plhashcomparator.rst @@ -0,0 +1,41 @@ +PLHashComparator +================ + + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef PRIntn (PR_CALLBACK *PLHashComparator)( + const void *v1, + const void *v2); + + +Description +----------- + +:ref:`PLHashComparator` is a function type that compares two values of an +unspecified type. It returns a nonzero value if the two values are +equal, and 0 if the two values are not equal. :ref:`PLHashComparator` +defines the meaning of equality for the unspecified type. + +For convenience, two comparator functions are provided. +:ref:`PL_CompareStrings` compare two character strings using ``strcmp``. +:ref:`PL_CompareValues` compares the values of the arguments v1 and v2 +numerically. + + +Remark +------ + +The return value of :ref:`PLHashComparator` functions should be of type +:ref:`PRBool`. + + +See Also +-------- + +:ref:`PL_CompareStrings`, :ref:`PL_CompareValues` diff --git a/docs/nspr/reference/plhashentry.rst b/docs/nspr/reference/plhashentry.rst new file mode 100644 index 0000000000..ea11ac3439 --- /dev/null +++ b/docs/nspr/reference/plhashentry.rst @@ -0,0 +1,36 @@ + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef struct PLHashEntry PLHashEntry; + + +Description +----------- + +``PLHashEntry`` is a structure that represents an entry in the hash +table. An entry has a key and a value, represented by the following +fields in the ``PLHashEntry`` structure. + +.. code:: + + const void *key; + void *value; + +The key field is a pointer to an opaque key. The value field is a +pointer to an opaque value. If the key of an entry is an integral value +that can fit into a ``void *`` pointer, you can just cast the key itself +to ``void *`` and store it in the key field. Similarly, if the value of +an entry is an integral value that can fit into a ``void *`` pointer, +you can cast the value itself to ``void *`` and store it in the value +field. + +.. warning:: + + **Warning**: There are other fields in the ``PLHashEntry`` structure + besides key and value. These fields are for use by the hash table + library functions and the user should not tamper with them. diff --git a/docs/nspr/reference/plhashenumerator.rst b/docs/nspr/reference/plhashenumerator.rst new file mode 100644 index 0000000000..eba3635c5e --- /dev/null +++ b/docs/nspr/reference/plhashenumerator.rst @@ -0,0 +1,41 @@ + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef PRIntn (PR_CALLBACK *PLHashEnumerator)(PLHashEntry *he, PRIntn index, void *arg); + + /* Return value */ + #define HT_ENUMERATE_NEXT 0 /* continue enumerating entries */ + #define HT_ENUMERATE_STOP 1 /* stop enumerating entries */ + #define HT_ENUMERATE_REMOVE 2 /* remove and free the current entry */ + #define HT_ENUMERATE_UNHASH 4 /* just unhash the current entry */ + + +Description +----------- + +``PLHashEnumerator`` is a function type used in the enumerating a hash +table. When all the table entries are enumerated, each entry is passed +to a user-specified function of type ``PLHashEnumerator`` with the hash +table entry, an integer index, and an arbitrary piece of user data as +argument. + + +Remark +------ + +The meaning of ``HT_ENUMERATE_UNHASH`` is not clear. In the current +implementation, it will leave the hash table in an inconsistent state. +The entries are unlinked from the table, they are not freed, but the +entry count (the ``nentries`` field of the ``PLHashTable`` structure) is +not decremented. + + +See Also +-------- + +:ref:`PL_HashTableEnumerateEntries` diff --git a/docs/nspr/reference/plhashfunction.rst b/docs/nspr/reference/plhashfunction.rst new file mode 100644 index 0000000000..e1767e7e94 --- /dev/null +++ b/docs/nspr/reference/plhashfunction.rst @@ -0,0 +1,22 @@ + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef PLHashNumber (PR_CALLBACK *PLHashFunction)(const void *key); + + +Description +----------- + +``PLHashNumber`` is a function type that maps the key of a hash table +entry to a hash number. + + +See Also +-------- + +`PL_HashString <PL_HashString>`__ diff --git a/docs/nspr/reference/plhashnumber.rst b/docs/nspr/reference/plhashnumber.rst new file mode 100644 index 0000000000..a84c147aa9 --- /dev/null +++ b/docs/nspr/reference/plhashnumber.rst @@ -0,0 +1,29 @@ + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef PRUint32 PLHashNumber; + + #define PL_HASH_BITS 32 + + +Description +----------- + +``PLHashNumber`` is an unsigned 32-bit integer. ``PLHashNumber`` is the +data type of the return value of a hash function. A hash function maps a +key to a hash number, which is then used to compute the index of the +bucket. + +The macro ``PL_HASH_BITS`` is the size (in bits) of the ``PLHashNumber`` +data type and has the value of 32. + + +See Also +-------- + +``PLHashFunction`` diff --git a/docs/nspr/reference/plhashtable.rst b/docs/nspr/reference/plhashtable.rst new file mode 100644 index 0000000000..70bad3aebe --- /dev/null +++ b/docs/nspr/reference/plhashtable.rst @@ -0,0 +1,21 @@ + +Syntax +------ + +.. code:: + + #include <plhash.h> + + typedef struct PLHashTable PLHashTable; + + +Description +----------- + +The opaque ``PLHashTable`` structure represents a hash table. Entries in +the table have the type ``PLHashEntry`` and are organized into buckets. +The number of buckets in a hash table may be changed by the library +functions during the lifetime of the table to optimize speed and space. + +A new hash table is created by the :ref:`PL_NewHashTable` function, and +destroyed by the :ref:`PL_HashTableDestroy` function. diff --git a/docs/nspr/reference/pr_abort.rst b/docs/nspr/reference/pr_abort.rst new file mode 100644 index 0000000000..5c14ea2e2e --- /dev/null +++ b/docs/nspr/reference/pr_abort.rst @@ -0,0 +1,21 @@ +PR_Abort +======== + +Aborts the process in a nongraceful manner. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_Abort(void); + + +Description +----------- + +:ref:`PR_Abort` results in a core file and a call to the debugger or +equivalent, in addition to causing the entire process to stop. diff --git a/docs/nspr/reference/pr_accept.rst b/docs/nspr/reference/pr_accept.rst new file mode 100644 index 0000000000..eb1b1ad3ed --- /dev/null +++ b/docs/nspr/reference/pr_accept.rst @@ -0,0 +1,65 @@ +PR_Accept +========= + +Accepts a connection on a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_Accept( + PRFileDesc *fd, + PRNetAddr *addr, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing the rendezvous + socket on which the caller is willing to accept new connections. +``addr`` + A pointer to a structure of type :ref:`PRNetAddr`. On output, this + structure contains the address of the connecting entity. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the accept operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful acceptance of a connection, a pointer to a new + :ref:`PRFileDesc` structure representing the newly accepted connection. +- If unsuccessful, ``NULL``. Further information can be obtained by + calling :ref:`PR_GetError`. + + +Description +----------- + +The socket ``fd`` is a rendezvous socket that has been bound to an +address with :ref:`PR_Bind` and is listening for connections after a call +to :ref:`PR_Listen`. :ref:`PR_Accept` accepts the first connection from the +queue of pending connections and creates a new socket for the newly +accepted connection. The rendezvous socket can still be used to accept +more connections. + +If the ``addr`` parameter is not ``NULL``, :ref:`PR_Accept` stores the +address of the connecting entity in the :ref:`PRNetAddr` object pointed to +by ``addr``. + +:ref:`PR_Accept` blocks the calling thread until either a new connection is +successfully accepted or an error occurs. If the timeout parameter is +not ``PR_INTERVAL_NO_TIMEOUT`` and no pending connection can be accepted +before the time limit, :ref:`PR_Accept` returns ``NULL`` with the error +code ``PR_IO_TIMEOUT_ERROR``. diff --git a/docs/nspr/reference/pr_acceptread.rst b/docs/nspr/reference/pr_acceptread.rst new file mode 100644 index 0000000000..d0e8fca61b --- /dev/null +++ b/docs/nspr/reference/pr_acceptread.rst @@ -0,0 +1,73 @@ +PR_AcceptRead +============= + +Accepts a new connection and receives a block of data. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_AcceptRead( + PRFileDesc *listenSock, + PRFileDesc **acceptedSock, + PRNetAddr **peerAddr, + void *buf, + PRInt32 amount, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``listenSock`` + A pointer to a :ref:`PRFileDesc` object representing a socket descriptor + that has been called with the :ref:`PR_Listen` function, also known as + the rendezvous socket. +``acceptedSock`` + A pointer to a pointer to a :ref:`PRFileDesc` object. On return, + ``*acceptedSock`` points to the :ref:`PRFileDesc` object for the newly + connected socket. This parameter is valid only if the function return + does not indicate failure. +``peerAddr`` + A pointer a pointer to a :ref:`PRNetAddr` object. On return, + ``peerAddr`` points to the address of the remote socket. The + :ref:`PRNetAddr` object that ``peerAddr`` points to will be in the + buffer pointed to by ``buf``. This parameter is valid only if the + function return does not indicate failure. +``buf`` + A pointer to a buffer to hold data sent by the peer and the peer's + address. This buffer must be large enough to receive ``amount`` bytes + of data and two :ref:`PRNetAddr` structures (thus allowing the runtime + to align the addresses as needed). +``amount`` + The number of bytes of data to receive. Does not include the size of + the :ref:`PRNetAddr` structures. If 0, no data will be read from the + peer. +``timeout`` + The timeout interval only applies to the read portion of the + operation. :ref:`PR_AcceptRead` blocks indefinitely until the connection + is accepted; the read will time out after the timeout interval + elapses. + + +Returns +~~~~~~~ + +- A positive number indicates the number of bytes read from the peer. +- The value -1 indicates a failure. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_AcceptRead` accepts a new connection and retrieves the newly +created socket's descriptor and the connecting peer's address. Also, as +its name suggests, :ref:`PR_AcceptRead` receives the first block of data +sent by the peer. diff --git a/docs/nspr/reference/pr_access.rst b/docs/nspr/reference/pr_access.rst new file mode 100644 index 0000000000..14fb5018b2 --- /dev/null +++ b/docs/nspr/reference/pr_access.rst @@ -0,0 +1,41 @@ +PR_Access +========= + +Determines the accessibility of a file. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Access( + const char *name, + PRAccessHow how); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``name`` + The pathname of the file whose accessibility is to be determined. +``how`` + Specifies which access permission to check for. Use one of the + following values: + + - :ref:`PR_ACCESS_READ_OK`. Test for read permission. + - :ref:`PR_ACCESS_WRITE_OK`. Test for write permission. + - :ref:`PR_ACCESS_EXISTS`. Check existence of file. + + +Returns +~~~~~~~ + +One of the following values: + +- If the requested access is permitted, ``PR_SUCCESS``. +- If the requested access is not permitted, ``PR_FAILURE``. diff --git a/docs/nspr/reference/pr_append_link.rst b/docs/nspr/reference/pr_append_link.rst new file mode 100644 index 0000000000..7525f348a5 --- /dev/null +++ b/docs/nspr/reference/pr_append_link.rst @@ -0,0 +1,32 @@ +PR_APPEND_LINK +============== + +Appends an element to the end of a list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_APPEND_LINK ( + PRCList *elemp, + PRCList *listp); + + +Parameters +~~~~~~~~~~ + +``elemp`` + A pointer to the element to be inserted. +``listp`` + A pointer to the list. + + +Description +----------- + +PR_APPEND_LINK adds the specified element to the end of the specified +list. diff --git a/docs/nspr/reference/pr_assert.rst b/docs/nspr/reference/pr_assert.rst new file mode 100644 index 0000000000..669c8d346a --- /dev/null +++ b/docs/nspr/reference/pr_assert.rst @@ -0,0 +1,43 @@ +PR_ASSERT +========= + +Terminates execution when a given expression is ``FALSE``. + + +Syntax +------ + +.. code:: + + #include <prlog.h> + + void PR_ASSERT ( expression ); + + +Parameters +~~~~~~~~~~ + +The macro has this parameter: + +expression + Any valid C language expression that evaluates to ``TRUE`` or + ``FALSE``. + + +Returns +~~~~~~~ + +Nothing + + +Description +----------- + +This macro evaluates the specified expression. When the result is zero +(``FALSE``) the application terminates; otherwise the application +continues. The macro converts the expression to a string and passes it +to ``PR_Assert``, using file and line parameters from the compile-time +environment. + +This macro compiles to nothing if compile-time options are not specified +to enable logging. diff --git a/docs/nspr/reference/pr_atomicadd.rst b/docs/nspr/reference/pr_atomicadd.rst new file mode 100644 index 0000000000..3f2afeece0 --- /dev/null +++ b/docs/nspr/reference/pr_atomicadd.rst @@ -0,0 +1,37 @@ +PR_AtomicAdd +============ + + +Syntax +------ + +.. code:: + + #include <pratom.h> + + PRInt32 PR_AtomicAdd( + PRInt32 *ptr, + PRInt32 val); + + +Parameter +~~~~~~~~~ + +The function has the following parameters: + +``ptr`` + A pointer to the value to increment. +``val`` + A value to be added. + + +Returns +~~~~~~~ + +The returned value is the result of the addition. + + +Description +----------- + +Atomically add a 32 bit value. diff --git a/docs/nspr/reference/pr_atomicdecrement.rst b/docs/nspr/reference/pr_atomicdecrement.rst new file mode 100644 index 0000000000..a27b8d8227 --- /dev/null +++ b/docs/nspr/reference/pr_atomicdecrement.rst @@ -0,0 +1,37 @@ +PR_AtomicDecrement +================== + +Atomically decrements a 32-bit value. + + +Syntax +------ + +.. code:: + + #include <pratom.h> + + PRInt32 PR_AtomicDecrement(PRInt32 *val); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``val`` + A pointer to the value to decrement. + + +Returns +~~~~~~~ + +The function returns the decremented value (i.e., the result). + + +Description +----------- + +:ref:`PR_AtomicDecrement` first decrements the referenced variable by one. +The value returned is the referenced variable's final value. The +modification to memory is unconditional. diff --git a/docs/nspr/reference/pr_atomicincrement.rst b/docs/nspr/reference/pr_atomicincrement.rst new file mode 100644 index 0000000000..126ed7989c --- /dev/null +++ b/docs/nspr/reference/pr_atomicincrement.rst @@ -0,0 +1,37 @@ +PR_AtomicIncrement +================== + +Atomically increments a 32-bit value. + + +Syntax +------ + +.. code:: + + #include <pratom.h> + + PRInt32 PR_AtomicIncrement(PRInt32 *val); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``val`` + A pointer to the value to increment. + + +Returns +~~~~~~~ + +The function returns the incremented value (i.e., the result). + + +Description +----------- + +The referenced variable is incremented by one. The result of the +function is the value of the memory after the operation. The writing of +the memory is unconditional. diff --git a/docs/nspr/reference/pr_atomicset.rst b/docs/nspr/reference/pr_atomicset.rst new file mode 100644 index 0000000000..3c9df0b1b9 --- /dev/null +++ b/docs/nspr/reference/pr_atomicset.rst @@ -0,0 +1,42 @@ +PR_AtomicSet +============ + +Atomically sets a 32-bit value and return its previous contents. + + +Syntax +------ + +.. code:: + + #include <pratom.h> + + PRInt32 PR_AtomicSet( + PRInt32 *val, + PRInt32 newval); + + +Parameters +~~~~~~~~~~ + +The function has the following parameter: + +``val`` + A pointer to the value to be set. +``newval`` + The new value to assign to the ``val`` parameter. + + +Returns +~~~~~~~ + +The function returns the prior value of the referenced variable. + + +Description +----------- + +:ref:`PR_AtomicSet` first reads the value of var, then updates it with the +supplied value. The returned value is the value that was read\ *before* +memory was updated. The memory modification is unconditional--that is, +it isn't a test and set operation. diff --git a/docs/nspr/reference/pr_attachsharedmemory.rst b/docs/nspr/reference/pr_attachsharedmemory.rst new file mode 100644 index 0000000000..ed7c38d4a3 --- /dev/null +++ b/docs/nspr/reference/pr_attachsharedmemory.rst @@ -0,0 +1,44 @@ +PR_AttachSharedMemory +===================== + +Attaches a memory segment previously opened with :ref:`PR_OpenSharedMemory` +and maps it into the process memory space. + + +Syntax +------ + +.. code:: + + #include <prshm.h> + +.. code:: + + NSPR_API( void * ) + PR_AttachSharedMemory( + PRSharedMemory *shm, + PRIntn flags + ); + + /* Define values for PR_AttachSharedMemory(...,flags) */ + #define PR_SHM_READONLY 0x01 + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +shm + The handle returned from :ref:`PR_OpenSharedMemory`. +flags + Options for mapping the shared memory. ``PR_SHM_READONLY`` causes the + memory to be attached read-only. + + +Returns +~~~~~~~ + +Address where shared memory is mapped, or ``NULL`` if an error occurs. +Retrieve the reason for the failure by calling :ref:`PR_GetError` and +:ref:`PR_GetOSError`. diff --git a/docs/nspr/reference/pr_attachthread.rst b/docs/nspr/reference/pr_attachthread.rst new file mode 100644 index 0000000000..a6287999c9 --- /dev/null +++ b/docs/nspr/reference/pr_attachthread.rst @@ -0,0 +1,76 @@ +PR_AttachThread +=============== + +.. container:: blockIndicator obsolete obsoleteHeader + + | **Obsolete** + | This feature is obsolete. Although it may still work in some + browsers, its use is discouraged since it could be removed at any + time. Try to avoid using it. + +Associates a :ref:`PRThread` object with an existing native thread. + + +Syntax +------ + +.. code:: + + #include <pprthread.h> + + PRThread* PR_AttachThread( + PRThreadType type, + PRThreadPriority priority, + PRThreadStack *stack); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_AttachThread` has the following parameters: + +``type`` + Specifies that the thread is either a user thread + (``PR_USER_THREAD``) or a system thread (``PR_SYSTEM_THREAD``). +``priority`` + The priority to assign to the thread being attached. +``stack`` + The stack for the thread being attached. + + +Returns +~~~~~~~ + +The function returns one of these values: + +- If successful, a pointer to a :ref:`PRThread` object. +- If unsuccessful, for example if system resources are not available, + ``NULL``. + + +Description +----------- + +You use :ref:`PR_AttachThread` when you want to use NSS functions on the +native thread that was not created with NSPR. :ref:`PR_AttachThread` +informs NSPR about the new thread by associating a :ref:`PRThread` object +with the native thread. + +The thread object is automatically destroyed when it is no longer +needed. + +You don't need to call :ref:`PR_AttachThread` unless you create your own +native thread. :ref:`PR_Init` calls :ref:`PR_AttachThread` automatically for +the primordial thread. + +.. note:: + + As of NSPR release v3.0, :ref:`PR_AttachThread` and + :ref:`PR_DetachThread` are obsolete. A native thread not created by NSPR + is automatically attached the first time it calls an NSPR function, + and automatically detached when it exits. + +In NSPR release 19980529B and earlier, it is necessary for a native +thread not created by NSPR to call :ref:`PR_AttachThread` before it calls +any NSPR functions, and call :ref:`PR_DetachThread` when it is done calling +NSPR functions. diff --git a/docs/nspr/reference/pr_available.rst b/docs/nspr/reference/pr_available.rst new file mode 100644 index 0000000000..8906bcace5 --- /dev/null +++ b/docs/nspr/reference/pr_available.rst @@ -0,0 +1,51 @@ +PR_Available +============ + +Determines the number of bytes (expressed as a 32-bit integer) that are +available for reading beyond the current read-write pointer in a +specified file or socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Available(PRFileDesc *fd); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``fd`` + Pointer to a :ref:`PRFileDesc` object representing a file or socket. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the function completes successfully, it returns the number of + bytes that are available for reading. For a normal file, these are + the bytes beyond the current file pointer. +- If the function fails, it returns the value -1. The error code can + then be retrieved via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Available` works on normal files and sockets. :ref:`PR_Available` +does not work with pipes on Win32 platforms. + + +See Also +-------- + +If the number of bytes available for reading is out of the range of a +32-bit integer, use :ref:`PR_Available64`. diff --git a/docs/nspr/reference/pr_available64.rst b/docs/nspr/reference/pr_available64.rst new file mode 100644 index 0000000000..7ee2dd07a7 --- /dev/null +++ b/docs/nspr/reference/pr_available64.rst @@ -0,0 +1,51 @@ +PR_Available64 +============== + +Determines the number of bytes (expressed as a 32-bit integer) that are +available for reading beyond the current read-write pointer in a +specified file or socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt64 PR_Available64(PRFileDesc *fd); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``fd`` + Pointer to a :ref:`PRFileDesc` object representing a file or socket. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the function completes successfully, it returns the number of + bytes that are available for reading. For a normal file, these are + the bytes beyond the current file pointer. +- If the function fails, it returns the value -1. The error code can + then be retrieved via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Available64` works on normal files and sockets. :ref:`PR_Available` +does not work with pipes on Win32 platforms. + + +See Also +-------- + +If the number of bytes available for reading is within the range of a +32-bit integer, use :ref:`PR_Available`. diff --git a/docs/nspr/reference/pr_bind.rst b/docs/nspr/reference/pr_bind.rst new file mode 100644 index 0000000000..25bba0bcd1 --- /dev/null +++ b/docs/nspr/reference/pr_bind.rst @@ -0,0 +1,54 @@ +PR_Bind +======= + +Binds an address to a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Bind( + PRFileDesc *fd, + const PRNetAddr *addr); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``addr`` + A pointer to a :ref:`PRNetAddr` object representing the address to which + the socket will be bound. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful binding of an address to a socket, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. Further information can be obtained + by calling :ref:`PR_GetError`. + + +Description +----------- + +When a new socket is created, it has no address bound to it. :ref:`PR_Bind` +assigns the specified address (also known as name) to the socket. If you +do not care about the exact IP address assigned to the socket, set the +``inet.ip`` field of :ref:`PRNetAddr` to :ref:`PR_htonl`\ (``PR_INADDR_ANY``). +If you do not care about the TCP/UDP port assigned to the socket, set +the ``inet.port`` field of :ref:`PRNetAddr` to 0. + +Note that if :ref:`PR_Connect` is invoked on a socket that is not bound, it +implicitly binds an arbitrary address the socket. + +Call :ref:`PR_GetSockName` to obtain the address (name) bound to a socket. diff --git a/docs/nspr/reference/pr_blockclockinterrupts.rst b/docs/nspr/reference/pr_blockclockinterrupts.rst new file mode 100644 index 0000000000..936dedb877 --- /dev/null +++ b/docs/nspr/reference/pr_blockclockinterrupts.rst @@ -0,0 +1,14 @@ +PR_BlockClockInterrupts +======================= + +Blocks the timer signal used for preemptive scheduling. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_BlockClockInterrupts(void); diff --git a/docs/nspr/reference/pr_callback.rst b/docs/nspr/reference/pr_callback.rst new file mode 100644 index 0000000000..47798a77b5 --- /dev/null +++ b/docs/nspr/reference/pr_callback.rst @@ -0,0 +1,24 @@ +PR_CALLBACKimplementation +========================= + +Used to define pointers to functions that will be implemented by the +client but called from a (different) shared library. + + +Syntax +------ + +.. code:: + + #include <prtypes.h>type PR_CALLBACKimplementation + + +Description +----------- + +Functions that are implemented in an application (or shared library) +that are intended to be called from another shared library (such as +NSPR) must be declared with the ``PR_CALLBACK`` attribute. Normally such +functions are passed by reference (pointer to function). The +``PR_CALLBACK`` attribute is included as part of the function's +definition between its return value type and the function's name. diff --git a/docs/nspr/reference/pr_calloc.rst b/docs/nspr/reference/pr_calloc.rst new file mode 100644 index 0000000000..b36a89d9b4 --- /dev/null +++ b/docs/nspr/reference/pr_calloc.rst @@ -0,0 +1,42 @@ +PR_Calloc +========= + +Allocates zeroed memory from the heap for a number of objects of a given +size. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + void *PR_Calloc ( + PRUint32 nelem, + PRUint32 elsize); + + +Parameters +~~~~~~~~~~ + +``nelem`` + The number of elements of size ``elsize`` to be allocated. +``elsize`` + The size of an individual element. + + +Returns +~~~~~~~ + +An untyped pointer to the allocated memory, or if the allocation attempt +fails, ``NULL``. Call ``PR_GetError()`` to retrieve the error returned +by the libc function ``malloc()``. + + +Description +----------- + +This function allocates memory on the heap for the specified number of +objects of the specified size. All bytes in the allocated memory are +cleared. diff --git a/docs/nspr/reference/pr_callonce.rst b/docs/nspr/reference/pr_callonce.rst new file mode 100644 index 0000000000..912f1a3ac3 --- /dev/null +++ b/docs/nspr/reference/pr_callonce.rst @@ -0,0 +1,35 @@ +PR_CallOnce +=========== + +Ensures that subsystem initialization occurs only once. + + +Syntax +------ + +.. code:: + + PRStatus PR_CallOnce( + PRCallOnceType *once, + PRCallOnceFN func); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_CallOnce` has these parameters: + +``once`` + A pointer to an object of type :ref:`PRCallOnceType`. Initially (before + any threading issues exist), the object must be initialized to all + zeros. From that time on, the client should consider the object + read-only (or even opaque) and allow the runtime to manipulate its + content appropriately. +``func`` + A pointer to the function the calling client has designed to perform + the subsystem initialization. The function will be called once, at + most, for each subsystem to be initialized. It should return a + :ref:`PRStatus` indicating the result of the initialization process. + While the first thread executes this function, other threads + attempting the same initialization will be blocked until it has been + completed. diff --git a/docs/nspr/reference/pr_canceljob.rst b/docs/nspr/reference/pr_canceljob.rst new file mode 100644 index 0000000000..6d49445d75 --- /dev/null +++ b/docs/nspr/reference/pr_canceljob.rst @@ -0,0 +1,30 @@ +PR_CancelJob +============ + +Causes a previously queued job to be canceled. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRStatus) PR_CancelJob(PRJob *job); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``job`` + A pointer to a :ref:`PRJob` structure returned by a :ref:`PR_QueueJob` + function representing the job to be cancelled. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_centermonitor.rst b/docs/nspr/reference/pr_centermonitor.rst new file mode 100644 index 0000000000..14d8b482ad --- /dev/null +++ b/docs/nspr/reference/pr_centermonitor.rst @@ -0,0 +1,57 @@ +PR_CEnterMonitor +================ + +Enters the lock associated with a cached monitor. + + +Syntax +------ + +.. code:: + + #include <prcmon.h> + + PRMonitor* PR_CEnterMonitor(void *address); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``address`` + A reference to the data that is to be protected by the monitor. This + reference must remain valid as long as there are monitoring + operations being performed. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, the function returns a pointer to the :ref:`PRMonitor` + associated with the value specified in the ``address`` parameter. +- If unsuccessful (the monitor cache needs to be expanded and the + system is out of memory), the function returns ``NULL``. + + +Description +----------- + +:ref:`PR_CEnterMonitor` uses the value specified in the ``address`` +parameter to find a monitor in the monitor cache, then enters the lock +associated with the monitor. If no match is found, an available monitor +is associated with the address and the monitor's entry count is +incremented (so it has a value of one). If a match is found, then either +the calling thread is already in the monitor (and this is a reentrant +call) or another thread is holding the monitor's mutex. In the former +case, the entry count is simply incremented and the function returns. In +the latter case, the calling thread is likely to find the monitor locked +by another thread and waits for that thread to exit before continuing. + +.. note:: + + :ref:`PR_CEnterMonitor` and :ref:`PR_CExitMonitor` must be + paired--that is, there must be an exit for every entry--or the object + will never become available for any other thread. diff --git a/docs/nspr/reference/pr_cexitmonitor.rst b/docs/nspr/reference/pr_cexitmonitor.rst new file mode 100644 index 0000000000..91e95f9bff --- /dev/null +++ b/docs/nspr/reference/pr_cexitmonitor.rst @@ -0,0 +1,44 @@ +PR_CExitMonitor +=============== + +Decrement the entry count associated with a cached monitor. + + +Syntax +------ + +.. code:: + + #include <prcmon.h> + + PRStatus PR_CExitMonitor(void *address); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``address`` + The address of the protected object--the same address previously + passed to :ref:`PR_CEnterMonitor`. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. This may indicate that the address + parameter is invalid or that the calling thread is not in the + monitor. + + +Description +----------- + +Using the value specified in the address parameter to find a monitor in +the monitor cache, :ref:`PR_CExitMonitor` decrements the entry count +associated with the monitor. If the decremented entry count is zero, the +monitor is exited. diff --git a/docs/nspr/reference/pr_cleanup.rst b/docs/nspr/reference/pr_cleanup.rst new file mode 100644 index 0000000000..6f4a93717e --- /dev/null +++ b/docs/nspr/reference/pr_cleanup.rst @@ -0,0 +1,39 @@ +PR_Cleanup +========== + +Coordinates a graceful shutdown of NSPR. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + PRStatus PR_Cleanup(void); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If NSPR has been shut down successfully, ``PR_SUCCESS``. +- If the calling thread of this function is not the primordial thread, + ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_Cleanup` must be called by the primordial thread near the end of +the ``main`` function. + +:ref:`PR_Cleanup` attempts to synchronize the natural termination of the +process. It does so by blocking the caller, if and only if it is the +primordial thread, until all user threads have terminated. When the +primordial thread returns from ``main``, the process immediately and +silently exits. That is, the process (if necessary) forcibly terminates +any existing threads and exits without significant blocking and without +error messages or core files. diff --git a/docs/nspr/reference/pr_clearinterrupt.rst b/docs/nspr/reference/pr_clearinterrupt.rst new file mode 100644 index 0000000000..27900e40d9 --- /dev/null +++ b/docs/nspr/reference/pr_clearinterrupt.rst @@ -0,0 +1,29 @@ +PR_ClearInterrupt +================= + +Clears the interrupt request for the calling thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + void PR_ClearInterrupt(void); + + +Description +----------- + +Interrupting is a cooperative process, so it's possible that the thread +passed to :ref:`PR_Interrupt` may never respond to the interrupt request. +For example, the target thread may reach the agreed-on control point +without providing an opportunity for the runtime to notify the thread of +the interrupt request. In this case, the request for interrupt is still +pending with the thread and must be explicitly canceled. Therefore it is +sometimes necessary to call :ref:`PR_ClearInterrupt` to clear a previous +interrupt request. + +If no interrupt request is pending, :ref:`PR_ClearInterrupt` is a no-op. diff --git a/docs/nspr/reference/pr_clist_is_empty.rst b/docs/nspr/reference/pr_clist_is_empty.rst new file mode 100644 index 0000000000..1794a8b7b4 --- /dev/null +++ b/docs/nspr/reference/pr_clist_is_empty.rst @@ -0,0 +1,28 @@ +PR_CLIST_IS_EMPTY +================= + +Checks for an empty circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PRIntn PR_CLIST_IS_EMPTY (PRCList *listp); + + +Parameter +~~~~~~~~~ + +``listp`` + A pointer to the linked list. + + +Description +----------- + +PR_CLIST_IS_EMPTY returns a non-zero value if the specified list is an +empty list, otherwise returns zero. diff --git a/docs/nspr/reference/pr_close.rst b/docs/nspr/reference/pr_close.rst new file mode 100644 index 0000000000..1bf310c495 --- /dev/null +++ b/docs/nspr/reference/pr_close.rst @@ -0,0 +1,40 @@ +PR_Close +======== + +Closes a file descriptor. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Close(PRFileDesc *fd); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object. + + +Returns +~~~~~~~ + +One of the following values: + +- If file descriptor is closed successfully, ``PR_SUCCESS``. +- If the file descriptor is not closed successfully, ``PR_FAILURE``. + + +Description +----------- + +The file descriptor may represent a normal file, a socket, or an end +point of a pipe. On successful return, :ref:`PR_Close` frees the dynamic +memory and other resources identified by the ``fd`` parameter. diff --git a/docs/nspr/reference/pr_closedir.rst b/docs/nspr/reference/pr_closedir.rst new file mode 100644 index 0000000000..e7a586282f --- /dev/null +++ b/docs/nspr/reference/pr_closedir.rst @@ -0,0 +1,47 @@ +PR_CloseDir +=========== + +Closes the specified directory. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_CloseDir(PRDir *dir); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``dir`` + A pointer to a :ref:`PRDir` structure representing the directory to be + closed. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + retrieved via :ref:`PR_GetError`. + + +Description +----------- + +When a :ref:`PRDir` object is no longer needed, it must be closed and freed +with a call to :ref:`PR_CloseDir` call. Note that after a :ref:`PR_CloseDir` +call, any ``PRDirEntry`` object returned by a previous :ref:`PR_ReadDir` +call on the same :ref:`PRDir` object becomes invalid. + + +See Also +-------- + +:ref:`PR_OpenDir` diff --git a/docs/nspr/reference/pr_closefilemap.rst b/docs/nspr/reference/pr_closefilemap.rst new file mode 100644 index 0000000000..a6a5590729 --- /dev/null +++ b/docs/nspr/reference/pr_closefilemap.rst @@ -0,0 +1,40 @@ +PR_CloseFileMap +=============== + +Closes a file mapping. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_CloseFileMap(PRFileMap *fmap); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``fmap`` + The file mapping to be closed. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the memory region is successfully unmapped, ``PR_SUCCESS``. +- If the memory region is not successfully unmapped, ``PR_FAILURE``. + The error code can be retrieved via :ref:`PR_GetError`. + + +Description +----------- + +When a file mapping created with a call to :ref:`PR_CreateFileMap` is no +longer needed, it should be closed with a call to :ref:`PR_CloseFileMap`. diff --git a/docs/nspr/reference/pr_closesemaphore.rst b/docs/nspr/reference/pr_closesemaphore.rst new file mode 100644 index 0000000000..07d1aca46e --- /dev/null +++ b/docs/nspr/reference/pr_closesemaphore.rst @@ -0,0 +1,30 @@ +PR_CloseSemaphore +================= + +Closes a specified semaphore. + + +Syntax +------ + +.. code:: + + #include <pripcsem.h> + + NSPR_API(PRStatus) PR_CloseSemaphore(PRSem *sem); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``sem`` + A pointer to a ``PRSem`` structure returned from a call to + :ref:`PR_OpenSemaphore`. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_closesharedmemory.rst b/docs/nspr/reference/pr_closesharedmemory.rst new file mode 100644 index 0000000000..221b07f2ba --- /dev/null +++ b/docs/nspr/reference/pr_closesharedmemory.rst @@ -0,0 +1,32 @@ +PR_CloseSharedMemory +==================== + +Closes a shared memory segment identified by name. + + +Syntax +------ + +.. code:: + + #include <prshm.h> + + NSPR_API( PRStatus ) + PR_CloseSharedMemory( + PRSharedMemory *shm + ); + + +Parameter +~~~~~~~~~ + +The function has these parameter: + +shm + The handle returned from :ref:`PR_OpenSharedMemory`. + + +Returns +~~~~~~~ + +:ref:`PRStatus`. diff --git a/docs/nspr/reference/pr_cnotify.rst b/docs/nspr/reference/pr_cnotify.rst new file mode 100644 index 0000000000..d3c5163a81 --- /dev/null +++ b/docs/nspr/reference/pr_cnotify.rst @@ -0,0 +1,43 @@ +PR_CNotify +========== + +Notify a thread waiting on a change in the state of monitored data. + + +Syntax +------ + +.. code:: + + #include <prcmon.h> + + PRStatus PR_CNotify(void *address); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``address`` + The address of the monitored object. The calling thread must be in + the monitor defined by the value of the address. + + +Returns +~~~~~~~ + + - :ref:`PR_SUCCESS` indicates that the calling thread is the holder of the + mutex for the monitor referred to by the address parameter. + - :ref:`PR_FAILURE` indicates that the monitor has not been entered by the + calling thread. + + +Description +----------- + +Using the value specified in the ``address`` parameter to find a monitor +in the monitor cache, :ref:`PR_CNotify` notifies single a thread waiting +for the monitor's state to change. If a thread is waiting on the monitor +(having called :ref:`PR_CWait`), then that thread is made ready. As soon as +the thread is scheduled, it attempts to reenter the monitor. diff --git a/docs/nspr/reference/pr_cnotifyall.rst b/docs/nspr/reference/pr_cnotifyall.rst new file mode 100644 index 0000000000..80a7c2aeb9 --- /dev/null +++ b/docs/nspr/reference/pr_cnotifyall.rst @@ -0,0 +1,43 @@ +PR_CNotifyAll +============= + +Notifies all the threads waiting for a change in the state of monitored +data. + + +Syntax +------ + +.. code:: + + #include <prcmon.h> + + PRStatus PR_CNotifyAll(void *address); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``address`` + The address of the monitored object. The calling thread must be in + the monitor at the time :ref:`PR_CNotifyAll` is called. + + +Returns +~~~~~~~ + + - :ref:`PR_SUCCESS` indicates that the referenced monitor was located and + the calling thread was in the monitor. + - :ref:`PR_FAILURE` indicates that the referenced monitor could not be + located or that the calling thread was not in the monitor + + +Description +----------- + +Using the value specified in the address parameter to find a monitor in +the monitor cache, :ref:`PR_CNotifyAll` notifies all threads waiting for +the monitor's state to change. All of the threads waiting on the state +change are then scheduled to reenter the monitor. diff --git a/docs/nspr/reference/pr_cnvtf.rst b/docs/nspr/reference/pr_cnvtf.rst new file mode 100644 index 0000000000..f2b0fa88b5 --- /dev/null +++ b/docs/nspr/reference/pr_cnvtf.rst @@ -0,0 +1,45 @@ +PR_cnvtf +======== + +Converts a floating point number to a string. + + +Syntax +------ + +.. code:: + + #include <prdtoa.h> + + void PR_cnvtf ( + char *buf, + PRIntn bufsz, + PRIntn prcsn, + PRFloat64 fval); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``buf`` + The address of the buffer in which to store the result. +``bufsz`` + The size of the buffer provided to hold the result. +``prcsn`` + The number of digits of precision to which to generate the floating + point value. +``fval`` + The double-precision floating point number to be converted. + + +Description +----------- + +:ref:`PR_cnvtf` is a simpler interface to convert a floating point number +to a string. It conforms to the ECMA standard of Javascript +(ECMAScript). + +On return, the result is written to the buffer pointed to by ``buf`` of +size ``bufsz``. diff --git a/docs/nspr/reference/pr_connect.rst b/docs/nspr/reference/pr_connect.rst new file mode 100644 index 0000000000..10978df792 --- /dev/null +++ b/docs/nspr/reference/pr_connect.rst @@ -0,0 +1,67 @@ +PR_Connect +========== + +Initiates a connection on a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Connect( + PRFileDesc *fd, + const PRNetAddr *addr, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``addr`` + A pointer to the address of the peer to which the socket is to be + connected. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the connect operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion of connection setup, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. Further information can be obtained + by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Connect` is usually invoked on a TCP socket, but it may also be +invoked on a UDP socket. Both cases are discussed here. + +If the socket is a TCP socket, :ref:`PR_Connect` establishes a TCP +connection to the peer. If the socket is not bound, it will be bound to +an arbitrary local address. + +:ref:`PR_Connect` blocks until either the connection is successfully +established or an error occurs. The function uses the lesser of the +provided timeout and the OS's connect timeout. In particular, if you +specify ``PR_INTERVAL_NO_TIMEOUT`` as the timeout, the OS's connection +time limit will be used. + +If the socket is a UDP socket, there is no connection setup to speak of, +since UDP is connectionless. If :ref:`PR_Connect` is invoked on a UDP +socket, it has an overloaded meaning: :ref:`PR_Connect` merely saves the +specified address as the default peer address for the socket, so that +subsequently one can send and receive datagrams from the socket using +:ref:`PR_Send` and :ref:`PR_Recv` instead of the usual :ref:`PR_SendTo` and +:ref:`PR_RecvFrom`. diff --git a/docs/nspr/reference/pr_connectcontinue.rst b/docs/nspr/reference/pr_connectcontinue.rst new file mode 100644 index 0000000000..b4ba88bc20 --- /dev/null +++ b/docs/nspr/reference/pr_connectcontinue.rst @@ -0,0 +1,53 @@ +PR_ConnectContinue +================== + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_ConnectContinue( + PRFileDesc *fd, + PRInt16 out_flags); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. + +``out_flags`` + The out_flags field of the poll descriptor returned by + `PR_Poll() <PR_Poll>`__. + + +Returns +~~~~~~~ + +- If the nonblocking connect has successfully completed, + PR_ConnectContinue returns PR_SUCCESS. +- If PR_ConnectContinue() returns PR_FAILURE, call PR_GetError(): +- PR_IN_PROGRESS_ERROR: the nonblocking connect is still in + progress and has not completed yet. The caller should poll the file + descriptor for the in_flags PR_POLL_WRITE|PR_POLL_EXCEPT and retry + PR_ConnectContinue later when PR_Poll() returns. +- Other errors: the nonblocking connect has failed with this + error code. + + +Description +----------- + +Continue a nonblocking connect. After a nonblocking connect is initiated +with PR_Connect() (which fails with PR_IN_PROGRESS_ERROR), one should +call PR_Poll() on the socket, with the in_flags PR_POLL_WRITE \| +PR_POLL_EXCEPT. When PR_Poll() returns, one calls PR_ConnectContinue() +on the socket to determine whether the nonblocking connect has completed +or is still in progress. Repeat the PR_Poll(), PR_ConnectContinue() +sequence until the nonblocking connect has completed. diff --git a/docs/nspr/reference/pr_convertipv4addrtoipv6.rst b/docs/nspr/reference/pr_convertipv4addrtoipv6.rst new file mode 100644 index 0000000000..c19535ccc2 --- /dev/null +++ b/docs/nspr/reference/pr_convertipv4addrtoipv6.rst @@ -0,0 +1,30 @@ +PR_ConvertIPv4AddrToIPv6 +======================== + +Converts an IPv4 address into an (IPv4-mapped) IPv6 address. + + +Syntax +~~~~~~ + +.. code:: + + #include <prnetdb.h> + + void PR_ConvertIPv4AddrToIPv6( + PRUint32 v4addr, + PRIPv6Addr *v6addr + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``v4addr`` + The IPv4 address to convert into an IPv4-mapped IPv6 address. This + must be specified in network byte order. +``v6addr`` + A pointer to a buffer, allocated by the caller, that is filled in + with the IPv6 address on return. diff --git a/docs/nspr/reference/pr_createfilemap.rst b/docs/nspr/reference/pr_createfilemap.rst new file mode 100644 index 0000000000..c347d94e5e --- /dev/null +++ b/docs/nspr/reference/pr_createfilemap.rst @@ -0,0 +1,66 @@ +PR_CreateFileMap +================ + +Creates a file mapping object. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileMap* PR_CreateFileMap( + PRFileDesc *fd, + PRInt64 size, + PRFileMapProtect prot); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing the file that is to + be mapped to memory. +``size`` + Size of the file specified by ``fd``. +``prot`` + Protection option for read and write accesses of a file mapping. This + parameter consists of one of the following options: + + - :ref:`PR_PROT_READONLY`. Read-only access. + - :ref:`PR_PROT_READWRITE`. Readable, and write is shared. + - :ref:`PR_PROT_WRITECOPY`. Readable, and write is private + (copy-on-write). + + +Returns +~~~~~~~ + +- If successful, a file mapping of type :ref:`PRFileMap`. +- If unsuccessful, ``NULL``. + + +Description +----------- + +The ``PRFileMapProtect`` enumeration used in the ``prot`` parameter is +defined as follows: + +.. code:: + + typedef enum PRFileMapProtect { + PR_PROT_READONLY, + PR_PROT_READWRITE, + PR_PROT_WRITECOPY + } PRFileMapProtect; + +:ref:`PR_CreateFileMap` only prepares for the mapping a file to memory. The +returned file-mapping object must be passed to :ref:`PR_MemMap` to actually +map a section of the file to memory. + +The file-mapping object should be closed with a :ref:`PR_CloseFileMap` call +when it is no longer needed. diff --git a/docs/nspr/reference/pr_createiolayerstub.rst b/docs/nspr/reference/pr_createiolayerstub.rst new file mode 100644 index 0000000000..3deb061db2 --- /dev/null +++ b/docs/nspr/reference/pr_createiolayerstub.rst @@ -0,0 +1,46 @@ +PR_CreateIOLayerStub +==================== + +Creates a new layer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_CreateIOLayerStub( + PRDescIdentity ident + PRIOMethods const *methods); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``ident`` + The identity to be associated with the new layer. +``methods`` + A pointer to the :ref:`PRIOMethods` structure specifying the functions + for the new layer. + + +Returns +~~~~~~~ + +A new file descriptor for the specified layer. + + +Description +----------- + +A new layer may be allocated by calling :ref:`PR_CreateIOLayerStub`. The +file descriptor returned contains the pointer to the I/O methods table +provided. The runtime neither modifies the table nor tests its +correctness. + +The caller should override appropriate contents of the file descriptor +returned before pushing it onto the protocol stack. diff --git a/docs/nspr/reference/pr_createpipe.rst b/docs/nspr/reference/pr_createpipe.rst new file mode 100644 index 0000000000..3409cb9912 --- /dev/null +++ b/docs/nspr/reference/pr_createpipe.rst @@ -0,0 +1,53 @@ +PR_CreatePipe +============= + +Creates an anonymous pipe and retrieves file descriptors for the read +and write ends of the pipe. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_CreatePipe( + PRFileDesc **readPipe, + PRFileDesc **writePipe); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``readPipe`` + A pointer to a :ref:`PRFileDesc` pointer. On return, this parameter + contains the file descriptor for the read end of the pipe. +``writePipe`` + A pointer to a :ref:`PRFileDesc` pointer. On return, this parameter + contains the file descriptor for the write end of the pipe. + + +Returns +~~~~~~~ + +The function returns one of these values: + +- If the pipe is successfully created, ``PR_SUCCESS``. +- If the pipe is not successfully created, ``PR_FAILURE``. The error + code can be retrieved via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_CreatePipe` creates an anonymous pipe. Data written into the write +end of the pipe can be read from the read end of the pipe. Pipes are +useful for interprocess communication between a parent and a child +process. When the pipe is no longer needed, both ends should be closed +with calls to :ref:`PR_Close`. + +:ref:`PR_CreatePipe` is currently implemented on Unix, Linux, Mac OS X, and +Win32 only. diff --git a/docs/nspr/reference/pr_createthread.rst b/docs/nspr/reference/pr_createthread.rst new file mode 100644 index 0000000000..cf733e624d --- /dev/null +++ b/docs/nspr/reference/pr_createthread.rst @@ -0,0 +1,79 @@ +PR_CreateThread +=============== + +Creates a new thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRThread* PR_CreateThread( + PRThreadType type, + void (*start)(void *arg), + void *arg, + PRThreadPriority priority, + PRThreadScope scope, + PRThreadState state, + PRUint32 stackSize); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_CreateThread` has the following parameters: + +``type`` + Specifies that the thread is either a user thread + (``PR_USER_THREAD``) or a system thread (``PR_SYSTEM_THREAD``). +``start`` + A pointer to the thread's root function, which is called as the root + of the new thread. Returning from this function is the only way to + terminate a thread. +``arg`` + A pointer to the root function's only parameter. NSPR does not assess + the type or the validity of the value passed in this parameter. +``priority`` + The initial priority of the newly created thread. +``scope`` + Specifies your preference for making the thread local + (``PR_LOCAL_THREAD``), global (``PR_GLOBAL_THREAD``) or global bound + (``PR_GLOBAL_BOUND_THREAD``). However, NSPR may override this + preference if necessary. +``state`` + Specifies whether the thread is joinable (``PR_JOINABLE_THREAD``) or + unjoinable (``PR_UNJOINABLE_THREAD``). +``stackSize`` + Specifies your preference for the size of the stack, in bytes, + associated with the newly created thread. If you pass zero in this + parameter, :ref:`PR_CreateThread` chooses the most favorable + machine-specific stack size. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, a pointer to the new thread. This pointer remains + valid until the thread returns from its root function. +- If unsuccessful, (for example, if system resources are unavailable), + ``NULL``. + + +Description +----------- + +If you want the thread to start up waiting for the creator to do +something, enter a lock before creating the thread and then have the +thread's root function enter and exit the same lock. When you are ready +for the thread to run, exit the lock. For more information on locks and +thread synchronization, see `Introduction to +NSPR <Introduction_to_NSPR>`__. + +If you want to detect the completion of the created thread, make it +joinable. You can then use :ref:`PR_JoinThread` to synchronize the +termination of another thread. diff --git a/docs/nspr/reference/pr_createthreadpool.rst b/docs/nspr/reference/pr_createthreadpool.rst new file mode 100644 index 0000000000..a4e6021991 --- /dev/null +++ b/docs/nspr/reference/pr_createthreadpool.rst @@ -0,0 +1,43 @@ +PR_CreateThreadPool +=================== + +Create a new hash table. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRThreadPool *) + PR_CreateThreadPool( + PRInt32 initial_threads, + PRInt32 max_threads, + PRUint32 stacksize + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``initial_threads`` + The number of threads to be created within this thread pool. +``max_threads`` + The limit on the number of threads that will be created to server the + thread pool. +``stacksize`` + Size of the stack allocated to each thread in the thread. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRThreadPool` structure or ``NULL`` on error. + + +Description +~~~~~~~~~~~ diff --git a/docs/nspr/reference/pr_cwait.rst b/docs/nspr/reference/pr_cwait.rst new file mode 100644 index 0000000000..9af79c42c3 --- /dev/null +++ b/docs/nspr/reference/pr_cwait.rst @@ -0,0 +1,63 @@ +PR_CWait +======== + +Wait for a notification that a monitor's state has changed. + + +Syntax +------ + +.. code:: + + #include <prcmon.h> + + PRStatus PR_CWait( + void *address, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``address`` + The address of the protected object--the same address previously + passed to :ref:`PR_CEnterMonitor`. +``timeout`` + The amount of time (in :ref:`PRIntervalTime` units) that the thread is + willing to wait for an explicit notification before being + rescheduled. If you specify ``PR_INTERVAL_NO_TIMEOUT``, the function + returns if and only if the object is notified. + + +Returns +~~~~~~~ + +The function returns one of the following values: + + - :ref:`PR_SUCCESS` indicates either that the monitored object has been + notified or that the interval specified in the timeout parameter has + been exceeded. + - :ref:`PR_FAILURE` indicates either that the monitor could not be located + in the cache or that the monitor was located and the calling thread + was not the thread that held the monitor's mutex. + + +Description +----------- + +Using the value specified in the ``address`` parameter to find a monitor +in the monitor cache, :ref:`PR_CWait` waits for a notification that the +monitor's state has changed. While the thread is waiting, it exits the +monitor (just as if it had called :ref:`PR_CExitMonitor` as many times as +it had called :ref:`PR_CEnterMonitor`). When the wait has finished, the +thread regains control of the monitor's lock with the same entry count +as before the wait began. + +The thread waiting on the monitor resumes execution when the monitor is +notified (assuming the thread is the next in line to receive the notify) +or when the interval specified in the ``timeout`` parameter has been +exceeded. When the thread resumes execution, it is the caller's +responsibility to test the state of the monitored data to determine the +appropriate action. diff --git a/docs/nspr/reference/pr_delete.rst b/docs/nspr/reference/pr_delete.rst new file mode 100644 index 0000000000..f3d5523836 --- /dev/null +++ b/docs/nspr/reference/pr_delete.rst @@ -0,0 +1,38 @@ +PR_Delete +========= + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Delete(const char *name); + + +Parameters +~~~~~~~~~~ + +The function has the following parameter: + +``name`` + The pathname of the file to be deleted. + + +Returns +~~~~~~~ + +One of the following values: + +- If file is deleted successfully, ``PR_SUCCESS``. +- If the file is not deleted, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_Delete` deletes a file with the specified pathname ``name``. If +the function fails, the error code can then be retrieved via +:ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_delete_.rst b/docs/nspr/reference/pr_delete_.rst new file mode 100644 index 0000000000..c441801d25 --- /dev/null +++ b/docs/nspr/reference/pr_delete_.rst @@ -0,0 +1,37 @@ +PR_DELETE +========= + + +Allocates memory of a specified size from the heap. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + void PR_DELETE(_ptr); + + +Parameter +~~~~~~~~~ + +``_ptr`` + The address of memory to be returned to the heap. Must be an lvalue + (an expression that can appear on the left side of an assignment + statement). + + +Returns +~~~~~~~ + +Nothing. + + +Description +----------- + +This macro returns allocated memory to the heap from the specified +location and sets ``_ptr`` to ``NULL``. diff --git a/docs/nspr/reference/pr_deletesemaphore.rst b/docs/nspr/reference/pr_deletesemaphore.rst new file mode 100644 index 0000000000..bfef8e89eb --- /dev/null +++ b/docs/nspr/reference/pr_deletesemaphore.rst @@ -0,0 +1,30 @@ +PR_DeleteSemaphore +================== + +Removes a semaphore specified by name from the system. + + +Syntax +------ + +.. code:: + + #include <pripcsem.h> + + NSPR_API(PRStatus) PR_DeleteSemaphore(const char *name); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``name`` + The name of a semaphore that was previously created via a call to + :ref:`PR_OpenSemaphore`. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_deletesharedmemory.rst b/docs/nspr/reference/pr_deletesharedmemory.rst new file mode 100644 index 0000000000..3e39bd6e04 --- /dev/null +++ b/docs/nspr/reference/pr_deletesharedmemory.rst @@ -0,0 +1,32 @@ +PR_DeleteSharedMemory +===================== + +Deletes a shared memory segment identified by name. + + +Syntax +------ + +.. code:: + + #include <prshm.h> + + NSPR_API( PRStatus ) + PR_DeleteSharedMemory( + const char *name + ); + + +Parameter +~~~~~~~~~ + +The function has these parameter: + +shm + The handle returned from :ref:`PR_OpenSharedMemory`. + + +Returns +~~~~~~~ + +:ref:`PRStatus`. diff --git a/docs/nspr/reference/pr_destroycondvar.rst b/docs/nspr/reference/pr_destroycondvar.rst new file mode 100644 index 0000000000..2347a2d389 --- /dev/null +++ b/docs/nspr/reference/pr_destroycondvar.rst @@ -0,0 +1,30 @@ +PR_DestroyCondVar +================= + +Destroys a condition variable. + + +Syntax +------ + +.. code:: + + #include <prcvar.h> + + void PR_DestroyCondVar(PRCondVar *cvar); + + +Parameter +~~~~~~~~~ + +:ref:`PR_DestroyCondVar` has one parameter: + +``cvar`` + A pointer to the condition variable object to be destroyed. + + +Description +----------- + +Before calling :ref:`PR_DestroyCondVar`, the caller is responsible for +ensuring that the condition variable is no longer in use. diff --git a/docs/nspr/reference/pr_destroylock.rst b/docs/nspr/reference/pr_destroylock.rst new file mode 100644 index 0000000000..9ed566efc5 --- /dev/null +++ b/docs/nspr/reference/pr_destroylock.rst @@ -0,0 +1,30 @@ +PR_DestroyLock +============== + +Destroys a specified lock object. + + +Syntax +------ + +.. code:: + + #include <prlock.h> + + void PR_DestroyLock(PRLock *lock); + + +Parameter +~~~~~~~~~ + +:ref:`PR_DestroyLock` has one parameter: + +``lock`` + A pointer to a lock object. + +Caution +------- + +The caller must ensure that no thread is currently in a lock-specific +function. Locks do not provide self-referential protection against +deletion. diff --git a/docs/nspr/reference/pr_destroymonitor.rst b/docs/nspr/reference/pr_destroymonitor.rst new file mode 100644 index 0000000000..4d9d9e58ac --- /dev/null +++ b/docs/nspr/reference/pr_destroymonitor.rst @@ -0,0 +1,31 @@ +PR_DestroyMonitor +================= + +Destroys a monitor object. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + void PR_DestroyMonitor(PRMonitor *mon); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``mon`` + A reference to an existing structure of type :ref:`PRMonitor`. + + +Description +----------- + +The caller is responsible for guaranteeing that the monitor is no longer +in use before calling :ref:`PR_DestroyMonitor`. There must be no thread +(including the calling thread) in the monitor or waiting on the monitor. diff --git a/docs/nspr/reference/pr_destroypollableevent.rst b/docs/nspr/reference/pr_destroypollableevent.rst new file mode 100644 index 0000000000..526a90258d --- /dev/null +++ b/docs/nspr/reference/pr_destroypollableevent.rst @@ -0,0 +1,33 @@ +PR_DestroyPollableEvent +======================= + +Close the file descriptor associated with a pollable event and release +related resources. + + +Syntax +------ + +.. code:: + + NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``event`` + Pointer to a :ref:`PRFileDesc` structure previously created via a call + to :ref:`PR_NewPollableEvent`. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + retrieved via :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_detachsharedmemory.rst b/docs/nspr/reference/pr_detachsharedmemory.rst new file mode 100644 index 0000000000..1954762970 --- /dev/null +++ b/docs/nspr/reference/pr_detachsharedmemory.rst @@ -0,0 +1,35 @@ +PR_DetachSharedMemory +===================== + +Unmaps a shared memory segment identified by name. + + +Syntax +------ + +.. code:: + + #include <prshm.h> + + NSPR_API( PRStatus ) + PR_DetachSharedMemory( + PRSharedMemory *shm, + void *addr + ); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +shm + The handle returned from :ref:`PR_OpenSharedMemory`. +addr + The address to which the shared memory segment is mapped. + + +Returns +~~~~~~~ + +:ref:`PRStatus`. diff --git a/docs/nspr/reference/pr_detachthread.rst b/docs/nspr/reference/pr_detachthread.rst new file mode 100644 index 0000000000..17c16f0f3b --- /dev/null +++ b/docs/nspr/reference/pr_detachthread.rst @@ -0,0 +1,57 @@ +PR_DetachThread +=============== + +.. container:: blockIndicator obsolete obsoleteHeader + + | **Obsolete** + | This feature is obsolete. Although it may still work in some + browsers, its use is discouraged since it could be removed at any + time. Try to avoid using it. + +Disassociates a PRThread object from a native thread. + + +Syntax +------ + +.. code:: + + #include <pprthread.h> + + void PR_DetachThread(void); + + +Parameters +~~~~~~~~~~ + +PR_DetachThread has no parameters. + + +Returns +~~~~~~~ + +The function returns nothing. + + +Description +----------- + +This function detaches the NSPR thread from the currently executing +native thread. The thread object and all related data attached to it are +destroyed. The exit process is invoked. The call returns after the NSPR +thread object is destroyed. + +This call is needed only if you attached the thread using +:ref:`PR_AttachThread`. + +.. note:: + + As of NSPR release v3.0, :ref:`PR_AttachThread` and + :ref:`PR_DetachThread` are obsolete. A native thread not created by NSPR + is automatically attached the first time it calls an NSPR function, + and automatically detached when it exits. + +In NSPR release 19980529B and earlier, it is necessary for a native +thread not created by NSPR to call :ref:`PR_AttachThread` before it calls +any NSPR functions, and call :ref:`PR_DetachThread` when it is done calling +NSPR functions. diff --git a/docs/nspr/reference/pr_disableclockinterrupts.rst b/docs/nspr/reference/pr_disableclockinterrupts.rst new file mode 100644 index 0000000000..9296395873 --- /dev/null +++ b/docs/nspr/reference/pr_disableclockinterrupts.rst @@ -0,0 +1,14 @@ +PR_DisableClockInterrupts +========================= + +Disables timer signals used for preemptive scheduling. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_DisableClockInterrupts(void); diff --git a/docs/nspr/reference/pr_dtoa.rst b/docs/nspr/reference/pr_dtoa.rst new file mode 100644 index 0000000000..d2f5d73bac --- /dev/null +++ b/docs/nspr/reference/pr_dtoa.rst @@ -0,0 +1,93 @@ +PR_dtoa +======= + +Converts a floating point number to a string. + + +Syntax +------ + +.. code:: + + #include <prdtoa.h> + + PRStatus PR_dtoa( + PRFloat64 d, + PRIntn mode, + PRIntn ndigits, + PRIntn *decpt, + PRIntn *sign, + char **rve, + char *buf, + PRSize bufsz); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``d`` + The floating point number to be converted to a string. +``mode`` + The type of conversion to employ. +``ndigits`` + The number of digits desired in the output string. +``decpt`` + A pointer to a memory location where the runtime will store the + offset, relative to the beginning of the output string, of the + conversion's decimal point. +``sign`` + A location where the runtime can store an indication that the + conversion was of a negative value. +``*rve`` + If not ``NULL`` this location is set to the address of the end of the + result. +``buf`` + The address of the buffer in which to store the result. +``bufsz`` + The size of the buffer provided to hold the result. + +Results +~~~~~~~ + +The principle output is the null-terminated string stored in ``buf``. If +``rve`` is not ``NULL``, ``*rve`` is set to point to the end of the +returned value. + + +Description +----------- + +This function converts the specified floating point number to a string, +using the method specified by ``mode``. Possible modes are: + +``0`` + Shortest string that yields ``d`` when read in and rounded to + nearest. +``1`` + Like 0, but with Steele & White stopping rule. For example, with IEEE + 754 arithmetic, mode 0 gives 1e23 whereas mode 1 gives + 9.999999999999999e22. +``2`` + ``max(1, ndigits)`` significant digits. This gives a return value + similar to that of ``ecvt``, except that trailing zeros are + suppressed. +``3`` + Through ``ndigits`` past the decimal point. This gives a return value + similar to that from ``fcvt``, except that trailing zeros are + suppressed, and ``ndigits`` can be negative. +``4,5,8,9`` + Same as modes 2 and 3, but using\ *left to right* digit generation. +``6-9`` + Same as modes 2 and 3, but do not try fast floating-point estimate + (if applicable). +``all others`` + Treated as mode 2. + +Upon return, the buffer specified by ``buf`` and ``bufsz`` contains the +converted string. Trailing zeros are suppressed. Sufficient space is +allocated to the return value to hold the suppressed trailing zeros. + +If the input parameter ``d`` is\ *+Infinity*,\ *-Infinity* or\ *NAN*, +``*decpt`` is set to 9999. diff --git a/docs/nspr/reference/pr_entermonitor.rst b/docs/nspr/reference/pr_entermonitor.rst new file mode 100644 index 0000000000..501104e082 --- /dev/null +++ b/docs/nspr/reference/pr_entermonitor.rst @@ -0,0 +1,41 @@ +PR_EnterMonitor +=============== + +Enters the lock associated with a specified monitor. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + void PR_EnterMonitor(PRMonitor *mon); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``mon`` + A reference to an existing structure of type :ref:`PRMonitor`. + + +Description +----------- + +When the calling thread returns, it will have acquired the monitor's +lock. Attempts to acquire the lock for a monitor that is held by some +other thread will result in the caller blocking. The operation is +neither timed nor interruptible. + +If the monitor's entry count is greater than zero and the calling thread +is recognized as the holder of the lock, :ref:`PR_EnterMonitor` increments +the entry count by one and returns. If the entry count is greater than +zero and the calling thread is not recognized as the holder of the lock, +the thread is blocked until the entry count reaches zero. When the entry +count reaches zero (or if it is already zero), the entry count is +incremented by one and the calling thread is recorded as the lock's +holder. diff --git a/docs/nspr/reference/pr_enumerateaddrinfo.rst b/docs/nspr/reference/pr_enumerateaddrinfo.rst new file mode 100644 index 0000000000..d978766da6 --- /dev/null +++ b/docs/nspr/reference/pr_enumerateaddrinfo.rst @@ -0,0 +1,58 @@ +PR_EnumerateAddrInfo +==================== + + +Enumerates each of the possible network addresses of a ``PRAddrInfo`` +structure, acquired from :ref:`PR_GetAddrInfoByName`. + + +Syntax +~~~~~~ + +.. code:: + + #include <prnetdb.h> + + void *PR_EnumerateAddrInfo( + void *enumPtr, + const PRAddrInfo *addrInfo, + PRUint16 port, + PRNetAddr *result); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``enumPtr`` + The index pointer of the enumeration. To begin an enumeration, this + argument is set to ``NULL``. To continue an enumeration (thereby + getting successive addresses from the ``PRAddrInfo`` structure), the + value should be set to the function's last returned value. The + enumeration is complete when a value of ``NULL`` is returned. +``addrInfo`` + A pointer to a ``PRAddrInfo`` structure returned by + :ref:`PR_GetAddrInfoByName`. +``port`` + The port number to be assigned as part of the :ref:`PRNetAddr` + structure. This parameter is not checked for validity. +``result`` + On input, a pointer to a :ref:`PRNetAddr` structure. On output, this + structure is filled in by the runtime if the result of the call is + not ``NULL``. + + +Returns +~~~~~~~ + +The function returns the value you should specify in the ``enumPtr`` +parameter for the next call of the enumerator. If the function returns +``NULL``, the enumeration is ended. + + +Description +----------- + +:ref:`PR_EnumerateAddrInfo` is a stateless enumerator. The principle input, +the ``PRAddrInfo`` structure, is not modified. diff --git a/docs/nspr/reference/pr_enumeratehostent.rst b/docs/nspr/reference/pr_enumeratehostent.rst new file mode 100644 index 0000000000..a808730330 --- /dev/null +++ b/docs/nspr/reference/pr_enumeratehostent.rst @@ -0,0 +1,61 @@ +PR_EnumerateHostEnt +=================== + +Evaluates each of the possible addresses of a :ref:`PRHostEnt` structure, +acquired from :ref:`PR_GetHostByName` or :ref:`PR_GetHostByAddr`. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRIntn PR_EnumerateHostEnt( + PRIntn enumIndex, + const PRHostEnt *hostEnt, + PRUint16 port, + PRNetAddr *address); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``enumIndex`` + The index of the enumeration. To begin an enumeration, this argument + is set to zero. To continue an enumeration (thereby getting + successive addresses from the host entry structure), the value should + be set to the function's last returned value. The enumeration is + complete when a value of zero is returned. +``hostEnt`` + A pointer to a :ref:`PRHostEnt` structure obtained from + :ref:`PR_GetHostByName` or :ref:`PR_GetHostByAddr`. +``port`` + The port number to be assigned as part of the :ref:`PRNetAddr` + structure. This parameter is not checked for validity. +``address`` + On input, a pointer to a :ref:`PRNetAddr` structure. On output, this + structure is filled in by the runtime if the result of the call is + greater than 0. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, the function returns the value you should specify in + the ``enumIndex`` parameter for the next call of the enumerator. If + the function returns 0, the enumeration is ended. +- If unsuccessful, the function returns -1. You can retrieve the reason + for the failure by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_EnumerateHostEnt` is a stateless enumerator. The principle input, +the :ref:`PRHostEnt` structure, is not modified. diff --git a/docs/nspr/reference/pr_exitmonitor.rst b/docs/nspr/reference/pr_exitmonitor.rst new file mode 100644 index 0000000000..3cb8463e85 --- /dev/null +++ b/docs/nspr/reference/pr_exitmonitor.rst @@ -0,0 +1,44 @@ +PR_ExitMonitor +============== + +Decrements the entry count associated with a specified monitor and, if +the entry count reaches zero, releases the monitor's lock. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + PRStatus PR_ExitMonitor(PRMonitor *mon); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``mon`` + A reference to an existing structure of type :ref:`PRMonitor`. The + monitor object referenced must be one for which the calling thread + currently holds the lock. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful (the calling thread has not entered the monitor), + ``PR_FAILURE``. + + +Description +----------- + +If the decremented entry count is zero, :ref:`PR_ExitMonitor` releases the +monitor's lock. Threads that were blocked trying to enter the monitor +will be rescheduled. diff --git a/docs/nspr/reference/pr_explodetime.rst b/docs/nspr/reference/pr_explodetime.rst new file mode 100644 index 0000000000..066ccfcd01 --- /dev/null +++ b/docs/nspr/reference/pr_explodetime.rst @@ -0,0 +1,46 @@ +PR_ExplodeTime +============== + +Converts an absolute time to a clock/calendar time. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + void PR_ExplodeTime( + PRTime usecs, + PRTimeParamFn params, + PRExplodedTime *exploded); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``usecs`` + An absolute time in the :ref:`PRTime` format. +``params`` + A time parameter callback function. +``exploded`` + A pointer to a location where the converted time can be stored. This + location must be preallocated by the caller. + + +Returns +~~~~~~~ + +Nothing; the buffer pointed to by ``exploded`` is filled with the +exploded time. + + +Description +----------- + +This function converts the specified absolute time to a clock/calendar +time in the specified time zone. Upon return, the location pointed to by +the exploded parameter contains the converted time value. diff --git a/docs/nspr/reference/pr_exportfilemapasstring.rst b/docs/nspr/reference/pr_exportfilemapasstring.rst new file mode 100644 index 0000000000..649a373a34 --- /dev/null +++ b/docs/nspr/reference/pr_exportfilemapasstring.rst @@ -0,0 +1,47 @@ +PR_ExportFileMapAsString +======================== + +Creates a string identifying a :ref:`PRFileMap`. + + +Syntax +------ + +.. code:: + + #include <prshma.h> + + NSPR_API( PRStatus ) + PR_ExportFileMapAsString( + PRFileMap *fm, + PRSize bufsize, + char *buf + ); + +#. define PR_FILEMAP_STRING_BUFSIZE 128 + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fm`` + A pointer to the :ref:`PRFileMap` to be represented as a string. +``bufsize`` + sizeof(buf) +``buf`` + A pointer to abuffer of length ``PR_FILEMAP_STRING_BUFSIZE``. + + +Returns +~~~~~~~ + +:ref:`PRStatus` + + +Description +----------- + +Creates an identifier, as a string, from a :ref:`PRFileMap` object +previously created with :ref:`PR_OpenAnonFileMap`. diff --git a/docs/nspr/reference/pr_extern.rst b/docs/nspr/reference/pr_extern.rst new file mode 100644 index 0000000000..64d38654b6 --- /dev/null +++ b/docs/nspr/reference/pr_extern.rst @@ -0,0 +1,30 @@ +PR_EXTERN +========= + +Used to define the prototypes for functions or variables that are to be +exported from a shared library. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + PR_EXTERN(type)prototype + + +Description +----------- + +:ref:`PR_EXTERN` is used to define externally visible routines and globals. +For syntax details for each platform, see +`prtypes.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtypes.h>`__. +The macro includes the proper specifications to declare the target +``extern`` and set up other required linkages. + +.. warning:: + + **Warning**: Some platforms do not allow the use of the underscore + character (_) as the first character of an exported symbol. diff --git a/docs/nspr/reference/pr_familyinet.rst b/docs/nspr/reference/pr_familyinet.rst new file mode 100644 index 0000000000..251286257f --- /dev/null +++ b/docs/nspr/reference/pr_familyinet.rst @@ -0,0 +1,23 @@ +PR_FamilyInet +============= + +Gets the value of the address family for Internet Protocol. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRUint16 PR_FamilyInet(void); + + +Returns +~~~~~~~ + +The value of the address family for Internet Protocol. This is usually +``PR_AF_INET``, but can also be ``PR_AF_INET6`` if IPv6 is enabled. The +returned value can be assigned to the ``inet.family`` field of a +:ref:`PRNetAddr` object. diff --git a/docs/nspr/reference/pr_findsymbol.rst b/docs/nspr/reference/pr_findsymbol.rst new file mode 100644 index 0000000000..c30ccfabfe --- /dev/null +++ b/docs/nspr/reference/pr_findsymbol.rst @@ -0,0 +1,52 @@ +PR_FindSymbol +============= + +``PR_FindSymbol()`` will return an untyped reference to a symbol in a +particular library given the identity of the library and a textual +representation of the symbol in question. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + void* PR_FindSymbol ( + PRLibrary *lib, + const char *name); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``lib`` + A valid reference to a loaded library, as returned by + :ref:`PR_LoadLibrary`, or ``NULL``. +``name`` + A textual representation of the symbol to resolve. + + +Returns +~~~~~~~ + +An untyped pointer. + + +Description +----------- + +This function finds and returns an untyped reference to the specified +symbol in the specified library. If the lib parameter is ``NULL``, all +libraries known to the runtime and the main program are searched in an +unspecified order. + +Use this function to look up functions or data symbols in a shared +library. Getting a pointer to a symbol in a library does indicate that +the library is available when the search was made. The runtime does +nothing to ensure the continued validity of the symbol. If the library +is unloaded, for instance, the results of any :ref:`PR_FindSymbol` calls +become invalid as well. diff --git a/docs/nspr/reference/pr_findsymbolandlibrary.rst b/docs/nspr/reference/pr_findsymbolandlibrary.rst new file mode 100644 index 0000000000..0df683a76c --- /dev/null +++ b/docs/nspr/reference/pr_findsymbolandlibrary.rst @@ -0,0 +1,59 @@ +PR_FindSymbolAndLibrary +======================= + +Finds a symbol in one of the currently loaded libraries, and returns +both the symbol and the library in which it was found. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + void* PR_FindSymbolAndLibrary ( + const char *name, + PRLibrary **lib); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``name`` + The textual representation of the symbol to locate. +``lib`` + A reference to a location at which the runtime will store the library + in which the symbol was discovered. This location must be + pre-allocated by the caller. + + +Returns +~~~~~~~ + +If successful, returns a non-``NULL`` pointer to the found symbol, and +stores a pointer to the library in which it was found at the location +pointed to by lib. + +If the symbol could not be found, returns ``NULL``. + + +Description +----------- + +This function finds the specified symbol in one of the currently loaded +libraries. It returns the address of the symbol. Upon return, the +location pointed to by the parameter lib contains a pointer to the +library that contains that symbol. The location must be pre-allocated by +the caller. + +The function returns ``NULL`` if no such function can be found. The +order in which the known libraries are searched in not specified. This +function is equivalent to calling first :ref:`PR_LoadLibrary`, then +:ref:`PR_FindSymbol`. + +The identity returned from this function must be the target of a +:ref:`PR_UnloadLibrary` in order to return the runtime to its original +state. diff --git a/docs/nspr/reference/pr_free.rst b/docs/nspr/reference/pr_free.rst new file mode 100644 index 0000000000..577955d205 --- /dev/null +++ b/docs/nspr/reference/pr_free.rst @@ -0,0 +1,33 @@ +PR_Free +======= + +Frees allocated memory in the heap. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + void PR_Free(void *ptr); + + +Parameter +~~~~~~~~~ + +``ptr`` + A pointer to the memory to be freed. + + +Returns +~~~~~~~ + +Nothing. + + +Description +----------- + +This function frees the memory addressed by ``ptr`` in the heap. diff --git a/docs/nspr/reference/pr_freeaddrinfo.rst b/docs/nspr/reference/pr_freeaddrinfo.rst new file mode 100644 index 0000000000..bc004c037e --- /dev/null +++ b/docs/nspr/reference/pr_freeaddrinfo.rst @@ -0,0 +1,32 @@ +PR_FreeAddrInfo +=============== + + +Destroys the ``PRAddrInfo`` structure returned by +:ref:`PR_GetAddrInfoByName`. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + void PR_EnumerateAddrInfo(PRAddrInfo *addrInfo); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``addrInfo`` + A pointer to a ``PRAddrInfo`` structure returned by a successful call + to :ref:`PR_GetAddrInfoByName`. + + +Returns +~~~~~~~ + +The function doesn't return anything. diff --git a/docs/nspr/reference/pr_freeif.rst b/docs/nspr/reference/pr_freeif.rst new file mode 100644 index 0000000000..3d8f9baba5 --- /dev/null +++ b/docs/nspr/reference/pr_freeif.rst @@ -0,0 +1,34 @@ +PR_FREEIF +========= + +Conditionally frees allocated memory. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + void PR_FREEIF(_ptr); + + +Parameter +~~~~~~~~~ + +``_ptr`` + The address of memory to be returned to the heap. + + +Returns +~~~~~~~ + +Nothing. + + +Description +----------- + +This macro returns memory to the heap when ``_ptr`` is not ``NULL``. If +``_ptr`` is ``NULL``, the macro has no effect. diff --git a/docs/nspr/reference/pr_freelibraryname.rst b/docs/nspr/reference/pr_freelibraryname.rst new file mode 100644 index 0000000000..2091277c79 --- /dev/null +++ b/docs/nspr/reference/pr_freelibraryname.rst @@ -0,0 +1,39 @@ +PR_FreeLibraryName +================== + +Frees memory allocated by NSPR for library names and path names. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + void PR_FreeLibraryName(char *mem); + + +Parameters +~~~~~~~~~~ + +The function has this parameter: + +``mem`` + A reference to a character array that was previously allocated by the + dynamic library runtime. + + +Returns +~~~~~~~ + +Nothing. + + +Description +----------- + +This function deletes the storage allocated by the runtime in the +functions described previously. It is important to use this function to +rather than calling directly into ``malloc`` in order to isolate the +runtime's semantics regarding storage management. diff --git a/docs/nspr/reference/pr_getaddrinfobyname.rst b/docs/nspr/reference/pr_getaddrinfobyname.rst new file mode 100644 index 0000000000..fd428124da --- /dev/null +++ b/docs/nspr/reference/pr_getaddrinfobyname.rst @@ -0,0 +1,48 @@ +PR_GetAddrInfoByName +==================== + +Looks up a host by name. Equivalent to ``getaddrinfo(host, NULL, ...)`` +of RFC 3493. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRAddrInfo *PR_GetAddrInfoByName( + const char *hostname, + PRUint16 af, + PRIntn flags); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``hostname`` + The character string defining the host name of interest. +``af`` + The address family. May be ``PR_AF_UNSPEC`` or ``PR_AF_INET``. +``flags`` + May be either ``PR_AI_ADDRCONFIG`` or + ``PR_AI_ADDRCONFIG | PR_AI_NOCANONNAME``. Include + ``PR_AI_NOCANONNAME`` to suppress the determination of the canonical + name corresponding to ``hostname`` + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, a pointer to the opaque ``PRAddrInfo`` structure + containing the results of the host lookup. Use + :ref:`PR_EnumerateAddrInfo` to inspect the :ref:`PRNetAddr` values stored + in this structure. When no longer needed, this pointer must be + destroyed with a call to :ref:`PR_FreeAddrInfo`. +- If unsuccessful, ``NULL``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getcanonnamefromaddrinfo.rst b/docs/nspr/reference/pr_getcanonnamefromaddrinfo.rst new file mode 100644 index 0000000000..b84fe84604 --- /dev/null +++ b/docs/nspr/reference/pr_getcanonnamefromaddrinfo.rst @@ -0,0 +1,33 @@ +PR_GetCanonNameFromAddrInfo +=========================== + +Extracts the canonical name of the hostname passed to +:ref:`PR_GetAddrInfoByName`. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + const char *PR_GetCanonNameFromAddrInfo(const PRAddrInfo *addrInfo); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``addrInfo`` + A pointer to a ``PRAddrInfo`` structure returned by a successful call + to :ref:`PR_GetAddrInfoByName`. + + +Returns +~~~~~~~ + +The function returns a const pointer to the canonical hostname stored in +the given ``PRAddrInfo`` structure. This pointer is invalidated once the +``PRAddrInfo`` structure is destroyed by a call to :ref:`PR_FreeAddrInfo`. diff --git a/docs/nspr/reference/pr_getconnectstatus.rst b/docs/nspr/reference/pr_getconnectstatus.rst new file mode 100644 index 0000000000..a8753e546e --- /dev/null +++ b/docs/nspr/reference/pr_getconnectstatus.rst @@ -0,0 +1,48 @@ +PR_GetConnectStatus +=================== + +Get the completion status of a nonblocking connection. + + +Syntax +------ + +.. code:: + + PRStatus PR_GetConnectStatus(const PRPollDesc *pd); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``pd`` + A pointer to a ``PRPollDesc`` satructure whose ``fd`` field is the + socket and whose ``in_flags`` field must contain ``PR_POLL_WRITE`` + and ``PR_POLL_EXCEPT``. + + +Returns +~~~~~~~ + +The function returns one of these values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + retrieved via :ref:`PR_GetError`. + +If :ref:`PR_GetError` returns ``PR_IN_PROGRESS_ERROR``, the nonblocking +connection is still in progress and has not completed yet.Other errors +indicate that the connection has failed. + + +Description +----------- + +After :ref:`PR_Connect` on a nonblocking socket fails with +``PR_IN_PROGRESS_ERROR``, you may wait for the connection to complete by +calling :ref:`PR_Poll` on the socket with the ``in_flags`` +``PR_POLL_WRITE`` \| ``PR_POLL_EXCEPT``. When :ref:`PR_Poll` returns, call +:ref:`PR_GetConnectStatus` on the socket to determine whether the +nonblocking connect has succeeded or failed. diff --git a/docs/nspr/reference/pr_getcurrentthread.rst b/docs/nspr/reference/pr_getcurrentthread.rst new file mode 100644 index 0000000000..b954deb16d --- /dev/null +++ b/docs/nspr/reference/pr_getcurrentthread.rst @@ -0,0 +1,32 @@ +PR_GetCurrentThread +=================== + +Returns the current thread object for the currently running code. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRThread* PR_GetCurrentThread(void); + + +Returns +~~~~~~~ + +Always returns a valid reference to the calling thread--a self-identity. + + +Description +~~~~~~~~~~~ + +The currently running thread may discover its own identity by calling +:ref:`PR_GetCurrentThread`. + +.. note:: + + This is the only safe way to establish the identity of a + thread. Creation and enumeration are both subject to race conditions. diff --git a/docs/nspr/reference/pr_getdefaultiomethods.rst b/docs/nspr/reference/pr_getdefaultiomethods.rst new file mode 100644 index 0000000000..674dea0366 --- /dev/null +++ b/docs/nspr/reference/pr_getdefaultiomethods.rst @@ -0,0 +1,31 @@ +PR_GetDefaultIOMethods +====================== + +Gets the default I/O methods table. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + const PRIOMethods* PR_GetDefaultIOMethods(void); + + +Returns +~~~~~~~ + +If successful, the function returns a pointer to a :ref:`PRIOMethods` +structure. + + +Description +----------- + +After using :ref:`PR_GetDefaultIOMethods` to identify the default I/O +methods table, you can select elements from that table with which to +build your own layer's methods table. You may not modify the default I/O +methods table directly. You can pass your own layer's methods table to +:ref:`PR_CreateIOLayerStub` to create your new layer. diff --git a/docs/nspr/reference/pr_getdesctype.rst b/docs/nspr/reference/pr_getdesctype.rst new file mode 100644 index 0000000000..66cbf58397 --- /dev/null +++ b/docs/nspr/reference/pr_getdesctype.rst @@ -0,0 +1,58 @@ +PR_GetDescType +============== + +Describes what type of file is referenced by a specified file +descriptor. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRDescType PR_GetDescType(PRFileDesc *file); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``file`` + A pointer to a :ref:`PRFileDesc` object whose descriptor type is to be + returned. + + +Returns +~~~~~~~ + +The function returns a ``PRDescType`` enumeration constant that +describes the type of file. + + +Description +----------- + +The ``PRDescType`` enumeration is defined as follows: + +.. code:: + + typedef enum PRDescType { + PR_DESC_FILE = 1, + PR_DESC_SOCKET_TCP = 2, + PR_DESC_SOCKET_UDP = 3, + PR_DESC_LAYERED = 4 + } PRDescType; + +The enumeration has the following enumerators: + +``PR_DESC_FILE`` + The :ref:`PRFileDesc` object represents a normal file. +``PR_DESC_SOCKET_TCP`` + The :ref:`PRFileDesc` object represents a TCP socket. +``PR_DESC_SOCKET_UDP`` + The :ref:`PRFileDesc` object represents a UDP socket. +``PR_DESC_LAYERED`` + The :ref:`PRFileDesc` object is a layered file descriptor. diff --git a/docs/nspr/reference/pr_geterror.rst b/docs/nspr/reference/pr_geterror.rst new file mode 100644 index 0000000000..9a50d8aacc --- /dev/null +++ b/docs/nspr/reference/pr_geterror.rst @@ -0,0 +1,23 @@ +PR_GetError +=========== + +Returns the current thread's last set platform-independent error code. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + PRErrorCode PR_GetError(void) + + +Returns +~~~~~~~ + +The value returned is a 32-bit number. NSPR provides no direct +interpretation of the number's value. NSPR does use :ref:`PR_SetError` to +set error numbers defined in `Error +Codes <NSPR_Error_Handling#Error_Code>`__. diff --git a/docs/nspr/reference/pr_geterrortext.rst b/docs/nspr/reference/pr_geterrortext.rst new file mode 100644 index 0000000000..e8a0508b8a --- /dev/null +++ b/docs/nspr/reference/pr_geterrortext.rst @@ -0,0 +1,32 @@ +PR_GetErrorText +=============== + +Copies the current thread's current error text without altering the text +as stored in the thread's context. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + PRInt32 PR_GetErrorText(char *text); + + +Parameters +~~~~~~~~~~ + +The function has one parameter: + +``text`` + On output, the array pointed to contains the thread's current error + text. + + +Returns +------- + +The actual number of bytes copied. If the result is zero, ``text`` is +unaffected. diff --git a/docs/nspr/reference/pr_geterrortextlength.rst b/docs/nspr/reference/pr_geterrortextlength.rst new file mode 100644 index 0000000000..c771e4c1ee --- /dev/null +++ b/docs/nspr/reference/pr_geterrortextlength.rst @@ -0,0 +1,22 @@ +PR_GetErrorTextLength +===================== + +Gets the length of the error text. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + PRInt32 PR_GetErrorTextLength(void) + + +Returns +~~~~~~~ + +If a zero is returned, no error text is currently set. Otherwise, the +value returned is sufficient to contain the error text currently +available. diff --git a/docs/nspr/reference/pr_getfileinfo.rst b/docs/nspr/reference/pr_getfileinfo.rst new file mode 100644 index 0000000000..1d1daf5427 --- /dev/null +++ b/docs/nspr/reference/pr_getfileinfo.rst @@ -0,0 +1,55 @@ +PR_GetFileInfo +============== + +Gets information about a file with a specified pathname. File size is +expressed as a 32-bit integer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetFileInfo( + const char *fn, + PRFileInfo *info); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fn`` + The pathname of the file to get information about. +``info`` + A pointer to a file information object (see :ref:`PRFileInfo`). On + output, :ref:`PR_GetFileInfo` writes information about the given file to + the file information object. + + +Returns +~~~~~~~ + +One of the following values: + +- If the file information is successfully obtained, ``PR_SUCCESS``. +- If the file information is not successfully obtained, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_GetFileInfo` stores information about the file with the specified +pathname in the :ref:`PRFileInfo` structure pointed to by ``info``. The +file size is returned as an unsigned 32-bit integer. + + +See Also +-------- + +For the 64-bit version of this function, see :ref:`PR_GetFileInfo64`. To +get equivalent information on a file that's already open, use +:ref:`PR_GetOpenFileInfo`. diff --git a/docs/nspr/reference/pr_getfileinfo64.rst b/docs/nspr/reference/pr_getfileinfo64.rst new file mode 100644 index 0000000000..f57217103a --- /dev/null +++ b/docs/nspr/reference/pr_getfileinfo64.rst @@ -0,0 +1,55 @@ +PR_GetFileInfo64 +================ + +Gets information about a file with a specified pathname. File size is +expressed as a 64-bit integer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetFileInfo64( + const char *fn, + PRFileInfo64 *info); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fn`` + The pathname of the file to get information about. +``info`` + A pointer to a 64-bit file information object (see :ref:`PRFileInfo64`). + On output, :ref:`PR_GetFileInfo64` writes information about the given + file to the file information object. + + +Returns +~~~~~~~ + +One of the following values: + +- If the file information is successfully obtained, ``PR_SUCCESS``. +- If the file information is not successfully obtained, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_GetFileInfo64` stores information about the file with the +specified pathname in the :ref:`PRFileInfo64` structure pointed to by +``info``. The file size is returned as an unsigned 64-bit integer. + + +See Also +-------- + +For the 32-bit version of this function, see :ref:`PR_GetFileInfo`. To get +equivalent information on a file that's already open, use +:ref:`PR_GetOpenFileInfo64`. diff --git a/docs/nspr/reference/pr_gethostbyaddr.rst b/docs/nspr/reference/pr_gethostbyaddr.rst new file mode 100644 index 0000000000..7140c5c5dd --- /dev/null +++ b/docs/nspr/reference/pr_gethostbyaddr.rst @@ -0,0 +1,57 @@ +PR_GetHostByAddr +================ + +Looks up a host entry by its network address. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRStatus PR_GetHostByAddr( + const PRNetAddr *hostaddr, + char *buf, + PRIntn bufsize, + PRHostEnt *hostentry); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``hostaddr`` + A pointer to the IP address of host in question. +``buf`` + A pointer to a buffer, allocated by the caller, that is filled in + with host data on output. All of the pointers in the ``hostentry`` + structure point to data saved in this buffer. This buffer is + referenced by the runtime during a call to :ref:`PR_EnumerateHostEnt`. +``bufsize`` + Number of bytes in the ``buf`` parameter. The buffer must be at least + :ref:`PR_NETDB_BUF_SIZE` bytes. +``hostentry`` + This structure is allocated by the caller. On output, this structure + is filled in by the runtime if the function returns ``PR_SUCCESS``. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. + + +Description +~~~~~~~~~~~ + +:ref:`PR_GetHostByAddr` is used to perform reverse lookups of network +addresses. That is, given a valid network address (of type +:ref:`PRNetAddr`), :ref:`PR_GetHostByAddr` discovers the address' primary +name, any aliases, and any other network addresses for the same host. diff --git a/docs/nspr/reference/pr_gethostbyname.rst b/docs/nspr/reference/pr_gethostbyname.rst new file mode 100644 index 0000000000..f1a1a4a108 --- /dev/null +++ b/docs/nspr/reference/pr_gethostbyname.rst @@ -0,0 +1,48 @@ +PR_GetHostByName +================ + +Looks up a host by name. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRStatus PR_GetHostByName( + const char *hostname, + char *buf, + PRIntn bufsize, + PRHostEnt *hostentry); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``hostname`` + The character string defining the host name of interest. +``buf`` + A pointer to a buffer, allocated by the caller, that is filled in + with host data on output. All of the pointers in the ``hostentry`` + structure point to data saved in this buffer. This buffer is + referenced by the runtime during a call to :ref:`PR_EnumerateHostEnt`. +``bufsize`` + Number of bytes in the ``buf`` parameter. The buffer must be at least + :ref:`PR_NETDB_BUF_SIZE` bytes. +``hostentry`` + This structure is allocated by the caller. On output, this structure + is filled in by the runtime if the function returns ``PR_SUCCESS``. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getidentitieslayer.rst b/docs/nspr/reference/pr_getidentitieslayer.rst new file mode 100644 index 0000000000..9a15f9b60d --- /dev/null +++ b/docs/nspr/reference/pr_getidentitieslayer.rst @@ -0,0 +1,48 @@ +PR_GetIdentitiesLayer +===================== + +Finds the layer with the specified identity in the specified stack of +layers. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_GetIdentitiesLayer( + PRFileDesc* stack, + PRDescIdentity id); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``stack`` + A pointer to a :ref:`PRFileDesc` object that is a layer in a stack of + layers. +``id`` + The identity of the specified layer. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, a pointer to a file descriptor of the layer with the + specified identity in the given stack of layers. +- If not successful, ``NULL``. + + +Description +----------- + +The stack of layers to be searched is specified by the fd parameter, +which is a layer in the stack. Both the layers underneath fd and the +layers above fd are searched to find the layer with the specified +identity. diff --git a/docs/nspr/reference/pr_getinheritedfilemap.rst b/docs/nspr/reference/pr_getinheritedfilemap.rst new file mode 100644 index 0000000000..62d93058f4 --- /dev/null +++ b/docs/nspr/reference/pr_getinheritedfilemap.rst @@ -0,0 +1,44 @@ +PR_GetInheritedFileMap +====================== + +Imports a :ref:`PRFileMap` previously exported by my parent process via +``PR_CreateProcess``. + + +Syntax +------ + +.. code:: + + #include <prshma.h> + + NSPR_API( PRFileMap *) + PR_GetInheritedFileMap( + const char *shmname + ); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``shmname`` + The name provided to :ref:`PR_ProcessAttrSetInheritableFileMap`. + + +Returns +~~~~~~~ + +Pointer to :ref:`PRFileMap` or ``NULL`` on error. + + +Description +----------- + +:ref:`PR_GetInheritedFileMap` retrieves a PRFileMap object exported from +its parent process via ``PR_CreateProcess``. + +.. note:: + + **Note:** This function is not implemented. diff --git a/docs/nspr/reference/pr_getlayersidentity.rst b/docs/nspr/reference/pr_getlayersidentity.rst new file mode 100644 index 0000000000..88a06602bc --- /dev/null +++ b/docs/nspr/reference/pr_getlayersidentity.rst @@ -0,0 +1,30 @@ +PR_GetLayersIdentity +==================== + +Gets the unique identity for the layer of the specified file descriptor. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRDescIdentity PR_GetLayersIdentity(PRFileDesc* fd); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``fd`` + A pointer to a file descriptor. + + +Returns +~~~~~~~ + +If successful, the function returns the :ref:`PRDescIdentity` for the layer +of the specified file descriptor. diff --git a/docs/nspr/reference/pr_getlibraryname.rst b/docs/nspr/reference/pr_getlibraryname.rst new file mode 100644 index 0000000000..7bbe3b05ef --- /dev/null +++ b/docs/nspr/reference/pr_getlibraryname.rst @@ -0,0 +1,53 @@ +PR_GetLibraryName +================= + +Constructs a full library path name. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + char* PR_GetLibraryName ( + const char *dir, + const char *lib); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``dir`` + A ``NULL``-terminated string representing the path name of the + library, as returned by :ref:`PR_GetLibraryPath`. +``lib`` + The leaf name of the library of interest. + + +Returns +~~~~~~~ + +If successful, returns a new character string containing a constructed +path name. In case of error, returns ``NULL``. + + +Description +----------- + +This function constructs a full path name from the specified directory +name and library name. The constructed path name refers to the actual +dynamically loaded library. It is suitable for use in the +:ref:`PR_LoadLibrary` call. + +This function does not test for existence of the specified file, it just +constructs the full filename. The way the name is constructed is system +dependent. + +If sufficient storage cannot be allocated to contain the constructed +path name, the function returns ``NULL``. Storage for the result is +allocated by the runtime and becomes the responsibility of the caller. +When it is no longer used, free it using :ref:`PR_FreeLibraryName`. diff --git a/docs/nspr/reference/pr_getlibrarypath.rst b/docs/nspr/reference/pr_getlibrarypath.rst new file mode 100644 index 0000000000..c604edc9cd --- /dev/null +++ b/docs/nspr/reference/pr_getlibrarypath.rst @@ -0,0 +1,37 @@ +PR_GetLibraryPath +================= + +Retrieves the current default library path. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + char* PR_GetLibraryPath(void); + + +Parameters +~~~~~~~~~~ + +The function has no parameters. + + +Returns +~~~~~~~ + +A copy of the default library pathname string. In case of error, returns +NULL. + + +Description +----------- + +This function retrieves the current default library pathname, copies it, +and returns the copy. If sufficient storage cannot be allocated to +contain the copy, the function returns ``NULL``. Storage for the result +is allocated by the runtime and becomes the responsibility of the +caller. When it is no longer used, free it using :ref:`PR_FreeLibraryName`. diff --git a/docs/nspr/reference/pr_getnameforidentity.rst b/docs/nspr/reference/pr_getnameforidentity.rst new file mode 100644 index 0000000000..4db060c81f --- /dev/null +++ b/docs/nspr/reference/pr_getnameforidentity.rst @@ -0,0 +1,41 @@ +PR_GetNameForIdentity +===================== + +Gets the string associated with a layer's unique identity. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + const char* PR_GetNameForIdentity(PRDescIdentity ident); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``ident`` + A layer's identity. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, the function returns a pointer to the string + associated with the specified layer. +- If unsuccessful, the function returns ``NULL``. + + +Description +----------- + +A string may be associated with a layer when the layer is created. The +string is copied by the runtime, and :ref:`PR_GetNameForIdentity` returns a +pointer to that copy. diff --git a/docs/nspr/reference/pr_getopenfileinfo.rst b/docs/nspr/reference/pr_getopenfileinfo.rst new file mode 100644 index 0000000000..7722606141 --- /dev/null +++ b/docs/nspr/reference/pr_getopenfileinfo.rst @@ -0,0 +1,54 @@ +PR_GetOpenFileInfo +================== + +Gets an open file's information. File size is expressed as a 32-bit +integer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetOpenFileInfo( + PRFileDesc *fd, + PRFileInfo *info); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object for an open file. +``info`` + A pointer to a :ref:`PRFileInfo` object. On output, information about + the given file is written into the file information object. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If file information is successfully obtained, ``PR_SUCCESS``. +- If file information is not successfully obtained, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_GetOpenFileInfo` obtains the file type (normal file, directory, or +other), file size (as a 32-bit integer), and the file creation and +modification times of the open file represented by the file descriptor. + + +See Also +-------- + +For the 64-bit version of this function, see :ref:`PR_GetOpenFileInfo64`. +To get equivalent information on a file that's not already open, use +:ref:`PR_GetFileInfo`. diff --git a/docs/nspr/reference/pr_getopenfileinfo64.rst b/docs/nspr/reference/pr_getopenfileinfo64.rst new file mode 100644 index 0000000000..aa0fa83fa2 --- /dev/null +++ b/docs/nspr/reference/pr_getopenfileinfo64.rst @@ -0,0 +1,56 @@ +PR_GetOpenFileInfo64 +==================== + +Gets an open file's information. File size is expressed as a 64-bit +integer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetOpenFileInfo64( + PRFileDesc *fd, + PRFileInfo *info); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object for an open file. +``info`` + A pointer to a :ref:`PRFileInfo64` object. On output, information about + the given file is written into the file information object. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If file information is successfully obtained, ``PR_SUCCESS``. +- If file information is not successfully obtained, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_GetOpenFileInfo64` is the 64-bit version of +:ref:`PR_GetOpenFileInfo`. It obtains the file type (normal file, +directory, or other), file size (as a 64-bit integer), and the creation +and modification times of the open file represented by the file +descriptor. + + +See Also +-------- + +For the 32-bit version of this function, see :ref:`PR_GetOpenFileInfo`. To +get equivalent information on a file that's not already open, use +:ref:`PR_GetFileInfo64`. diff --git a/docs/nspr/reference/pr_getoserror.rst b/docs/nspr/reference/pr_getoserror.rst new file mode 100644 index 0000000000..5068018a63 --- /dev/null +++ b/docs/nspr/reference/pr_getoserror.rst @@ -0,0 +1,31 @@ +PR_GetOSError +============= + +Returns the current thread's last set OS-specific error code. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + PRInt32 PR_GetOSError(void) + + +Returns +~~~~~~~ + +The value returned is a 32-bit signed number. Its interpretation is left +to the caller. + + +Description +----------- + +Used for platform-specific code that requires the underlying OS error. +For portability, clients should not create dependencies on the values of +OS-specific error codes. However, this information is preserved, along +with a platform neutral error code, on a per thread basis. It is most +useful during development. diff --git a/docs/nspr/reference/pr_getpeername.rst b/docs/nspr/reference/pr_getpeername.rst new file mode 100644 index 0000000000..d45896444d --- /dev/null +++ b/docs/nspr/reference/pr_getpeername.rst @@ -0,0 +1,35 @@ +PR_GetPeerName +============== + +Gets the network address of the connected peer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetPeerName( + PRFileDesc *fd, + PRNetAddr *addr); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``addr`` + On return, the address of the peer connected to the socket. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getprotobyname.rst b/docs/nspr/reference/pr_getprotobyname.rst new file mode 100644 index 0000000000..d558b334dd --- /dev/null +++ b/docs/nspr/reference/pr_getprotobyname.rst @@ -0,0 +1,47 @@ +PR_GetProtoByName +================= + +Looks up a protocol entry based on the protocol's name. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRStatus PR_GetProtoByName( + const char* protocolname, + char* buffer, + PRInt32 bufsize, + PRProtoEnt* result); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``protocolname`` + A pointer to the character string of the protocol's name. +``buffer`` + A pointer to a scratch buffer for the runtime to return result. This + buffer is allocated by the caller. +``bufsize`` + Number of bytes in the ``buffer`` parameter. The buffer must be at + least :ref:`PR_NETDB_BUF_SIZE` bytes. +``result`` + On input, a pointer to a :ref:`PRProtoEnt` structure. On output, this + structure is filled in by the runtime if the function returns + ``PR_SUCCESS``. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getprotobynumber.rst b/docs/nspr/reference/pr_getprotobynumber.rst new file mode 100644 index 0000000000..423b1fa16a --- /dev/null +++ b/docs/nspr/reference/pr_getprotobynumber.rst @@ -0,0 +1,47 @@ +PR_GetProtoByNumber +=================== + +Looks up a protocol entry based on protocol's number. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRStatus PR_GetProtoByNumber( + PRInt32 protocolnumber, + char* buffer, + PRInt32 bufsize, + PRProtoEnt* result); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``protocolnumber`` + The number assigned to the protocol. +``buffer`` + A pointer to a scratch buffer for the runtime to return result. This + buffer is allocated by the caller. +``bufsize`` + Number of bytes in the ``buffer`` parameter. The buffer must be at + least :ref:`PR_NETDB_BUF_SIZE` bytes. +``result`` + On input, a pointer to a :ref:`PRNetAddr` structure. On output, this + structure is filled in by the runtime if the function returns + ``PR_SUCCESS``. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getrandomnoise.rst b/docs/nspr/reference/pr_getrandomnoise.rst new file mode 100644 index 0000000000..1d482572f1 --- /dev/null +++ b/docs/nspr/reference/pr_getrandomnoise.rst @@ -0,0 +1,56 @@ +PR_GetRandomNoise +================= + +Produces a random value for use as a seed value for another random +number generator. + + +Syntax +------ + +.. code:: + + #include <prrng.h> + + NSPR_API(PRSize) PR_GetRandomNoise( + void *buf, + PRSize size + ); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``buf`` + A pointer to a caller-supplied buffer to contain the generated random + number. ``buf`` must be at least as large as specified in ``size``. + +``size`` + The size, in bytes, of the requested random number. + + +Returns +~~~~~~~ + +:ref:`PRSize` value equal to the size of the random number actually +generated, or zero. The generated size may be less than the size +requested. A return value of zero means that :ref:`PR_GetRandomNoise` is +not implemented on this platform, or there is no available noise to be +returned at the time of the call. + + +Description +----------- + +:ref:`PR_GetRandomNoise` provides a random value, depending on platform. +The length of the random value is dependent on the platform and its +ability to provide a random value at that moment. + +:ref:`PR_GetRandomNoise` is intended to provide a "seed" value for a +another random number generator that may be suitable for cryptographic +operations. This implies that the random value provided may not be, by +itself, cryptographically secure. The value generated by +:ref:`PR_GetRandomNoise` is at best, extremely difficult to predict and is +as nondeterministic as the underlying platform permits. diff --git a/docs/nspr/reference/pr_getsocketoption.rst b/docs/nspr/reference/pr_getsocketoption.rst new file mode 100644 index 0000000000..3e2112300c --- /dev/null +++ b/docs/nspr/reference/pr_getsocketoption.rst @@ -0,0 +1,40 @@ +PR_GetSocketOption +================== + +Retrieves the socket options set for a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetSocketOption( + PRFileDesc *fd, + PRSocketOptionData *data); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing the socket whose + options are to be retrieved. +``data`` + A pointer to a structure of type :ref:`PRSocketOptionData`. On input, + the ``option`` field of this structure must be set to indicate which + socket option to retrieve for the socket represented by the ``fd`` + parameter. On output, this structure contains the requested socket + option data. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getsockname.rst b/docs/nspr/reference/pr_getsockname.rst new file mode 100644 index 0000000000..7cb6804a3c --- /dev/null +++ b/docs/nspr/reference/pr_getsockname.rst @@ -0,0 +1,35 @@ +PR_GetSockName +============== + +Gets network address for a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_GetSockName( + PRFileDesc *fd, + PRNetAddr *addr); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing the socket. +``addr`` + On return, the address of the socket. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_getspecialfd.rst b/docs/nspr/reference/pr_getspecialfd.rst new file mode 100644 index 0000000000..4cb50fc3c1 --- /dev/null +++ b/docs/nspr/reference/pr_getspecialfd.rst @@ -0,0 +1,56 @@ +PR_GetSpecialFD +=============== + +Gets the file descriptor that represents the standard input, output, or +error stream. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_GetSpecialFD(PRSpecialFD id); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``id`` + A pointer to an enumerator of type ``PRSpecialFD``, indicating the + type of I/O stream desired: ``PR_StandardInput``, + ``PR_StandardOutput``, or ``PR_StandardError``. + + +Returns +~~~~~~~ + +If the ``id`` parameter is valid, :ref:`PR_GetSpecialFD` returns a file +descriptor that represents the corresponding standard I/O stream. +Otherwise, :ref:`PR_GetSpecialFD` returns ``NULL`` and sets the error to +``PR_INVALID_ARGUMENT_ERROR``. + + +Description +----------- + +Type ``PRSpecialFD`` is defined as follows: + +.. code:: + + typedef enum PRSpecialFD{ + PR_StandardInput, + PR_StandardOutput, + PR_StandardError + } PRSpecialFD; + +``#define PR_STDIN PR_GetSpecialFD(PR_StandardInput)`` +``#define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput)`` +``#define PR_STDERR PR_GetSpecialFD(PR_StandardError)`` + +File descriptors returned by :ref:`PR_GetSpecialFD` are owned by the +runtime and should not be closed by the caller. diff --git a/docs/nspr/reference/pr_getthreadpriority.rst b/docs/nspr/reference/pr_getthreadpriority.rst new file mode 100644 index 0000000000..ff678c9938 --- /dev/null +++ b/docs/nspr/reference/pr_getthreadpriority.rst @@ -0,0 +1,23 @@ +PR_GetThreadPriority +==================== + +Returns the priority of a specified thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRThreadPriority PR_GetThreadPriority(PRThread *thread); + + +Parameter +~~~~~~~~~ + +:ref:`PR_GetThreadPriority` has the following parameter: + +``thread`` + A valid identifier for the thread whose priority you want to know. diff --git a/docs/nspr/reference/pr_getthreadprivate.rst b/docs/nspr/reference/pr_getthreadprivate.rst new file mode 100644 index 0000000000..7303eae93b --- /dev/null +++ b/docs/nspr/reference/pr_getthreadprivate.rst @@ -0,0 +1,38 @@ +PR_GetThreadPrivate +=================== + +Recovers the per-thread private data for the current thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + void* PR_GetThreadPrivate(PRUintn index); + + +Parameter +~~~~~~~~~ + +:ref:`PR_GetThreadPrivate` has the following parameters: + +``index`` + The index into the per-thread private data table. + + +Returns +~~~~~~~ + +``NULL`` if the data has not been set. + + +Description +----------- + +:ref:`PR_GetThreadPrivate` may be called at any time during a thread's +execution. A thread can get access only to its own per-thread private +data. Do not delete the object that the private data refers to without +first clearing the thread's value. diff --git a/docs/nspr/reference/pr_getthreadscope.rst b/docs/nspr/reference/pr_getthreadscope.rst new file mode 100644 index 0000000000..32899683d9 --- /dev/null +++ b/docs/nspr/reference/pr_getthreadscope.rst @@ -0,0 +1,21 @@ +PR_GetThreadScope +================= + +Gets the scoping of the current thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRThreadScope PR_GetThreadScope(void); + + +Returns +~~~~~~~ + +A value of type :ref:`PRThreadScope` indicating whether the thread is local +or global. diff --git a/docs/nspr/reference/pr_getuniqueidentity.rst b/docs/nspr/reference/pr_getuniqueidentity.rst new file mode 100644 index 0000000000..a0b49ac66f --- /dev/null +++ b/docs/nspr/reference/pr_getuniqueidentity.rst @@ -0,0 +1,49 @@ +PR_GetUniqueIdentity +==================== + +Asks the runtime to allocate a unique identity for a layer identified by +the layer's name. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRDescIdentity PR_GetUniqueIdentity(const char *layer_name); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``layer_name`` + The string associated with the creation of a layer's identity. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, the :ref:`PRDescIdentity` for the layer associated with + the string specified in the layer named ``layer_name``. +- If the function cannot allocate enough dynamic memory, it fails and + returns the value ``PR_INVALID_IO_LAYER`` with the error code + ``PR_OUT_OF_MEMORY_ERROR``. + + +Description +----------- + +A string may be associated with a layer when the layer is created. +:ref:`PR_GetUniqueIdentity` allocates a unique layer identity and +associates it with the string. The string can be subsequently passed to +:ref:`PR_CreateIOLayerStub` to create a new file descriptor of that layer. + +Call :ref:`PR_GetUniqueIdentity` only once for any particular layer name. +If you're creating a custom I/O layer, cache the result, and then use +that cached result every time you call :ref:`PR_CreateIOLayerStub`. diff --git a/docs/nspr/reference/pr_gmtparameters.rst b/docs/nspr/reference/pr_gmtparameters.rst new file mode 100644 index 0000000000..d9abb9c0b6 --- /dev/null +++ b/docs/nspr/reference/pr_gmtparameters.rst @@ -0,0 +1,47 @@ +PR_GMTParameters +================ + +Returns the time zone offset information that maps the specified +:ref:`PRExplodedTime` to GMT. + +.. note:: + + **Note:** Since this function requires GMT as input, its primary use + is as "filler" for cases in which you need a do-nothing callback. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + PRTimeParameters PR_GMTParameters ( + const PRExplodedTime *gmt); + + +Parameter +~~~~~~~~~ + +``gmt`` + A pointer to the clock/calendar time whose offsets are to be + determined. This time should be specified in GMT. + + +Returns +~~~~~~~ + +A time parameters structure that expresses the time zone offsets at the +specified time. + + +Description +----------- + +This is a frequently-used time parameter callback function. You don't +normally call it directly; instead, you pass it as a parameter to +``PR_ExplodeTime()`` or ``PR_NormalizeTime()``. + +This is a trivial function; for any input, it returns a +:ref:`PRTimeParameters` structure with both fields set to zero. diff --git a/docs/nspr/reference/pr_htonl.rst b/docs/nspr/reference/pr_htonl.rst new file mode 100644 index 0000000000..094c59ced8 --- /dev/null +++ b/docs/nspr/reference/pr_htonl.rst @@ -0,0 +1,29 @@ +PR_htonl +======== + +Performs 32-bit conversion from host byte order to network byte order. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRUint32 PR_htonl(PRUint32 conversion); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``conversion`` + The 32-bit unsigned integer, in host byte order, to be converted. + + +Returns +~~~~~~~ + +The value of the ``conversion`` parameter in network byte order. diff --git a/docs/nspr/reference/pr_htons.rst b/docs/nspr/reference/pr_htons.rst new file mode 100644 index 0000000000..1e5b845ca9 --- /dev/null +++ b/docs/nspr/reference/pr_htons.rst @@ -0,0 +1,29 @@ +PR_htons +======== + +Performs 16-bit conversion from host byte order to network byte order. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRUint16 PR_htons(PRUint16 conversion); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``conversion`` + The 16-bit unsigned integer, in host byte order, to be converted. + + +Returns +~~~~~~~ + +The value of the ``conversion`` parameter in network byte order. diff --git a/docs/nspr/reference/pr_implement.rst b/docs/nspr/reference/pr_implement.rst new file mode 100644 index 0000000000..583716a15b --- /dev/null +++ b/docs/nspr/reference/pr_implement.rst @@ -0,0 +1,28 @@ +PR_IMPLEMENT +============ + +Used to define implementations of symbols that are to be exported from a +shared library. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + PR_IMPLEMENT(type)implementation + + +Description +----------- + +:ref:`PR_IMPLEMENT` is used to define implementations of externally visible +routines and globals. For syntax details for each platform, see +`prtypes.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtypes.h>`__. + +.. warning:: + + **Warning**: Some platforms do not allow the use of the underscore + character (_) as the first character of an exported symbol. diff --git a/docs/nspr/reference/pr_implodetime.rst b/docs/nspr/reference/pr_implodetime.rst new file mode 100644 index 0000000000..1426d57a79 --- /dev/null +++ b/docs/nspr/reference/pr_implodetime.rst @@ -0,0 +1,36 @@ +PR_ImplodeTime +============== + +Converts a clock/calendar time to an absolute time. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + PRTime PR_ImplodeTime(const PRExplodedTime *exploded); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``exploded`` + A pointer to the clock/calendar time to be converted. + + +Returns +~~~~~~~ + +An absolute time value. + + +Description +----------- + +This function converts the specified clock/calendar time to an absolute +time and returns the converted time value. diff --git a/docs/nspr/reference/pr_importfilemapfromstring.rst b/docs/nspr/reference/pr_importfilemapfromstring.rst new file mode 100644 index 0000000000..bc9694d557 --- /dev/null +++ b/docs/nspr/reference/pr_importfilemapfromstring.rst @@ -0,0 +1,39 @@ +PR_ImportFileMapFromString +========================== + +Creates a :ref:`PRFileMap` from an identifying string. + + +Syntax +~~~~~~ + +.. code:: + + #include <prshma.h> + + NSPR_API( PRFileMap * ) + PR_ImportFileMapFromString( + const char *fmstring + ); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +fmstring + A pointer to string created by :ref:`PR_ExportFileMapAsString`. + + +Returns +~~~~~~~ + +:ref:`PRFileMap` pointer or ``NULL`` on error. + + +Description +----------- + +:ref:`PR_ImportFileMapFromString` creates a :ref:`PRFileMap` object from a +string previously created by :ref:`PR_ExportFileMapAsString`. diff --git a/docs/nspr/reference/pr_importtcpsocket.rst b/docs/nspr/reference/pr_importtcpsocket.rst new file mode 100644 index 0000000000..4722744b3d --- /dev/null +++ b/docs/nspr/reference/pr_importtcpsocket.rst @@ -0,0 +1,70 @@ +PR_ImportTCPSocket +================== + +Imports a native TCP socket into NSPR. + + +Syntax +------ + +.. code:: + + #include "private/pprio.h" + + PRFileDesc* PR_ImportTCPSocket(PROsfd osfd); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``osfd`` + The native file descriptor for the TCP socket to import. On POSIX + systems, this is an ``int``. On Windows, this is a ``SOCKET``. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion, a pointer to the :ref:`PRFileDesc` object + created for the newly imported native TCP socket. +- If the import of the native TCP socket failed, ``NULL``. + + +Description +----------- + +A native TCP socket ``osfd`` can be imported into NSPR with +:ref:`PR_ImportTCPSocket`. The caller gives up control of the native TCP +socket ``osfd`` and should use the ``PRFileDesc*`` returned by +:ref:`PR_ImportTCPSocket` instead. + +Although :ref:`PR_ImportTCPSocket` is a supported function, it is declared +in ``"private/pprio.h"`` to stress the fact that this function depends +on the internals of the NSPR implementation. The caller needs to +understand what NSPR will do to the native file descriptor and make sure +that NSPR can use the native file descriptor successfully. + +For example, on POSIX systems, NSPR will put the native file descriptor +(an ``int``) in non-blocking mode by calling ``fcntl`` to set the +``O_NONBLOCK`` file status flag on the native file descriptor, and then +NSPR will call socket functions such as ``recv``, ``send``, and ``poll`` +on the native file descriptor. The caller must not do anything to the +native file descriptor before the :ref:`PR_ImportTCPSocket` call that will +prevent the native file descriptor from working in non-blocking mode. + +Warning +------- + +In theory, code that uses :ref:`PR_ImportTCPSocket` may break when NSPR's +implementation changes. In practice, this is unlikely to happen because +NSPR's implementation has been stable for years and because of NSPR's +strong commitment to backward compatibility. Using +:ref:`PR_ImportTCPSocket` is much more convenient than writing an NSPR I/O +layer that wraps your native TCP sockets. Of course, it is best if you +just use :ref:`PR_OpenTCPSocket` or :ref:`PR_NewTCPSocket`. If you are not +sure whether :ref:`PR_ImportTCPSocket` is right for you, please ask in the +mozilla.dev.tech.nspr newsgroup. diff --git a/docs/nspr/reference/pr_init.rst b/docs/nspr/reference/pr_init.rst new file mode 100644 index 0000000000..c047b2ed2d --- /dev/null +++ b/docs/nspr/reference/pr_init.rst @@ -0,0 +1,44 @@ +PR_Init +======= + +Initializes the runtime. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_Init( + PRThreadType type, + PRThreadPriority priority, + PRUintn maxPTDs); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_Init` has the following parameters: + +``type`` + This parameter is ignored. +``priority`` + This parameter is ignored. +``maxPTDs`` + This parameter is ignored. + + +Description +----------- + +NSPR is now implicitly initialized, usually by the first NSPR function +called by a program. :ref:`PR_Init` is necessary only if a program has +specific initialization-sequencing requirements. + +Call :ref:`PR_Init` as follows: + +.. code:: + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); diff --git a/docs/nspr/reference/pr_init_clist.rst b/docs/nspr/reference/pr_init_clist.rst new file mode 100644 index 0000000000..d6d57afade --- /dev/null +++ b/docs/nspr/reference/pr_init_clist.rst @@ -0,0 +1,27 @@ +PR_INIT_CLIST +============= + +Initializes a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_INIT_CLIST (PRCList *listp); + + +Parameter +~~~~~~~~~ + +``listp`` + A pointer to the anchor of the linked list. + + +Description +----------- + +Initializes the specified list to be an empty list. diff --git a/docs/nspr/reference/pr_init_static_clist.rst b/docs/nspr/reference/pr_init_static_clist.rst new file mode 100644 index 0000000000..b837694efd --- /dev/null +++ b/docs/nspr/reference/pr_init_static_clist.rst @@ -0,0 +1,32 @@ +PR_INIT_STATIC_CLIST +==================== + +Statically initializes a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_INIT_STATIC_CLIST (PRCList *listp); + + +Parameter +~~~~~~~~~ + +``listp`` + A pointer to the anchor of the linked list. + + +Description +----------- + +PR_INIT_STATIC_CLIST statically initializes the specified list to be an +empty list. For example, + +:: + + PRCList free_object_list = PR_INIT_STATIC_CLIST(&free_object_list); diff --git a/docs/nspr/reference/pr_initialize.rst b/docs/nspr/reference/pr_initialize.rst new file mode 100644 index 0000000000..027f040a79 --- /dev/null +++ b/docs/nspr/reference/pr_initialize.rst @@ -0,0 +1,63 @@ +PR_Initialize +============= + +Provides an alternate form of explicit initialization. In addition to +establishing the sequence of operations, :ref:`PR_Initialize` implicitly +calls :ref:`PR_Cleanup` on exiting the primordial function. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + PRIntn PR_Initialize( + PRPrimordialFn prmain, + PRIntn argc, + char **argv, + PRUintn maxPTDs); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_Initialize` has the following parameters: + +``prmain`` + The function that becomes the primordial thread's root function. + Returning from prmain leads to termination of the process. +``argc`` + The length of the argument vector, whether passed in from the host's + program-launching facility or fabricated by the actual main program. + This approach conforms to standard C programming practice. +``argv`` + The base address of an array of strings that compromise the program's + argument vector. This approach conforms to standard C programming + practice. +``maxPTDs`` + This parameter is ignored. + + +Returns +~~~~~~~ + +The value returned from the root function, ``prmain``. + + +Description +----------- + +:ref:`PR_Initialize` initializes the NSPR runtime and places NSPR between +the caller and the runtime library. This allows ``main`` to be treated +like any other function, signaling its completion by returning and +allowing the runtime to coordinate the completion of the other threads +of the runtime. + +:ref:`PR_Initialize` does not return to its caller until all user threads +have terminated. + +The priority of the main (or primordial) thread is +``PR_PRIORITY_NORMAL``. The thread may adjust its own priority by using +:ref:`PR_SetThreadPriority`. diff --git a/docs/nspr/reference/pr_initialized.rst b/docs/nspr/reference/pr_initialized.rst new file mode 100644 index 0000000000..c5323637b1 --- /dev/null +++ b/docs/nspr/reference/pr_initialized.rst @@ -0,0 +1,23 @@ +PR_Initialized +============== + +Checks whether the runtime has been initialized. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + PRBool PR_Initialized(void); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If :ref:`PR_Init` has already been called, ``PR_TRUE``. +- If :ref:`PR_Init` has not already been called, ``PR_FALSE``. 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. diff --git a/docs/nspr/reference/pr_insert_after.rst b/docs/nspr/reference/pr_insert_after.rst new file mode 100644 index 0000000000..b51377e3dc --- /dev/null +++ b/docs/nspr/reference/pr_insert_after.rst @@ -0,0 +1,32 @@ +PR_INSERT_AFTER +=============== + +Inserts an element after another element in a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_INSERT_AFTER ( + PRCList *elemp1 + PRCList *elemp2); + + +Parameters +~~~~~~~~~~ + +``elemp1`` + A pointer to the element to be inserted. +``elemp2`` + A pointer to the element after which ``elemp1`` is to be inserted. + + +Description +----------- + +PR_INSERT_AFTER inserts the element specified by ``elemp1`` into the +circular list, after the element specified by ``elemp2``. diff --git a/docs/nspr/reference/pr_insert_before.rst b/docs/nspr/reference/pr_insert_before.rst new file mode 100644 index 0000000000..6d6bcc8a3c --- /dev/null +++ b/docs/nspr/reference/pr_insert_before.rst @@ -0,0 +1,32 @@ +PR_INSERT_BEFORE +================ + +Inserts an element before another element in a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_INSERT_BEFORE ( + PRCList *elemp1 + PRCList *elemp2); + + +Parameters +~~~~~~~~~~ + +``elemp1`` + A pointer to the element to be inserted. +``elemp2`` + A pointer to the element before which ``elemp1`` is to be inserted. + + +Description +----------- + +PR_INSERT_BEFORE inserts the element specified by ``elemp1`` into the +circular list, before the element specified by ``elemp2``. diff --git a/docs/nspr/reference/pr_insert_link.rst b/docs/nspr/reference/pr_insert_link.rst new file mode 100644 index 0000000000..24a6dd9cfd --- /dev/null +++ b/docs/nspr/reference/pr_insert_link.rst @@ -0,0 +1,32 @@ +PR_INSERT_LINK +============== + +Inserts an element at the head of the list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_INSERT_LINK ( + PRCList *elemp, + PRCList *listp); + + +Parameters +~~~~~~~~~~ + +``elemp`` + A pointer to the element to be inserted. +``listp`` + A pointer to the list. + + +Description +----------- + +PR_INSERT_LINK inserts the specified element at the head of the +specified list. diff --git a/docs/nspr/reference/pr_interrupt.rst b/docs/nspr/reference/pr_interrupt.rst new file mode 100644 index 0000000000..67bf324e96 --- /dev/null +++ b/docs/nspr/reference/pr_interrupt.rst @@ -0,0 +1,71 @@ +PR_Interrupt +============ + +Sets the interrupt request for a target thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRStatus PR_Interrupt(PRThread *thread); + + +Parameter +~~~~~~~~~ + +:ref:`PR_Interrupt` has the following parameter: + +``thread`` + The thread whose interrupt request you want to set. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the specified thread is currently blocked, ``PR_SUCCESS``. +- Otherwise, ``PR_FAILURE``. + + +Description +----------- + +The purpose of :ref:`PR_Interrupt` is to request that a thread performing +some task stop what it is doing and return to some control point. It is +assumed that a control point has been mutually arranged between the +thread doing the interrupting and the thread being interrupted. When the +interrupted thread reaches the prearranged point, it can communicate +with its peer to discover the real reason behind the change in plans. + +The interrupt request remains in the thread's state until it is +delivered exactly once or explicitly canceled. The interrupted thread +returns ``PR_FAILURE`` (-1) with an error code (see :ref:`PR_GetError`) for +blocking operations that return a :ref:`PRStatus` (such as I/O operations, +monitor waits, or waiting on a condition). To check whether the thread +was interrupted, compare the result of :ref:`PR_GetError` with +``PR_PENDING_INTERRUPT_ERROR``. + +:ref:`PR_Interrupt` may itself fail if the target thread is invalid. + +Bugs +---- + +:ref:`PR_Interrupt` has the following limitations and known bugs: + +- There can be a delay for a thread to be interrupted from a blocking + I/O function. In all NSPR implementations, the maximum delay is at + most five seconds. In the pthreads-based implementation on Unix, the + maximum delay is 0.1 seconds. +- File I/O is considered instantaneous, so file I/O functions cannot be + interrupted. Unfortunately the standard input, output, and error + streams are treated as files by NSPR, so a :ref:`PR_Read` call on + ``PR_STDIN`` cannot be interrupted even though it may block + indefinitely. +- In the NT implementation, :ref:`PR_Connect` cannot be interrupted. +- In the NT implementation, a file descriptor is not usable and must be + closed after an I/O function on the file descriptor is interrupted. diff --git a/docs/nspr/reference/pr_intervalnow.rst b/docs/nspr/reference/pr_intervalnow.rst new file mode 100644 index 0000000000..360dd6455a --- /dev/null +++ b/docs/nspr/reference/pr_intervalnow.rst @@ -0,0 +1,50 @@ +PR_IntervalNow +============== + +Returns the value of NSPR's free-running interval timer. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRIntervalTime PR_IntervalNow(void); + + +Returns +~~~~~~~ + +A :ref:`PRIntervalTime` object. + + +Description +----------- + +You can use the value returned by ``PR_IntervalNow()`` to establish +epochs and to determine intervals (that is, compute the difference +between two times). ``PR_IntervalNow()`` is both very efficient and +nonblocking, so it is appropriate to use (for example) while holding a +mutex. + +The most common use for ``PR_IntervalNow()`` is to establish an epoch +and test for the expiration of intervals. In this case, you typically +call ``PR_IntervalNow()`` in a sequence that looks like this: + +.. code:: + + PRUint32 interval = ... ; // milliseconds + // ... + PRStatus rv; + PRIntervalTime epoch = PR_IntervalNow(); + PR_Lock(data->mutex); + while (!EvaluateData(data)) /* wait until condition is met */ + { + PRUint32 delta = PR_IntervalToMilliseconds(PR_IntervalNow() - epoch); + if (delta > interval) break; /* timeout */ + rv = PR_Wait(data->condition, PR_MillisecondsToInterval(interval - delta)); + if (PR_FAILURE == rv) break; /* likely an interrupt */ + } + PR_Unlock(data->mutex); diff --git a/docs/nspr/reference/pr_intervaltomicroseconds.rst b/docs/nspr/reference/pr_intervaltomicroseconds.rst new file mode 100644 index 0000000000..a8e3fec038 --- /dev/null +++ b/docs/nspr/reference/pr_intervaltomicroseconds.rst @@ -0,0 +1,34 @@ +PR_IntervalToMicroseconds +========================= + +Converts platform-dependent intervals to standard clock microseconds. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRUint32 PR_IntervalToMicroseconds(PRIntervalTime ticks); + + +Parameter +~~~~~~~~~ + +``ticks`` + The number of platform-dependent intervals to convert. + + +Returns +~~~~~~~ + +Equivalent in microseconds of the value passed in the ``ticks`` +parameter. + + +Description +----------- + +Conversion may cause overflow, which is not reported. diff --git a/docs/nspr/reference/pr_intervaltomilliseconds.rst b/docs/nspr/reference/pr_intervaltomilliseconds.rst new file mode 100644 index 0000000000..a68c4534bb --- /dev/null +++ b/docs/nspr/reference/pr_intervaltomilliseconds.rst @@ -0,0 +1,34 @@ +PR_IntervalToMilliseconds +========================= + +Converts platform-dependent intervals to standard clock milliseconds. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRUint32 PR_IntervalToMilliseconds(PRIntervalTime ticks); + + +Parameter +~~~~~~~~~ + +``ticks`` + The number of platform-dependent intervals to convert. + + +Returns +~~~~~~~ + +Equivalent in milliseconds of the value passed in the ``ticks`` +parameter. + + +Description +----------- + +Conversion may cause overflow, which is not reported. diff --git a/docs/nspr/reference/pr_intervaltoseconds.rst b/docs/nspr/reference/pr_intervaltoseconds.rst new file mode 100644 index 0000000000..16d77f0ade --- /dev/null +++ b/docs/nspr/reference/pr_intervaltoseconds.rst @@ -0,0 +1,33 @@ +PR_IntervalToSeconds +==================== + +Converts platform-dependent intervals to standard clock seconds. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRUint32 PR_IntervalToSeconds(PRIntervalTime ticks); + + +Parameter +~~~~~~~~~ + +``ticks`` + The number of platform-dependent intervals to convert. + + +Returns +~~~~~~~ + +Equivalent in seconds of the value passed in the ``ticks`` parameter. + + +Description +----------- + +Conversion may cause overflow, which is not reported. diff --git a/docs/nspr/reference/pr_joinjob.rst b/docs/nspr/reference/pr_joinjob.rst new file mode 100644 index 0000000000..1153cd9dcf --- /dev/null +++ b/docs/nspr/reference/pr_joinjob.rst @@ -0,0 +1,30 @@ +PR_JoinJob +========== + +Blocks the current thread until a job has completed. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRStatus) PR_JoinJob(PRJob *job); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``job`` + A pointer to a :ref:`PRJob` structure returned by a :ref:`PR_QueueJob` + function representing the job to be cancelled. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_jointhread.rst b/docs/nspr/reference/pr_jointhread.rst new file mode 100644 index 0000000000..a1bfddf81c --- /dev/null +++ b/docs/nspr/reference/pr_jointhread.rst @@ -0,0 +1,57 @@ +PR_JoinThread +============= + +Blocks the calling thread until a specified thread terminates. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRStatus PR_JoinThread(PRThread *thread); + + +Parameter +~~~~~~~~~ + +:ref:`PR_JoinThread` has the following parameter: + +``thread`` + A valid identifier for the thread that is to be joined. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS`` +- If unsuccessful--for example, if no joinable thread can be found that + corresponds to the specified target thread, or if the target thread + is unjoinable--``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_JoinThread` is used to synchronize the termination of a thread. +The function is synchronous in that it blocks the calling thread until +the target thread is in a joinable state. :ref:`PR_JoinThread` returns to +the caller only after the target thread returns from its root function. + +:ref:`PR_JoinThread` must not be called until after :ref:`PR_CreateThread` has +returned. If :ref:`PR_JoinThread` is not called on the same thread as +:ref:`PR_CreateThread`, then it is the caller's responsibility to ensure +that :ref:`PR_CreateThread` has completed. + +Several threads cannot wait for the same thread to complete. One of the +calling threads operates successfully, and the others terminate with the +error ``PR_FAILURE``. + +The calling thread is not blocked if the target thread has already +terminated. + +:ref:`PR_JoinThread` is interruptible. diff --git a/docs/nspr/reference/pr_jointhreadpool.rst b/docs/nspr/reference/pr_jointhreadpool.rst new file mode 100644 index 0000000000..86d8ecf822 --- /dev/null +++ b/docs/nspr/reference/pr_jointhreadpool.rst @@ -0,0 +1,31 @@ +PR_JoinThreadPool +================= + +Waits for all threads in a thread pool to complete, then releases +resources allocated to the thread pool. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRStatus) PR_JoinThreadPool( PRThreadPool *tpool ); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_list_head.rst b/docs/nspr/reference/pr_list_head.rst new file mode 100644 index 0000000000..e930c36295 --- /dev/null +++ b/docs/nspr/reference/pr_list_head.rst @@ -0,0 +1,33 @@ +PR_LIST_HEAD +============ + +Returns the head of a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PRCList *PR_LIST_HEAD (PRCList *listp); + + +Parameter +~~~~~~~~~ + +``listp`` + A pointer to the linked list. + + +Returns +~~~~~~~ + +A pointer to a list element. + + +Description +----------- + +:ref:`PR_LIST_HEAD` returns the head of the specified circular list. diff --git a/docs/nspr/reference/pr_list_tail.rst b/docs/nspr/reference/pr_list_tail.rst new file mode 100644 index 0000000000..87d9126f92 --- /dev/null +++ b/docs/nspr/reference/pr_list_tail.rst @@ -0,0 +1,33 @@ +PR_LIST_TAIL +============ + +Returns the tail of a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PRCList *PR_LIST_TAIL (PRCList *listp); + + +Parameter +~~~~~~~~~ + +``listp`` + A pointer to the linked list. + + +Returns +~~~~~~~ + +A pointer to a list element. + + +Description +----------- + +:ref:`PR_LIST_TAIL` returns the tail of the specified circular list. diff --git a/docs/nspr/reference/pr_listen.rst b/docs/nspr/reference/pr_listen.rst new file mode 100644 index 0000000000..1b1efefc21 --- /dev/null +++ b/docs/nspr/reference/pr_listen.rst @@ -0,0 +1,48 @@ +PR_Listen +========= + +Listens for connections on a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Listen( + PRFileDesc *fd, + PRIntn backlog); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket that will + be used to listen for new connections. +``backlog`` + The maximum length of the queue of pending connections. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion of listen request, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. Further information can be obtained + by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Listen` turns the specified socket into a rendezvous socket. It +creates a queue for pending connections and starts to listen for +connection requests on the socket. The maximum size of the queue for +pending connections is specified by the ``backlog`` parameter. Pending +connections may be accepted by calling :ref:`PR_Accept`. diff --git a/docs/nspr/reference/pr_loadlibrary.rst b/docs/nspr/reference/pr_loadlibrary.rst new file mode 100644 index 0000000000..707973ec51 --- /dev/null +++ b/docs/nspr/reference/pr_loadlibrary.rst @@ -0,0 +1,46 @@ +PR_LoadLibrary +============== + +Loads a referenced library. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + PRLibrary* PR_LoadLibrary(const char *name); + + +Parameters +~~~~~~~~~~ + +The function has this parameter: + +``name`` + A platform-dependent character array that names the library to be + loaded, as returned by :ref:`PR_GetLibraryName`. + + +Returns +~~~~~~~ + +If successful, returns a reference to an opaque :ref:`PRLibrary` object. + +If the operation fails, returns ``NULL``. Use :ref:`PR_GetError` to find +the reason for the failure. + + +Description +----------- + +This function loads and returns a reference to the specified library. +The returned reference becomes the library's identity. The function +suppresses duplicate loading if the library is already known by the +runtime. + +Each call to :ref:`PR_LoadLibrary` must be paired with a corresponding call +to :ref:`PR_UnloadLibrary` in order to return the runtime to its original +state. diff --git a/docs/nspr/reference/pr_localtimeparameters.rst b/docs/nspr/reference/pr_localtimeparameters.rst new file mode 100644 index 0000000000..976db05547 --- /dev/null +++ b/docs/nspr/reference/pr_localtimeparameters.rst @@ -0,0 +1,39 @@ +PR_LocalTimeParameters +====================== + +Returns the time zone offset information that maps the specified +:ref:`PRExplodedTime` to local time. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + PRTimeParameters PR_LocalTimeParameters ( + const PRExplodedTime *gmt); + + +Parameter +~~~~~~~~~ + +``gmt`` + A pointer to the clock/calendar time whose offsets are to be + determined. This time should be specified in GMT. + + +Returns +~~~~~~~ + +A time parameters structure that expresses the time zone offsets at the +specified time. + + +Description +----------- + +This is a frequently-used time parameter callback function. You don't +normally call it directly; instead, you pass it as a parameter to +``PR_ExplodeTime()`` or ``PR_NormalizeTime()``. diff --git a/docs/nspr/reference/pr_lock.rst b/docs/nspr/reference/pr_lock.rst new file mode 100644 index 0000000000..53cb17deea --- /dev/null +++ b/docs/nspr/reference/pr_lock.rst @@ -0,0 +1,42 @@ +PR_Lock +======= + +Locks a specified lock object. + + +Syntax +------ + +.. code:: + + #include <prlock.h> + + void PR_Lock(PRLock *lock); + + +Parameter +~~~~~~~~~ + +:ref:`PR_Lock` has one parameter: + +``lock`` + A pointer to a lock object to be locked. + + +Description +----------- + +When :ref:`PR_Lock` returns, the calling thread is "in the monitor," also +called "holding the monitor's lock." Any thread that attempts to acquire +the same lock blocks until the holder of the lock exits the monitor. +Acquiring the lock is not an interruptible operation, nor is there any +timeout mechanism. + +:ref:`PR_Lock` is not reentrant. Calling it twice on the same thread +results in undefined behavior. + + +See Also +-------- + + - :ref:`PR_Unlock` diff --git a/docs/nspr/reference/pr_malloc.rst b/docs/nspr/reference/pr_malloc.rst new file mode 100644 index 0000000000..d475ab6a4b --- /dev/null +++ b/docs/nspr/reference/pr_malloc.rst @@ -0,0 +1,35 @@ +PR_MALLOC +========= + +Allocates memory of a specified size from the heap. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + void * PR_MALLOC(_bytes); + + +Parameter +~~~~~~~~~ + +``_bytes`` + Size of the requested memory block. + + +Returns +~~~~~~~ + +An untyped pointer to the allocated memory, or if the allocation attempt +fails, ``NULL``. Call ``PR_GetError()`` to retrieve the error returned +by the libc function ``malloc()``. + + +Description +----------- + +This macro allocates memory of the requested size from the heap. diff --git a/docs/nspr/reference/pr_memmap.rst b/docs/nspr/reference/pr_memmap.rst new file mode 100644 index 0000000000..6b37fe313a --- /dev/null +++ b/docs/nspr/reference/pr_memmap.rst @@ -0,0 +1,50 @@ +PR_MemMap +========= + +Maps a section of a file to memory. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + void* PR_MemMap( + PRFileMap *fmap, + PRInt64 offset, + PRUint32 len); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fmap`` + A pointer to the file-mapping object representing the file to be + memory-mapped. +``offset`` + The starting offset of the section of file to be mapped. The offset + must be aligned to whole pages. +``len`` + Length of the section of the file to be mapped. + + +Returns +~~~~~~~ + +The starting address of the memory region to which the section of file +is mapped. Returns ``NULL`` on error. + + +Description +----------- + +:ref:`PR_MemMap` maps a section of the file represented by the file mapping +``fmap`` to memory. The section of the file starts at ``offset`` and has +the length ``len``. + +When the file-mapping memory region is no longer needed, it should be +unmapped with a call to :ref:`PR_MemUnmap`. diff --git a/docs/nspr/reference/pr_microsecondstointerval.rst b/docs/nspr/reference/pr_microsecondstointerval.rst new file mode 100644 index 0000000000..9771809bb8 --- /dev/null +++ b/docs/nspr/reference/pr_microsecondstointerval.rst @@ -0,0 +1,30 @@ +PR_MicrosecondsToInterval +========================= + +Converts standard clock microseconds to platform-dependent intervals. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRIntervalTime PR_MicrosecondsToInterval(PRUint32 milli); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``micro`` + The number of microseconds to convert to interval form. + + +Returns +~~~~~~~ + +Platform-dependent equivalent of the value passed in the ``micro`` +parameter. diff --git a/docs/nspr/reference/pr_millisecondstointerval.rst b/docs/nspr/reference/pr_millisecondstointerval.rst new file mode 100644 index 0000000000..b456b0096d --- /dev/null +++ b/docs/nspr/reference/pr_millisecondstointerval.rst @@ -0,0 +1,30 @@ +PR_MillisecondsToInterval +========================= + +Converts standard clock milliseconds to platform-dependent intervals. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRIntervalTime PR_MillisecondsToInterval(PRUint32 milli); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``milli`` + The number of milliseconds to convert to interval form. + + +Returns +~~~~~~~ + +Platform-dependent equivalent of the value passed in the ``milli`` +parameter. diff --git a/docs/nspr/reference/pr_mkdir.rst b/docs/nspr/reference/pr_mkdir.rst new file mode 100644 index 0000000000..6d1a629f9a --- /dev/null +++ b/docs/nspr/reference/pr_mkdir.rst @@ -0,0 +1,67 @@ +PR_MkDir +======== + +Creates a directory with a specified name and access mode. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_MkDir( + const char *name, + PRIntn mode); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``name`` + The name of the directory to be created. All the path components up + to but not including the leaf component must already exist. +``mode`` + The access permission bits of the file mode of the new directory if + the file is created when ``PR_CREATE_FILE`` is on. + +Caveat: The mode parameter is currently applicable only on Unix +platforms. It may be applicable to other platforms in the future. + +Possible values include the following: + + - :ref:`00400`. Read by owner. + - :ref:`00200`. Write by owner. + - :ref:`00100`. Search by owner. + - :ref:`00040`. Read by group. + - :ref:`00020`. Write by group. + - :ref:`00010`. Search by group. + - :ref:`00004`. Read by others. + - :ref:`00002`. Write by others. + - :ref:`00001`. Search by others. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The actual reason can be retrieved + via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_MkDir` creates a new directory with the pathname ``name``. All the +path components up to but not including the leaf component must already +exist. For example, if the pathname of the directory to be created is +``a/b/c/d``, the directory ``a/b/c`` must already exist. + + +See Also +-------- + +:ref:`PR_RmDir` diff --git a/docs/nspr/reference/pr_msec_per_sec.rst b/docs/nspr/reference/pr_msec_per_sec.rst new file mode 100644 index 0000000000..86cabb124a --- /dev/null +++ b/docs/nspr/reference/pr_msec_per_sec.rst @@ -0,0 +1,16 @@ +PR_MSEC_PER_SEC +=============== + +A convenience macro to improve code readability as well as to avoid +mistakes in counting the number of zeros; represents the number of +milliseconds in a second. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + #define PR_MSEC_PER_SEC 1000UL diff --git a/docs/nspr/reference/pr_name.rst b/docs/nspr/reference/pr_name.rst new file mode 100644 index 0000000000..cddb792155 --- /dev/null +++ b/docs/nspr/reference/pr_name.rst @@ -0,0 +1,18 @@ +PR_NAME +======= + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + #define PR_NAME "NSPR" + + +Description +----------- + +NSPR Name. diff --git a/docs/nspr/reference/pr_netaddrtostring.rst b/docs/nspr/reference/pr_netaddrtostring.rst new file mode 100644 index 0000000000..d21f4d5ecc --- /dev/null +++ b/docs/nspr/reference/pr_netaddrtostring.rst @@ -0,0 +1,50 @@ +PR_NetAddrToString +================== + +Converts a character string to a network address. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRStatus PR_NetAddrToString( + const PRNetAddr *addr, + char *string, + PRUint32 size); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``addr`` + A pointer to the network address to be converted. +``string`` + A buffer that will hold the converted string on output. +``size`` + The size of the result buffer (``string``). + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. + + +Description +----------- + +The network address to be converted (``addr``) may be either an IPv4 or +IPv6 address structure, assuming that the NSPR library and the host +system are both configured to utilize IPv6 addressing. If ``addr`` is an +IPv4 address, ``size`` needs to be at least 16. If ``addr`` is an IPv6 +address, ``size`` needs to be at least 46. diff --git a/docs/nspr/reference/pr_netdb_buf_size.rst b/docs/nspr/reference/pr_netdb_buf_size.rst new file mode 100644 index 0000000000..6c5c79d560 --- /dev/null +++ b/docs/nspr/reference/pr_netdb_buf_size.rst @@ -0,0 +1,20 @@ +PR_NETDB_BUF_SIZE +================= + +Recommended size to use when specifying a scratch buffer for +:ref:`PR_GetHostByName`, :ref:`PR_GetHostByAddr`, :ref:`PR_GetProtoByName`, or +:ref:`PR_GetProtoByNumber`. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + #if defined(AIX) || defined(OSF1) + #define PR_NETDB_BUF_SIZE sizeof(struct protoent_data) + #else + #define PR_NETDB_BUF_SIZE 1024 + #endif diff --git a/docs/nspr/reference/pr_new.rst b/docs/nspr/reference/pr_new.rst new file mode 100644 index 0000000000..0fd9973419 --- /dev/null +++ b/docs/nspr/reference/pr_new.rst @@ -0,0 +1,36 @@ +PR_NEW +====== + +Allocates memory of a specified size from the heap. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + _type * PR_NEW(_struct); + + +Parameter +~~~~~~~~~ + +``_struct`` + The name of a type. + + +Returns +~~~~~~~ + +An pointer to a buffer sized to contain the type ``_struct``, or if the +allocation attempt fails, ``NULL``. Call ``PR_GetError()`` to retrieve +the error returned by the libc function. + + +Description +----------- + +This macro allocates memory whose size is ``sizeof(_struct)`` and +returns a pointer to that memory. diff --git a/docs/nspr/reference/pr_newcondvar.rst b/docs/nspr/reference/pr_newcondvar.rst new file mode 100644 index 0000000000..1ce70e8fe5 --- /dev/null +++ b/docs/nspr/reference/pr_newcondvar.rst @@ -0,0 +1,34 @@ +PR_NewCondVar +============= + +Creates a new condition variable. + + +Syntax +------ + +.. code:: + + #include <prcvar.h> + + PRCondVar* PR_NewCondVar(PRLock *lock); + + +Parameter +~~~~~~~~~ + +:ref:`PR_NewCondVar` has one parameter: + +``lock`` + The identity of the mutex that protects the monitored data, including + this condition variable. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, a pointer to the new condition variable object. +- If unsuccessful (for example, if system resources are unavailable), + ``NULL``. diff --git a/docs/nspr/reference/pr_newlock.rst b/docs/nspr/reference/pr_newlock.rst new file mode 100644 index 0000000000..7fbc51348e --- /dev/null +++ b/docs/nspr/reference/pr_newlock.rst @@ -0,0 +1,30 @@ +PR_NewLock +========== + +Creates a new lock. + + +Syntax +------ + +.. code:: + + #include <prlock.h> + + PRLock* PR_NewLock(void); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, a pointer to the new lock object. +- If unsuccessful (for example, the lock cannot be created because of + resource constraints), ``NULL``. + + +Description +----------- + +:ref:`PR_NewLock` creates a new opaque lock. diff --git a/docs/nspr/reference/pr_newmonitor.rst b/docs/nspr/reference/pr_newmonitor.rst new file mode 100644 index 0000000000..3f80340c77 --- /dev/null +++ b/docs/nspr/reference/pr_newmonitor.rst @@ -0,0 +1,31 @@ +PR_NewMonitor +============= + +Creates a new monitor object. The caller is responsible for the object +and is expected to destroy it when appropriate. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + PRMonitor* PR_NewMonitor(void); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, a pointer to a :ref:`PRMonitor` object. +- If unsuccessful (for example, if some operating system resource is + unavailable), ``NULL``. + + +Description +----------- + +A newly created monitor has an entry count of zero. diff --git a/docs/nspr/reference/pr_newpollableevent.rst b/docs/nspr/reference/pr_newpollableevent.rst new file mode 100644 index 0000000000..be4e0f9bd8 --- /dev/null +++ b/docs/nspr/reference/pr_newpollableevent.rst @@ -0,0 +1,24 @@ +PR_NewPollableEvent +=================== + +Create a pollable event file descriptor. + + +Syntax +------ + +.. code:: + + NSPR_API(PRFileDesc *) PR_NewPollableEvent( void); + + +Parameter +~~~~~~~~~ + +None. + + +Returns +~~~~~~~ + +Pointer to :ref:`PRFileDesc` or ``NULL``, on error. diff --git a/docs/nspr/reference/pr_newprocessattr.rst b/docs/nspr/reference/pr_newprocessattr.rst new file mode 100644 index 0000000000..a01e55498f --- /dev/null +++ b/docs/nspr/reference/pr_newprocessattr.rst @@ -0,0 +1,39 @@ +PR_NewProcessAttr +================= + +Creates a process attributes structure. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + PRProcessAttr *PR_NewProcessAttr(void); + + +Parameters +~~~~~~~~~~ + +The function has no parameters. + + +Returns +~~~~~~~ + +A pointer to the new process attributes structure. + + +Description +----------- + +This function creates a new :ref:`PRProcessAttr`\ structure that specifies +the attributes of a new process, then returns a pointer to the +structure. The new :ref:`PRProcessAttr`\ structure is initialized with +these default attributes: + +- The standard I/O streams (standard input, standard output, and + standard error) are not redirected. +- No file descriptors are inherited by the new process. diff --git a/docs/nspr/reference/pr_newtcpsocket.rst b/docs/nspr/reference/pr_newtcpsocket.rst new file mode 100644 index 0000000000..4a6b285669 --- /dev/null +++ b/docs/nspr/reference/pr_newtcpsocket.rst @@ -0,0 +1,56 @@ +PR_NewTCPSocket +=============== + +Creates a new IPv4 TCP socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_NewTCPSocket(void); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion, a pointer to the :ref:`PRFileDesc` object + created for the newly opened IPv4 TCP socket. +- If the creation of a new TCP socket failed, ``NULL``. + + +Description +----------- + +TCP (Transmission Control Protocol) is a connection-oriented, reliable +byte-stream protocol of the TCP/IP protocol suite. :ref:`PR_NewTCPSocket` +creates a new IPv4 TCP socket. A TCP connection is established by a +passive socket (the server) accepting a connection setup request from an +active socket (the client). Typically, the server binds its socket to a +well-known port with :ref:`PR_Bind`, calls :ref:`PR_Listen` to start listening +for connection setup requests, and calls :ref:`PR_Accept` to accept a +connection. The client makes a connection request using :ref:`PR_Connect`. + +After a connection is established, the client and server may send and +receive data between each other. To receive data, one can call +:ref:`PR_Read` or :ref:`PR_Recv`. To send data, one can call :ref:`PR_Write`, +:ref:`PR_Writev`, :ref:`PR_Send`, or :ref:`PR_TransmitFile`. :ref:`PR_AcceptRead` is +suitable for use by the server to accept a new client connection and +read the client's first request in one function call. + +A TCP connection can be shut down by :ref:`PR_Shutdown`, and the sockets +should be closed by :ref:`PR_Close`. + + +See Also +-------- + +:ref:`PR_NewTCPSocket` is deprecated because it is hardcoded to create an +IPv4 TCP socket. New code should use :ref:`PR_OpenTCPSocket` instead, which +allows the address family (IPv4 or IPv6) of the new TCP socket to be +specified. diff --git a/docs/nspr/reference/pr_newthreadprivateindex.rst b/docs/nspr/reference/pr_newthreadprivateindex.rst new file mode 100644 index 0000000000..8cb926bbee --- /dev/null +++ b/docs/nspr/reference/pr_newthreadprivateindex.rst @@ -0,0 +1,65 @@ +PR_NewThreadPrivateIndex +======================== + +Returns a new index for a per-thread private data table and optionally +associates a destructor with the data that will be assigned to the +index. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRStatus PR_NewThreadPrivateIndex( + PRUintn *newIndex, + PRThreadPrivateDTOR destructor); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_NewThreadPrivateIndex` has the following parameters: + +``newIndex`` + On output, an index that is valid for all threads in the process. You + use this index with :ref:`PR_SetThreadPrivate` and + :ref:`PR_GetThreadPrivate`. +``destructor`` + Specifies a destructor function :ref:`PRThreadPrivateDTOR` for the + private data associated with the index. This function can be + specified as ``NULL``. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If the total number of indices exceeds 128, ``PR_FAILURE``. + + +Description +----------- + +If :ref:`PR_NewThreadPrivateIndex` is successful, every thread in the same +process is capable of associating private data with the new index. Until +the data for an index is actually set, the value of the private data at +that index is ``NULL``. You pass this index to :ref:`PR_SetThreadPrivate` +and :ref:`PR_GetThreadPrivate` to set and retrieve data associated with the +index. + +When you allocate the index, you may also register a destructor function +of type :ref:`PRThreadPrivateDTOR`. If a destructor function is registered +with a new index, it will be called at one of two times, as long as the +private data is not ``NULL``: + +- when replacement private data is set with :ref:`PR_SetThreadPrivate` +- when a thread exits + +The index maintains independent data values for each binding thread. A +thread can get access only to its own thread-specific data. There is no +way to deallocate a private data index once it is allocated. diff --git a/docs/nspr/reference/pr_newudpsocket.rst b/docs/nspr/reference/pr_newudpsocket.rst new file mode 100644 index 0000000000..67aff3e5d4 --- /dev/null +++ b/docs/nspr/reference/pr_newudpsocket.rst @@ -0,0 +1,46 @@ +PR_NewUDPSocket +=============== + +Creates a new UDP socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_NewUDPSocket(void); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion, a pointer to the :ref:`PRFileDesc` object + created for the newly opened UDP socket. +- If the creation of a new UDP socket failed, ``NULL``. + + +Description +----------- + +UDP (User Datagram Protocol) is a connectionless, unreliable datagram +protocol of the TCP/IP protocol suite. UDP datagrams may be lost or +delivered in duplicates or out of sequence. + +:ref:`PR_NewUDPSocket` creates a new UDP socket. The socket may be bound to +a well-known port number with :ref:`PR_Bind`. Datagrams can be sent with +:ref:`PR_SendTo` and received with :ref:`PR_RecvFrom`. When the socket is no +longer needed, it should be closed with a call to :ref:`PR_Close`. + + +See Also +-------- + +:ref:`PR_NewUDPSocket` is deprecated because it is hardcoded to create an +IPv4 UDP socket. New code should use :ref:`PR_OpenUDPSocket` instead, which +allows the address family (IPv4 or IPv6) of the new UDP socket to be +specified. diff --git a/docs/nspr/reference/pr_newzap.rst b/docs/nspr/reference/pr_newzap.rst new file mode 100644 index 0000000000..55d77885b1 --- /dev/null +++ b/docs/nspr/reference/pr_newzap.rst @@ -0,0 +1,38 @@ +PR_NEWZAP +========= + +Allocates and clears memory from the heap for an instance of a given +type. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + _type * PR_NEWZAP(_struct); + + +Parameter +~~~~~~~~~ + +``_struct`` + The name of a type. + + +Returns +~~~~~~~ + +An pointer to a buffer sized to contain the type ``_struct``, or if the +allocation attempt fails, ``NULL``. The bytes in the buffer are all +initialized to 0. Call ``PR_GetError()`` to retrieve the error returned +by the libc function. + + +Description +----------- + +This macro allocates an instance of the specified type from the heap and +sets the content of that memory to zero. diff --git a/docs/nspr/reference/pr_next_link.rst b/docs/nspr/reference/pr_next_link.rst new file mode 100644 index 0000000000..1a48065e69 --- /dev/null +++ b/docs/nspr/reference/pr_next_link.rst @@ -0,0 +1,35 @@ +PR_NEXT_LINK +============ + +Returns the next element in a list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PRCList *PR_NEXT_LINK (PRCList *elemp); + + +Parameter +~~~~~~~~~ + +``elemp`` + A pointer to the element. + + +Returns +~~~~~~~ + +A pointer to a list element. + + +Description +----------- + +PR_NEXT_LINK returns a pointer to the element following the specified +element. It can be used to traverse a list. The following element is not +removed from the list. diff --git a/docs/nspr/reference/pr_normalizetime.rst b/docs/nspr/reference/pr_normalizetime.rst new file mode 100644 index 0000000000..47a82ae78b --- /dev/null +++ b/docs/nspr/reference/pr_normalizetime.rst @@ -0,0 +1,62 @@ +PR_NormalizeTime +================ + +Adjusts the fields of a clock/calendar time to their proper ranges, +using a callback function. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + void PR_NormalizeTime ( + PRExplodedTime *time, + PRTimeParamFn params); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``time`` + A pointer to a clock/calendar time in the :ref:`PRExplodedTime` format. +``params`` + A time parameter callback function. + + +Returns +~~~~~~~ + +Nothing; the ``time`` parameter is altered by the callback function. + + +Description +----------- + +This function adjusts the fields of the specified time structure using +the specified time parameter callback function, so that they are in the +proper range. + +Call this function in these situations: + +- To normalize a time after performing arithmetic operations directly + on the field values of the calendar time object. For example, if you + have a ``]`` object that represents the date 3 March 1998 and you + want to say "forty days from 3 March 1998", you can simply add 40 to + the ``tm_mday`` field and then call ``PR_NormalizeTime()``. + +- To calculate the optional field values ``tm_wday`` and ``tm_yday``. + For example, suppose you want to compute the day of week for 3 March + 1998. You can set ``tm_mday`` to 3, ``tm_month`` to 2, and + ``tm_year`` to 1998, and all the other fields to 0, then call + ``PR_NormalizeTime()`` with :ref:`PR_GMTParameters`. On return, + ``tm_wday`` (and ``tm_yday``) are set for you. + +- To convert from one time zone to another. For example, if the input + argument time is in time zone A and the input argument ``params`` + represents time zone B, when ``PR_NormalizeTime()`` returns, time + will be in time zone B. diff --git a/docs/nspr/reference/pr_notify.rst b/docs/nspr/reference/pr_notify.rst new file mode 100644 index 0000000000..c34d07f89b --- /dev/null +++ b/docs/nspr/reference/pr_notify.rst @@ -0,0 +1,48 @@ +PR_Notify +========= + +Notifies a monitor that a change in state of the monitored data has +occurred. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + PRStatus PR_Notify(PRMonitor *mon); + + +Parameters +~~~~~~~~~~ + +The function has the following parameter: + +``mon`` + A reference to an existing structure of type :ref:`PRMonitor`. The + monitor object referenced must be one for which the calling thread + currently holds the lock. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. + + +Description +----------- + +Notification of a monitor signals the change of state of some monitored +data. The changing of that data and the notification must all be +performed while in the monitor. When the notification occurs, the +runtime promotes a thread that is waiting on the monitor to a ready +state. If more than one thread is waiting, the selection of which thread +gets promoted cannot be determined in advance. This implies that all +threads waiting on a single monitor must have the same semantics. If no +thread is waiting on the monitor, the notify operation is a no-op. diff --git a/docs/nspr/reference/pr_notifyall.rst b/docs/nspr/reference/pr_notifyall.rst new file mode 100644 index 0000000000..0dd3a62b7e --- /dev/null +++ b/docs/nspr/reference/pr_notifyall.rst @@ -0,0 +1,46 @@ +PR_NotifyAll +============ + +Promotes all threads waiting on a specified monitor to a ready state. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + PRStatus PR_NotifyAll(PRMonitor *mon); + + +Parameters +~~~~~~~~~~ + +The function has the following parameter: + +``mon`` + A reference to an existing structure of type :ref:`PRMonitor`. The + monitor object referenced must be one for which the calling thread + currently holds the lock. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. + + +Description +----------- + +A call to :ref:`PR_NotifyAll` causes all of the threads waiting on the +monitor to be scheduled to be promoted to a ready state. If no threads +are waiting, the operation is no-op. + +:ref:`PR_NotifyAll` should be used with some care. The expense of +scheduling multiple threads increases dramatically as the number of +threads increases. diff --git a/docs/nspr/reference/pr_notifyallcondvar.rst b/docs/nspr/reference/pr_notifyallcondvar.rst new file mode 100644 index 0000000000..aa73167c99 --- /dev/null +++ b/docs/nspr/reference/pr_notifyallcondvar.rst @@ -0,0 +1,35 @@ +PR_NotifyAllCondVar +=================== + +Notifies all of the threads waiting on a specified condition variable. + + +Syntax +------ + +.. code:: + + #include <prcvar.h> + + PRStatus PR_NotifyAllCondVar(PRCondVar *cvar); + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful (for example, if the caller has not locked the lock + associated with the condition variable), ``PR_FAILURE``. + + +Description +----------- + +The calling thread must hold the lock that protects the condition, as +well as the invariants that are tightly bound to the condition. + +A call to :ref:`PR_NotifyAllCondVar` causes all of the threads waiting on +the specified condition variable to be promoted to a ready state. If no +threads are waiting, the operation is no-op. diff --git a/docs/nspr/reference/pr_notifycondvar.rst b/docs/nspr/reference/pr_notifycondvar.rst new file mode 100644 index 0000000000..e7289d9b06 --- /dev/null +++ b/docs/nspr/reference/pr_notifycondvar.rst @@ -0,0 +1,49 @@ +PR_NotifyCondVar +================ + +Notifies a condition variable of a change in its associated monitored +data. + + +Syntax +------ + +.. code:: + + #include <prcvar.h> + + PRStatus PR_NotifyCondVar(PRCondVar *cvar); + + +Parameter +~~~~~~~~~ + +:ref:`PR_NotifyCondVar` has one parameter: + +``cvar`` + The condition variable to notify. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful (for example, if the caller has not locked the lock + associated with the condition variable), ``PR_FAILURE``. + + +Description +----------- + +The calling thread must hold the lock that protects the condition, as +well as the invariants that are tightly bound to the condition. + +Notification of a condition variable signals a change of state in some +monitored data. When the notification occurs, the runtime promotes a +thread that is waiting on the condition variable to a ready state. If +more than one thread is waiting, the selection of which thread gets +promoted cannot be predicted. This implies that all threads waiting on a +single condition variable must have the same semantics. If no thread is +waiting on the condition variable, the notify operation is a no-op. diff --git a/docs/nspr/reference/pr_now.rst b/docs/nspr/reference/pr_now.rst new file mode 100644 index 0000000000..5f5efc0203 --- /dev/null +++ b/docs/nspr/reference/pr_now.rst @@ -0,0 +1,38 @@ +PR_Now +====== + +Returns the current time. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + PRTime PR_Now(void); + + +Parameters +~~~~~~~~~~ + +None. + + +Returns +~~~~~~~ + +The current time as a :ref:`PRTime` value. + + +Description +----------- + +``PR_Now()`` returns the current time as number of microseconds since +the NSPR epoch, which is midnight (00:00:00) 1 January 1970 UTC. + +You cannot assume that the values returned by ``PR_Now()`` are +monotonically increasing because the system clock of the computer may be +reset. To obtain monotonically increasing time stamps suitable for +measuring elapsed time, use ``PR_IntervalNow()``. diff --git a/docs/nspr/reference/pr_nsec_per_msec.rst b/docs/nspr/reference/pr_nsec_per_msec.rst new file mode 100644 index 0000000000..8d471bd300 --- /dev/null +++ b/docs/nspr/reference/pr_nsec_per_msec.rst @@ -0,0 +1,16 @@ +PR_NSEC_PER_MSEC +================ + +A convenience macro to improve code readability as well as to avoid +mistakes in counting the number of zeros; represents the number of +nanoseconds in a millisecond. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + #define PR_NSEC_PER_MSEC 1000000UL diff --git a/docs/nspr/reference/pr_nsec_per_sec.rst b/docs/nspr/reference/pr_nsec_per_sec.rst new file mode 100644 index 0000000000..78ceb7b326 --- /dev/null +++ b/docs/nspr/reference/pr_nsec_per_sec.rst @@ -0,0 +1,16 @@ +PR_NSEC_PER_SEC +=============== + +A convenience macro to improve code readability as well as to avoid +mistakes in counting the number of zeros; represents the number of +nanoseconds in a second. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + #define PR_NSEC_PER_SEC 1000000000UL diff --git a/docs/nspr/reference/pr_ntohl.rst b/docs/nspr/reference/pr_ntohl.rst new file mode 100644 index 0000000000..8c48f88f40 --- /dev/null +++ b/docs/nspr/reference/pr_ntohl.rst @@ -0,0 +1,29 @@ +PR_ntohl +======== + +Performs 32-bit conversion from network byte order to host byte order. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRUint32 PR_ntohl(PRUint32 conversion); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``conversion`` + The 32-bit unsigned integer, in network byte order, to be converted. + + +Returns +~~~~~~~ + +The value of the ``conversion`` parameter in host byte order. diff --git a/docs/nspr/reference/pr_ntohs.rst b/docs/nspr/reference/pr_ntohs.rst new file mode 100644 index 0000000000..a20c9d2851 --- /dev/null +++ b/docs/nspr/reference/pr_ntohs.rst @@ -0,0 +1,29 @@ +PR_ntohs +======== + +Performs 16-bit conversion from network byte order to host byte order. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRUint16 PR_ntohs(PRUint16 conversion); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``conversion`` + The 16-bit unsigned integer, in network byte order, to be converted. + + +Returns +~~~~~~~ + +The value of the ``conversion`` parameter in host byte order. diff --git a/docs/nspr/reference/pr_open.rst b/docs/nspr/reference/pr_open.rst new file mode 100644 index 0000000000..805ca6fa83 --- /dev/null +++ b/docs/nspr/reference/pr_open.rst @@ -0,0 +1,117 @@ +PR_Open +======= + +Opens a file for reading, writing, or both. Also used to create a file. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_Open( + const char *name, + PRIntn flags, + PRIntn mode); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``name`` + The pathname of the file to be opened. +``flags`` + The file status flags define how the file is accessed. It is a + bitwise ``OR`` of the following bit flags. In most cases, only one of + the first three flags may be used. If the ``flags`` parameter does + not include any of the first three flags (``PR_RDONLY``, + ``PR_WRONLY``, or ``PR_RDWR``), the open file can't be read or + written, which is not useful. + +.. note:: + + The constants PR_RDWR and friends are not in any interface + (`bug 433295 <https://bugzilla.mozilla.org/show_bug.cgi?id=433295>`__). + Thus they cannot be used in JavaScript, you have to use the octal + constants (see `File I/O Snippets </en/Code_snippets:File_I/O>`__). + ++--------------------+-------+---------------------------------------+ +| Name | Value | Description | ++====================+=======+=======================================+ +| ``PR_RDONLY`` | 0x01 | Open for reading only. | ++--------------------+-------+---------------------------------------+ +| ``PR_WRONLY`` | 0x02 | Open for writing only. | ++--------------------+-------+---------------------------------------+ +| ``PR_RDWR`` | 0x04 | Open for reading and writing. | ++--------------------+-------+---------------------------------------+ +| ``PR_CREATE_FILE`` | 0x08 | If the file does not exist, the file | +| | | is created. If the file exists, this | +| | | flag has no effect. | ++--------------------+-------+---------------------------------------+ +| ``PR_APPEND`` | 0x10 | The file pointer is set to the end of | +| | | the file prior to each write. | ++--------------------+-------+---------------------------------------+ +| ``PR_TRUNCATE`` | 0x20 | If the file exists, its length is | +| | | truncated to 0. | ++--------------------+-------+---------------------------------------+ +| ``PR_SYNC`` | 0x40 | If set, each write will wait for both | +| | | the file data and file status to be | +| | | physically updated. | ++--------------------+-------+---------------------------------------+ +| ``PR_EXCL`` | 0x80 | With ``PR_CREATE_FILE``, if the file | +| | | does not exist, the file is created. | +| | | If the file already exists, no action | +| | | and NULL is returned. | ++--------------------+-------+---------------------------------------+ + + + +``mode`` + When ``PR_CREATE_FILE`` flag is set and the file is created, these + flags define the access permission bits of the newly created file. + This feature is currently only applicable on Unix platforms. It is + ignored by any other platform but it may apply to other platforms in + the future. Possible values of the ``mode`` parameter are listed in + the table below. + +============ ===== ===================================== +Name Value Description +============ ===== ===================================== +``PR_IRWXU`` 0700 read, write, execute/search by owner. +``PR_IRUSR`` 0400 read permission, owner. +``PR_IWUSR`` 0200 write permission, owner. +``PR_IXUSR`` 0100 execute/search permission, owner. +``PR_IRWXG`` 0070 read, write, execute/search by group +``PR_IRGRP`` 0040 read permission, group +``PR_IWGRP`` 0020 write permission, group +``PR_IXGRP`` 0010 execute/search permission, group +``PR_IRWXO`` 0007 read, write, execute/search by others +``PR_IROTH`` 0004 read permission, others +``PR_IWOTH`` 0002 write permission, others +``PR_IXOTH`` 0001 execute/search permission, others +============ ===== ===================================== + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the file is successfully opened, a pointer to a dynamically + allocated :ref:`PRFileDesc` for the newly opened file. The + :ref:`PRFileDesc` should be freed by calling :ref:`PR_Close`. +- If the file was not opened successfully, a ``NULL`` pointer. + + +Description +----------- + +:ref:`PR_Open` creates a file descriptor (:ref:`PRFileDesc`) for the file with +the pathname ``name`` and sets the file status flags of the file +descriptor according to the value of ``flags``. If a new file is created +as a result of the :ref:`PR_Open` call, its file mode bits are set +according to the ``mode`` parameter. diff --git a/docs/nspr/reference/pr_openanonfilemap.rst b/docs/nspr/reference/pr_openanonfilemap.rst new file mode 100644 index 0000000000..30964c5dd7 --- /dev/null +++ b/docs/nspr/reference/pr_openanonfilemap.rst @@ -0,0 +1,51 @@ +PR_OpenAnonFileMap +================== + +Creates or opens a named semaphore with the specified name + + +Syntax +------ + +.. code:: + + #include <prshma.h> + + NSPR_API( PRFileMap *) + PR_OpenAnonFileMap( + const char *dirName, + PRSize size, + PRFileMapProtect prot + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``dirName`` + A pointer to a directory name that will contain the anonymous file. +``size`` + The size of the shared memory. +``prot`` + How the shared memory is mapped. + + +Returns +~~~~~~~ + +Pointer to :ref:`PRFileMap` or ``NULL`` on error. + + +Description +----------- + +If the shared memory already exists, a handle is returned to that shared +memory object. + +On Unix platforms, :ref:`PR_OpenAnonFileMap` uses ``dirName`` as a +directory name, without the trailing '/', to contain the anonymous file. +A filename is generated for the name. + +On Windows platforms, ``dirName`` is ignored. diff --git a/docs/nspr/reference/pr_opendir.rst b/docs/nspr/reference/pr_opendir.rst new file mode 100644 index 0000000000..9bfe91a6e7 --- /dev/null +++ b/docs/nspr/reference/pr_opendir.rst @@ -0,0 +1,41 @@ +PR_OpenDir +========== + +Opens the directory with the specified pathname. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRDir* PR_OpenDir(const char *name); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``name`` + The pathname of the directory to be opened. + + +Returns +~~~~~~~ + +- If the directory is successfully opened, a :ref:`PRDir` object is + dynamically allocated and the function returns a pointer to it. +- If the directory cannot be opened, the function returns ``NULL``. + + +Description +----------- + +:ref:`PR_OpenDir` opens the directory specified by the pathname ``name`` +and returns a pointer to a directory stream (a :ref:`PRDir` object) that +can be passed to subsequent :ref:`PR_ReadDir` calls to get the directory +entries (files and subdirectories) in the directory. The :ref:`PRDir` +pointer should eventually be closed by a call to :ref:`PR_CloseDir`. diff --git a/docs/nspr/reference/pr_opensemaphore.rst b/docs/nspr/reference/pr_opensemaphore.rst new file mode 100644 index 0000000000..6ac69cbe71 --- /dev/null +++ b/docs/nspr/reference/pr_opensemaphore.rst @@ -0,0 +1,58 @@ +PR_OpenSemaphore +================ + +Creates or opens a named semaphore with the specified name. + + +Syntax +------ + +.. code:: + + #include <pripcsem.h> + + #define PR_SEM_CREATE 0x1 /* create if not exist */ + + #define PR_SEM_EXCL 0x2 /* fail if already exists */ + + NSPR_API(PRSem *) PR_OpenSemaphore( + const char *name, + PRIntn flags, + PRIntn mode, + PRUintn value + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``name`` + The name to be given the semaphore. +``flags`` + How to create or open the semaphore. +``mode`` + Unix style file mode to be used when creating the semaphore. +``value`` + The initial value assigned to the semaphore. + + +Returns +~~~~~~~ + +A pointer to a PRSem structure or ``NULL/code> on error.`` + + +Description +~~~~~~~~~~~ + +If the named semaphore doesn't exist and the ``PR_SEM_CREATE`` flag is +specified, the named semaphore is created. The created semaphore needs +to be removed from the system with a :ref:`PR_DeleteSemaphore` call. + +If ``PR_SEM_CREATE`` is specified, the third argument is the access +permission bits of the new semaphore (same interpretation as the mode +argument to :ref:`PR_Open`) and the fourth argument is the initial value of +the new semaphore. ``If PR_SEM_CREATE`` is not specified, the third and +fourth arguments are ignored. diff --git a/docs/nspr/reference/pr_opensharedmemory.rst b/docs/nspr/reference/pr_opensharedmemory.rst new file mode 100644 index 0000000000..759a81dbf8 --- /dev/null +++ b/docs/nspr/reference/pr_opensharedmemory.rst @@ -0,0 +1,68 @@ +PR_OpenSharedMemory +=================== + +Opens an existing shared memory segment or, if one with the specified +name doesn't exist, creates a new one. + + +Syntax +------ + +.. code:: + + #include <prshm.h> + + NSPR_API( PRSharedMemory * ) + PR_OpenSharedMemory( + const char *name, + PRSize size, + PRIntn flags, + PRIntn mode + ); + + /* Define values for PR_OpenShareMemory(...,create) */ + #define PR_SHM_CREATE 0x1 /* create if not exist */ + #define PR_SHM_EXCL 0x2 /* fail if already exists */ + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +name + The name of the shared memory segment. +size + The size of the shared memory segment. +flags + Options for creating the shared memory. +mode + Same as passed to :ref:`PR_Open`. + + +Returns +~~~~~~~ + +Pointer to opaque structure ``PRSharedMemory``, or ``NULL`` if an error +occurs. Retrieve the reason for the failure by calling :ref:`PR_GetError` +and :ref:`PR_GetOSError`. + + +Description +----------- + +:ref:`PR_OpenSharedMemory` creates a new shared memory segment or +associates a previously created memory segment with the specified name. +When parameter ``create`` is (``PR_SHM_EXCL`` \| ``PR_SHM_CREATE``) and +the shared memory already exists, the function returns ``NULL`` with the +error set to ``PR_FILE_EXISTS_ERROR``. + +When parameter ``create`` is ``PR_SHM_CREATE`` and the shared memory +already exists, a handle to that memory segment is returned. If the +segment does not exist, it is created and a pointer to the related +``PRSharedMemory`` structure is returned. + +When parameter ``create`` is 0, and the shared memory exists, a pointer +to a ``PRSharedMemory`` structure is returned. If the shared memory does +not exist, ``NULL`` is returned with the error set to +``PR_FILE_NOT_FOUND_ERROR``. diff --git a/docs/nspr/reference/pr_opentcpsocket.rst b/docs/nspr/reference/pr_opentcpsocket.rst new file mode 100644 index 0000000000..c9c11799cf --- /dev/null +++ b/docs/nspr/reference/pr_opentcpsocket.rst @@ -0,0 +1,59 @@ +PR_OpenTCPSocket +================ + +Creates a new TCP socket of the specified address family. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_OpenTCPSocket(PRIntn af); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``af`` + The address family of the new TCP socket. Can be ``PR_AF_INET`` + (IPv4), ``PR_AF_INET6`` (IPv6), or ``PR_AF_LOCAL`` (Unix domain, + supported on POSIX systems only). + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion, a pointer to the :ref:`PRFileDesc` object + created for the newly opened TCP socket. +- If the creation of a new TCP socket failed, ``NULL``. + + +Description +----------- + +TCP (Transmission Control Protocol) is a connection-oriented, reliable +byte-stream protocol of the TCP/IP protocol suite. :ref:`PR_OpenTCPSocket` +creates a new TCP socket of the address family ``af``. A TCP connection +is established by a passive socket (the server) accepting a connection +setup request from an active socket (the client). Typically, the server +binds its socket to a well-known port with :ref:`PR_Bind`, calls +:ref:`PR_Listen` to start listening for connection setup requests, and +calls :ref:`PR_Accept` to accept a connection. The client makes a +connection request using :ref:`PR_Connect`. + +After a connection is established, the client and server may send and +receive data between each other. To receive data, one can call +:ref:`PR_Read` or :ref:`PR_Recv`. To send data, one can call :ref:`PR_Write`, +:ref:`PR_Writev`, :ref:`PR_Send`, or :ref:`PR_TransmitFile`. :ref:`PR_AcceptRead` is +suitable for use by the server to accept a new client connection and +read the client's first request in one function call. + +A TCP connection can be shut down by :ref:`PR_Shutdown`, and the sockets +should be closed by :ref:`PR_Close`. diff --git a/docs/nspr/reference/pr_openudpsocket.rst b/docs/nspr/reference/pr_openudpsocket.rst new file mode 100644 index 0000000000..f25373d7d8 --- /dev/null +++ b/docs/nspr/reference/pr_openudpsocket.rst @@ -0,0 +1,49 @@ +PR_OpenUDPSocket +================ + +Creates a new UDP socket of the specified address family. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc* PR_OpenUDPSocket(PRIntn af); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``af`` + The address family of the new UDP socket. Can be ``PR_AF_INET`` + (IPv4), ``PR_AF_INET6`` (IPv6), or ``PR_AF_LOCAL`` (Unix domain, + supported on POSIX systems only). + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion, a pointer to the :ref:`PRFileDesc` object + created for the newly opened UDP socket. +- If the creation of a new UDP socket failed, ``NULL``. + + +Description +----------- + +UDP (User Datagram Protocol) is a connectionless, unreliable datagram +protocol of the TCP/IP protocol suite. UDP datagrams may be lost or +delivered in duplicates or out of sequence. + +:ref:`PR_OpenUDPSocket` creates a new UDP socket of the address family +``af``. The socket may be bound to a well-known port number with +:ref:`PR_Bind`. Datagrams can be sent with :ref:`PR_SendTo` and received with +:ref:`PR_RecvFrom`. When the socket is no longer needed, it should be +closed with a call to :ref:`PR_Close`. diff --git a/docs/nspr/reference/pr_poll.rst b/docs/nspr/reference/pr_poll.rst new file mode 100644 index 0000000000..bc40620a2a --- /dev/null +++ b/docs/nspr/reference/pr_poll.rst @@ -0,0 +1,110 @@ +PR_Poll +======= + +Detects when I/O is ready for a set of socket file descriptors. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Poll( + PRPollDesc *pds, + PRIntn npds, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``pds`` + A pointer to the first element of an array of ``PRPollDesc`` + structures. +``npds`` + The number of elements in the ``pds`` array. If this parameter is + zero, :ref:`PR_Poll` is equivalent to :ref:`PR_Sleep` with a timeout. +``timeout`` + Amount of time the call will block waiting for I/O to become ready. + If this time expires without any I/O becoming ready, :ref:`PR_Poll` + returns zero. + + +Returns +~~~~~~~ + +The function returns one of these values: + +- If successful, the function returns a positive number indicating the + number of ``PRPollDesc`` structures in ``pds`` that have events. +- The value 0 indicates the function timed out. +- The value -1 indicates the function failed. The reason for the + failure can be obtained by calling :ref:`PR_GetError`. + + +Description +~~~~~~~~~~~ + +This function returns as soon as I/O is ready on one or more of the +underlying socket objects. A count of the number of ready descriptors is +returned unless a timeout occurs, in which case zero is returned. + +The ``in_flags`` field of the ``PRPollDesc`` data structure should be +set to the I/O events (readable, writable, exception, or some +combination) that the caller is interested in. On successful return, the +``out_flags`` field of the ``PRPollDesc`` data structure is set to +indicate what kind of I/O is ready on the respective descriptor. +:ref:`PR_Poll` uses the ``out_flags`` fields as scratch variables during +the call. If :ref:`PR_Poll` returns 0 or -1, the ``out_flags`` fields do +not contain meaningful values and must not be used. + +The ``PRPollDesc`` structure is defined as follows: + +.. code:: + + struct PRPollDesc { + PRFileDesc* fd; + PRInt16 in_flags; + PRInt16 out_flags; + }; + + typedef struct PRPollDesc PRPollDesc; + +The structure has the following fields: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket or a + pollable event. This field can be set to ``NULL`` to indicate to + :ref:`PR_Poll` that this ``PRFileDesc object`` should be ignored. + + .. note:: + + On Unix, the ``fd`` field can be set to a pointer to any + :ref:`PRFileDesc` object, including one representing a file or a + pipe. Cross-platform applications should only set the ``fd`` field + to a pointer to a :ref:`PRFileDesc` object representing a socket or a + pollable event because on Windows the ``select`` function can only + be used with sockets. +``in_flags`` + A bitwise ``OR`` of the following bit flags: + + - :ref:`PR_POLL_READ`: ``fd`` is readable. + - :ref:`PR_POLL_WRITE`: ``fd`` is writable. + - :ref:`PR_POLL_EXCEPT`: ``fd`` has an exception condition. + +``out_flags`` + A bitwise ``OR`` of the following bit flags: + + - :ref:`PR_POLL_READ` + - :ref:`PR_POLL_WRITE` + - :ref:`PR_POLL_EXCEPT` + - :ref:`PR_POLL_ERR`: ``fd`` has an error. + - :ref:`PR_POLL_NVAL`: ``fd`` is bad. + +Note that the ``PR_POLL_ERR`` and ``PR_POLL_NVAL`` flags are used only +in ``out_flags``. The ``PR_POLL_ERR`` and ``PR_POLL_NVAL`` events are +always reported by :ref:`PR_Poll`. diff --git a/docs/nspr/reference/pr_popiolayer.rst b/docs/nspr/reference/pr_popiolayer.rst new file mode 100644 index 0000000000..42fae4c074 --- /dev/null +++ b/docs/nspr/reference/pr_popiolayer.rst @@ -0,0 +1,53 @@ +PR_PopIOLayer +============= + +Removes a layer from the stack. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRFileDesc *PR_PopIOLayer( + PRFileDesc *stack, + PRDescIdentity id); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``stack`` + A pointer to a :ref:`PRFileDesc` object representing the stack from + which the specified layer is to be removed. +``id`` + Identity of the layer to be removed from the stack. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the layer is successfully removed from the stack, a pointer to the + removed layer. +- If the layer is not found in the stack or cannot be popped (for + example, the bottommost layer), the function returns ``NULL`` with + the error code ``PR_INVALID_ARGUMENT_ERROR``. + + +Description +----------- + +:ref:`PR_PopIOLayer` pops the specified layer from the stack. If the object +to be removed is found, :ref:`PR_PopIOLayer` returns a pointer to the +removed object The object then becomes the responsibility of the caller. + +Even if the identity indicates the top layer of the stack, the reference +returned is not the file descriptor for the stack and that file +descriptor remains valid. In other words, ``stack`` continues to point +to the top of the stack after the function returns. diff --git a/docs/nspr/reference/pr_postsemaphore.rst b/docs/nspr/reference/pr_postsemaphore.rst new file mode 100644 index 0000000000..e7145a60fe --- /dev/null +++ b/docs/nspr/reference/pr_postsemaphore.rst @@ -0,0 +1,30 @@ +PR_PostSemaphore +================ + +Increments the value of a specified semaphore. + + +Syntax +------ + +.. code:: + + #include <pripcsem.h> + + NSPR_API(PRStatus) PR_PostSemaphore(PRSem *sem); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``sem`` + A pointer to a ``PRSem`` structure returned from a call to + :ref:`PR_OpenSemaphore`. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_prev_link.rst b/docs/nspr/reference/pr_prev_link.rst new file mode 100644 index 0000000000..2b887db657 --- /dev/null +++ b/docs/nspr/reference/pr_prev_link.rst @@ -0,0 +1,35 @@ +PR_PREV_LINK +============ + +Returns the preceding element in a list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PRCList *PR_PREV_LINK (PRCList *elemp); + + +Parameter +~~~~~~~~~ + +``elemp`` + A pointer to the element. + + +Returns +~~~~~~~ + +A pointer to a list element. + + +Description +----------- + +:ref:`PR_PREV_LINK` returns a pointer to the element preceding the +specified element. It can be used to traverse a list. The preceding +element is not removed from the list. diff --git a/docs/nspr/reference/pr_processattrsetinheritablefilemap.rst b/docs/nspr/reference/pr_processattrsetinheritablefilemap.rst new file mode 100644 index 0000000000..c89f2740eb --- /dev/null +++ b/docs/nspr/reference/pr_processattrsetinheritablefilemap.rst @@ -0,0 +1,53 @@ +PR_ProcessAttrSetInheritableFileMap +=================================== + +Prepare filemap for export to my children processes via +``PR_CreateProcess``. + + +Syntax +------ + +.. code:: + + #include <prshma.h> + + NSPR_API(PRStatus) + PR_ProcessAttrSetInheritableFileMap( + PRProcessAttr *attr, + PRFileMap *fm, + const char *shmname + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``attr`` + Pointer to a PRProcessAttr structure used to pass data to + PR_CreateProcess. +``fm`` + Pointer to a PRFileMap structure to be passed to the child process. +``shmname`` + Pointer to the name for the PRFileMap; used by child. + + +Returns +~~~~~~~ + +:ref:`PRStatus` + + +Description +~~~~~~~~~~~ + +:ref:`PR_ProcessAttrSetInheritableFileMap` connects the :ref:`PRFileMap` to +:ref:`PRProcessAttr` with ``shmname``. A subsequent call to +``PR_CreateProcess`` makes the :ref:`PRFileMap` importable by the child +process. + +.. note:: + + **Note:** This function is not implemented. diff --git a/docs/nspr/reference/pr_processexit.rst b/docs/nspr/reference/pr_processexit.rst new file mode 100644 index 0000000000..862e48bb5e --- /dev/null +++ b/docs/nspr/reference/pr_processexit.rst @@ -0,0 +1,23 @@ +PR_ProcessExit +============== + +Causes an immediate, nongraceful, forced termination of the process. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_ProcessExit(PRIntn status); + + +Parameter +~~~~~~~~~ + +:ref:`PR_ProcessExit` has one parameter: + +status + The exit status code of the process. 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`. diff --git a/docs/nspr/reference/pr_queuejob.rst b/docs/nspr/reference/pr_queuejob.rst new file mode 100644 index 0000000000..0ad0eb3b8b --- /dev/null +++ b/docs/nspr/reference/pr_queuejob.rst @@ -0,0 +1,43 @@ +PR_QueueJob +=========== + +Queues a job to a thread pool for execution. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRJob *) + PR_QueueJob( + PRThreadPool *tpool, + PRJobFn fn, + void *arg, + PRBool joinable + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. +``fn`` + The function to be executed when the job is executed. +``arg`` + A pointer to an argument passed to ``fn``. +``joinable`` + If ``PR_TRUE``, the job is joinable. If ``PR_FALSE``, the job is not + joinable. See :ref:`PR_JoinJob`. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRJob` structure or ``NULL`` on error. diff --git a/docs/nspr/reference/pr_queuejob_connect.rst b/docs/nspr/reference/pr_queuejob_connect.rst new file mode 100644 index 0000000000..b5aeaf899e --- /dev/null +++ b/docs/nspr/reference/pr_queuejob_connect.rst @@ -0,0 +1,49 @@ +PR_QueueJob_Connect +=================== + +Causes a job to be queued when a socket can be connected. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRJob *) + PR_QueueJob_Connect( + PRThreadPool *tpool, + PRJobIoDesc *iod, + const PRNetAddr *addr, + PRJobFn fn, + void * arg, + PRBool joinable + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. +``iod`` + A pointer to a :ref:`PRJobIoDesc` structure. +``addr`` + Pointer to a :ref:`PRNetAddr` structure for the socket being connected. +``fn`` + The function to be executed when the job is executed. +``arg`` + A pointer to an argument passed to ``fn``. +``joinable`` + If ``PR_TRUE``, the job is joinable. If ``PR_FALSE``, the job is not + joinable. See :ref:`PR_JoinJob`. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRJob` structure or ``NULL`` on error. diff --git a/docs/nspr/reference/pr_queuejob_read.rst b/docs/nspr/reference/pr_queuejob_read.rst new file mode 100644 index 0000000000..0b715a7fa5 --- /dev/null +++ b/docs/nspr/reference/pr_queuejob_read.rst @@ -0,0 +1,46 @@ +PR_QueueJob_Read +================ + +Causes a job to be queued when a socket becomes readable. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRJob *) + PR_QueueJob_Read( + PRThreadPool *tpool, + PRJobIoDesc *iod, + PRJobFn fn, + void *arg, + PRBool joinable + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. +``iod`` + A pointer to a :ref:`PRJobIoDesc` structure. +``fn`` + The function to be executed when the job is executed. +``arg`` + A pointer to an argument passed to ``fn``. +``joinable`` + If ``PR_TRUE``, the job is joinable. If ``PR_FALSE``, the job is not + joinable. See :ref:`PR_JoinJob`. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRJob` structure or ``NULL`` on error. diff --git a/docs/nspr/reference/pr_queuejob_timer.rst b/docs/nspr/reference/pr_queuejob_timer.rst new file mode 100644 index 0000000000..4460433fa5 --- /dev/null +++ b/docs/nspr/reference/pr_queuejob_timer.rst @@ -0,0 +1,49 @@ +PR_QueueJob_Timer +================= + +Causes a job to be queued when a timer expires. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRJob *) + PR_QueueJob_Timer( + PRThreadPool *tpool, + PRIntervalTime timeout, + PRJobFn fn, + void * arg, + PRBool joinable + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. +``iod`` + A pointer to a :ref:`PRJobIoDesc` structure. +``timeout`` + A value, expressed as a :ref:`PRIntervalTime`, to wait before queuing + the job. +``fn`` + The function to be executed when the job is executed. +``arg`` + A pointer to an argument passed to ``fn``. +``joinable`` + If ``PR_TRUE``, the job is joinable. If ``PR_FALSE``, the job is not + joinable. See :ref:`PR_JoinJob`. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRJob` structure or ``NULL`` on error. diff --git a/docs/nspr/reference/pr_queuejob_write.rst b/docs/nspr/reference/pr_queuejob_write.rst new file mode 100644 index 0000000000..9551b3bc4b --- /dev/null +++ b/docs/nspr/reference/pr_queuejob_write.rst @@ -0,0 +1,46 @@ +PR_QueueJob_Write +================= + +Causes a job to be queued when a socket becomes writable. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRJob *) + PR_QueueJob_Write( + PRThreadPool *tpool, + PRJobIoDesc *iod, + PRJobFn fn, + void *arg, + PRBool joinable + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. +``iod`` + A pointer to a :ref:`PRJobIoDesc` structure. +``fn`` + The function to be executed when the job is executed. +``arg`` + A pointer to an argument passed to ``fn``. +``joinable`` + If ``PR_TRUE``, the job is joinable. If ``PR_FALSE``, the job is not + joinable. See :ref:`PR_JoinJob`. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRJob` structure or ``NULL`` on error. diff --git a/docs/nspr/reference/pr_queuejobaccept.rst b/docs/nspr/reference/pr_queuejobaccept.rst new file mode 100644 index 0000000000..234a2148f4 --- /dev/null +++ b/docs/nspr/reference/pr_queuejobaccept.rst @@ -0,0 +1,46 @@ +PR_QueueJob_Accept +================== + +Causes a job to be queued when a socket has a pending connection. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRJob *) + PR_QueueJob_Accept( + PRThreadPool *tpool, + PRJobIoDesc *iod, + PRJobFn fn, + void *arg, + PRBool joinable + ); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. +``iod`` + A pointer to a :ref:`PRJobIoDesc` structure. +``fn`` + The function to be executed when the job is executed. +``arg`` + A pointer to an argument passed to ``fn``. +``joinable`` + If ``PR_TRUE``, the job is joinable. If ``PR_FALSE``, the job is not + joinable. See :ref:`PR_JoinJob`. + + +Returns +~~~~~~~ + +Pointer to a :ref:`PRJob` structure or ``NULL`` on error. diff --git a/docs/nspr/reference/pr_read.rst b/docs/nspr/reference/pr_read.rst new file mode 100644 index 0000000000..a6d7c03efa --- /dev/null +++ b/docs/nspr/reference/pr_read.rst @@ -0,0 +1,50 @@ +PR_Read +======= + +Reads bytes from a file or socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Read(PRFileDesc *fd, + void *buf, + PRInt32 amount); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object for the file or socket. +``buf`` + A pointer to a buffer to hold the data read in. On output, the buffer + contains the data. +``amount`` + The size of ``buf`` (in bytes). + + +Returns +~~~~~~~ + +One of the following values: + +- A positive number indicates the number of bytes actually read in. +- The value 0 means end of file is reached or the network connection is + closed. +- The value -1 indicates a failure. To get the reason for the failure, + call :ref:`PR_GetError`. + + +Description +----------- + +The thread invoking :ref:`PR_Read` blocks until it encounters an +end-of-stream indication, some positive number of bytes (but no more +than ``amount`` bytes) are read in, or an error occurs. diff --git a/docs/nspr/reference/pr_readdir.rst b/docs/nspr/reference/pr_readdir.rst new file mode 100644 index 0000000000..1379b694c9 --- /dev/null +++ b/docs/nspr/reference/pr_readdir.rst @@ -0,0 +1,93 @@ +PR_ReadDir +========== + +Gets a pointer to the next entry in the directory. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRDirEntry* PR_ReadDir( + PRDir *dir, + PRDirFlags flags); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``dir`` + A pointer to a :ref:`PRDir` object that designates an open directory. +``flags`` + Specifies which directory entries, if any, to skip. Values can + include the following: + + - :ref:`PR_SKIP_NONE`. Do not skip any files. + - :ref:`PR_SKIP_DOT`. Skip the directory entry "." representing the + current directory. + - :ref:`PR_SKIP_DOT_DOT`. Skip the directory entry ".." representing + the parent directory. + - :ref:`PR_SKIP_BOTH`. Skip both "." and ".." + - :ref:`PR_SKIP_HIDDEN`. Skip hidden files. On Windows platforms and + the Mac OS, this value identifies files with the "hidden" + attribute set. On Unix platform, this value identifies files whose + names begin with a period ("."). + + +Returns +~~~~~~~ + +- A pointer to the next entry in the directory. +- If the end of the directory is reached or an error occurs, ``NULL``. + The reason can be retrieved via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_ReadDir` returns a pointer to a directory entry structure: + +.. code:: + + struct PRDirEntry { + const char *name; + }; + + typedef struct PRDirEntry PRDirEntry; + +The structure has the following field: + +``name`` + Name of entry, relative to directory name. + +The ``flags`` parameter is an enum of type ``PRDirFlags``: + +.. code:: + + typedef enum PRDirFlags { + PR_SKIP_NONE = 0x0, + PR_SKIP_DOT = 0x1, + PR_SKIP_DOT_DOT = 0x2, + PR_SKIP_BOTH = 0x3, + PR_SKIP_HIDDEN = 0x4 + } PRDirFlags; + +The memory associated with the returned PRDirEntry structure is managed +by NSPR. The caller must not free the ``PRDirEntry`` structure. +Moreover, the ``PRDirEntry`` structure returned by each :ref:`PR_ReadDir` +call is valid only until the next :ref:`PR_ReadDir` or :ref:`PR_CloseDir` call +on the same :ref:`PRDir` object. + +If the end of the directory is reached, :ref:`PR_ReadDir` returns ``NULL``, +and :ref:`PR_GetError` returns ``PR_NO_MORE_FILES_ERROR``. + + +See Also +-------- + +:ref:`PR_OpenDir` diff --git a/docs/nspr/reference/pr_realloc.rst b/docs/nspr/reference/pr_realloc.rst new file mode 100644 index 0000000000..011b389086 --- /dev/null +++ b/docs/nspr/reference/pr_realloc.rst @@ -0,0 +1,43 @@ + +PR_Realloc +========== + +Resizes allocated memory on the heap. + + +Syntax +------ + +.. code:: + + #include <prmem.h> + + void *PR_Realloc ( + void *ptr, + PRUint32 size); + + +Parameters +~~~~~~~~~~ + +``ptr`` + A pointer to the existing memory block being resized. +``size`` + The size of the new memory block. + + +Returns +~~~~~~~ + +An untyped pointer to the allocated memory, or if the allocation attempt +fails, ``NULL``. Call ``PR_GetError()`` to retrieve the error returned +by the libc function ``realloc()``. + + +Description +~~~~~~~~~~~ + +This function attempts to enlarge or shrink the memory block addressed +by ptr to a new size. The contents of the specified memory remains the +same up to the smaller of its old size and new size, although the new +memory block's address can be different from the original address. diff --git a/docs/nspr/reference/pr_recv.rst b/docs/nspr/reference/pr_recv.rst new file mode 100644 index 0000000000..bfc1b7e5f9 --- /dev/null +++ b/docs/nspr/reference/pr_recv.rst @@ -0,0 +1,56 @@ +PR_Recv +======= + +Receives bytes from a connected socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Recv( + PRFileDesc *fd, + void *buf, + PRInt32 amount, + PRIntn flags, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``buf`` + A pointer to a buffer to hold the data received. +``amount`` + The size of ``buf`` (in bytes). +``flags`` + Must be zero or ``PR_MSG_PEEK``. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the receive operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- A positive number indicates the number of bytes actually received. +- The value 0 means the network connection is closed. +- The value -1 indicates a failure. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Recv` blocks until some positive number of bytes are transferred, +a timeout occurs, or an error occurs. No more than ``amount`` bytes will +be transferred. diff --git a/docs/nspr/reference/pr_recvfrom.rst b/docs/nspr/reference/pr_recvfrom.rst new file mode 100644 index 0000000000..4d2cee79f6 --- /dev/null +++ b/docs/nspr/reference/pr_recvfrom.rst @@ -0,0 +1,62 @@ +PR_RecvFrom +=========== + +Receives bytes from a socket and stores the sending peer's address. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_RecvFrom( + PRFileDesc *fd, + void *buf, + PRInt32 amount, + PRIntn flags, + PRNetAddr *addr, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``buf`` + A pointer to a buffer containing the data received. +``amount`` + The size of ``buf`` (in bytes). +``flags`` + This obsolete parameter must always be zero. +``addr`` + A pointer to the :ref:`PRNetAddr` object that will be filled in with the + address of the sending peer on return. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the receive operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- A positive number indicates the number of bytes actually received. +- The value 0 means the network connection is closed. +- The value -1 indicates a failure. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_RecvFrom` receives up to a specified number of bytes from socket, +which may or may not be connected. The operation blocks until one or +more bytes are transferred, a timeout has occurred, or there is an +error. No more than ``amount`` bytes will be transferred. +:ref:`PR_RecvFrom` is usually used with a UDP socket. diff --git a/docs/nspr/reference/pr_remove_and_init_link.rst b/docs/nspr/reference/pr_remove_and_init_link.rst new file mode 100644 index 0000000000..667a072b21 --- /dev/null +++ b/docs/nspr/reference/pr_remove_and_init_link.rst @@ -0,0 +1,29 @@ +PR_REMOVE_AND_INIT_LINK +======================= + +Removes an element from a circular list and initializes the linkage. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_REMOVE_AND_INIT_LINK (PRCList *elemp); + + +Parameter +~~~~~~~~~ + +``elemp`` + A pointer to the element. + + +Description +----------- + +:ref:`PR_REMOVE_AND_INIT_LINK` removes the specified element from its +circular list and initializes the links of the element to point to +itself. diff --git a/docs/nspr/reference/pr_remove_link.rst b/docs/nspr/reference/pr_remove_link.rst new file mode 100644 index 0000000000..ab5492f810 --- /dev/null +++ b/docs/nspr/reference/pr_remove_link.rst @@ -0,0 +1,27 @@ +PR_REMOVE_LINK +============== + +Removes an element from a circular list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + PR_REMOVE_LINK (PRCList *elemp); + + +Parameter +~~~~~~~~~ + +``elemp`` + A pointer to the element. + + +Description +----------- + +:ref:`PR_REMOVE_LINK` removes the specified element from its circular list. diff --git a/docs/nspr/reference/pr_rename.rst b/docs/nspr/reference/pr_rename.rst new file mode 100644 index 0000000000..67bb1b2673 --- /dev/null +++ b/docs/nspr/reference/pr_rename.rst @@ -0,0 +1,45 @@ +PR_Rename +========= + +Renames a file. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Rename( + const char *from, + const char *to); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``from`` + The old name of the file to be renamed. +``to`` + The new name of the file. + + +Returns +~~~~~~~ + +One of the following values: + +- If file is successfully renamed, ``PR_SUCCESS``. +- If file is not successfully renamed, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_Rename` renames a file from its old name (``from``) to a new name +(``to``). If a file with the new name already exists, :ref:`PR_Rename` +fails with the error code ``PR_FILE_EXISTS_ERROR``. In this case, +:ref:`PR_Rename` does not overwrite the existing filename. diff --git a/docs/nspr/reference/pr_rmdir.rst b/docs/nspr/reference/pr_rmdir.rst new file mode 100644 index 0000000000..7aa4aeb8c7 --- /dev/null +++ b/docs/nspr/reference/pr_rmdir.rst @@ -0,0 +1,46 @@ +PR_RmDir +======== + +Removes a directory with a specified name. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_RmDir(const char *name); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``name`` + The name of the directory to be removed. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The actual reason can be retrieved + via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_RmDir` removes the directory specified by the pathname ``name``. +The directory must be empty. If the directory is not empty, :ref:`PR_RmDir` +fails and :ref:`PR_GetError` returns the error code +``PR_DIRECTORY_NOT_EMPTY_ERROR``. + + +See Also +-------- + +:ref:`PR_MkDir` diff --git a/docs/nspr/reference/pr_secondstointerval.rst b/docs/nspr/reference/pr_secondstointerval.rst new file mode 100644 index 0000000000..18c8947a36 --- /dev/null +++ b/docs/nspr/reference/pr_secondstointerval.rst @@ -0,0 +1,30 @@ +PR_SecondsToInterval +==================== + +Converts standard clock seconds to platform-dependent intervals. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRIntervalTime PR_SecondsToInterval(PRUint32 seconds); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``seconds`` + The number of seconds to convert to interval form. + + +Returns +~~~~~~~ + +Platform-dependent equivalent of the value passed in the ``seconds`` +parameter. diff --git a/docs/nspr/reference/pr_seek.rst b/docs/nspr/reference/pr_seek.rst new file mode 100644 index 0000000000..b06351d059 --- /dev/null +++ b/docs/nspr/reference/pr_seek.rst @@ -0,0 +1,85 @@ +PR_Seek +======= + +Moves the current read-write file pointer by an offset expressed as a +32-bit integer. + +.. container:: blockIndicator deprecated deprecatedHeader + + | **Deprecated** + | This feature is no longer recommended. Though some browsers might + still support it, it may have already been removed from the + relevant web standards, may be in the process of being dropped, or + may only be kept for compatibility purposes. Avoid using it, and + update existing code if possible; see the `compatibility + table <#Browser_compatibility>`__ at the bottom of this page to + guide your decision. Be aware that this feature may cease to work + at any time. + +Deprecated in favor of :ref:`PR_Seek64`. + + +Syntax +~~~~~~ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Seek( + PRFileDesc *fd, + PRInt32 offset, + PRSeekWhence whence); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object. +``offset`` + A value, in bytes, used with the whence parameter to set the file + pointer. A negative value causes seeking in the reverse direction. +``whence`` + A value of type :ref:`PRSeekWhence` that specifies how to interpret the + ``offset`` parameter in setting the file pointer associated with the + fd parameter. The value for the ``whence`` parameter can be one of + the following: + + - :ref:`PR_SEEK_SET`. Sets the file pointer to the value of the + ``offset`` parameter. + - :ref:`PR_SEEK_CUR`. Sets the file pointer to its current location + plus the value of the ``offset`` parameter. + - :ref:`PR_SEEK_END`. Sets the file pointer to the size of the file + plus the value of the ``offset`` parameter. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the function completes successfully, it returns the resulting file + pointer location, measured in bytes from the beginning of the file. +- If the function fails, the file pointer remains unchanged and the + function returns -1. The error code can then be retrieved with + :ref:`PR_GetError`. + + +Description +----------- + +Here's an idiom for obtaining the current location of the file pointer +for the file descriptor ``fd``: + +``PR_Seek(fd, 0, PR_SEEK_CUR)`` + + +See Also +-------- + +If you need to move the file pointer by a large offset that's out of the +range of a 32-bit integer, use :ref:`PR_Seek64`. New code should use +:ref:`PR_Seek64` so that it can handle files larger than 2 GB. diff --git a/docs/nspr/reference/pr_seek64.rst b/docs/nspr/reference/pr_seek64.rst new file mode 100644 index 0000000000..3c144575dc --- /dev/null +++ b/docs/nspr/reference/pr_seek64.rst @@ -0,0 +1,73 @@ +PR_Seek64 +========= + +Moves the current read-write file pointer by an offset expressed as a +64-bit integer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt64 PR_Seek64( + PRFileDesc *fd, + PRInt64 offset, + PRSeekWhence whence); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object. +``offset`` + A value, in bytes, used with the whence parameter to set the file + pointer. A negative value causes seeking in the reverse direction. +``whence`` + A value of type :ref:`PRSeekWhence` that specifies how to interpret the + ``offset`` parameter in setting the file pointer associated with the + fd parameter. The value for the ``whence`` parameter can be one of + the following: + + - :ref:`PR_SEEK_SET`. Sets the file pointer to the value of the + ``offset`` parameter. + - :ref:`PR_SEEK_CUR`. Sets the file pointer to its current location + plus the value of the ``offset`` parameter. + - :ref:`PR_SEEK_END`. Sets the file pointer to the size of the file + plus the value of the ``offset`` parameter. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the function completes successfully, it returns the resulting file + pointer location, measured in bytes from the beginning of the file. +- If the function fails, the file pointer remains unchanged and the + function returns -1. The error code can then be retrieved with + :ref:`PR_GetError`. + + +Description +----------- + +This is the idiom for obtaining the current location (expressed as a +64-bit integer) of the file pointer for the file descriptor ``fd``: + +``PR_Seek64(fd, 0, PR_SEEK_CUR)`` + +If the operating system can handle only a 32-bit file offset, +:ref:`PR_Seek64` may fail with the error code ``PR_FILE_TOO_BIG_ERROR`` if +the ``offset`` parameter is out of the range of a 32-bit integer. + + +See Also +-------- + +:ref:`PR_Seek` diff --git a/docs/nspr/reference/pr_send.rst b/docs/nspr/reference/pr_send.rst new file mode 100644 index 0000000000..1ffdad63e4 --- /dev/null +++ b/docs/nspr/reference/pr_send.rst @@ -0,0 +1,56 @@ +PR_Send +======= + +Sends bytes from a connected socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Send( + PRFileDesc *fd, + const void *buf, + PRInt32 amount, + PRIntn flags, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``buf`` + A pointer to a buffer containing the data to be sent. +``amount`` + The size of ``buf`` (in bytes). +``flags`` + This obsolete parameter must always be zero. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the receive operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- A positive number indicates the number of bytes successfully sent. If + the parameter fd is a blocking socket, this number must always equal + amount. +- The value -1 indicates a failure. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_Send` blocks until all bytes are sent, a timeout occurs, or an +error occurs. diff --git a/docs/nspr/reference/pr_sendto.rst b/docs/nspr/reference/pr_sendto.rst new file mode 100644 index 0000000000..ba3ce59868 --- /dev/null +++ b/docs/nspr/reference/pr_sendto.rst @@ -0,0 +1,58 @@ +PR_SendTo +========= + +Sends bytes a socket to a specified destination. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_SendTo( + PRFileDesc *fd, + const void *buf, + PRInt32 amount, + PRIntn flags, + const PRNetAddr *addr, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a socket. +``buf`` + A pointer to a buffer containing the data to be sent. +``amount`` + The size of ``buf`` (in bytes). +``flags`` + This obsolete parameter must always be zero. +``addr`` + A pointer to the address of the destination. +``timeout`` + A value of type :ref:`PRIntervalTime` specifying the time limit for + completion of the receive operation. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- A positive number indicates the number of bytes successfully sent. +- The value -1 indicates a failure. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_SendTo` sends a specified number of bytes from a socket to the +specified destination address. The calling thread blocks until all bytes +are sent, a timeout has occurred, or there is an error. diff --git a/docs/nspr/reference/pr_setconcurrency.rst b/docs/nspr/reference/pr_setconcurrency.rst new file mode 100644 index 0000000000..309a0312bc --- /dev/null +++ b/docs/nspr/reference/pr_setconcurrency.rst @@ -0,0 +1,42 @@ +PR_SetConcurrency +================= + +Creates extra virtual processor threads. Generally used with MP systems. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_SetConcurrency(PRUintn numCPUs); + + +Parameter +~~~~~~~~~ + +:ref:`PR_SetConcurrency` has one parameter: + +``numCPUs`` + The number of extra virtual processor threads to be created. + + +Description +----------- + +Setting concurrency controls the number of virtual processors that NSPR +uses to implement its ``M x N`` threading model. The ``M x N`` model is +not available on all host systems. On those where it is not available, +:ref:`PR_SetConcurrency` is ignored. + +Virtual processors are actually\ *global* threads, each of which is +designed to support an arbitrary number of\ *local* threads. Since +global threads are scheduled by the host operating system, this model is +particularly applicable to multiprocessor architectures, where true +parallelism is possible. However, it may also prove advantageous on +uniprocessor systems to reduce the impact of having a locally scheduled +thread calling incidental blocking functions. In such cases, all the +threads being supported by the virtual processor will block, but those +assigned to another virtual processor will be unaffected. diff --git a/docs/nspr/reference/pr_seterror.rst b/docs/nspr/reference/pr_seterror.rst new file mode 100644 index 0000000000..87d256139a --- /dev/null +++ b/docs/nspr/reference/pr_seterror.rst @@ -0,0 +1,35 @@ +PR_SetError +=========== + +Sets error information within a thread context. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + void PR_SetError(PRErrorCode errorCode, PRInt32 oserr) + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``errorCode`` + The NSPR (platform-independent) translation of the error. + +``oserr`` + The platform-specific error. If there is no appropriate OS error + number, a zero may be supplied. + + +Description +----------- + +NSPR does not validate the value of the error number or OS error number +being specified. The runtime merely stores the value and returns it when +requested. diff --git a/docs/nspr/reference/pr_seterrortext.rst b/docs/nspr/reference/pr_seterrortext.rst new file mode 100644 index 0000000000..5fa385cc52 --- /dev/null +++ b/docs/nspr/reference/pr_seterrortext.rst @@ -0,0 +1,43 @@ +PR_SetErrorText +=============== + +Sets the text associated with an error. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + void PR_SetErrorText(PRIntn textLength, const char *text) + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``textLength`` + The length of the text in the ``text``. May be ``NULL``. If not + ``NULL``, and if ``text`` is zero, the string is assumed to be a + null-terminated C string. Otherwise the text is assumed to be the + length specified and to possibly include ``NULL`` characters (as + might occur in a multilingual string). + +``text`` + The text to associate with the error. + + +Description +----------- + +The text is copied into the thread structure and remains there until the +next call to :ref:`PR_SetError`. If there is error text already present in +the thread, the previous value is first deleted. The new value is copied +into storage allocated and owned by NSPR and remains there until the +next call to :ref:`PR_SetError` or another call to :ref:`PR_SetErrorText`. + +NSPR makes no use of this function. Clients may use it for their own +purposes. diff --git a/docs/nspr/reference/pr_setlibrarypath.rst b/docs/nspr/reference/pr_setlibrarypath.rst new file mode 100644 index 0000000000..52336e62d9 --- /dev/null +++ b/docs/nspr/reference/pr_setlibrarypath.rst @@ -0,0 +1,45 @@ +PR_SetLibraryPath +================= + +Registers a default library pathname with a runtime. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + PRStatus PR_SetLibraryPath(const char *path); + + +Parameters +~~~~~~~~~~ + +The function has this parameter: + +``path`` + A pointer to a character array that contains the directory path that + the application should use as a default. The syntax of the pathname + is not defined, nor whether that pathname should be absolute or + relative. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. This may indicate that the function + cannot allocate sufficient storage to make a copy of the path string + + +Description +----------- + +This function registers a default library pathname with the runtime. +This allows an environment to express policy decisions globally and +lazily, rather than hardcoding and distributing the decisions throughout +the code. diff --git a/docs/nspr/reference/pr_setpollableevent.rst b/docs/nspr/reference/pr_setpollableevent.rst new file mode 100644 index 0000000000..e9de4eb19e --- /dev/null +++ b/docs/nspr/reference/pr_setpollableevent.rst @@ -0,0 +1,32 @@ +PR_SetPollableEvent +=================== + +Set a pollable event. + + +Syntax +------ + +.. code:: + + NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``event`` + Pointer to a :ref:`PRFileDesc` structure previously created via a call + to :ref:`PR_NewPollableEvent`. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + retrieved via :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_setsocketoption.rst b/docs/nspr/reference/pr_setsocketoption.rst new file mode 100644 index 0000000000..8484a4b727 --- /dev/null +++ b/docs/nspr/reference/pr_setsocketoption.rst @@ -0,0 +1,45 @@ +PR_SetSocketOption +================== + +Retrieves the socket options set for a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_SetSocketOption( + PRFileDesc *fd, + PRSocketOptionData *data); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing the socket whose + options are to be set. +``data`` + A pointer to a structure of type :ref:`PRSocketOptionData` specifying + the options to set. + + +Returns +~~~~~~~ + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +On input, the caller must set both the ``option`` and ``value`` fields +of the :ref:`PRSocketOptionData` object pointed to by the ``data`` +parameter. diff --git a/docs/nspr/reference/pr_setthreadpriority.rst b/docs/nspr/reference/pr_setthreadpriority.rst new file mode 100644 index 0000000000..32ca051656 --- /dev/null +++ b/docs/nspr/reference/pr_setthreadpriority.rst @@ -0,0 +1,37 @@ +PR_SetThreadPriority +==================== + +Sets the priority of a specified thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + void PR_SetThreadPriority( + PRThread *thread, + PRThreadPriority priority); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_SetThreadPriority` has the following parameters: + +``thread`` + A valid identifier for the thread whose priority you want to set. +``priority`` + The priority you want to set. + + +Description +----------- + +Modifying the priority of a thread other than the calling thread is +risky. It is difficult to ensure that the state of the target thread +permits a priority adjustment without ill effects. It is preferable for +a thread to specify itself in the thread parameter when it calls +:ref:`PR_SetThreadPriority`. diff --git a/docs/nspr/reference/pr_setthreadprivate.rst b/docs/nspr/reference/pr_setthreadprivate.rst new file mode 100644 index 0000000000..0f24c5b386 --- /dev/null +++ b/docs/nspr/reference/pr_setthreadprivate.rst @@ -0,0 +1,56 @@ +PR_SetThreadPrivate +=================== + +Sets per-thread private data. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRStatus PR_SetThreadPrivate(PRUintn index, void *priv); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_SetThreadPrivate` has the following parameters: + +``index`` + An index into the per-thread private data table. +``priv`` + The per-thread private data, or more likely, a pointer to the data. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If the index is invalid, ``PR_FAILURE``. + + +Description +----------- + +If the thread already has non-``NULL`` private data associated with it, +and if the destructor function for the index is known (not ``NULL``), +NSPR calls the destructor function associated with the index before +setting the new data value. The pointer at the index is swapped with +``NULL``. If the swapped out value is not ``NULL``, the destructor +function is called. On return, the private data associated with the +index is reassigned the new private data's value, even if it is +``NULL``. The runtime provides no protection for the private data. The +destructor is called with the runtime holding no locks. Synchronization +is the client's responsibility. + +The only way to eliminate thread private data at an index prior to the +thread's termination is to call :ref:`PR_SetThreadPrivate` with a ``NULL`` +argument. This causes the index's destructor function to be called, and +afterwards assigns a ``NULL`` in the table. A client must not delete the +referent object of a non-``NULL`` private data without first eliminating +it from the table. diff --git a/docs/nspr/reference/pr_shutdown.rst b/docs/nspr/reference/pr_shutdown.rst new file mode 100644 index 0000000000..faee7dfe15 --- /dev/null +++ b/docs/nspr/reference/pr_shutdown.rst @@ -0,0 +1,57 @@ +PR_Shutdown +=========== + +Shuts down part of a full-duplex connection on a specified socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Shutdown( + PRFileDesc *fd, + PRShutdownHow how); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object representing a connected socket. +``how`` + The kind of disallowed operations on the socket. Possible values + include the following: + + - :ref:`PR_SHUTDOWN_RCV`. Further receives will be disallowed. + - :ref:`PR_SHUTDOWN_SEND`. Further sends will be disallowed. + - :ref:`PR_SHUTDOWN_BOTH`. Further sends and receives will be + disallowed. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- Upon successful completion of shutdown request, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. Further information can be obtained + by calling :ref:`PR_GetError`. + + +Description +----------- + +The ``PRShutdownHow`` enumeration is defined as follows: + +.. code:: + + typedef enum PRShutdownHow{ + PR_SHUTDOWN_RCV = 0, + PR_SHUTDOWN_SEND = 1, + PR_SHUTDOWN_BOTH = 2 + } PRShutdownHow; diff --git a/docs/nspr/reference/pr_shutdownthreadpool.rst b/docs/nspr/reference/pr_shutdownthreadpool.rst new file mode 100644 index 0000000000..3fb411af64 --- /dev/null +++ b/docs/nspr/reference/pr_shutdownthreadpool.rst @@ -0,0 +1,30 @@ +PR_ShutdownThreadPool +===================== + +Notifies all threads in a thread pool to terminate. + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + NSPR_API(PRStatus) PR_ShutdownThreadPool( PRThreadPool *tpool ); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``tpool`` + A pointer to a :ref:`PRThreadPool` structure previously created by a + call to :ref:`PR_CreateThreadPool`. + + +Returns +~~~~~~~ + +:ref:`PRStatus` diff --git a/docs/nspr/reference/pr_sleep.rst b/docs/nspr/reference/pr_sleep.rst new file mode 100644 index 0000000000..b3ad0ec2cd --- /dev/null +++ b/docs/nspr/reference/pr_sleep.rst @@ -0,0 +1,52 @@ +PR_Sleep +======== + +Causes the current thread to yield for a specified amount of time. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + PRStatus PR_Sleep(PRIntervalTime ticks); + + +Parameter +~~~~~~~~~ + +:ref:`PR_Sleep` has the following parameter: + +``ticks`` + The number of ticks you want the thread to sleep for (see + :ref:`PRIntervalTime`). + + +Returns +~~~~~~~ + +Calling :ref:`PR_Sleep` with a parameter equivalent to +``PR_INTERVAL_NO_TIMEOUT`` is an error and results in a ``PR_FAILURE`` +error. + + +Description +----------- + +:ref:`PR_Sleep` simply waits on a condition for the amount of time +specified. If you set ticks to ``PR_INTERVAL_NO_WAIT``, the thread +yields. + +If ticks is not ``PR_INTERVAL_NO_WAIT``, :ref:`PR_Sleep` uses an existing +lock, but has to create a new condition for this purpose. If you have +already created such structures, it is more efficient to use them +directly. + +Calling :ref:`PR_Sleep` with the value of ticks set to +``PR_INTERVAL_NO_WAIT`` simply surrenders the processor to ready threads +of the same priority. All other values of ticks cause :ref:`PR_Sleep` to +block the calling thread for the specified interval. + +Threads blocked in :ref:`PR_Sleep` are interruptible. diff --git a/docs/nspr/reference/pr_static_assert.rst b/docs/nspr/reference/pr_static_assert.rst new file mode 100644 index 0000000000..4aa2e31c58 --- /dev/null +++ b/docs/nspr/reference/pr_static_assert.rst @@ -0,0 +1,46 @@ +PR_STATIC_ASSERT +================ + +Prevents code from compiling when an expression has the value ``FALSE`` +at compile time. + + +Syntax +------ + +.. code:: + + #include <prlog.h> + + PR_STATIC_ASSERT ( expression ); + + +Parameters +~~~~~~~~~~ + +The macro has this parameter: + +expression + Any valid expression which evaluates at compile-time to ``TRUE`` or + ``FALSE``. An expression which cannot be evaluated at compile time + will cause a compiler error; see :ref:`PR_ASSERT` for a runtime + alternative. + + +Returns +~~~~~~~ + +Nothing + + +Description +----------- + +This macro evaluates the specified expression. When the result is zero +(``FALSE``) program compilation will fail with a compiler error; +otherwise compilation completes successfully. The compiler error will +include the number of the line for which the compile-time assertion +failed. + +This macro may only be used in locations where an ``extern`` function +declaration may be used. diff --git a/docs/nspr/reference/pr_stringtonetaddr.rst b/docs/nspr/reference/pr_stringtonetaddr.rst new file mode 100644 index 0000000000..af6e3b3e4f --- /dev/null +++ b/docs/nspr/reference/pr_stringtonetaddr.rst @@ -0,0 +1,48 @@ +PR_StringToNetAddr +================== + +Converts a character string to a network address. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + PRStatus PR_StringToNetAddr( + const char *string, + PRNetAddr *addr); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``string`` + The string to be converted. +``addr`` + On output, the equivalent network address. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. You can retrieve the reason for the + failure by calling :ref:`PR_GetError`. + + +Description +----------- + +For IPv4 addresses, the input string represents numbers in the Internet +standard "." notation. IPv6 addresses are indicated as strings using ":" +characters separating octets, with numerous caveats for shortcutting +(see RFC #1884). If the NSPR library and the host are configured to +support IPv6, both formats are supported. Otherwise, use of anything +other than IPv4 dotted notation results in an error. diff --git a/docs/nspr/reference/pr_strtod.rst b/docs/nspr/reference/pr_strtod.rst new file mode 100644 index 0000000000..af870ce03b --- /dev/null +++ b/docs/nspr/reference/pr_strtod.rst @@ -0,0 +1,50 @@ +PR_strtod +========= + +Converts the prefix of a decimal string to the nearest double-precision +floating point number. + + +Syntax +------ + +.. code:: + + #include <prdtoa.h> + + PRFloat64 PR_strtod(const char *s00, char **se); + + +Parameters +~~~~~~~~~~ + +The function has these parameters: + +``s00`` + The input string to be scanned. +``se`` + A pointer that, if not ``NULL``, will be assigned the address of the + last character scanned in the input string. + + +Returns +~~~~~~~ + +The result of the conversion is a ``PRFloat64`` value equivalent to the +input string. If the parameter ``se`` is not ``NULL`` the location it +references is also set. + + +Description +----------- + +:ref:`PR_strtod` converts the prefix of the input decimal string pointed to +by ``s00`` to a nearest double-precision floating point number. Ties are +broken by the IEEE round-even rule. The string is scanned up to the +first unrecognized character. If the value of ``se`` is not +(``char **``) ``NULL``, :ref:`PR_strtod` stores a pointer to the character +terminating the scan in ``*se``. If the answer would overflow, a +properly signed ``HUGE_VAL`` (infinity) is returned. If the answer would +underflow, a properly signed 0 is returned. In both cases, +``PR_GetError()`` returns the error code ``PR_RANGE_ERROR``. If no +number can be formed, ``se`` is set to ``s00``, and 0 is returned. diff --git a/docs/nspr/reference/pr_sync.rst b/docs/nspr/reference/pr_sync.rst new file mode 100644 index 0000000000..5d6df28689 --- /dev/null +++ b/docs/nspr/reference/pr_sync.rst @@ -0,0 +1,40 @@ +PR_Sync +======= + +Synchronizes any buffered data for a file descriptor to its backing +device (disk). + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_Sync(PRFileDesc *fd); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``fd`` + Pointer to a :ref:`PRFileDesc` object representing a file. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- On successful completion, ``PR_SUCCESS``. +- If the function fails, ``PR_FAILURE``. + + +Description +----------- + +:ref:`PR_Sync` writes all the in-memory buffered data of the specified file +to the disk. diff --git a/docs/nspr/reference/pr_tickspersecond.rst b/docs/nspr/reference/pr_tickspersecond.rst new file mode 100644 index 0000000000..362a817d94 --- /dev/null +++ b/docs/nspr/reference/pr_tickspersecond.rst @@ -0,0 +1,36 @@ +PR_TicksPerSecond +================= + +Returns the number of ticks per second currently used to determine the +value of :ref:`PRIntervalTime`. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + PRUint32 PR_TicksPerSecond(void); + + +Returns +~~~~~~~ + +An integer between 1000 and 100000 indicating the number of ticks per +second counted by :ref:`PRIntervalTime` on the current platform. This value +is platform-dependent and does not change after NSPR is initialized. + + +Description +----------- + +The value returned by ``PR_TicksPerSecond()`` lies between +``PR_INTERVAL_MIN`` and ``PR_INTERVAL_MAX``. + +The relationship between a :ref:`PRIntervalTime` tick and standard clock +units is platform-dependent. PR\_\ ``PR_TicksPerSecond()`` allows you to +discover exactly what that relationship is. Seconds per tick (the +inverse of PR\_\ ``PR_TicksPerSecond()``) is always between 10 +microseconds and 1 millisecond. diff --git a/docs/nspr/reference/pr_transmitfile.rst b/docs/nspr/reference/pr_transmitfile.rst new file mode 100644 index 0000000000..c9812b072e --- /dev/null +++ b/docs/nspr/reference/pr_transmitfile.rst @@ -0,0 +1,76 @@ +PR_TransmitFile +=============== + +Sends a complete file across a connected socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_TransmitFile( + PRFileDesc *networkSocket, + PRFileDesc *sourceFile, + const void *headers, + PRInt32 hlen, + PRTransmitFileFlags flags, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``networkSocket`` + A pointer to a :ref:`PRFileDesc` object representing the connected + socket to send data over. +``sourceFile`` + A pointer to a :ref:`PRFileDesc` object representing the file to send. +``headers`` + A pointer to the buffer holding the headers to be sent before sending + data. +``hlen`` + Length of the ``headers`` buffer in bytes. +``flags`` + One of the following flags: + + - :ref:`PR_TRANSMITFILE_KEEP_OPEN` indicates that the socket will be kept + open after the data is sent. + - :ref:`PR_TRANSMITFILE_CLOSE_SOCKET` indicates that the connection should + be closed immediately after successful transfer of the file. + +``timeout`` + Time limit for completion of the transmit operation. + + +Returns +~~~~~~~ + +- A positive number indicates the number of bytes successfully written, + including both the headers and the file. +- The value -1 indicates a failure. If an error occurs while sending + the file, the ``PR_TRANSMITFILE_CLOSE_SOCKET`` flag is ignored. The + reason for the failure can be obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +The :ref:`PR_TransmitFile` function sends a complete file (``sourceFile``) +across a connected socket (``networkSocket``). If ``headers`` is +non-``NULL``, :ref:`PR_TransmitFile` sends the headers across the socket +before sending the file. + +The enumeration ``PRTransmitFileFlags``, used in the ``flags`` +parameter, is defined as follows: + +.. code:: + + typedef enum PRTransmitFileFlags { + PR_TRANSMITFILE_KEEP_OPEN = 0, + PR_TRANSMITFILE_CLOSE_SOCKET = 1 + } PRTransmitFileFlags; diff --git a/docs/nspr/reference/pr_unblockclockinterrupts.rst b/docs/nspr/reference/pr_unblockclockinterrupts.rst new file mode 100644 index 0000000000..79bf984272 --- /dev/null +++ b/docs/nspr/reference/pr_unblockclockinterrupts.rst @@ -0,0 +1,14 @@ +PR_UnblockClockInterrupts +========================= + +Unblocks the timer signal used for preemptive scheduling. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + void PR_UnblockClockInterrupts(void); diff --git a/docs/nspr/reference/pr_unloadlibrary.rst b/docs/nspr/reference/pr_unloadlibrary.rst new file mode 100644 index 0000000000..fc9659c4e4 --- /dev/null +++ b/docs/nspr/reference/pr_unloadlibrary.rst @@ -0,0 +1,41 @@ +PR_UnloadLibrary +================ + +Unloads a library loaded with :ref:`PR_LoadLibrary`. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + PRStatus PR_UnloadLibrary(PRLibrary *lib); + + +Parameters +~~~~~~~~~~ + +The function has this parameter: + +``lib`` + A reference previously returned from :ref:`PR_LoadLibrary`. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. Use :ref:`PR_GetError` to find the + reason for the failure. + + +Description +----------- + +This function undoes the effect of a :ref:`PR_LoadLibrary`. After calling +this function, future references to the library using its identity as +returned by :ref:`PR_LoadLibrary` will be invalid. diff --git a/docs/nspr/reference/pr_unlock.rst b/docs/nspr/reference/pr_unlock.rst new file mode 100644 index 0000000000..4243a7510f --- /dev/null +++ b/docs/nspr/reference/pr_unlock.rst @@ -0,0 +1,43 @@ +PR_Unlock +========= + +Releases a specified lock object. Releasing an unlocked lock results in +an error. + +Attempting to release a lock that was locked by a different thread +causes undefined behavior. + + +Syntax +------ + +.. code:: + + #include <prlock.h> + + PRStatus PR_Unlock(PRLock *lock); + + +Parameter +~~~~~~~~~ + +:ref:`PR_Unlock` has one parameter: + +``lock`` + A pointer to a lock object to be released. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful (for example, if the caller does not own the lock), + ``PR_FAILURE``. + + +See Also +-------- + +- `PR_Lock <PR_Lock>`__ diff --git a/docs/nspr/reference/pr_unmap.rst b/docs/nspr/reference/pr_unmap.rst new file mode 100644 index 0000000000..85182b6e02 --- /dev/null +++ b/docs/nspr/reference/pr_unmap.rst @@ -0,0 +1,45 @@ +PR_MemUnmap +=========== + +Unmap a memory region that is backed by a memory-mapped file. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRStatus PR_MemUnmap( + void *addr, + PRUint32 len); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``addr`` + The starting address of the memory region to be unmapped. +``len`` + The length, in bytes, of the memory region. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the memory region is successfully unmapped, ``PR_SUCCESS``. +- If the memory region is not successfully unmapped, ``PR_FAILURE``. + The error code can be retrieved via :ref:`PR_GetError`. + + +Description +----------- + +:ref:`PR_MemUnmap` removes the file mapping for the memory region +(``addr``, ``addr + len``). The parameter ``addr`` is the return value +of an earlier call to :ref:`PR_MemMap`. diff --git a/docs/nspr/reference/pr_usec_per_msec.rst b/docs/nspr/reference/pr_usec_per_msec.rst new file mode 100644 index 0000000000..afed88bd57 --- /dev/null +++ b/docs/nspr/reference/pr_usec_per_msec.rst @@ -0,0 +1,16 @@ +PR_USEC_PER_MSEC +================ + +A convenience macro to improve code readability as well as to avoid +mistakes in counting the number of zeros; represents the number of +microseconds in a millisecond. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + #define PR_USEC_PER_MSEC 1000UL diff --git a/docs/nspr/reference/pr_usec_per_sec.rst b/docs/nspr/reference/pr_usec_per_sec.rst new file mode 100644 index 0000000000..8389f7db6b --- /dev/null +++ b/docs/nspr/reference/pr_usec_per_sec.rst @@ -0,0 +1,16 @@ +PR_USEC_PER_SEC +=============== + +A convenience macro to improve code readability as well as to avoid +mistakes in counting the number of zeros; represents the number of +microseconds in a second. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + #define PR_USEC_PER_SEC 1000000UL diff --git a/docs/nspr/reference/pr_version.rst b/docs/nspr/reference/pr_version.rst new file mode 100644 index 0000000000..bb838b14ff --- /dev/null +++ b/docs/nspr/reference/pr_version.rst @@ -0,0 +1,19 @@ +PR_VERSION +========== + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + #define PR_VERSION "2.1 yyyymmdd" + + +Description +----------- + +The format of the version string is\ *MajorVersion.MinorVersion +BuildDate*. diff --git a/docs/nspr/reference/pr_versioncheck.rst b/docs/nspr/reference/pr_versioncheck.rst new file mode 100644 index 0000000000..5d42827ad3 --- /dev/null +++ b/docs/nspr/reference/pr_versioncheck.rst @@ -0,0 +1,50 @@ +PR_VersionCheck +=============== + +Compares the version of NSPR assumed by the caller (the imported +version) with the version being offered by the runtime (the exported +version). + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + PRBool PR_VersionCheck(const char *importedVersion); + + +Parameter +~~~~~~~~~ + +:ref:`PR_VersionCheck` has one parameter: + +``importedVersion`` + The version of the shared library being imported. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If the version of the shared library is compatible with that expected + by the caller, ``PR_TRUE``. +- If the versions are not compatible, ``PR_FALSE``. + + +Description +----------- + +:ref:`PR_VersionCheck` tests whether the version of the library being +imported (``importedVersion``) is compatible with the running version of +the shared library. This is a string comparison of sorts, though the +details of the comparison will vary over time. + + +See Also +-------- + +- `PR_VERSION <PR_VERSION>`__ diff --git a/docs/nspr/reference/pr_wait.rst b/docs/nspr/reference/pr_wait.rst new file mode 100644 index 0000000000..3eb6e16f30 --- /dev/null +++ b/docs/nspr/reference/pr_wait.rst @@ -0,0 +1,82 @@ +PR_Wait +======= + +Waits for an application-defined state of the monitored data to exist. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + PRStatus PR_Wait( + PRMonitor *mon, + PRIntervalTime ticks); + + +Parameters +~~~~~~~~~~ + +The function has the following parameter: + +``mon`` + A reference to an existing structure of type :ref:`PRMonitor`. The + monitor object referenced must be one for which the calling thread + currently holds the lock. +``ticks`` + The amount of time (in :ref:`PRIntervalTime` units) that the thread is + willing to wait for an explicit notification before being + rescheduled. + + +Returns +~~~~~~~ + +The function returns one of the following values: + + - :ref:`PR_SUCCESS`` means the thread is being resumed from the ``PR_Wait` + call either because it was explicitly notified or because the time + specified by the parameter ``ticks`` has expired. + - :ref:`PR_FAILURE` means ``PR_Wait`` encountered a system error (such as + an invalid monitor reference) or the thread was interrupted by + another thread. + + +Description +----------- + +A call to :ref:`PR_Wait` causes the thread to release the monitor's lock, +just as if it had called :ref:`PR_ExitMonitor` as many times as it had +called :ref:`PR_EnterMonitor`. This has the effect of making the monitor +available to other threads. When the wait is over, the thread regains +control of the monitor's lock with the same entry count it had before +the wait began. + +A thread waiting on the monitor resumes when the monitor is notified or +when the timeout specified by the ``ticks`` parameter elapses. The +resumption from the wait is merely a hint that a change of state has +occurred. It is the responsibility of the programmer to evaluate the +data and act accordingly. This is usually done by evaluating a Boolean +expression involving the monitored data. While the Boolean expression is +false, the thread should wait. The thread should act on the data only +when the expression is true. The boolean expression must be evaluated +while in the monitor and within a loop. + +In pseudo-code, the sequence is as follows: + +| ``PR_EnterMonitor(&ml);`` +| ``while (!expression) wait;`` +| ``... act on the state change ...`` +| ``PR_ExitMonitor(&ml);`` + +A thread can be resumed from a wait for a variety of reasons. The most +obvious is that it was notified by another thread. If the value of +timeout is not ``PR_INTERVAL_NO_TIMEOUT``, :ref:`PR_Wait` resumes execution +after the specified interval has expired. If a timeout value is used, +the Boolean expression must include elapsed time as part of the +monitored data. + +Resuming from the wait is merely an opportunity to evaluate the +expression, not an assertion that the expression is true. diff --git a/docs/nspr/reference/pr_waitcondvar.rst b/docs/nspr/reference/pr_waitcondvar.rst new file mode 100644 index 0000000000..f915464f7b --- /dev/null +++ b/docs/nspr/reference/pr_waitcondvar.rst @@ -0,0 +1,68 @@ +PR_WaitCondVar +============== + +Waits on a condition. + + +Syntax +------ + +.. code:: + + #include <prcvar.h> + + PRStatus PR_WaitCondVar( + PRCondVar *cvar, + PRIntervalTime timeout); + + +Parameters +~~~~~~~~~~ + +:ref:`PR_WaitCondVar` has the following parameters: + +``cvar`` + The condition variable on which to wait. +``timeout`` + The value ``PR_INTERVAL_NO_TIMEOUT`` requires that a condition be + notified (or the thread interrupted) before it will resume from the + wait. The value ``PR_INTERVAL_NO_WAIT`` causes the thread to release + the lock, possibly causing a rescheduling within the runtime, then + immediately attempt to reacquire the lock and resume. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful (for example, if the caller has not locked the lock + associated with the condition variable or the thread was interrupted + with :ref:`PR_Interrupt`), ``PR_FAILURE``. The details can be determined + with :ref:`PR_GetError`. + + +Description +----------- + +Before the call to :ref:`PR_WaitCondVar`, the lock associated with the +condition variable must be held by the calling thread. After a call to +:ref:`PR_WaitCondVar`, the lock is released and the thread is blocked in a +"waiting on condition" state until another thread notifies the condition +or a caller-specified amount of time expires. + +When the condition variable is notified, a thread waiting on that +condition moves from the "waiting on condition" state to the "ready" +state. When scheduled, the thread attempts to reacquire the lock that it +held when :ref:`PR_WaitCondVar` was called. + +Any value other than ``PR_INTERVAL_NO_TIMEOUT`` or +``PR_INTERVAL_NO_WAIT`` for the timeout parameter will cause the thread +to be rescheduled due to either explicit notification or the expiration +of the specified interval. The latter must be determined by treating +time as one part of the monitored data being protected by the lock and +tested explicitly for an expired interval. To detect the expiration of +the specified interval, call :ref:`PR_IntervalNow` before and after the +call to :ref:`PR_WaitCondVar` and compare the elapsed time with the +specified interval. diff --git a/docs/nspr/reference/pr_waitforpollableevent.rst b/docs/nspr/reference/pr_waitforpollableevent.rst new file mode 100644 index 0000000000..5996dd4872 --- /dev/null +++ b/docs/nspr/reference/pr_waitforpollableevent.rst @@ -0,0 +1,33 @@ +PR_WaitForPollableEvent +======================= + +Blocks the calling thread until the pollable event is set, and then +atomically unsetting the event before returning. + + +Syntax +------ + +.. code:: + + NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``event`` + Pointer to a :ref:`PRFileDesc` structure previously created via a call + to :ref:`PR_NewPollableEvent`. + + +Returns +~~~~~~~ + +The function returns one of the following values: + +- If successful, ``PR_SUCCESS``. +- If unsuccessful, ``PR_FAILURE``. The reason for the failure can be + retrieved via :ref:`PR_GetError`. diff --git a/docs/nspr/reference/pr_waitsemaphore.rst b/docs/nspr/reference/pr_waitsemaphore.rst new file mode 100644 index 0000000000..1a0c7b3d1c --- /dev/null +++ b/docs/nspr/reference/pr_waitsemaphore.rst @@ -0,0 +1,42 @@ +PR_WaitSemaphore +================ + +Returns the value of the environment variable. + + +Syntax +------ + +.. code:: + + #include <pripcsem.h> + + NSPR_API(PRStatus) PR_WaitSemaphore(PRSem *sem); + + +Parameter +~~~~~~~~~ + +The function has the following parameter: + +``sem`` + A pointer to a ``PRSem`` structure returned from a call to + :ref:`PR_OpenSemaphore`. + + +Returns +~~~~~~~ + +:ref:`PRStatus` + + +Description +----------- + +:ref:`PR_WaitSemaphore` tests the value of the semaphore. If the value of +the semaphore is > 0, the value of the semaphore is decremented and the +function returns. If the value of the semaphore is 0, the function +blocks until the value becomes > 0, then the semaphore is decremented +and the function returns. + +The "test and decrement" operation is performed atomically. diff --git a/docs/nspr/reference/pr_write.rst b/docs/nspr/reference/pr_write.rst new file mode 100644 index 0000000000..2ec2f1e5c6 --- /dev/null +++ b/docs/nspr/reference/pr_write.rst @@ -0,0 +1,50 @@ +PR_Write +======== + +Writes a buffer of data to a file or socket. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Write( + PRFileDesc *fd, + const void *buf, + PRInt32 amount); + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to the :ref:`PRFileDesc` object for a file or socket. +``buf`` + A pointer to the buffer holding the data to be written. +``amount`` + The amount of data, in bytes, to be written from the buffer. + + +Returns +~~~~~~~ + +One of the following values: + +- A positive number indicates the number of bytes successfully written. +- The value -1 indicates that the operation failed. The reason for the + failure is obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +The thread invoking :ref:`PR_Write` blocks until all the data is written or +the write operation fails. Therefore, the return value is equal to +either ``amount`` (success) or -1 (failure). Note that if :ref:`PR_Write` +returns -1, some data (less than ``amount`` bytes) may have been written +before an error occurred. diff --git a/docs/nspr/reference/pr_writev.rst b/docs/nspr/reference/pr_writev.rst new file mode 100644 index 0000000000..0100b72afc --- /dev/null +++ b/docs/nspr/reference/pr_writev.rst @@ -0,0 +1,79 @@ +PR_Writev +========= + +Writes data to a socket from multiple buffers. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + PRInt32 PR_Writev( + PRFileDesc *fd, + PRIOVec *iov, + PRInt32 size, + PRIntervalTime timeout); + + #define PR_MAX_IOVECTOR_SIZE 16 + + +Parameters +~~~~~~~~~~ + +The function has the following parameters: + +``fd`` + A pointer to a :ref:`PRFileDesc` object for a socket. +``iov`` + An array of ``PRIOVec`` structures that describe the buffers to write + from. +``size`` + Number of ``PRIOVec`` structures in the ``iov`` array. The value of + this parameter must not be greater than ``PR_MAX_IOVECTOR_SIZE``. If + it is, the function will fail and the error will be set to + ``PR_BUFFER_OVERFLOW_ERROR``. +``timeout`` + A value of type :ref:`PRIntervalTime` describing the time limit for + completion of the entire write operation. + + +Returns +~~~~~~~ + +One of the following values: + +- A positive number indicates the number of bytes successfully written. +- The value -1 indicates that the operation failed. The reason for the + failure can be obtained by calling :ref:`PR_GetError`. + + +Description +----------- + +The thread calling :ref:`PR_Writev` blocks until all the data is written or +the write operation fails. Therefore, the return value is equal to +either the sum of all the buffer lengths (on success) or -1 (on +failure). Note that if :ref:`PR_Writev` returns -1, part of the data may +have been written before an error occurred. If the timeout parameter is +not ``PR_INTERVAL_NO_TIMEOUT`` and all the data cannot be written in the +specified interval, :ref:`PR_Writev` returns -1 with the error code +``PR_IO_TIMEOUT_ERROR``. + +This is the type definition for ``PRIOVec``: + +.. code:: + + typedef struct PRIOVec { + char *iov_base; + int iov_len; + } PRIOVec; + +The ``PRIOVec`` structure has the following fields: + +``iov_base`` + A pointer to the beginning of the buffer. +``iov_len`` + The size of the buffer. diff --git a/docs/nspr/reference/praccesshow.rst b/docs/nspr/reference/praccesshow.rst new file mode 100644 index 0000000000..b269dd93a1 --- /dev/null +++ b/docs/nspr/reference/praccesshow.rst @@ -0,0 +1,17 @@ +PRAccessHow +=========== + +This is the declaration for the enumeration :ref:`PRAccessHow`, used in the +``how`` parameter of :ref:`PR_Access`: + +.. code:: + + #include <prio.h> + + typedef enum PRAccessHow { + PR_ACCESS_EXISTS = 1, + PR_ACCESS_WRITE_OK = 2, + PR_ACCESS_READ_OK = 3 + } PRAccessHow; + +See `PR_Access <en/PR_Access>`__ for what each of these values mean. diff --git a/docs/nspr/reference/prbool.rst b/docs/nspr/reference/prbool.rst new file mode 100644 index 0000000000..098cbae81b --- /dev/null +++ b/docs/nspr/reference/prbool.rst @@ -0,0 +1,27 @@ +PRBool +====== + +Boolean value. + + +Syntax +~~~~~~ + +.. code:: + + #include <prtypes.h> + + typedef enum { PR_FALSE = 0, PR_TRUE = 1 } PRBool; + + +Description +~~~~~~~~~~~ + +Wherever possible, do not use PRBool in Mozilla C++ code. Use standard +C++ ``bool`` instead. + +Otherwise, use :ref:`PRBool` for variables and parameter types. Use +``PR_FALSE`` and ``PR_TRUE`` for clarity of target type in assignments +and actual arguments. Use ``if (bool)``, ``while (!bool)``, +``(bool) ? x : y``, and so on to test Boolean values, just as you would +C ``int``-valued conditions. diff --git a/docs/nspr/reference/prcalloncefn.rst b/docs/nspr/reference/prcalloncefn.rst new file mode 100644 index 0000000000..da37a9c86e --- /dev/null +++ b/docs/nspr/reference/prcalloncefn.rst @@ -0,0 +1,22 @@ +PRCallOnceFN +============ + +Defines the signature of the function a client must implement. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + typedef PRStatus (PR_CALLBACK *PRCallOnceFN)(void); + + +Description +----------- + +The function is called to perform the initialization desired. The +function is expected to return a :ref:`PRStatus` indicating the outcome of +the process. diff --git a/docs/nspr/reference/prcalloncetype.rst b/docs/nspr/reference/prcalloncetype.rst new file mode 100644 index 0000000000..6d306d0222 --- /dev/null +++ b/docs/nspr/reference/prcalloncetype.rst @@ -0,0 +1,41 @@ +PRCallOnceType +============== + +Structure for tracking initialization. + + +Syntax +------ + +.. code:: + + #include <prinit.h> + + typedef struct PRCallOnceType { + PRIntn initialized; + PRInt32 inProgress; + PRStatus status; + } PRCallOnceType; + + +Fields +~~~~~~ + +The structure has these fields: + +``initialized`` + If not zero, the initialization process has been completed. +``inProgress`` + If not zero, the initialization process is currently being executed. + Calling threads that observe this status block until inProgress is + zero. +``status`` + An indication of the outcome of the initialization process. + + +Description +----------- + +The client is responsible for initializing the :ref:`PRCallOnceType` +structure to all zeros. This initialization must be accomplished before +any threading issues exist. diff --git a/docs/nspr/reference/prclist.rst b/docs/nspr/reference/prclist.rst new file mode 100644 index 0000000000..05dfdd5255 --- /dev/null +++ b/docs/nspr/reference/prclist.rst @@ -0,0 +1,27 @@ +PRCList +======= + +A circular linked list. + + +Syntax +------ + +.. code:: + + #include <prclist.h> + + typedef struct PRCListStr PRCList; + + typedef struct PRCListStr { + PRCList *next; + PRCList *previous; + }; + + +Description +----------- + +PRClist defines a node in a circular linked list. It can be used as the +anchor of a list and can be embedded in data structures that are +maintained in a linked list. diff --git a/docs/nspr/reference/prcondvar.rst b/docs/nspr/reference/prcondvar.rst new file mode 100644 index 0000000000..6d40fe224d --- /dev/null +++ b/docs/nspr/reference/prcondvar.rst @@ -0,0 +1,20 @@ +PRCondVar +========= + +Structure for a condition variable. + + +Syntax +------ + +.. code:: + + #include <prcvar.h> + + typedef struct PRCondVar PRCondVar; + + +Description +----------- + +An NSPR condition variable is an opaque object identified by a pointer. diff --git a/docs/nspr/reference/prdescidentity.rst b/docs/nspr/reference/prdescidentity.rst new file mode 100644 index 0000000000..da900f37a7 --- /dev/null +++ b/docs/nspr/reference/prdescidentity.rst @@ -0,0 +1,36 @@ +PRDescIdentity +============== + +The identity of a file descriptor's layer. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef PRUintn PRDescIdentity; + + +Description +----------- + +File descriptors may be layered. Each layer has it own identity. +Identities are allocated by the runtime and are to be associated (by the +layer implementer) with all file descriptors of that layer. It is then +possible to scan the chain of layers and find a layer that one +recognizes, then predict that it will implement a desired protocol. + +There are three well-known identities: + + - :ref:`PR_INVALID_IO_LAYER`, an invalid layer identity, for error return + - :ref:`PR_TOP_IO_LAYER`, the identity of the top of the stack + - :ref:`PR_NSPR_IO_LAYER`, the identity used by NSPR proper + +Layers are created by :ref:`PR_GetUniqueIdentity`. A string may be +associated with a layer when the layer is created. The string is copied +by the runtime, and :ref:`PR_GetNameForIdentity` returns a reference to +that copy. There is no way to delete a layer's identity after the layer +is created. diff --git a/docs/nspr/reference/prdir.rst b/docs/nspr/reference/prdir.rst new file mode 100644 index 0000000000..feabd3eafc --- /dev/null +++ b/docs/nspr/reference/prdir.rst @@ -0,0 +1,26 @@ +PRDir +===== + +Directory structure used with `Directory I/O +Functions <I_O_Functions#Directory_I.2FO_Functions>`__. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef struct PRDir PRDir; + + +Description +----------- + +The opaque structure :ref:`PRDir` represents an open directory in the file +system. The function :ref:`PR_OpenDir` opens a specified directory and +returns a pointer to a :ref:`PRDir` structure, which can be passed to +:ref:`PR_ReadDir` repeatedly to obtain successive entries (files or +subdirectories in the open directory). To close the directory, pass the +:ref:`PRDir` pointer to :ref:`PR_CloseDir`. diff --git a/docs/nspr/reference/prerrorcode.rst b/docs/nspr/reference/prerrorcode.rst new file mode 100644 index 0000000000..9207ab80f7 --- /dev/null +++ b/docs/nspr/reference/prerrorcode.rst @@ -0,0 +1,30 @@ +PRErrorCode +=========== + + +Type for error codes that can be retrieved with :ref:`PR_GetError`. You can +also set your own errors using :ref:`PR_SetError`. + + +Syntax +------ + +.. code:: + + #include <prerror.h> + + typedef PRInt32 PRErrorCode + + +Description +----------- + +The service NSPR offers in this area is the ability to associate a +thread-specific condition with an error number. The error number +namespace is not well managed. NSPR assumes error numbers starting at +-6000 (decimal) and progressing towards zero. At present less than 100 +error codes have been defined. If NSPR's error handling is adopted by +calling clients, then some sort of partitioning of the namespace will +have to be employed. NSPR does not attempt to address this issue. + +For NSPR errors, see `Error Codes <NSPR_Error_Handling#Error_Code>`__. diff --git a/docs/nspr/reference/prexplodedtime.rst b/docs/nspr/reference/prexplodedtime.rst new file mode 100644 index 0000000000..c970394709 --- /dev/null +++ b/docs/nspr/reference/prexplodedtime.rst @@ -0,0 +1,70 @@ +PRExplodedTime +============== + +A clock/calendar representation of times. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + typedef struct PRExplodedTime { + PRInt32 tm_usec; + PRInt32 tm_sec; + PRInt32 tm_min; + PRInt32 tm_hour; + PRInt32 tm_mday; + PRInt32 tm_month; + PRInt16 tm_year; + PRInt8 tm_wday; + PRInt16 tm_yday; + PRTimeParameters tm_params; + } PRExplodedTime; + + +Description +----------- + +The :ref:`PRExplodedTime` structure represents clock/calendar time. +:ref:`PRExplodedTime` has the familiar time components: year, month, day of +month, hour, minute, second. It also has a microsecond component, as +well as the day of week and the day of year. In addition, +:ref:`PRExplodedTime` includes a :ref:`PRTimeParameters` structure +representing the local time zone information, so that the time point is +non-ambiguously specified. + +The essential members of :ref:`PRExplodedTime` are: + + - :ref:`tm_year`: absolute year, AD (by "absolute," we mean if the year is + 2000, this field's value is 2000). + - :ref:`tm_month`: number of months past tm_year. The range is [0, 11]. 0 + is January and 11 is December. + - :ref:`tm_mday`: the day of month. The range is [1, 31]. Note that it + starts from 1 as opposed to 0. + - :ref:`tm_hour`: number of hours past tm_mday. The range is [0, 23]. + - :ref:`tm_min`: number of minutes past tm_hour. The range is [0, 59]. + - :ref:`tm_sec`: number of seconds past tm_min. The range is [0, 61]. The + values 60 and 61 are for accommodating up to two leap seconds. + - :ref:`tm_usec`: number of microseconds past tm_sec. The range is [0, + 999999]. + - :ref:`tm_params`: a `PRTimeParameters` structure representing the + local time zone information. + +The nonessential members of :ref:`PRExplodedTime` are: + + - :ref:`tm_wday`: day of week. The range is [0, 6]. 0 is Sunday, 1 is + Monday, and 6 is Saturday. + - :ref:`tm_yday`: day of year. The range is [0, 365]. 0 is the 1st of + January. + +On input to NSPR functions, only the essential members of +:ref:`PRExplodedTime` must be specified. The two nonessential members (day +of week and day of year) are ignored by NSPR functions as input. When an +NSPR function returns a :ref:`PRExplodedTime` object or sets a +:ref:`PRExplodedTime` object as output, all of the :ref:`PRExplodedTime` +members are set, including the nonessential members. You can also use +``PR_NormalizeTime()`` to calculate the values of the nonessential +members. diff --git a/docs/nspr/reference/prfiledesc.rst b/docs/nspr/reference/prfiledesc.rst new file mode 100644 index 0000000000..50df48f83f --- /dev/null +++ b/docs/nspr/reference/prfiledesc.rst @@ -0,0 +1,53 @@ +PRFileDesc +========== + +A file descriptor used to represent any open file, such as a normal +file, an end point of a pipe, or a socket (end point of network +communication). + + +Syntax +------ + +.. code:: + + #include <prio.h> + + struct PRFileDesc { + PRIOMethods *methods; + PRFilePrivate *secret; + PRFileDesc *lower, *higher; + void (*dtor)(PRFileDesc *fd); + PRDescIdentity identity; + }; + + typedef struct PRFileDesc PRFileDesc; + + +Parameters +~~~~~~~~~~ + +``methods`` + The I/O methods table. See :ref:`PRIOMethods`. +``secret`` + Layer-dependent implementation data. See :ref:`PRFilePrivate`. +``lower`` + Pointer to lower layer. +``higher`` + Pointer to higher layer. +``dtor`` + A destructor function for the layer. +``identity`` + Identity of this particular layer. See :ref:`PRDescIdentity`. + + +Description +----------- + +The fields of this structure are significant only if you are +implementing a layer on top of NSPR, such as SSL. Otherwise, you use +functions such as :ref:`PR_Open` and :ref:`PR_NewTCPSocket` to obtain a file +descriptor, which you should treat as an opaque structure. + +For more details about the use of :ref:`PRFileDesc` and related structures, +see `File Descriptor Types <I_O_Types#File_Descriptor_Types>`__. diff --git a/docs/nspr/reference/prfileinfo.rst b/docs/nspr/reference/prfileinfo.rst new file mode 100644 index 0000000000..2fe487ac2f --- /dev/null +++ b/docs/nspr/reference/prfileinfo.rst @@ -0,0 +1,49 @@ +PRFileInfo +========== + +File information structure used with :ref:`PR_GetFileInfo` and +:ref:`PR_GetOpenFileInfo`. + + +Syntax +~~~~~~ + +.. code:: + + #include <prio.h> + + struct PRFileInfo { + PRFileType type; + PRUint32 size; + PRTime creationTime; + PRTime modifyTime; + }; + + typedef struct PRFileInfo PRFileInfo; + + + + +Fields +~~~~~~ + +The structure has the following fields: + +``type`` + Type of file. See :ref:`PRFileType`. +``size`` + Size, in bytes, of file's contents. +``creationTime`` + Creation time per definition of :ref:`PRTime`. See + `prtime.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtime.h>`__. +``modifyTime`` + Last modification time per definition of :ref:`PRTime`. See + `prtime.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtime.h>`__. + + +Description +----------- + +The :ref:`PRFileInfo` structure provides information about a file, a +directory, or some other kind of file system object, as specified by the +``type`` field. diff --git a/docs/nspr/reference/prfileinfo64.rst b/docs/nspr/reference/prfileinfo64.rst new file mode 100644 index 0000000000..329a98bccc --- /dev/null +++ b/docs/nspr/reference/prfileinfo64.rst @@ -0,0 +1,47 @@ +PRFileInfo64 +============ + +File information structure used with :ref:`PR_GetFileInfo64` and +:ref:`PR_GetOpenFileInfo64`. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + struct PRFileInfo64 { + PRFileType type; + PRUint64 size; + PRTime creationTime; + PRTime modifyTime; + }; + + typedef struct PRFileInfo64 PRFileInfo64; + + +Fields +~~~~~~ + +The structure has the following fields: + +``type`` + Type of file. See :ref:`PRFileType`. +``size`` + 64-bit size, in bytes, of file's contents. +``creationTime`` + Creation time per definition of :ref:`PRTime`. See + `prtime.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtime.h>`__. +``modifyTime`` + Last modification time per definition of :ref:`PRTime`. See + `prtime.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtime.h>`__. + + +Description +----------- + +The :ref:`PRFileInfo64` structure provides information about a file, a +directory, or some other kind of file system object, as specified by the +``type`` field. diff --git a/docs/nspr/reference/prfilemap.rst b/docs/nspr/reference/prfilemap.rst new file mode 100644 index 0000000000..3002ee034d --- /dev/null +++ b/docs/nspr/reference/prfilemap.rst @@ -0,0 +1,27 @@ +PRFileMap +========= + +Type returned by :ref:`PR_CreateFileMap` and passed to :ref:`PR_MemMap` and +:ref:`PR_CloseFileMap`. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef struct PRFileMap PRFileMap; + + +Description +----------- + +The opaque structure :ref:`PRFileMap` represents a memory-mapped file +object. Before actually mapping a file to memory, you must create a +memory-mapped file object by calling :ref:`PR_CreateFileMap`, which returns +a pointer to :ref:`PRFileMap`. Then sections of the file can be mapped into +memory by passing the :ref:`PRFileMap` pointer to :ref:`PR_MemMap`. The +memory-mapped file object is closed by passing the :ref:`PRFileMap` pointer +to :ref:`PR_CloseFileMap`. diff --git a/docs/nspr/reference/prfileprivate.rst b/docs/nspr/reference/prfileprivate.rst new file mode 100644 index 0000000000..4fa215d9d3 --- /dev/null +++ b/docs/nspr/reference/prfileprivate.rst @@ -0,0 +1,24 @@ +PRFilePrivate +============= + + +Layer-dependent implementation data. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef struct PRFilePrivate PRFilePrivate; + + +Description +----------- + +A layer implementer should collect all the private data of the layer in +the :ref:`PRFilePrivate` structure. Each layer has its own definition of +:ref:`PRFilePrivate`, which is hidden from other layers as well as from the +users of the layer. diff --git a/docs/nspr/reference/prfiletype.rst b/docs/nspr/reference/prfiletype.rst new file mode 100644 index 0000000000..2382f50cca --- /dev/null +++ b/docs/nspr/reference/prfiletype.rst @@ -0,0 +1,34 @@ +PRFileType +========== + + +Type for enumerators used in the type field of the :ref:`PRFileInfo` and +:ref:`PRFileInfo64` structures. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef enum PRFileType{ + PR_FILE_FILE = 1, + PR_FILE_DIRECTORY = 2, + PR_FILE_OTHER = 3 + } PRFileType; + + +Enumerators +~~~~~~~~~~~ + +The enumeration has the following enumerators: + +``PR_FILE_FILE`` + The information in the structure describes a file. +``PR_FILE_DIRECTORY`` + The information in the structure describes a directory. +``PR_FILE_OTHER`` + The information in the structure describes some other kind of file + system object. diff --git a/docs/nspr/reference/prfloat64.rst b/docs/nspr/reference/prfloat64.rst new file mode 100644 index 0000000000..704eabec96 --- /dev/null +++ b/docs/nspr/reference/prfloat64.rst @@ -0,0 +1,15 @@ + +PRFloat64 +========= + +The NSPR floating-point type is always 64 bits. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef double PRFloat64; diff --git a/docs/nspr/reference/prhostent.rst b/docs/nspr/reference/prhostent.rst new file mode 100644 index 0000000000..daf2d89d40 --- /dev/null +++ b/docs/nspr/reference/prhostent.rst @@ -0,0 +1,69 @@ +PRHostEnt +========= + +A structure that defines a list of network addresses. This structure is +output from :ref:`PR_GetHostByName` and :ref:`PR_GetHostByAddr` and passed to +:ref:`PR_EnumerateHostEnt`. Clients should avoid directly accessing any of +the structure's fields. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + typedef struct PRHostEnt { + char *h_name; + char **h_aliases; + #if defined(_WIN32) + PRInt16 h_addrtype; + PRInt16 h_length; + #else + PRInt32 h_addrtype; + PRInt32 h_length; + #endif + char **h_addr_list; + } PRHostEnt; + + +Fields +~~~~~~ + +The structure has the following fields: + +``h_name`` + Pointer to the official name of host. +``h_aliases`` + Pointer to a pointer to list of aliases. The list is terminated with + a ``NULL`` entry. +``h_addrtype`` + Host address type. For valid NSPR usage, this field must have a value + indicating either an IPv4 or an IPv6 address. +``h_length`` + Length of internal representation of the address in bytes. All of the + addresses in the list are of the same type and therefore of the same + length. +``h_addr_list`` + Pointer to a pointer to a list of addresses from name server (in + network byte order). The list is terminated with a ``NULL`` entry. + + +Description +----------- + +This structure is used by many of the network address functions. All +addresses are passed in host order and returned in network order +(suitable for use in system calls). + +Use the network address functions to manipulate the :ref:`PRHostEnt` +structure. To make the transition to IP version 6 easier, it's best to +treat :ref:`PRHostEnt` as an opaque structure. + +Note +---- + +``WINSOCK.H`` defines ``h_addrtype`` and ``h_length`` as a 16-bit field, +whereas other platforms treat it as a 32-bit field. The ``#ifdef`` in +the structure allows direct assignment of the :ref:`PRHostEnt` structure. diff --git a/docs/nspr/reference/print16.rst b/docs/nspr/reference/print16.rst new file mode 100644 index 0000000000..8701a0ea5d --- /dev/null +++ b/docs/nspr/reference/print16.rst @@ -0,0 +1,14 @@ +PRInt16 +======= + +Guaranteed to be a signed 16-bit integer on all platforms. + + +Syntax +------ + +:: + + #include <prtypes.h> + + typedefdefinition PRInt16; diff --git a/docs/nspr/reference/print32.rst b/docs/nspr/reference/print32.rst new file mode 100644 index 0000000000..8b179c6f37 --- /dev/null +++ b/docs/nspr/reference/print32.rst @@ -0,0 +1,22 @@ +PRInt32 +======= + +Guaranteed to be a signed 32-bit integer on all platforms. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedefdefinition PRInt32; + + +Description +----------- + +May be defined as an ``int`` or a ``long``, depending on the platform. +For syntax details for each platform, see +`prtypes.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtypes.h>`__. diff --git a/docs/nspr/reference/print64.rst b/docs/nspr/reference/print64.rst new file mode 100644 index 0000000000..3ef8c31d3f --- /dev/null +++ b/docs/nspr/reference/print64.rst @@ -0,0 +1,22 @@ +PRInt64 +======= + +Guaranteed to be a signed 64-bit integer on all platforms. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef definition PRInt64; + + +Description +----------- + +May be defined in several different ways, depending on the platform. For +syntax details for each platform, see +`prtypes.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtypes.h>`__. diff --git a/docs/nspr/reference/print8.rst b/docs/nspr/reference/print8.rst new file mode 100644 index 0000000000..6dd21a8efe --- /dev/null +++ b/docs/nspr/reference/print8.rst @@ -0,0 +1,14 @@ +PRInt8 +====== + +Guaranteed to be a signed 8-bit integer on all platforms. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef definition PRInt8; diff --git a/docs/nspr/reference/printervaltime.rst b/docs/nspr/reference/printervaltime.rst new file mode 100644 index 0000000000..9367d6ad7f --- /dev/null +++ b/docs/nspr/reference/printervaltime.rst @@ -0,0 +1,72 @@ +PRIntervalTime +============== + +A platform-dependent type that represents a monotonically increasing +integer--the NSPR runtime clock. + + +Syntax +------ + +.. code:: + + #include <prinrval.h> + + typedef PRUint32 PRIntervalTime; + + #define PR_INTERVAL_MIN 1000UL + #define PR_INTERVAL_MAX 100000UL + + #define PR_INTERVAL_NO_WAIT 0UL + #define PR_INTERVAL_NO_TIMEOUT 0xffffffffUL + + +Description +----------- + +The units of :ref:`PRIntervalTime` are platform-dependent. They are chosen +to be appropriate for the host OS, yet provide sufficient resolution and +period to be useful to clients. + +The increasing interval value represented by :ref:`PRIntervalTime` wraps. +It should therefore never be used for intervals greater than +approximately 6 hours. Interval times are accurate regardless of host +processing requirements and are very cheap to acquire. + +The constants ``PR_INTERVAL_MIN`` and ``PR_INTERVAL_MAX`` define a range +in ticks per second. These constants bound both the period and the +resolution of a :ref:`PRIntervalTime` object. + +The reserved constants ``PR_INTERVAL_NO_WAIT`` and +``PR_INTERVAL_NO_TIMEOUT`` have special meaning for NSPR. They indicate +that the process should wait no time (return immediately) or wait +forever (never time out), respectively. + +.. _Important_Note: + +Important Note +~~~~~~~~~~~~~~ + +The counters used for interval times are allowed to overflow. Since the +sampling of the counter used to define an arbitrary epoch may have any +32-bit value, some care must be taken in the use of interval times. The +proper coding style to test the expiration of an interval is as follows: + +.. code:: + + if ((PRIntervalTime)(now - epoch) > interval) + <... interval has expired ...> + +As long as the interval and the elapsed time (now - epoch) do not exceed +half the namespace allowed by a :ref:`PRIntervalTime` (2\ :sup:`31`-1), the +expression shown above provides the expected result even if the signs of +now and epoch differ. + +The resolution of a :ref:`PRIntervalTime` object is defined by the API. +NSPR guarantees that there will be at least 1000 ticks per second and +not more than 100000. At the maximum resolution of 10000 ticks per +second, each tick represents 1/100000 of a second. At that rate, a +32-bit register will overflow in approximately 28 hours, making the +maximum useful interval approximately 6 hours. Waiting on events more +than half a day in the future must therefore be based on a calendar +time. diff --git a/docs/nspr/reference/printn.rst b/docs/nspr/reference/printn.rst new file mode 100644 index 0000000000..0d7a465da8 --- /dev/null +++ b/docs/nspr/reference/printn.rst @@ -0,0 +1,17 @@ +PRIntn +====== + +This type is one of the most appropriate for automatic variables. It is +guaranteed to be at least 16 bits, though various architectures may +define it to be wider (for example, 32 or even 64 bits). This types is +never valid for fields of a structure. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef int PRIntn; diff --git a/docs/nspr/reference/priomethods.rst b/docs/nspr/reference/priomethods.rst new file mode 100644 index 0000000000..127c64f543 --- /dev/null +++ b/docs/nspr/reference/priomethods.rst @@ -0,0 +1,132 @@ +PRIOMethods +=========== + +The table of I/O methods used in a file descriptor. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + struct PRIOMethods { + PRDescType file_type; + PRCloseFN close; + PRReadFN read; + PRWriteFN write; + PRAvailableFN available; + PRAvailable64FN available64; + PRFsyncFN fsync; + PRSeekFN seek; + PRSeek64FN seek64; + PRFileInfoFN fileInfo; + PRFileInfo64FN fileInfo64; + PRWritevFN writev; + PRConnectFN connect; + PRAcceptFN accept; + PRBindFN bind; + PRListenFN listen; + PRShutdownFN shutdown; + PRRecvFN recv; + PRSendFN send; + PRRecvfromFN recvfrom; + PRSendtoFN sendto; + PRPollFN poll; + PRAcceptreadFN acceptread; + PRTransmitfileFN transmitfile; + PRGetsocknameFN getsockname; + PRGetpeernameFN getpeername; + PRGetsockoptFN getsockopt; + PRSetsockoptFN setsockopt; + }; + + typedef struct PRIOMethods PRIOMethods; + + +Parameters +~~~~~~~~~~ + +``file_type`` + Type of file represented (tos). +``close`` + Close file and destroy descriptor. +``read`` + Read up to the specified number of bytes into buffer. +``write`` + Write specified number of bytes from buffer. +``available`` + Determine number of bytes available for reading. +``available64`` + Same as previous field, except 64-bit. +``fsync`` + Flush all in-memory buffers of file to permanent store. +``seek`` + Position the file pointer to the desired place. +``seek64`` + Same as previous field, except 64-bit. +``fileInfo`` + Get information about an open file. +``fileInfo64`` + Same as previous field, except 64-bit. +``writev`` + Write from a vector of buffers. +``connect`` + Connect to the specified network address. +``accept`` + Accept a connection from a network peer. +``bind`` + Associate a network address with the file descriptor. +``listen`` + Prepare to listen for network connections. +``shutdown`` + Shut down a network connection. +``recv`` + Receive up to the specified number of bytes. +``send`` + Send all the bytes specified. +``recvfrom`` + Receive up to the specified number of bytes and report network + source. +``sendto`` + Send bytes to specified network address. +``poll`` + Test the file descriptor to see if it is ready for I/O. +``acceptread`` + Accept and read from a new network file descriptor. +``transmitfile`` + Transmit an entire file to the specified socket. +``getsockname`` + Get network address associated with a file descriptor. +``getpeername`` + Get peer's network address. +``getsockopt`` + Get current setting of specified socket option. +``setsockopt`` + Set value of specified socket option. + + +Description +----------- + +You don't need to know the type declaration for each function listed in +the method table unless you are implementing a layer. For information +about each function, see the corresponding function description in this +document. For example, the ``write`` method in :ref:`PRIOMethods` +implements the :ref:`PR_Write` function. For type definition details, see +``prio.h``. + +The I/O methods table provides procedural access to the functions of the +file descriptor. It is the responsibility of a layer implementer to +provide suitable functions at every entry point (that is, for every +function in the I/O methods table). If a layer provides no +functionality, it should call the next lower (higher) function of the +same name (for example, the "close" method would return +``fd->lower->method->close(fd->lower)``). + +Not all functions in the methods table are implemented for all types of +files. For example, the seek method is implemented for normal files but +not for sockets. In cases where this partial implementation occurs, the +function returns an error indication with an error code of +``PR_INVALID_METHOD_ERROR``. diff --git a/docs/nspr/reference/pripv6addr.rst b/docs/nspr/reference/pripv6addr.rst new file mode 100644 index 0000000000..94250f5ad1 --- /dev/null +++ b/docs/nspr/reference/pripv6addr.rst @@ -0,0 +1,26 @@ +PRIPv6Addr +========== + +Type used in the ``ipv6.ip`` field of the :ref:`PRNetAddr` structure. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + #if defined(_PR_INET6) + typedef struct in6_addr PRIPv6Addr; + #endif /* defined(_PR_INET6) */ + + +Description +----------- + +PRIPv6Addr represents a 128-bit IPv6 address. It is equivalent to struct +``in6_addr`` in the Berkeley socket interface. :ref:`PRIPv6Addr` is always +manipulated as a byte array. Unlike the IPv4 address (a 4-byte unsigned +integer) or the port number (a 2-byte unsigned integer), it has no +network or host byte order. diff --git a/docs/nspr/reference/prjob.rst b/docs/nspr/reference/prjob.rst new file mode 100644 index 0000000000..7407f43cf1 --- /dev/null +++ b/docs/nspr/reference/prjob.rst @@ -0,0 +1,10 @@ +PRJob +===== + + +Syntax +------ + +:: + + #include <prtpool.h> diff --git a/docs/nspr/reference/prjobfn.rst b/docs/nspr/reference/prjobfn.rst new file mode 100644 index 0000000000..46e6bbc3f0 --- /dev/null +++ b/docs/nspr/reference/prjobfn.rst @@ -0,0 +1,12 @@ +PRJobFn +======= + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + typedef void (PR_CALLBACK *PRJobFn)(void *arg); diff --git a/docs/nspr/reference/prjobiodesc.rst b/docs/nspr/reference/prjobiodesc.rst new file mode 100644 index 0000000000..60d10a6dc2 --- /dev/null +++ b/docs/nspr/reference/prjobiodesc.rst @@ -0,0 +1,16 @@ +PRJobIoDesc +=========== + + +Syntax +------ + +.. code:: + + #include <prtpool.h> + + typedef struct PRJobIoDesc { + PRFileDesc *socket; + PRErrorCode error; + PRIntervalTime timeout; + } PRJobIoDesc; diff --git a/docs/nspr/reference/prlibrary.rst b/docs/nspr/reference/prlibrary.rst new file mode 100644 index 0000000000..d0c8ba1ad7 --- /dev/null +++ b/docs/nspr/reference/prlibrary.rst @@ -0,0 +1,22 @@ +PRLibrary +========= + +An opaque structure identifying a library. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + typedef struct PRLibrary PRLibrary; + + +Description +----------- + +A PRLibrary is an opaque structure. A reference to such a structure can +be returned by some of the functions in the runtime and serve to +identify a particular instance of a library. diff --git a/docs/nspr/reference/prlinger.rst b/docs/nspr/reference/prlinger.rst new file mode 100644 index 0000000000..9506dc0240 --- /dev/null +++ b/docs/nspr/reference/prlinger.rst @@ -0,0 +1,56 @@ +PRLinger +======== + +Structure used with the ``PR_SockOpt_Linger`` socket option to specify +the time interval (in :ref:`PRIntervalTime` units) to linger on closing a +socket if any data remain in the socket send buffer. + + +Syntax +~~~~~~ + +.. code:: + + #include <prio.h> + + typedef struct PRLinger { + PRBool polarity; + PRIntervalTime linger; + } PRLinger; + + +Fields +~~~~~~ + +The structure has the following fields: + +``polarity`` + Polarity of the option's setting: ``PR_FALSE`` means the option is + off, in which case the value of ``linger`` is ignored. ``PR_TRUE`` + means the option is on, and the value of ``linger`` will be used to + determine how long :ref:`PR_Close` waits before returning. +``linger`` + Time (in :ref:`PRIntervalTime` units) to linger before closing if any + data remain in the socket send buffer. + + +Description +~~~~~~~~~~~ + +By default, :ref:`PR_Close` returns immediately, but if there are any data +remaining in the socket send buffer, the system attempts to deliver the +data to the peer. The ``PR_SockOpt_Linger`` socket option, with a value +represented by a structure of type :ref:`PRLinger`, makes it possible to +change this default as follows: + +- If ``polarity`` is set to ``PR_FALSE``, :ref:`PR_Close` returns + immediately, but if there are any data remaining in the socket send + buffer, the runtime attempts to deliver the data to the peer. +- If ``polarity`` is set to ``PR_TRUE`` and ``linger`` is set to 0 + (``PR_INTERVAL_NO_WAIT``), the runtime aborts the connection when it + is closed and discards any data remaining in the socket send buffer. +- If ``polarity`` is set to ``PR_TRUE`` and ``linger`` is nonzero, the + runtime *lingers* when the socket is closed. That is, if any data + remains in the socket send buffer, :ref:`PR_Close` blocks until either + all the data is sent and acknowledged by the peer or the interval + specified by ``linger`` expires. diff --git a/docs/nspr/reference/prlock.rst b/docs/nspr/reference/prlock.rst new file mode 100644 index 0000000000..a7a736d340 --- /dev/null +++ b/docs/nspr/reference/prlock.rst @@ -0,0 +1,22 @@ +PRLock +====== + +A mutual exclusion lock. + + +Syntax +------ + +.. code:: + + #include <prlock.h> + + typedef struct PRLock PRLock; + + +Description +----------- + +NSPR represents a lock as an opaque entity to clients of the functions +described in `"Locks" <en/NSPR_API_Reference/Locks>`__. Functions that +operate on locks do not have timeouts and are not interruptible. diff --git a/docs/nspr/reference/prlogmoduleinfo.rst b/docs/nspr/reference/prlogmoduleinfo.rst new file mode 100644 index 0000000000..ea616e435a --- /dev/null +++ b/docs/nspr/reference/prlogmoduleinfo.rst @@ -0,0 +1,23 @@ +PR_NewLogModule +=============== + + +The ``PRLogModuleInfo`` structure controls logging from within your +application. To log your program's activity, create a +``PRLogModuleInfo`` structure using +`:ref:`PR_NewLogModule` <http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25372>`__ +. + + +Syntax +------ + +:: + + #include <prlog.h> + + typedef struct PRLogModuleInfo { + const char *name; + PRLogModuleLevel level; + struct PRLogModuleInfo *next; + } PRLogModuleInfo; diff --git a/docs/nspr/reference/prlogmodulelevel.rst b/docs/nspr/reference/prlogmodulelevel.rst new file mode 100644 index 0000000000..d9ed3f78ca --- /dev/null +++ b/docs/nspr/reference/prlogmodulelevel.rst @@ -0,0 +1,26 @@ +PRLogModuleLevel +================ + +The enumerated type :ref:`PRLogModuleLevel` defines levels of logging +available to application programs. + + +Syntax +------ + +:: + + #include <prlog.h> + + typedef enum PRLogModuleLevel { + PR_LOG_NONE = 0, + PR_LOG_ALWAYS = 1, + PR_LOG_ERROR = 2, + PR_LOG_WARNING = 3, + PR_LOG_DEBUG = 4, + + PR_LOG_NOTICE = PR_LOG_DEBUG, + PR_LOG_WARN = PR_LOG_WARNING, + PR_LOG_MIN = PR_LOG_DEBUG, + PR_LOG_MAX = PR_LOG_DEBUG + } PRLogModuleLevel; diff --git a/docs/nspr/reference/prmcastrequest.rst b/docs/nspr/reference/prmcastrequest.rst new file mode 100644 index 0000000000..9c7c63ecef --- /dev/null +++ b/docs/nspr/reference/prmcastrequest.rst @@ -0,0 +1,40 @@ +PRMcastRequest +============== + +Structure used to specify values for the ``PR_SockOpt_AddMember`` and +``PR_SockOpt_DropMember`` socket options that define a request to join +or leave a multicast group. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + struct PRMcastRequest { + PRNetAddr mcaddr; + PRNetAddr ifaddr; + }; + + typedef struct PRMcastRequest PRMcastRequest; + + +Fields +~~~~~~ + +The structure has the following fields: + +``mcaddr`` + IP multicast address of group. +``ifaddr`` + Local IP address of interface. + + +Description +----------- + +The ``mcaddr`` and ``ifaddr`` fields are of the type :ref:`PRNetAddr`, but +their ``port`` fields are ignored. Only the IP address (``inet.ip``) +fields are used. diff --git a/docs/nspr/reference/prmonitor.rst b/docs/nspr/reference/prmonitor.rst new file mode 100644 index 0000000000..5a420f9452 --- /dev/null +++ b/docs/nspr/reference/prmonitor.rst @@ -0,0 +1,15 @@ +PRMonitor +========= + +An opaque structure managed entirely by the client. Clients create them +when needed and must destroy them when no longer needed. + + +Syntax +------ + +.. code:: + + #include <prmon.h> + + typedef struct PRMonitor PRMonitor; diff --git a/docs/nspr/reference/prnetaddr.rst b/docs/nspr/reference/prnetaddr.rst new file mode 100644 index 0000000000..71fe1a65d4 --- /dev/null +++ b/docs/nspr/reference/prnetaddr.rst @@ -0,0 +1,85 @@ +PRNetAddr +========= + +Type used with `Socket Manipulation +Functions <Socket_Manipulation_Functions>`__ to specify a network +address. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + union PRNetAddr { + struct { + PRUint16 family; + char data[14]; + } raw; + struct { + PRUint16 family; + PRUint16 port; + PRUint32 ip; + char pad[8]; + } inet; + #if defined(_PR_INET6) + struct { + PRUint16 family; + PRUint16 port; + PRUint32 flowinfo; + PRIPv6Addr ip; + } ipv6; + #endif /* defined(_PR_INET6) */ + }; + + typedef union PRNetAddr PRNetAddr; + + +Fields +~~~~~~ + +The structure has the following fields: + +``family`` + Address family: ``PR_AF_INET|PR_AF_INET6`` for ``raw.family``, + ``PR_AF_INET`` for ``inet.family``, ``PR_AF_INET6`` for + ``ipv6.family``. +``data`` + Raw address data. +``port`` + Port number of TCP or UDP, in network byte order. +``ip`` + The actual 32 (for ``inet.ip``) or 128 (for ``ipv6.ip``) bits of IP + address. The ``inet.ip`` field is in network byte order. +``pad`` + Unused. +``flowinfo`` + Routing information. + + +Description +----------- + +The union :ref:`PRNetAddr` represents a network address. NSPR supports only +the Internet address family. By default, NSPR is built to support only +IPv4, but it's possible to build the NSPR library to support both IPv4 +and IPv6. Therefore, the ``family`` field can be ``PR_AF_INET`` only for +default NSPR, and can also be ``PR_AF_INET6`` if the binary supports +``IPv6``. + +:ref:`PRNetAddr` is binary-compatible with the socket address structures in +the familiar Berkeley socket interface, although this fact should not be +relied upon. The raw member of the union is equivalent to +``struct sockaddr``, the ``inet`` member is equivalent to +``struct sockaddr_in``, and if the binary is built with ``IPv6`` +support, the ``ipv6`` member is equivalent to ``struct sockaddr_in6``. +(Note that :ref:`PRNetAddr` does not have the ``length`` field that is +present in ``struct sockaddr_in`` on some Unix platforms.) + +The macros ``PR_AF_INET``, ``PR_AF_INET6``, ``PR_INADDR_ANY``, +``PR_INADDR_LOOPBACK`` are defined if ``prio.h`` is included. +``PR_INADDR_ANY`` and ``PR_INADDR_LOOPBACK`` are special ``IPv4`` +addresses in host byte order, so they must be converted to network byte +order before being assigned to the ``inet.ip`` field. diff --git a/docs/nspr/reference/process_initialization.rst b/docs/nspr/reference/process_initialization.rst new file mode 100644 index 0000000000..c5b0fd1763 --- /dev/null +++ b/docs/nspr/reference/process_initialization.rst @@ -0,0 +1,63 @@ +Process Initialization +====================== + +This chapter describes the NSPR API for versioning, process +initialization, and shutdown of NSPR. + +- `Identity and Versioning <#Identity_and_Versioning>`__ +- `Initialization and Cleanup <#Initialization_and_Cleanup>`__ +- `Module Initialization <#Module_Initialization>`__ + +.. _Identity_and_Versioning: + +Identity and Versioning +----------------------- + +.. _Name_and_Version_Constants: + +Name and Version Constants +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_NAME` + - :ref:`PR_VERSION` + - :ref:`PR_VersionCheck` + +.. _Initialization_and_Cleanup: + +Initialization and Cleanup +-------------------------- + +NSPR detects whether the library has been initialized and performs +implicit initialization if it hasn't. Implicit initialization should +suffice unless a program has specific sequencing requirements or needs +to characterize the primordial thread. Explicit initialization is rarely +necessary. + +Implicit initialization assumes that the initiator is the primordial +thread and that the thread is a user thread of normal priority. + + - :ref:`PR_Init` + - :ref:`PR_Initialize` + - :ref:`PR_Initialized` + - :ref:`PR_Cleanup` + - :ref:`PR_DisableClockInterrupts` + - :ref:`PR_BlockClockInterrupts` + - :ref:`PR_UnblockClockInterrupts` + - :ref:`PR_SetConcurrency` + - :ref:`PR_ProcessExit` + - :ref:`PR_Abort` + +.. _Module_Initialization: + +Module Initialization +~~~~~~~~~~~~~~~~~~~~~ + +Initialization can be tricky in a threaded environment, especially +initialization that must happen exactly once. :ref:`PR_CallOnce` ensures +that such initialization code is called only once. This facility is +recommended in situations where complicated global initialization is +required. + + - :ref:`PRCallOnceType` + - :ref:`PRCallOnceFN` + - :ref:`PR_CallOnce` diff --git a/docs/nspr/reference/process_management_and_interprocess_communication.rst b/docs/nspr/reference/process_management_and_interprocess_communication.rst new file mode 100644 index 0000000000..c508c7362c --- /dev/null +++ b/docs/nspr/reference/process_management_and_interprocess_communication.rst @@ -0,0 +1,64 @@ +Process Management And Interprocess Communication +================================================= + +This chapter describes the NSPR routines that deal with processes. A +process is an instance of a program. NSPR provides routines to create a +new process and to wait for the termination of another process. + +NSPR does not provide an equivalent of the Unix ``fork()``. The +newly-created process executes its program from the beginning. A new +process can inherit specified file descriptors from its parent, and the +parent can redirect the standard I/O streams of the child process to +specified file descriptors. + +Note that the functions described in this chapter are not available for +MacOS or Win16 operating systems. + +.. _Process_Management_Types_and_Constants: + +Process Management Types and Constants +-------------------------------------- + +The types defined for process management are: + + - :ref:`PRProcess` + - :ref:`PRProcessAttr` + +.. _Process_Management_Functions: + +Process Management Functions +---------------------------- + +The process manipulation function fall into these categories: + +- `Setting the Attributes of a New + Process <#Setting_the_Attributes_of_a_New_Process>`__ +- `Creating and Managing + Processes <#Creating_and_Managing_Processes>`__ + +.. _Setting_the_Attributes_of_a_New_Process: + +Setting the Attributes of a New Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The functions that create and manipulate attribute sets of new processes +are: + + - :ref:`PR_NewProcessAttr` + - :ref:`PR_ResetProcessAttr` + - :ref:`PR_DestroyProcessAttr` + - :ref:`PR_ProcessAttrSetStdioRedirect` + - :ref:`PR_ProcessAttrSetCurrentDirectory` + - :ref:`PR_ProcessAttrSetInheritableFD` + +.. _Creating_and_Managing_Processes: + +Creating and Managing Processes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The functions that create and manage processes are: + + - :ref:`PR_CreateProcess` + - :ref:`PR_DetachProcess` + - :ref:`PR_WaitProcess` + - :ref:`PR_KillProcess` diff --git a/docs/nspr/reference/prpackedbool.rst b/docs/nspr/reference/prpackedbool.rst new file mode 100644 index 0000000000..c32888de84 --- /dev/null +++ b/docs/nspr/reference/prpackedbool.rst @@ -0,0 +1,20 @@ +PRPackedBool +============ + +Packed Boolean value. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef PRUint8 PRPackedBool; + + +Description +----------- + +Use :ref:`PRPackedBool` within structures where bit fields are not desirable but minimum and consistent overhead matters. diff --git a/docs/nspr/reference/prprimordialfn.rst b/docs/nspr/reference/prprimordialfn.rst new file mode 100644 index 0000000000..5bb4266ff1 --- /dev/null +++ b/docs/nspr/reference/prprimordialfn.rst @@ -0,0 +1,19 @@ +PRPrimordialFn +============== + +The type for the root function used by :ref:`PR_Initialize` is specified as +follows: + + +Syntax +------ + +.. code:: + + typedef PRIntn (PR_CALLBACK *PRPrimordialFn)(PRIntn argc, char **argv); + + +See Also +-------- + + - :ref:`PR_Initialize` diff --git a/docs/nspr/reference/prprocess.rst b/docs/nspr/reference/prprocess.rst new file mode 100644 index 0000000000..b17db0b3da --- /dev/null +++ b/docs/nspr/reference/prprocess.rst @@ -0,0 +1,20 @@ +PRProcess +========= + +Represents a process. + + +Syntax +------ + +:: + + #include <prproces.h> + + typedef struct PRProcess PRProcess; + + +Description +----------- + +A pointer to the opaque :ref:`PRProcess` structure identifies a process. diff --git a/docs/nspr/reference/prprocessattr.rst b/docs/nspr/reference/prprocessattr.rst new file mode 100644 index 0000000000..65e48e1201 --- /dev/null +++ b/docs/nspr/reference/prprocessattr.rst @@ -0,0 +1,23 @@ +PRProcessAttr +============= + +Represents the attributes of a new process. + + +Syntax +------ + +:: + + #include <prproces.h> + + typedef struct PRProcessAttr PRProcessAttr; + + +Description +----------- + +This opaque structure describes the attributes of a process to be +created. Pass a pointer to a :ref:`PRProcessAttr` into ``PR_CreateProcess`` +when you create a new process, specifying information such as standard +input/output redirection and file descriptor inheritance. diff --git a/docs/nspr/reference/prprotoent.rst b/docs/nspr/reference/prprotoent.rst new file mode 100644 index 0000000000..6d913a1cc8 --- /dev/null +++ b/docs/nspr/reference/prprotoent.rst @@ -0,0 +1,37 @@ +PRProtoEnt +========== + +Protocol entry returned by :ref:`PR_GetProtoByName` and +:ref:`PR_GetProtoByNumber`. + + +Syntax +------ + +.. code:: + + #include <prnetdb.h> + + typedef struct PRProtoEnt { + char *p_name; + char **p_aliases; + #if defined(_WIN32) + PRInt16 p_num; + #else + PRInt32 p_num; + #endif + } PRProtoEnt; + + +Fields +~~~~~~ + +The structure has the following fields: + +``p_name`` + Pointer to official protocol name. +``p_aliases`` + Pointer to a pointer to a list of aliases. The list is terminated + with a ``NULL`` entry. +``p_num`` + Protocol number. diff --git a/docs/nspr/reference/prptrdiff.rst b/docs/nspr/reference/prptrdiff.rst new file mode 100644 index 0000000000..c069649215 --- /dev/null +++ b/docs/nspr/reference/prptrdiff.rst @@ -0,0 +1,14 @@ +PRPtrdiff +========= + +Signed pointer difference type. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef ptrdiff_t PRPtrdiff; diff --git a/docs/nspr/reference/prseekwhence.rst b/docs/nspr/reference/prseekwhence.rst new file mode 100644 index 0000000000..4d6ae71371 --- /dev/null +++ b/docs/nspr/reference/prseekwhence.rst @@ -0,0 +1,35 @@ +PRSeekWhence +============ + +Specifies how to interpret the ``offset`` parameter in setting the file +pointer associated with the ``fd`` parameter for the :ref:`PR_Seek` and +:ref:`PR_Seek64` functions. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef PRSeekWhence { + PR_SEEK_SET = 0, + PR_SEEK_CUR = 1, + PR_SEEK_END = 2 + } PRSeekWhence; + + +Enumerators +~~~~~~~~~~~ + +The enumeration has the following enumerators: + +``PR_SEEK_SET`` + Sets the file pointer to the value of the ``offset`` parameter. +``PR_SEEK_CUR`` + Sets the file pointer to its current location plus the value of the + ``offset`` parameter. +``PR_SEEK_END`` + Sets the file pointer to the size of the file plus the value of the + ``offset`` parameter. diff --git a/docs/nspr/reference/prsize.rst b/docs/nspr/reference/prsize.rst new file mode 100644 index 0000000000..8d0810574e --- /dev/null +++ b/docs/nspr/reference/prsize.rst @@ -0,0 +1,15 @@ +PRSize +====== + +A type for representing the size of an object (not the size of a +pointer). This is the same as the corresponding type in ``libc``. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef size_t PRSize; diff --git a/docs/nspr/reference/prsocketoptiondata.rst b/docs/nspr/reference/prsocketoptiondata.rst new file mode 100644 index 0000000000..442d1559e9 --- /dev/null +++ b/docs/nspr/reference/prsocketoptiondata.rst @@ -0,0 +1,83 @@ +PRSocketOptionData +================== + +Type for structure used with :ref:`PR_GetSocketOption` and +:ref:`PR_SetSocketOption` to specify options for file descriptors that +represent sockets. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef struct PRSocketOptionData + { + PRSockOption option; + union + { + PRUintn ip_ttl; + PRUintn mcast_ttl; + PRUintn tos; + PRBool non_blocking; + PRBool reuse_addr; + PRBool keep_alive; + PRBool mcast_loopback; + PRBool no_delay; + PRSize max_segment; + PRSize recv_buffer_size; + PRSize send_buffer_size; + PRLinger linger; + PRMcastRequest add_member; + PRMcastRequest drop_member; + PRNetAddr mcast_if; + } value; + } PRSocketOptionData; + + +Fields +~~~~~~ + +The structure has the following fields: + +``ip_ttl`` + IP time-to-live. +``mcast_ttl`` + IP multicast time-to-live. +``tos`` + IP type-of-service and precedence. +``non_blocking`` + Nonblocking (network) I/O. +``reuse_addr`` + Allow local address reuse. +``keep_alive`` + Periodically test whether connection is still alive. +``mcast_loopback`` + IP multicast loopback. +``no_delay`` + Disable Nagle algorithm. Don't delay send to coalesce packets. +``max_segment`` + TCP maximum segment size. +``recv_buffer_size`` + Receive buffer size. +``send_buffer_size`` + Send buffer size. +``linger`` + Time to linger on close if data are present in socket send buffer. +``add_member`` + Join an IP multicast group. +``drop_member`` + Leave an IP multicast group. +``mcast_if`` + IP multicast interface address. + + +Description +~~~~~~~~~~~ + +:ref:`PRSocketOptionData` is a name-value pair for a socket option. The +``option`` field (of enumeration type :ref:`PRSockOption`) specifies the +name of the socket option, and the ``value`` field (a union of all +possible values) specifies the value of the option. diff --git a/docs/nspr/reference/prsockoption.rst b/docs/nspr/reference/prsockoption.rst new file mode 100644 index 0000000000..daaa20cb21 --- /dev/null +++ b/docs/nspr/reference/prsockoption.rst @@ -0,0 +1,79 @@ +PRSockOption +============ + +Enumeration type used in the ``option`` field of :ref:`PRSocketOptionData` +to form the name portion of a name-value pair. + + +Syntax +------ + +.. code:: + + #include <prio.h> + + typedef enum PRSockOption { + PR_SockOpt_Nonblocking, + PR_SockOpt_Linger, + PR_SockOpt_Reuseaddr, + PR_SockOpt_Keepalive, + PR_SockOpt_RecvBufferSize, + PR_SockOpt_SendBufferSize, + PR_SockOpt_IpTimeToLive, + PR_SockOpt_IpTypeOfService, + PR_SockOpt_AddMember, + PR_SockOpt_DropMember, + PR_SockOpt_McastInterface, + PR_SockOpt_McastTimeToLive, + PR_SockOpt_McastLoopback, + PR_SockOpt_NoDelay, + PR_SockOpt_MaxSegment, + PR_SockOpt_Last + } PRSockOption; + + +Enumerators +~~~~~~~~~~~ + +The enumeration has the following enumerators: + +``PR_SockOpt_Nonblocking`` + Nonblocking I/O. +``PR_SockOpt_Linger`` + Time to linger on close if data is present in the socket send buffer. +``PR_SockOpt_Reuseaddr`` + Allow local address reuse. +``PR_SockOpt_Keepalive`` + Periodically test whether connection is still alive. +``PR_SockOpt_RecvBufferSize`` + Receive buffer size. +``PR_SockOpt_SendBufferSize`` + Send buffer size. +``PR_SockOpt_IpTimeToLive`` + IP time-to-live. +``PR_SockOpt_IpTypeOfService`` + IP type-of-service and precedence. +``PR_SockOpt_AddMember`` + Join an IP multicast group. +``PR_SockOpt_DropMember`` + Leave an IP multicast group. +``PR_SockOpt_McastInterface`` + IP multicast interface address. +``PR_SockOpt_McastTimeToLive`` + IP multicast time-to-live. +``PR_SockOpt_McastLoopback`` + IP multicast loopback. +``PR_SockOpt_NoDelay`` + Disable Nagle algorithm. Don't delay send to coalesce packets. +``PR_SockOpt_MaxSegment`` + Maximum segment size. +``PR_SockOpt_Last`` + Always one greater than the maximum valid socket option numerator. + + +Description +----------- + +The :ref:`PRSockOption` enumeration consists of all the socket options +supported by NSPR. The ``option`` field of :ref:`PRSocketOptionData` should +be set to an enumerator of type :ref:`PRSockOption`. diff --git a/docs/nspr/reference/prstaticlinktable.rst b/docs/nspr/reference/prstaticlinktable.rst new file mode 100644 index 0000000000..ce76ab10a3 --- /dev/null +++ b/docs/nspr/reference/prstaticlinktable.rst @@ -0,0 +1,22 @@ +PRStaticLinkTable +================= + +A static link table entry can be created by a client of the runtime so +that other clients can access static or dynamic libraries transparently. +The basic function on a dynamic library is to acquire a pointer to a +function that the library exports. If, during initialization, such +entries are manually created, then future attempts to link to the +symbols can be treated in a consistent fashion. + + +Syntax +------ + +.. code:: + + #include <prlink.h> + + typedef struct PRStaticLinkTable { + const char *name; + void (*fp)(); + } PRStaticLinkTable; diff --git a/docs/nspr/reference/prstatus.rst b/docs/nspr/reference/prstatus.rst new file mode 100644 index 0000000000..15106b276b --- /dev/null +++ b/docs/nspr/reference/prstatus.rst @@ -0,0 +1,14 @@ +PRStatus +======== + +Type for status code returned by some functions. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef enum { PR_FAILURE = -1, PR_SUCCESS = 0 } PRStatus; diff --git a/docs/nspr/reference/prthread.rst b/docs/nspr/reference/prthread.rst new file mode 100644 index 0000000000..7f479735f4 --- /dev/null +++ b/docs/nspr/reference/prthread.rst @@ -0,0 +1,26 @@ +PRThread +======== + +An NSPR thread. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef struct PRThread PRThread; + + +Description +~~~~~~~~~~~ + +In NSPR, a thread is represented by a pointer to an opaque structure of +type :ref:`PRThread`. This pointer is a required parameter for most of the +functions that operate on threads. + +A ``PRThread*`` is the successful result of creating a new thread. The +identifier remains valid until it returns from its root function and, if +the thread was created joinable, is joined. diff --git a/docs/nspr/reference/prthreadpool.rst b/docs/nspr/reference/prthreadpool.rst new file mode 100644 index 0000000000..3659f189c7 --- /dev/null +++ b/docs/nspr/reference/prthreadpool.rst @@ -0,0 +1,10 @@ +PRThreadPool +============ + + +Syntax +------ + +.. code:: + + #include <prtpool.h> diff --git a/docs/nspr/reference/prthreadpriority.rst b/docs/nspr/reference/prthreadpriority.rst new file mode 100644 index 0000000000..97c5c358da --- /dev/null +++ b/docs/nspr/reference/prthreadpriority.rst @@ -0,0 +1,62 @@ +PRThreadPriority +================ + +A thread's priority setting. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef enum PRThreadPriority + { + PR_PRIORITY_FIRST = 0, + PR_PRIORITY_LOW = 0, + PR_PRIORITY_NORMAL = 1, + PR_PRIORITY_HIGH = 2, + PR_PRIORITY_URGENT = 3, + PR_PRIORITY_LAST = 3 + } PRThreadPriority; + + +Enumerators +~~~~~~~~~~~ + +``PR_PRIORITY_FIRST`` + Placeholder. +``PR_PRIORITY_LOW`` + The lowest possible priority. This priority is appropriate for + threads that are expected to perform intensive computation. +``PR_PRIORITY_NORMAL`` + The most commonly expected priority. +``PR_PRIORITY_HIGH`` + Slightly higher priority than ``PR_PRIORITY_NORMAL``. This priority + is for threads performing work of high urgency but short duration. +``PR_PRIORITY_URGENT`` + Highest priority. Only one thread at a time typically has this + priority. +``PR_PRIORITY_LAST`` + Placeholder + + +Description +----------- + +In general, an NSPR thread of higher priority has a statistically better +chance of running relative to threads of lower priority. However, +because of the multiple strategies NSPR uses to implement threading on +various host platforms, NSPR priorities are not precisely defined. At +best they are intended to specify a preference in the amount of CPU time +that a higher-priority thread might expect relative to a lower-priority +thread. This preference is still subject to resource availability and +must not be used in place of proper synchronization. + + +See Also +-------- + +`Setting Thread +Priorities <Introduction_to_NSPR#Setting_Thread_Priorities>`__. diff --git a/docs/nspr/reference/prthreadprivatedtor.rst b/docs/nspr/reference/prthreadprivatedtor.rst new file mode 100644 index 0000000000..6a9339d07d --- /dev/null +++ b/docs/nspr/reference/prthreadprivatedtor.rst @@ -0,0 +1,24 @@ +PRThreadPrivateDTOR +=================== + +The destructor function passed to PR_NewThreadPrivateIndex that is +associated with the resulting thread private index. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef void (PR_CALLBACK *PRThreadPrivateDTOR)(void *priv); + + +Description +~~~~~~~~~~~ + +Until the data associated with an index is actually set with a call to +:ref:`PR_SetThreadPrivate`, the value of the data is ``NULL``. If the data +associated with the index is not ``NULL``, NSPR passes a reference to +the data to the destructor function when the thread terminates. diff --git a/docs/nspr/reference/prthreadscope.rst b/docs/nspr/reference/prthreadscope.rst new file mode 100644 index 0000000000..c468704295 --- /dev/null +++ b/docs/nspr/reference/prthreadscope.rst @@ -0,0 +1,56 @@ +PRThreadScope +============= + +The scope of an NSPR thread, specified as a parameter to +:ref:`PR_CreateThread` or returned by :ref:`PR_GetThreadScope`. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef enum PRThreadScope { + PR_LOCAL_THREAD, + PR_GLOBAL_THREAD + PR_GLOBAL_BOUND_THREAD + } PRThreadScope; + + +Enumerators +~~~~~~~~~~~ + +``PR_LOCAL_THREAD`` + A local thread, scheduled locally by NSPR within the process. +``PR_GLOBAL_THREAD`` + A global thread, scheduled by the host OS. +``PR_GLOBAL_BOUND_THREAD`` + A global bound (kernel) thread, scheduled by the host OS + + +Description +----------- + +An enumerator of type :ref:`PRThreadScope` specifies how a thread is +scheduled: either locally by NSPR within the process (a local thread) or +globally by the host (a global thread). + +Global threads are scheduled by the host OS and compete with all other +threads on the host OS for resources. They are subject to fairly +sophisticated scheduling techniques. + +Local threads are scheduled by NSPR within the process. The process is +assumed to be globally scheduled, but NSPR can manipulate local threads +without system intervention. In most cases, this leads to a significant +performance benefit. + +However, on systems that require NSPR to make a distinction between +global and local threads, global threads are invariably required to do +any form of I/O. If a thread is likely to do a lot of I/O, making it a +global thread early is probably warranted. + +On systems that don't make a distinction between local and global +threads, NSPR silently ignores the scheduling request. To find the scope +of the thread, call :ref:`PR_GetThreadScope`. diff --git a/docs/nspr/reference/prthreadstack.rst b/docs/nspr/reference/prthreadstack.rst new file mode 100644 index 0000000000..374ac3ac07 --- /dev/null +++ b/docs/nspr/reference/prthreadstack.rst @@ -0,0 +1,31 @@ +PRThreadStack +============= + +.. container:: blockIndicator obsolete obsoleteHeader + + | **Obsolete** + | This feature is obsolete. Although it may still work in some + browsers, its use is discouraged since it could be removed at any + time. Try to avoid using it. + +The opaque :ref:`PRThreadStack` structure is only used in the third +argument "``PRThreadStack *stack``" to the :ref:`PR_AttachThread` function. +The '``stack``' argument is now obsolete and ignored by +:ref:`PR_AttachThread`. You should pass ``NULL`` as the 'stack' argument to +:ref:`PR_AttachThread`. + +.. _Definition: + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef struct PRThreadStack PRThreadStack; + +.. _Definition_2: + + +- diff --git a/docs/nspr/reference/prthreadstate.rst b/docs/nspr/reference/prthreadstate.rst new file mode 100644 index 0000000000..7285779f39 --- /dev/null +++ b/docs/nspr/reference/prthreadstate.rst @@ -0,0 +1,54 @@ +PRThreadState +============= + +A thread's thread state is either joinable or unjoinable. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef enum PRThreadState { + PR_JOINABLE_THREAD, + PR_UNJOINABLE_THREAD + } PRThreadState; + + +Enumerators +~~~~~~~~~~~ + +``PR_UNJOINABLE_THREAD`` + Thread termination happens implicitly when the thread returns from + the root function. The time of release of the resources assigned to + the thread cannot be determined in advance. Threads created with a + ``PR_UNJOINABLE_THREAD`` state cannot be used as arguments to + :ref:`PR_JoinThread`. +``PR_JOINABLE_THREAD`` + Joinable thread references remain valid after they have returned from + their root function until :ref:`PR_JoinThread` is called. This approach + facilitates management of the process' critical resources. + + +Description +----------- + +A thread is a critical resource and must be managed. + +The lifetime of a thread extends from the time it is created to the time +it returns from its root function. What happens when it returns from its +root function depends on the thread state passed to :ref:`PR_CreateThread` +when the thread was created. + +If a thread is created as a joinable thread, it continues to exist after +returning from its root function until another thread joins it. The join +process permits strict synchronization of thread termination and +therefore promotes effective resource management. + +If a thread is created as an unjoinable (also called detached) thread, +it terminates and cleans up after itself after returning from its root +function. This results in some ambiguity after the thread's root +function has returned and before the thread has finished terminating +itself. diff --git a/docs/nspr/reference/prthreadtype.rst b/docs/nspr/reference/prthreadtype.rst new file mode 100644 index 0000000000..4934af7a2f --- /dev/null +++ b/docs/nspr/reference/prthreadtype.rst @@ -0,0 +1,40 @@ +PRThreadType +============ + +The type of an NSPR thread, specified as a parameter to +:ref:`PR_CreateThread`. + + +Syntax +------ + +.. code:: + + #include <prthread.h> + + typedef enum PRThreadType { + PR_USER_THREAD, + PR_SYSTEM_THREAD + } PRThreadType; + + +Enumerators +~~~~~~~~~~~ + +``PR_USER_THREAD`` + :ref:`PR_Cleanup` blocks until the last thread of type + ``PR_USER_THREAD`` terminates. +``PR_SYSTEM_THREAD`` + NSPR ignores threads of type ``PR_SYSTEM_THREAD`` when determining + when a call to :ref:`PR_Cleanup` should return. + + +Description +----------- + +Threads can be either user threads or system threads. NSPR allows the +client to synchronize the termination of all user threads and ignores +those created as system threads. This arrangement implies that a system +thread should not have volatile data that needs to be safely stored +away. The applicability of system threads is somewhat dubious; +therefore, they should be used with caution. diff --git a/docs/nspr/reference/prtime.rst b/docs/nspr/reference/prtime.rst new file mode 100644 index 0000000000..8498e942ff --- /dev/null +++ b/docs/nspr/reference/prtime.rst @@ -0,0 +1,33 @@ +PRTime +====== + +A representation of absolute times. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + typedef PRInt64 PRTime; + + +Description +----------- + +This type is a 64-bit integer representing the number of microseconds +since the NSPR epoch, midnight (00:00:00) 1 January 1970 Coordinated +Universal Time (UTC). A time after the epoch has a positive value, and a +time before the epoch has a negative value. + +In NSPR, we use the more familiar term Greenwich Mean Time (GMT) in +place of UTC. Although UTC and GMT are not exactly the same in their +precise definitions, they can generally be treated as if they were. + +.. note:: + + **Note:** Keep in mind that while :ref:`PRTime` stores times in + microseconds since epoch, JavaScript date objects store times in + milliseconds since epoch. diff --git a/docs/nspr/reference/prtimeparameters.rst b/docs/nspr/reference/prtimeparameters.rst new file mode 100644 index 0000000000..4ddd01c7cd --- /dev/null +++ b/docs/nspr/reference/prtimeparameters.rst @@ -0,0 +1,54 @@ +PRTimeParameters +================ + +A representation of time zone information. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + typedef struct PRTimeParameters { + PRInt32 tp_gmt_offset; + PRInt32 tp_dst_offset; + } PRTimeParameters; + + +Description +----------- + +Each geographic location has a standard time zone, and if Daylight +Saving Time (DST) is practiced, a daylight time zone. The +:ref:`PRTimeParameters` structure represents the local time zone +information in terms of the offset (in seconds) from GMT. The overall +offset is broken into two components: + +``tp_gmt_offset`` + The offset of the local standard time from GMT. + +``tp_dst_offset`` + If daylight savings time (DST) is in effect, the DST adjustment from + the local standard time. This is most commonly 1 hour, but may also + be 30 minutes or some other amount. If DST is not in effect, the + tp_dst_offset component is 0. + +For example, the US Pacific Time Zone has both a standard time zone +(Pacific Standard Time, or PST) and a daylight time zone (Pacific +Daylight Time, or PDT). + +- In PST, the local time is 8 hours behind GMT, so ``tp_gmt_offset`` is + -28800 seconds. ``tp_dst_offset`` is 0, indicating that daylight + saving time is not in effect. + +- In PDT, the clock is turned forward by one hour, so the local time is + 7 hours behind GMT. This is broken down as -8 + 1 hours, so + ``tp_gmt_offset`` is -28800 seconds, and ``tp_dst_offset`` is 3600 + seconds. + +A second example is Japan, which is 9 hours ahead of GMT. Japan does not +use daylight saving time, so the only time zone is Japan Standard Time +(JST). In JST ``tp_gmt_offset`` is 32400 seconds, and ``tp_dst_offset`` +is 0. diff --git a/docs/nspr/reference/prtimeparamfn.rst b/docs/nspr/reference/prtimeparamfn.rst new file mode 100644 index 0000000000..1efd6a5895 --- /dev/null +++ b/docs/nspr/reference/prtimeparamfn.rst @@ -0,0 +1,24 @@ +PRTimeParamFn +============= + +This type defines a callback function to calculate and return the time +parameter offsets from a calendar time object in GMT. + + +Syntax +------ + +.. code:: + + #include <prtime.h> + + typedef PRTimeParameters (PR_CALLBACK_DECL *PRTimeParamFn) + (const PRExplodedTime *gmt); + + +Description +----------- + +The type :ref:`PRTimeParamFn` represents a callback function that, when +given a time instant in GMT, returns the time zone information (offset +from GMT and DST offset) at that time instant. diff --git a/docs/nspr/reference/pruint16.rst b/docs/nspr/reference/pruint16.rst new file mode 100644 index 0000000000..f4e699caed --- /dev/null +++ b/docs/nspr/reference/pruint16.rst @@ -0,0 +1,14 @@ +PRUint16 +======== + +Guaranteed to be an unsigned 16-bit integer on all platforms. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedefdefinition PRUint16; diff --git a/docs/nspr/reference/pruint32.rst b/docs/nspr/reference/pruint32.rst new file mode 100644 index 0000000000..5ea00f9b54 --- /dev/null +++ b/docs/nspr/reference/pruint32.rst @@ -0,0 +1,22 @@ +PRUint32 +======== + +Guaranteed to be an unsigned 32-bit integer on all platforms. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedefdefinition PRUint32; + + +Description +----------- + +May be defined as an unsigned ``int`` or an unsigned ``long``, depending +on the platform. For syntax details for each platform, see +`prtypes.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtypes.h>`__. diff --git a/docs/nspr/reference/pruint64.rst b/docs/nspr/reference/pruint64.rst new file mode 100644 index 0000000000..0bc74917e5 --- /dev/null +++ b/docs/nspr/reference/pruint64.rst @@ -0,0 +1,22 @@ +PRUint64 +======== + +Guaranteed to be an unsigned 64-bit integer on all platforms. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef definition PRUint64; + + +Description +----------- + +May be defined in several different ways, depending on the platform. For +syntax details for each platform, see +`prtypes.h <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prtypes.h>`__. diff --git a/docs/nspr/reference/pruint8.rst b/docs/nspr/reference/pruint8.rst new file mode 100644 index 0000000000..2f4224d179 --- /dev/null +++ b/docs/nspr/reference/pruint8.rst @@ -0,0 +1,15 @@ +PRUint8 +======= + +Guaranteed to be an unsigned 8-bit integer on all platforms. There is no +type equivalent to a plain ``char``. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedefdefinition PRUint8; diff --git a/docs/nspr/reference/pruintn.rst b/docs/nspr/reference/pruintn.rst new file mode 100644 index 0000000000..d3aa4a9bb8 --- /dev/null +++ b/docs/nspr/reference/pruintn.rst @@ -0,0 +1,17 @@ +PRUintn +======= + +This (unsigned) type is one of the most appropriate for automatic +variables. It is guaranteed to be at least 16 bits, though various +architectures may define it to be wider (for example, 32 or even 64 +bits). This types is never valid for fields of a structure. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef unsigned int PRUintn; diff --git a/docs/nspr/reference/prunichar.rst b/docs/nspr/reference/prunichar.rst new file mode 100644 index 0000000000..35ebf41562 --- /dev/null +++ b/docs/nspr/reference/prunichar.rst @@ -0,0 +1,18 @@ +PRUnichar +========= + +An unsigned 16-bit type, like ``char`` in Java or the "characters" of a +JavaScript string defined in +`/mozilla/xpcom/base/nscore.h <http://hg.mozilla.org/mozilla-central/file/d35b4d003e9e/xpcom/base/nscore.h>`__. + + +Syntax +------ + +.. code:: + + #if defined(NS_WIN32) + typedef wchar_t PRUnichar; + #else + typedef PRUInt16 PRUnichar; + #endif diff --git a/docs/nspr/reference/pruptrdiff.rst b/docs/nspr/reference/pruptrdiff.rst new file mode 100644 index 0000000000..f58f0a5eb8 --- /dev/null +++ b/docs/nspr/reference/pruptrdiff.rst @@ -0,0 +1,14 @@ +PRUptrdiff +========== + +Unsigned pointer difference type. + + +Syntax +------ + +.. code:: + + #include <prtypes.h> + + typedef unsigned long PRUptrdiff; diff --git a/docs/nspr/reference/random_number_generator.rst b/docs/nspr/reference/random_number_generator.rst new file mode 100644 index 0000000000..0caaf3bbf8 --- /dev/null +++ b/docs/nspr/reference/random_number_generator.rst @@ -0,0 +1,12 @@ +Random Number Generator +======================= + +This chapter describes the NSPR random number generator. + +.. _Random_Number_Generator_Function: + +Random Number Generator Function +-------------------------------- + + - :ref:`PR_GetRandomNoise` - Produces a random value for use as a seed + value for another random number generator. diff --git a/docs/nspr/reference/string_operations.rst b/docs/nspr/reference/string_operations.rst new file mode 100644 index 0000000000..b160f093d2 --- /dev/null +++ b/docs/nspr/reference/string_operations.rst @@ -0,0 +1,11 @@ +This chapter describes some of the key NSPR functions for manipulating +strings. Libraries built on top of NSPR, such as the Netscape security +libraries, use these functions to manipulate strings. If you are copying +or examining strings for use by such libraries or freeing strings that +were allocated by such libraries, you must use these NSPR functions +rather than the libc equivalents. + + - :ref:`PL_strlen` + - :ref:`PL_strcpy` + - :ref:`PL_strdup` + - :ref:`PL_strfree` diff --git a/docs/nspr/reference/thread_pools.rst b/docs/nspr/reference/thread_pools.rst new file mode 100644 index 0000000000..75fc9f75a2 --- /dev/null +++ b/docs/nspr/reference/thread_pools.rst @@ -0,0 +1,41 @@ +This chapter describes the NSPR API Thread Pools. + +.. note:: + + **Note:** This API is a preliminary version in NSPR 4.0 and is + subject to change. + +Thread pools create and manage threads to provide support for scheduling +work (jobs) onto one or more threads. NSPR's thread pool is modeled on +the thread pools described by David R. Butenhof in\ *Programming with +POSIX Threads* (Addison-Wesley, 1997). + +- `Thread Pool Types <#Thread_Pool_Types>`__ +- `Thread Pool Functions <#Thread_Pool_Functions>`__ + +.. _Thread_Pool_Types: + +Thread Pool Types +----------------- + + - :ref:`PRJobIoDesc` + - :ref:`PRJobFn` + - :ref:`PRThreadPool` + - :ref:`PRJob` + +.. _Thread_Pool_Functions: + +Thread Pool Functions +--------------------- + + - :ref:`PR_CreateThreadPool` + - :ref:`PR_QueueJob` + - :ref:`PR_QueueJob_Read` + - :ref:`PR_QueueJob_Write` + - :ref:`PR_QueueJob_Accept` + - :ref:`PR_QueueJob_Connect` + - :ref:`PR_QueueJob_Timer` + - :ref:`PR_CancelJob` + - :ref:`PR_JoinJob` + - :ref:`PR_ShutdownThreadPool` + - :ref:`PR_JoinThreadPool` diff --git a/docs/nspr/reference/thread_synchronization_sample.rst b/docs/nspr/reference/thread_synchronization_sample.rst new file mode 100644 index 0000000000..e1417b130c --- /dev/null +++ b/docs/nspr/reference/thread_synchronization_sample.rst @@ -0,0 +1,2 @@ +This page has no content. Enrich Mozilla Developer Center by +contributing. diff --git a/docs/nspr/reference/threads.rst b/docs/nspr/reference/threads.rst new file mode 100644 index 0000000000..fdcdcc271e --- /dev/null +++ b/docs/nspr/reference/threads.rst @@ -0,0 +1,129 @@ +NSPR provides an execution environment that promotes the use of +lightweight threads. Each thread is an execution entity that is +scheduled independently from other threads in the same process. This +chapter describes the basic NSPR threading API. + +- `Threading Types and Constants <#Threading_Types_and_Constants>`__ +- `Threading Functions <#Threading_Functions>`__ + +A thread has a limited number of resources that it truly owns. These +resources include a stack and the CPU registers (including PC). To an +NSPR client, a thread is represented by a pointer to an opaque structure +of type :ref:`PRThread`. A thread is created by an explicit client request +and remains a valid, independent execution entity until it returns from +its root function or the process abnormally terminates. Threads are +critical resources and therefore require some management. To synchronize +the termination of a thread, you can **join** it with another thread +(see :ref:`PR_JoinThread`). Joining a thread provides definitive proof that +the target thread has terminated and has finished with both the +resources to which the thread has access and the resources of the thread +itself. + +For an overview of the NSPR threading model and sample code that +illustrates its use, see `Introduction to +NSPR <Introduction_to_NSPR>`__. + +For API reference information related to thread synchronization, see +`Locks <Locks>`__ and `Condition Variables <Condition_Variables>`__. + +.. _Threading_Types_and_Constants: + +Threading Types and Constants +----------------------------- + + - :ref:`PRThread` + - :ref:`PRThreadType` + - :ref:`PRThreadScope` + - :ref:`PRThreadState` + - :ref:`PRThreadPriority` + - :ref:`PRThreadPrivateDTOR` + +.. _Threading_Functions: + +Threading Functions +------------------- + +Most of the functions described here accept a pointer to the thread as +an argument. NSPR does not check for the validity of the thread. It is +the caller's responsibility to ensure that the thread is valid. The +effects of these functions on invalid threads are undefined. + +- `Creating, Joining, and Identifying + Threads <#Creating,_Joining,_and_Identifying_Threads>`__ +- `Controlling Thread Priorities <#Controlling_Thread_Priorities>`__ +- `Interrupting and Yielding <#Interrupting_and_Yielding>`__ +- `Setting Global Thread + Concurrency <#Setting_Global_Thread_Concurrency>`__ +- `Getting a Thread's Scope <#Getting_a_Thread's_Scope>`__ + +.. _Creating.2C_Joining.2C_and_Identifying_Threads: + +Creating, Joining, and Identifying Threads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_CreateThread` creates a new thread. + - :ref:`PR_JoinThread` blocks the calling thread until a specified thread + terminates. + - :ref:`PR_GetCurrentThread` returns the current thread object for the + currently running code. + - :ref:`PR_AttachThread`` associates a :ref:`PRThread` object with an existing + native thread. + - :ref:`PR_DetachThread`` disassociates a :ref:`PRThread` object from a native + thread. + +.. _Controlling_Thread_Priorities: + +Controlling Thread Priorities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For an overview of the way NSPR controls thread priorities, see `Setting +Thread Priorities <Introduction_to_NSPR#Setting_Thread_Priorities.>`__. + +You set a thread's NSPR priority when you create it with +:ref:`PR_CreateThread`. After a thread has been created, you can get and +set its priority with these functions: + + - :ref:`PR_GetThreadPriority` + - :ref:`PR_SetThreadPriority` + +.. _Controlling_Per-Thread_Private_Data: + +Controlling Per-Thread Private Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use these functions to associate private data with each of the +threads in a process: + + - :ref:`PR_NewThreadPrivateIndex` allocates a unique index. If the call is + successful, every thread in the same process is capable of + associating private data with the new index. + - :ref:`PR_SetThreadPrivate` associates private thread data with an index. + - :ref:`PR_GetThreadPrivate` retrieves data associated with an index. + +.. _Interrupting_and_Yielding: + +Interrupting and Yielding +~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_Interrupt` requests an interrupt of another thread. Once the + target thread has been notified of the request, the request stays + with the thread until the notification either has been delivered + exactly once or is cleared. + - :ref:`PR_ClearInterrupt` clears a previous interrupt request. + - :ref:`PR_Sleep` causes a thread to yield to other threads for a + specified number of ticks. + +.. _Setting_Global_Thread_Concurrency: + +Setting Global Thread Concurrency +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_SetConcurrency` sets the number of global threads used by NSPR + to create local threads. + +.. _Getting_a_Thread.27s_Scope: + +Getting a Thread's Scope +~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_GetThreadScope` gets the scoping of the current thread. |