diff options
Diffstat (limited to '')
363 files changed, 17494 insertions, 0 deletions
diff --git a/docs/nspr/about_nspr.rst b/docs/nspr/about_nspr.rst new file mode 100644 index 0000000000..622bdeac52 --- /dev/null +++ b/docs/nspr/about_nspr.rst @@ -0,0 +1,154 @@ +About NSPR +========== + +NetScape Portable Runtime (NSPR) provides platform independence for +non-GUI operating system facilities. These facilities include threads, +thread synchronization, normal file and network I/O, interval timing and +calendar time, basic memory management (malloc and free) and shared +library linking. + +History +~~~~~~~ + +A good portion of the library's purpose, and perhaps the primary purpose +in the Gromit environment, was to provide the underpinnings of the Java +VM, more or less mapping the *sys layer* that Sun defined for the +porting of the Java VM to various platforms. NSPR went beyond that +requirement in some areas and since it was also the platform independent +layer for most of the servers produced by Netscape. It was expected and +preferred that existing code be restructured and perhaps even rewritten +in order to use the NSPR API. It is not a goal to provide a platform for +the porting into Netscape of externally developed code. + +At the time of writing the current generation of NSPR was known as +NSPR20. The first generation of NSPR was originally conceived just to +satisfy the requirements of porting Java to various host environments. +NSPR20, an effort started in 1996, built on that original idea, though +very little is left of the original code. (The "20" in "NSPR20" does not +mean "version 2.0" but rather "second generation".) Many of the concepts +have been reformed, expanded, and matured. Today NSPR may still be +appropriate as the platform dependent layer under Java, but its primary +application is supporting clients written entirely in C or C++. + +.. _How_It_Works: + +How It Works +~~~~~~~~~~~~ + +NSPR's goal is to provide uniform service over a wide range of operating +system environments. It strives to not export the *lowest common +denominator*, but to exploit the best features of each operating system +on which it runs, and still provide a uniform service across a wide +range of host offerings. + +Threads +^^^^^^^ + +Threads are the major feature of NSPR. The industry's offering of +threads is quite sundry. NSPR, while far from perfect, does provide a +single API to which clients may program and expect reasonably consistent +behavior. The operating systems provide everything from no concept of +threading at all up to and including sophisticated, scalable and +efficient implementations. NSPR makes as much use of what the systems +offer as it can. It is a goal of NSPR that NSPR impose as little +overhead as possible in accessing those appropriate system features. + +.. _Thread_synchronization: + +Thread synchronization +^^^^^^^^^^^^^^^^^^^^^^ + +Thread synchronization is loosely based on Monitors as described by +C.A.R. Hoare in *Monitors: An operating system structuring concept* , +Communications of the ACM, 17(10), October 1974 and then formalized by +Xerox' Mesa programming language ("Mesa Language Manual", J.G. Mitchell +et al, Xerox PARC, CSL-79-3 (Apr 1979)). This mechanism provides the +basic mutual exclusion (mutex) and thread notification facilities +(condition variables) implemented by NSPR. Additionally, NSPR provides +synchronization methods more suited for use by Java. The Java-like +facilities include monitor *reentrancy*, implicit and tightly bound +notification capabilities with the ability to associate the +synchronization objects dynamically. + +.. _I.2FO: + +I/O +^^^ + +NSPR's I/O is a slightly augmented BSD sockets model that allows +arbitrary layering. It was originally intended to export synchronous I/O +methods only, relying on threads to provide the concurrency needed for +complex applications. That method of operation is preferred though it is +possible to configure the network I/O channels as *non-blocking* in the +traditional sense. + +.. _Network_addresses: + +Network addresses +^^^^^^^^^^^^^^^^^ + +Part of NSPR deals with manipulation of network addresses. NSPR defines +a network address object that is Internet Protocol (IP) centric. While +the object is not declared as opaque, the API provides methods that +allow and encourage clients to treat the addresses as polymorphic items. +The goal in this area is to provide a migration path between IPv4 and +IPv6. To that end it is possible to perform translations of ASCII +strings (DNS names) into NSPR's network address structures, with no +regard to whether the addressing technology is IPv4 or IPv6. + +Time +^^^^ + +Timing facilities are available in two forms: interval timing and +calendar functions. + +Interval timers are based on a free running, 32-bit, platform dependent +resolution timer. Such timers are normally used to specify timeouts on +I/O, waiting on condition variables and other rudimentary thread +scheduling. Since these timers have finite namespace and are free +running, they can wrap at any time. NSPR does not provide an *epoch* , +but expects clients to deal with that issue. The *granularity* of the +timers is guaranteed to be between 10 microseconds and 1 millisecond. +This allows a minimal timer *period* in of approximately 12 hours. But +in order to deal with the wrap-around issue, only half that namespace +may be utilized. Therefore, the minimal usable interval available from +the timers is slightly less than six hours. + +Calendar times are 64-bit signed numbers with units of microseconds. The +*epoch* for calendar times is midnight, January 1, 1970, Greenwich Mean +Time. Negative times extend to times before 1970, and positive numbers +forward. Use of 64 bits allows a representation of times approximately +in the range of -30000 to the year 30000. There is a structural +representation (*i.e., exploded* view), routines to acquire the current +time from the host system, and convert them to and from the 64-bit and +structural representation. Additionally there are routines to convert to +and from most well-known forms of ASCII into the 64-bit NSPR +representation. + +.. _Memory_management: + +Memory management +^^^^^^^^^^^^^^^^^ + +NSPR provides API to perform the basic malloc, calloc, realloc and free +functions. Depending on the platform, the functions may be implemented +almost entirely in the NSPR runtime or simply shims that call +immediately into the host operating system's offerings. + +Linking +^^^^^^^ + +Support for linking (shared library loading and unloading) is part of +NSPR's feature set. In most cases this is simply a smoothing over of the +facilities offered by the various platform providers. + +Where It's Headed +~~~~~~~~~~~~~~~~~ + +NSPR is applicable as a platform on which to write threaded applications +that need to be ported to multiple platforms. + +NSPR is functionally complete and has entered a mode of sustaining +engineering. As operating system vendors issue new releases of their +operating systems, NSPR will be moved forward to these new releases by +interested players. diff --git a/docs/nspr/creating_a_cookie_log.rst b/docs/nspr/creating_a_cookie_log.rst new file mode 100644 index 0000000000..06a0e90596 --- /dev/null +++ b/docs/nspr/creating_a_cookie_log.rst @@ -0,0 +1,65 @@ +Creating a cookie log +===================== + +Creating a cookie log is often necessary to troubleshoot problems with +Firefox's cookie handling. If you are reading this, you have probably +been directed here from a bug report. Please follow the instructions +below to run Firefox with cookie logging enabled. + +.. _Enabling_Cookie_Logging: + +Enabling Cookie Logging +~~~~~~~~~~~~~~~~~~~~~~~ + +Windows +^^^^^^^ + +Open a command prompt (this is under Programs or Programs/Accessories in +normal installations of Windows). + +#. Change to your Firefox directory (usually C:\Program Files\Mozilla + Firefox) +#. Type "set NSPR_LOG_FILE=C:\temp\cookie-log.txt", enter +#. Type "set NSPR_LOG_MODULES=cookie:4" and press Enter +#. Run Firefox by typing "firefox.exe" and pressing Enter. + +Linux +^^^^^ + +Start a command shell (these instructions are for bash, if you use +something else, you probably know how to modify these instructions +already). + +#. Change to the installation directory for Firefox. +#. Type "export NSPR_LOG_FILE=~/cookie-log.txt" and press Enter. +#. Type "export NSPR_LOG_MODULES=cookie:4" and press Enter. +#. Run Firefox by typing "./firefox" and pressing Enter + +Mac OS X +^^^^^^^^ + +Open Terminal.app, which is located in the /Applications/Utilities +folder (these instructions are for bash, the default shell in Mac OS X +10.3 and higher; if you use something else, you probably know how to +modify these instructions already). + +#. Change to the installation directory for Firefox, e.g. type "cd + /Applications/Firefox.app/Contents/MacOS" and press Return. +#. Type "export NSPR_LOG_FILE=~/Desktop/cookie-log.txt" and press + Return. +#. Type "export NSPR_LOG_MODULES=cookie:4" and press Return. +#. Run Firefox by typing "./firefox-bin" and pressing Return (note that + Firefox will launch behind windows for other applications). + +Creating the Log +~~~~~~~~~~~~~~~~ + +Now that you have Firefox running with logging enabled, please try to +replicate the bug using the steps to reproduce from the bug report. Once +you have reproduced the bug, shut down Firefox. Close out of the command +prompt/shell/Terminal, and then launch Firefox normally. Finally, attach +the cookie-log.txt file to the bug where it was requested (by clicking +on Create New Attachment). It should be in C:\temp on Windows, your home +directory on Linux, or the Desktop on Mac OS X. + +Thanks for helping us make Firefox better! diff --git a/docs/nspr/index.rst b/docs/nspr/index.rst new file mode 100644 index 0000000000..89e81d2517 --- /dev/null +++ b/docs/nspr/index.rst @@ -0,0 +1,66 @@ +NSPR +==== + +**Netscape Portable Runtime (NSPR)** provides a platform-neutral API for +system level and libc-like functions. The API is used in the Mozilla +clients, many of Red Hat's and Oracle's server applications, and other +software offerings. + +Documentation +------------- + +:ref:`About NSPR` + This topic describes, in general terms, the goals of NSPR and a bit + about how it does it. +:ref:`NSPR API Reference` + The reference describes each API public macro, structure and function + in the NSPR API. +:ref:`NSPR build instructions` + How to checkout and build from source. +:ref:`NSPR listing` + All NSPR pages + +.. _Getting_NSPR: + +Getting NSPR +------------ + +NSPR is available in various source and binary packages, depending on +your platform: + +- **Windows:** Build the source package, using the :ref:`NSPR build + instructions`. +- **Mac:** Install the `MacPorts <http://www.macports.org/>`__ *nspr* + package, or the `Homebrew <http://brew.sh>`__ *nspr* package. +- **Ubuntu:** Install the *libnspr4-dev* package via ``apt-get.`` +- **Debian:** Install the *libnspr4-dev* package via ``apt-get``. +- **openSUSE Linux:** Install one or more of the following via ``yast`` + or ``zypper`` : + + - *mozilla-nspr* : Binary libraries for your platform + - *mozilla-nspr-32bit* : Binary libraries needed to run 32-bit + programs on a 64-bit OS + - *mozilla-nspr-devel* : Files needed (in addition to the above + libraries) to compile programs using NSPR + - *mozilla-nspr-debuginfo* : Debug information (including build + symbols) for package *mozilla-nspr* + - *mozilla-nspr-debuginfo-32bit* : Debug information (including + build symbols) for package *mozilla-nspr-32bit* + - *mozilla-nspr-debugsource* : Debug sources for all of the above + +Community +--------- + +View Mozilla forums: + +- `Mailing list <https://lists.mozilla.org/listinfo/dev-tech-nspr>`__ +- `Newsgroup <http://groups.google.com/group/mozilla.dev.tech.nspr>`__ +- `RSS + feed <http://groups.google.com/group/mozilla.dev.tech.nspr/feeds>`__ + +.. _Related_Topics: + +Related Topics +-------------- + +- :ref:`Networking`, :ref:`Network Security Services (NSS)` diff --git a/docs/nspr/layeredpoll.rst b/docs/nspr/layeredpoll.rst new file mode 100644 index 0000000000..6f5cb80efe --- /dev/null +++ b/docs/nspr/layeredpoll.rst @@ -0,0 +1,118 @@ +PR_Poll() and the layered I/O +============================= + +*[last edited by AOF 8 August 1998]* +This memo discusses some of the nuances of using PR_Poll() in +conjunction with *layered I/O*. This is a relatively new feature in NSPR +2.0, not that it hasn't been in the source tree for a while, but in that +it has had no clients. + +Implementation +-------------- + +NSPR provides a public API function, PR_Poll() that is modeled after +UNIX' ``poll()`` system call. + +The implementation of :ref:`PR_Poll` is somewhat complicated. Not only +does it map the :ref:`PRPollDesc` array into structures needed by the +underlying OS, it also must deal with layered I/O. This is done despite +the fact that :ref:`PR_Poll` itself is *not* layered. For every element +of the :ref:`PRPollDesc` array that has a non-NULL :ref:`PRFileDesc` and whose +``in_flags`` are not zero, it calls the file descriptor's +``poll() method``. +The ``poll()`` method is one of the vector contained in the +:ref:`PRIOMethods` table. In the case of layered I/O, the elements (the +methods) of the methods table may be overridden by the implementor of +that layer. The layers are then *stacked.* I/O using that *stack* will +call through the method at the top layer, and each layer may make +altering decisions regarding how the I/O operation should proceed. + +The purpose of the ``poll()`` method is to allow a layer to modify the +flags that will ultimately be used in the call to the underlying OS' +``poll()`` (or equivalent) function. Such modification might be useful +if one was implementing an augmented stream protocol (*e.g.,* **SSL**). +SSL stands for **Secure Socket Layer**, hence the obvious applicability +as an example. But it is way to complicated to describe in this memo, so +this memo will use a much simpler layered protocol. +The example protocol is one that, in order to send *n* bytes, it must +first ask the connection's peer if the peer is willing to receive that +many bytes. The form of the request is 4 bytes (binary) stating the +number of bytes the sender wishes to transmit. The peer will send back +the number of bytes it is willing to receive (in the test code there are +no error conditions, so don't even ask). + +The implication of the protocol is obvious. In order to do a +:ref:`PR_Send` operation, the layer must first do a *different* send and +then *receive* a response. Doing this and keeping the *stack's* client +unaware is the goal. **It is not a goal of NSPR 2.0 to hide the nuances +of synchronous verses non-blocking I/O**. + +The layered methods +------------------- + +Each layer must implement a suitable function for *every* element of the +methods table. One can get a copy of default methods by calling +:ref:`PR_GetDefaultIOMethods` These methods simply pass all calls +through the layer on to the next lower layer of the stack. + +A layer implementor might copy the elements of the ``PRIOMethods`` +acquired from this function into a methods table of its own, then +override just those methods of interest. *Usually* (with only a single +exception) a layered method will perform its design duties and then call +the next lower layer's equivalent function. + +Layered ``poll()`` +------------------ + +One of the more interesting methods is the ``poll()``. It is called by +the runtime whenever the client calls :ref:`PR_Poll`. It may be called at +the *top* layer for *every* file descriptor in the poll descriptor. It +may be called zero or more times. The purpose of the ``poll()`` method +is to provide the layer an opportunity to adjust the polling bits as +needed. For instance, if a client (*i.e.*, top layer) is calling +:ref:`PR_Poll` for a particular file descriptor with a *read* poll +request, a lower layer might decide that it must perform a *write* +first. +In that case, the layer's ``poll()`` method would be called with +**``in_flags``** including a ``PR_POLL_READ`` flag. However, the +``poll()`` method would call the next lower layer's ``poll()`` method +with a ``PR_POLL_WRITE`` bit set. This process of re-assigning the poll +flags can happen as many times as there are layers in the stack. It is +the final value, the one returned to the caller of the top layer's +``poll()`` method (:ref:`PR_Poll`) that will be used by the runtime when +calling the OS' ``poll()`` (or equivalent) system call. + +It is expected that the modification of the polling bits propagate from +the top of the stack down, allowing the layer closest to the bottom of +the stack to provide the final setting. The implication is that there +should be no modifications of the **``in_flags``** during the *return* +phase of the layered function. + +For example: + +It is not advised to modify the ``final_in_flags`` between the call to +the lower layer's ``poll()`` method and the ``return`` statement. +The third argument of the ``poll()`` method is a pointer to a 16-bit +word. If the layer sets a value in memory through that pointer *and* +returns with a value that has *corresponding* bits, the runtime assumes +that the file descriptor is ready immediately. + +There are two important deviations from the normal. First, this is the +one (known) exception to having a layered routine call the stack's next +lower layer method. If bits are set in the ``out_flags`` the method +should return *directly*. Second, the runtime will observe that the +layer claims this file descriptor is ready and suppress the call to the +OS' ``poll()`` system call. + +At this time the only known use for this feature is to allow a layer to +indicate it has buffered *input*. Note that it is not appropriate for +buffered *output* since in order to write/send output the runtime must +still confirm with the OS that such an operation is permitted. + +Since the ``poll()`` method may be called zero or more times it must +therefore be *idempotent* or at least *functional*. It will need to look +at the layer's state, but must not make modifications to that state that +would cause subsequent calls within the same :ref:`PR_Poll` call to +return a different answer. Since the ``poll()`` method may not be called +at all, so there is not guarantee that any modifications that would have +been performed by the routine will every happen. diff --git a/docs/nspr/listing.rst b/docs/nspr/listing.rst new file mode 100644 index 0000000000..33d0359e01 --- /dev/null +++ b/docs/nspr/listing.rst @@ -0,0 +1,10 @@ +NSPR listing +============ + +This page lists all the NSPR page. + +.. toctree:: + :glob: + + * + reference/* diff --git a/docs/nspr/nonblocking_io_in_nspr.rst b/docs/nspr/nonblocking_io_in_nspr.rst new file mode 100644 index 0000000000..a5ba816412 --- /dev/null +++ b/docs/nspr/nonblocking_io_in_nspr.rst @@ -0,0 +1,153 @@ +Nonblocking IO in NSPR +====================== + + +Introduction +------------ + +Previously, all I/O in the NetScape Portable Runtime (NSPR) was +*blocking* (or *synchronous*). A thread invoking an io function is +blocked until the io operation is finished. The blocking io model +encourages the use of multiple threads as a programming model. A thread +is typically created to attend to one of the simultaneous I/O operations +that may potentially block. + +In the *nonblocking* io model, a file descriptor may be marked as +nonblocking. An io function on a nonblocking file descriptor either +succeeds immediately or fails immediately with +<tt>PR_WOULD_BLOCK_ERROR</tt>. A single thread is sufficient to attend +to multiple nonblocking file descriptors simultaneously. Typically, this +central thread invokes <tt>PR_Poll()</tt> on a set of nonblocking file +descriptors. (Note: <tt>PR_Poll()</tt> also works with blocking file +descriptors, although it is less useful in the blocking io model.) When +<tt>PR_Poll()</tt> reports that a file descriptor is ready for some io +operation, the central thread invokes that io function on the file +descriptor. + +.. _Creating_a_Nonblocking_Socket: + +Creating a Nonblocking Socket +----------------------------- + +*Only sockets can be made nonblocking*. Regular files always operate in +blocking mode. This is not a serious constraint as one can assume that +disk I/O never blocks. Fundamentally, this constraint is due to the fact +that nonblocking I/O and <tt>select()</tt> are only available to sockets +on some platforms (e.g., Winsock). + +In NSPR, a new socket returned by <tt>PR_NewTCPSocket()</tt> or +<tt>PR_NewUDPSocket()</tt> is always created in blocking mode. One can +make the new socket nonblocking by using <tt>PR_SetSockOpt()</tt> as in +the example below (error checking is omitted for clarity): + +| +| <tt>PRFileDesc \*sock;</tt> +| **<tt>PRIntn optval = 1;</tt>** + +<tt>sock = PR_NewTCPSocket();</tt> + +:: + + /* + * Make the socket nonblocking + */ + + PR_SetSockOpt(sock, PR_SockOpt_Nonblocking, &optval, sizeof(optval)); + +.. _Programming_Constraints: + +Programming Constraints +----------------------- + +There are some constraints due to the use of NT asynchronous I/O in the +NSPR. In NSPR, blocking sockets on NT are associated with an I/O +completion port. Once associated with an I/O completion port, we can't +disassociate the socket from the I/O completion port. I have seen some +strange problems with using a nonblocking socket associated with an I/O +completion port. So the first constraint is: + + **The blocking/nonblocking io mode of a new socket is committed the + first time a potentially-blocking io function is invoked on the + socket. Once the io mode of a socket is committed, it cannot be + changed.** + +The potentially-blocking io functions include <tt>PR_Connect()</tt>, +<tt>PR_Accept()</tt>, <tt>PR_AcceptRead()</tt>, <tt>PR_Read()</tt>, +<tt>PR_Write()</tt>, <tt>PR_Writev()</tt>, <tt>PR_Recv()</tt>, +<tt>PR_Send()</tt>, <tt>PR_RecvFrom()</tt>, <tt>PR_SendTo()</tt>, and +<tt>PR_TransmitFile(),</tt> and do not include <tt>PR_Bind()</tt> and +<tt>PR_Listen()</tt>. + +In blocking mode, any of these potentially-blocking functions requires +the use of the NT I/O completion port. So at that point we must +determine whether to associate the socket with the I/O completion or +not, and that decision cannot be changed later. + +There is a second constraint, due to the use of NT asynchronous I/O and +the recycling of used sockets: + + **The new socket returned by <tt>PR_Accept()</tt> or + <tt>PR_AcceptRead()</tt> inherits the blocking/nonblocking io mode of + the listening socket and this cannot be changed.** + +The socket returned by <tt>PR_Accept()</tt> or <tt>PR_AcceptRead()</tt> +on a blocking, listening socket may be a recycled socket previously used +in a <tt>PR_TransmitFile()</tt> call. Since <tt>PR_TransmitFile()</tt> +only operates in blocking mode, this recycled socket can only be reused +in blocking mode, hence the above constraint. + +Because these constraints only apply to NT, it is advised that you test +your cross-platform code that uses nonblocking io on NT early in the +development cycle. These constraints are enforced in the debug NSPR +library by assertions. + +.. _Differences_from_Blocking_IO: + +Differences from Blocking IO +---------------------------- + +- In nonblocking mode, the timeout argument for the io functions is + ignored. +- <tt>PR_AcceptRead()</tt> and <tt>PR_TransmitFile()</tt> only work on + blocking sockets. They do not make sense in nonblocking mode. +- <tt>PR_Write()</tt>, <tt>PR_Send()</tt>, <tt>PR_Writev()</tt> in + blocking mode block until the entire buffer is sent. In nonblocking + mode, they cannot block, so they may return with just sending part of + the buffer. + +.. _PR_Poll()_or_PR_Select(): + +PR_Poll() or PR_Select()? +------------------------- + +<tt>PR_Select()</tt> is deprecated, now declared in +<tt>private/pprio.h</tt>. Use <tt>PR_Poll()</tt> instead. + +The current implementation of <tt>PR_Select()</tt> simply calls +<tt>PR_Poll()</tt>, so it is sure to have worse performance. Also, +native file descriptors (socket handles) cannot be added to +<tt>PR_fd_set</tt>, i.e., the functions <tt>PR_FD_NSET</tt>, +<tt>PR_FD_NCLR</tt>, <tt>PR_FD_NISSET</tt> do not work. + +PR_Available() +-------------- + +When <tt>PR_Available()</tt> returns 0, it may mean one of two things: + +- There is no data available for reading on that socket. I.e., + <tt>PR_Recv()</tt> would block (a blocking socket) or fail with + <tt>PR_WOULD_BLOCK_ERROR</tt> (a nonblocking socket). +- The TCP connection on that socket has been closed (end of stream). + +These two cases can be distinguished by <tt>PR_Poll()</tt>. If +<tt>PR_Poll()</tt> reports that the socket is readable (i.e., +<tt>PR_POLL_READ</tt> is set in <tt>out_flags</tt>), and +<tt>PR_Available()</tt> returns 0, this means that the socket connection +is closed. + +.. _Current_Status: + +Current Status +-------------- + +Implemented across all supported platforms. diff --git a/docs/nspr/nonblockinglayeredio.rst b/docs/nspr/nonblockinglayeredio.rst new file mode 100644 index 0000000000..19de77a888 --- /dev/null +++ b/docs/nspr/nonblockinglayeredio.rst @@ -0,0 +1,94 @@ +Non-blocking layered I/O +======================== + +*[last edited by AOF 24 March 1998 14:15]* +I've recently been working on a long standing issue regarding NSPR's I/O +model. For a long time I've believed that the non-blocking I/O prevalent +in classic operating systems (e.g., UNIX) was the major determent for +having an reasonable layered protocols. Now that I have some first hand +experience, albeit just a silly little test program, I am more convinced +that ever of this truth. + +This memo is some of what I think must be done in NSPR's I/O subsystem +to make layered, non-blocking protocols workable. It is just a proposal. +There is an API change. + +Layered I/O +----------- + +NSPR 2.0 defines a structure by which one may define I/O layers. Each +layer looks basically like any other in that it still uses a +:ref:`PRFileDesc` as a object identifier, complete with the +**``IOMethods``** table of functions. However, each layer may override +default behavior of a particular operation to implement other services. +For instance, the experiment at hand is one that implements a little +reliable echo protocol; the client sends *n* bytes, and the same bytes +get echoed back by the server. In the non-layered design of this it is +straight forward. +The goal of the experiment was to put a layer between the client and +the network, and not have the client know about it. This additional +layer is one that, before sending the client's data, must ask permission +from the peer layer to send that many bytes. It imposes an additional +send and response inside of each client visible send operation. The +receive operations parallel the sends. Before actually receiving real +client data, the layer receives a notification that the other would like +to send some bytes. The layer is responsible for granting permission for +that data to be sent, then actually receiving the data itself, which is +delivered to the client. + +The synchronous form of the layer's operation is straight forward. A +call to receive (:ref:`PR_Recv`) first receives the request to send, +sends (:ref:`PR_Send`) the grant, then receives the actual data +(:ref:`PR_Recv`). All the client of the layer sees is the data coming +in. Similar behavior is observed on the sending side. + +Non-blocking layered +-------------------- + +The non-blocking method is not so simple. Any of the I/O operations +potentially result in an indication that no progress can be made. The +intermediate layers cannot act directly on this information, but must +store the state of the I/O operation until it can be resumed. The method +for determining that a I/O operation can make progress is to call +:ref:`PR_Poll` and indicating what type of progress is desired, +either input or output (or some others). Therein lies the problem. +The intermediate layer is performing operations that the client is +unaware. So when the client calls send (:ref:`PR_Send`) and is told +that the operation would block, it is possible that the layer below is +actually doing a receive (:ref:`PR_Recv`). The problem is that the +flag bits passed to :ref:`PR_Poll` are only reflective of the +client's knowledge and desires. This is further complicated by the fact +that :ref:`PR_Poll` is not layered. That is each layer does not have +the opportunity to override the behavior. It operates, not on a single +file descriptor (:ref:`PRFileDesc`), but on an arbitrary collection of +file descriptors. + +Into the picture comes another I/O method, **``poll()``**. Keep in mind +that all I/O methods are those that are part of the I/O methods table +structure (:ref:`PRIOMethods`). These functions are layered, and layers +may and sometimes must override their behavior by offering unique +implementations. The **``poll()``** method is used to provide two +modifying aspects to the semantics of :ref:`PR_Poll`: redefining the +polling bits (i.e., what to poll for) and to indicate that a layer is +already able to make progress in the manner suggested by the polling +bits. + +The **``poll()``** method is called by :ref:`PR_Poll` as the latter +is building the structure to provide the operating system call. The +stack's top layer will be called first. Each layer's implementation is +responsible for performing appropriate operations and possibly calling +the next lower layer's **``poll()``** method. +What the poll method is returning are the appropriate flags to assign to +the operating system's call. A layer would compute these based on the +values of the argument **``in_flags``** and possibly some state +maintained by the layer for the particular file descriptor. + +Additionally, if the layer has buffered data that will allow the +operation defined by **``in_flags``** to make progress, it will set +corresponding bits in **``out_flags``**. For instance, if +**``in_flags``** indicates that the client (or higher layer) wishes to +test for read ready and the layer has input data buffered, it would set +the read bits in the **``out_flags``**. If that is the case, then it +should also suppress the calling of the next lower layer's +**``poll()``** method and return a value equal to that of +**``in_flags``**. diff --git a/docs/nspr/nspr_build_instructions.rst b/docs/nspr/nspr_build_instructions.rst new file mode 100644 index 0000000000..d927a6bd05 --- /dev/null +++ b/docs/nspr/nspr_build_instructions.rst @@ -0,0 +1,136 @@ +NSPR build instructions +======================= + +Prerequisites +~~~~~~~~~~~~~ + +On Windows, the NSPR build system needs GNU make and a Unix command-line +utility suite such as MKS Toolkit, Cygwin, and MSYS. The easiest way to +get these tools is to install the +:ref:`MozillaBuild` package. + +Introduction +~~~~~~~~~~~~ + +The top level of the NSPR source tree is the ``mozilla/nsprpub`` +directory. Although ``nsprpub`` is a subdirectory under ``mozilla``, +NSPR is independent of the Mozilla client source tree. + +Building NSPR consists of three steps: + +#. run the configure script. You may override the compilers (the CC + environment variable) or specify options. +#. build the libraries +#. build the test programs + +For example, + +:: + + # check out the source tree from Mercurial + hg clone https://hg.mozilla.org/projects/nspr + # create a build directory + mkdir target.debug + cd target.debug + # run the configure script + ../nspr/configure [optional configure options] + # build the libraries + gmake + # build the test programs + cd pr/tests + gmake + +On Mac OS X, use ``make``, which is GNU ``make``. + +.. _Configure_options: + +Configure options +~~~~~~~~~~~~~~~~~ + +Although NSPR uses autoconf, its configure script has two default values +that are different from most open source projects. + +#. If the OS vendor provides a compiler (for example, Sun and HP), NSPR + uses that compiler instead of GCC by default. +#. NSPR build generates a debug build by default. + +.. _--disable-debug_--enable-optimize: + +--disable-debug --enable-optimize +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Specify these two options to generate an optimized (release) build. + +These two options can actually be used independently, but it's not +recommended. + +--enable-64bit +^^^^^^^^^^^^^^ + +On a dual 32-bit/64-bit platform, NSPR build generates a 32-bit build by +default. To generate a 64-bit build, specify the ``--enable-64bit`` +configure option. + +.. _--targetx86_64-pc-mingw32: + +--target=x86_64-pc-mingw32 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For 64-bit builds on Windows, when using the mozbuild environment. + +.. _--enable-win32-target.3DWIN95: + +--enable-win32-target=WIN95 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This option is only used on Windows. NSPR build generates a "WINNT" +configuration by default on Windows for historical reasons. We recommend +most applications use the "WIN95" configuration. The "WIN95" +configuration supports all versions of Windows. The "WIN95" name is +historical; it should have been named "WIN32". + +To generate a "WIN95" configuration, specify the +``--enable-win32-target=WIN95`` configure option. + +.. _--enable-debug-rtl: + +--enable-debug-rtl +^^^^^^^^^^^^^^^^^^ + +This option is only used on Windows. NSPR debug build uses the release C +run-time library by default. To generate a debug build that uses the +debug C run-time library, specify the ``--enable-debug-rtl`` configure +option. + +.. _Makefile_targets: + +Makefile targets +~~~~~~~~~~~~~~~~ + +- all (default) +- clean +- realclean +- distclean +- install +- release + +.. _Running_the_test_programs: + +Running the test programs +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The tests were built above, in the ``pr/tests`` directory. + +On Mac OS X, they can be executed with the following: + +.. code:: + + /bin/sh: + + $ cd pr/tests + $ DYLD_LIBRARY_PATH=../../dist/lib ./accept + PASS + $ + $ # to run all the NSPR tests... + $ + $ DYLD_LIBRARY_PATH=../../dist/lib ../../../nspr/pr/tests/runtests.sh ../.. diff --git a/docs/nspr/nspr_contributor_guide.rst b/docs/nspr/nspr_contributor_guide.rst new file mode 100644 index 0000000000..08a0ac2f99 --- /dev/null +++ b/docs/nspr/nspr_contributor_guide.rst @@ -0,0 +1,182 @@ +NSPR contributor guide +====================== + +**Abstract:** + + NSPR accepts contributions in the form of bugfixes, new features, + libraries, platform ports, documentation, test cases and other items + from many sources. We (the NSPR module owners) sometimes disappoint + our contributors when we must reject their contributions. We reject + contributions for a variety of reasons. Some of these reasons are not + obvious to an outside observer. NSPR wishes to document some + guidelines for those who would contribute to NSPR. These guidelines + should help the contributor in crafting his contribution, increasing + its likelihood for acceptance. + +General Guidelines +~~~~~~~~~~~~~~~~~~ + +*Downward Compatibility* +^^^^^^^^^^^^^^^^^^^^^^^^ + +Because many different applications, besides the mozilla client, use the +NSPR API, the API must remain downward compatible across even major +releases. This means that the behavior of an existing public API item in +NSPR cannot change. Should you need to have a similar API, with some +slightly different behavior or different function prototype, then +suggest a new API with a different name. + +*C Language API* +^^^^^^^^^^^^^^^^ + +The NSPR API is a C Language API. Please do not contribute Java, C or +other language wrappers. + +*Coding Style* +^^^^^^^^^^^^^^ + +NSPR does not have a documented coding style guide. Look at the extant +code. Make yours look like that. Some guidelines concerning naming +conventions can be found in :ref:`NSPR_Naming_Conventions`. +in the :ref:`NSPR API Reference`. + +*Ownership of your contribution* +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you contribute something to NSPR, you must have intellectual +property rights to that contribution. This means that you cannot give us +something you snatched from somewhere else;. it must be your own +invention, free and clear of encumberment of anyone or anything else; +pay close attention to the rights of your "Day-Job" employer. If you +snatched it from somewhere else, tell us where; show us where the right +to incorporate it into NSPR exists. + +*License under MPL or GPL* +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you contribute material to NSPR, you agree to allow your +contribution to be licensed under the MPL or GPL. + +BugFixes +~~~~~~~~ + +Use `Bugzilla <https://bugzilla.mozilla.org/>`__ to track bugs. Document +the bug or use an existing report. Be verbose in describing what you are +doing and why. + +Include your changes as diffs in an attachment to the BugZilla report. + +Use a coding style consistent with the source file you are changing. + +New Features +~~~~~~~~~~~~ + +For purposes of this paper, a "new feature" is defined as some API +addition that goes into the core NSPR library, for example: +``libnspr4.dll`` + +NSPR is mostly complete. New APIs are driven mostly by the OS vendors as +they add new features. Should you decide that there's something that +NSPR does not cover that should be covered, let's talk. Your proposed +API should encapsulate a relatively low level capability as would be +found in a system call or libc. + +Your new feature must be implemented on all platforms supported by NSPR. +When you consider a new API for NSPR ask yourself if your proposed +feature can implement it across all platforms supported by NSPR. If +several platforms cannot be made to implement your API, then it is not a +good candidate for inclusion in NSPR. + +Before you begin what may be a substantial effort in making a candidate +feature for NSPR, talk to us. We may tell you that you have a good idea; +we may say that it really is not a good candidate for inclusion in NSPR; +we may give you suggestions on what would make it more generalized, +hence a good candidate for inclusion in NSPR. + +Use `Bugzilla <https://bugzilla.mozilla.org>`__ to track your work. Be +verbose. + +NSPR wants you to document your work. If we accept it, we are going to +have to answer questions about it and/or maintain it. These are some +guidelines for new APIs that you may add to NSPR. + +**Header File Descriptions**. Provide header file descriptions that +fully document your public typedefs, enums, macros and functions. + +See: +`prshm.h <http://lxr.mozilla.org/nspr/source/nsprpub/pr/include/prshm.h>`__ +as an example of how your header file(s) should be documented. + +*Source File Descriptions*o. Provide descriptive documentation in your +source (*.c) files. Alas, we have no source files documented as we think +they should be. + +The following are some general guidelines to use when implementing new +features: + +- Don't export global variables +- Your code must be thread safe +- You must provide test cases that test all APIs you are adding. See: + [#TestCases Test Cases] + +New Libraries +~~~~~~~~~~~~~ + +All the guidelines applicable to [#NewFeatures New Features] applies to +new libraries. + +For purposes of this paper, a "new library" is defined as a library under +the ``mozilla/nsprpub/lib`` directory tree and built as a separate +library. These libraries exist, for the most part, as "legacy" code from +NSPR 1.0. [Note that the current NSPR module owners do not now nor never +have been involved with NSPR 1.0.]. Such is life. That said: There are +some libraries that implement functions intended for use with +applications using NSPR, such as ``...nsprpub/lib/libc/plgetopt.*.`` + +- generally useful +- platform abstractions +- you agree to sustain, bug fix +- May rely on the NSPR API +- May NOT rely on any other library API + +New Platform Ports +~~~~~~~~~~~~~~~~~~ + +- all NSPR API items must be implemented +- platform specific headers in ``pr/include/md/_platformname.[h!cfg]`` +- platform specific code in ``pr/src/md/platform/*.c`` +- make rules in ``config/_platform.mk`` + +Documentation +~~~~~~~~~~~~~ + +The files for NSPR's documentation are maintained using a proprietary +word processing system [don't ask]. Document your work as described in +[#NewFeatures New Features]. Use the style of other NSPR documentation. +We will see that your documentation is transcribed into the appropriate +word processor and the derived HTML shows up on mozilla.org + +Test Cases +~~~~~~~~~~ + +You should provide test cases for all new features and new libraries. + +Give consideration to providing a test case when fixing a bug if an +existing test case did not catch a bug it should have caught. + +The new test cases should be implemented in the style of other NSPR test +cases. + +Test cases should prove that the added API items work as advertised. + +Test cases should serve as an example of how to use the API items. + +Test cases should provoke failure of every API item and report its +failure. + +Frequently Asked Questions (FAQ) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Q:** Why was my contribution rejected? + +**A:** Check the Bugzilla report covering your contribution. diff --git a/docs/nspr/nspr_poll_method.rst b/docs/nspr/nspr_poll_method.rst new file mode 100644 index 0000000000..6c15861562 --- /dev/null +++ b/docs/nspr/nspr_poll_method.rst @@ -0,0 +1,134 @@ +NSPR pool method +================ + +This technical note documents the poll method of PRFileDesc. The poll +method is not to be confused with the PR_Poll function. The poll method +operates on a single NetScape Portable Runtime (NSPR) file descriptor, +whereas PR_Poll operates on a collection of NSPR file descriptors. +PR_Poll uses the poll method behind the scene, but it is also possible +to use the poll method directly. + +We consider a stack of *NSPR I/O layers* on top of the *network +transport*. Each I/O layer is represented by a PRFileDesc structure and +the protocol of that layer is implemented by a PRIOMethods table. The +bottom layer is a wrapper for the underlying network transport. The NSPR +library provides a reference implementation of the bottom layer using +the sockets API, but you can provide your own implementation of the +bottom layer using another network transport API. The poll method is one +of the functions in the PRIOMethods table. The prototype of the poll +method is + +.. code:: + + PRInt16 poll_method(PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags); + +The purpose of the poll method is to allow a layer to modify that flags +that will ultimately be used in the call to the underlying network +transport's select (or equivalent) function, and to indicate that a +layer is already able to make progress in the manner suggested by the +polling flags. The arguments and return value of the poll method are +described below. + +.. _in_flags_input_argument: + +in_flags [input argument] +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The in_flags argument specifies the events at the **top layer** of the +I/O layer stack that the caller is interested in. + +- For PR_Recv, you should pass PR_POLL_READ as the in_flags argument to + the poll method +- For PR_Send, you should pass PR_POLL_WRITE as the in_flags argument + to the poll method + +.. _out_flags_output_argument: + +out_flags [output argument] +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If an I/O layer is ready to satisfy the I/O request defined by in_flags +without involving the underlying network transport, its poll method sets +the corresponding event in \*out_flags on return. + +For example, consider an I/O layer that buffers input data. If the +caller wishes to test for read ready (that is, PR_POLL_READ is set in +in_flags) and the layer has input data buffered, the poll method would +set the PR_POLL_READ event in \*out_flags. It can determine that without +asking the underlying network transport. + +The current implementation of PR_Poll (the primary user of the poll +method) requires that the events in \*out_flags reflect the caller's +view. This requirement may be relaxed in a future NSPR release. To +remain compatible with this potential semantic change, NSPR clients +should only use \*out_flags as described in the *How to use the poll +method* section below. + +.. _Return_value: + +Return value +~~~~~~~~~~~~ + +If the poll method stores a nonzero value in \*out_flags, the return +value will be the value of in_flags. (Note: this may change in a future +NSPR release if we make the semantic change to \*out_flags mentioned +above. Therefore, NSPR clients should only use the return value as +described in *How to use the poll method* section below.) If the poll +method stores zero in \*out_flags, the return value will be the bottom +layer's desires with respect to the in_flags. Those are the events that +the caller should poll the underlying network transport for. These +events may be different from the events in in_flags (which reflect the +caller's view) for some protocols. + +.. _How_to_use_the_poll_method: + +How to use the poll method +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The poll method should only be used with a NSPR file descriptor in +**non-blocking** mode. Most NSPR clients call PR_Poll and do not call +the poll method directly. However, PR_Poll can only used with a stack +whose bottom layer is NSPR's reference implementation. If you are using +your own implementation of the bottom layer, you must call the poll +method as follows. + +Declare two PRInt16 variables to receive the return value and the +out_flags output argument of the poll method. + +.. code:: + + PRInt16 new_flags, out_flags; + +If you are going to call PR_Recv, pass PR_POLL_READ as the in_flags +argument. + +.. code:: + + new_flags = fd->methods->poll(fd, PR_POLL_READ, &out_flags); + +If you are going to call PR_Send, pass PR_POLL_WRITE as the in_flags +argument. + +.. code:: + + new_flags = fd->methods->poll(fd, PR_POLL_WRITE, &out_flags); + +If you are interested in calling both PR_Recv and PR_Send on the same +file descriptor, make two separate calls to the poll method, one with +PR_POLL_READ as in_flags and the other with PR_POLL_WRITE as in_flags, +so that you know what events at the network transport layer PR_POLL_READ +and PR_POLL_WRITE are mapped to, respectively. + +On return, if (new_flags & out_flags) is nonzero, you can try PR_Recv or +PR_Send immediately. + +Otherwise ((new_flags & out_flags) is 0), you should do the following. + +- If new_flags contains PR_POLL_READ, you should try PR_Recv or PR_Send + when the underlying network transport is readable +- If new_flags contains PR_POLL_WRITE, you should try PR_Recv or + PR_Send when the underlying network transport is writable + +**Important** do not use out_flags in any way other than testing if +(new_flags & out_flags) is 0. This is how PR_Poll (the primary user and +hence the de facto specification of the poll method) uses out_flags. diff --git a/docs/nspr/nspr_release_procedure.rst b/docs/nspr/nspr_release_procedure.rst new file mode 100644 index 0000000000..c482c882d9 --- /dev/null +++ b/docs/nspr/nspr_release_procedure.rst @@ -0,0 +1,50 @@ +NSPR release procedure +====================== + +Release checklist +~~~~~~~~~~~~~~~~~ + +#. Change the NSPR version in ``mozilla/nsprpub/pr/include/prinit.h``. +#. Change the NSPR version in + ``mozilla/nsprpub/{configure.in,configure}``. +#. Change the NSPR version in ``mozilla/nsprpub/pr/tests/vercheck.c``. +#. Change the NSPR version in ``mozilla/nsprpub/admin/repackage.sh``. + +.. _Source_tarball: + +Source tarball +~~~~~~~~~~~~~~ + +.. _Binary_distributions: + +Binary distributions +~~~~~~~~~~~~~~~~~~~~ + +Right now I use the ``mozilla/nsprpub/admin/repackage.sh`` script to +generate the binary distributions published on ftp.mozilla.org. As the +name of the shell script implies, ``repackage.sh`` merely repackages +binary distributions in a different format. + +Before you run ``repackage.sh``, you need to have built the binary +distributions using the "gmake release" makefile target. These binary +distributions are jar files, which are really zip files, and they are +published in the directory ``/share/builds/components``. This design +comes from the Netscape days. + +The ``repackage.sh`` script repackages the jar files into the form most +commonly used on that platform. So on Unix it repackages the jar files +into gzipped tar files, and on Windows it repackages the jar files into +zip files. + +Edit the ``repackage.sh`` script to customize it for your environment. + +After you have run ``repackage.sh``, follow the +`instructions <http://www.mozilla.org/build/ftp-stage.html>`__ in to +upload the files to ftp.mozilla.org's staging server, so that they +eventually show up on ftp.mozilla.org. The host ftp.mozilla.org can be +accessed via the ftp, http, and https protocols. We recommend using +https://ftp.mozilla.org/. + +**Note:** For NSS, the script equivalent to NSPR's ``repackage.sh`` is +``/u/robobld/bin/sbsinit/nss/push/buildbindist.sh`` in the "SVBuild" +source tree. diff --git a/docs/nspr/nspr_s_position_on_abrupt_thread_termination.rst b/docs/nspr/nspr_s_position_on_abrupt_thread_termination.rst new file mode 100644 index 0000000000..7cbda0c2c6 --- /dev/null +++ b/docs/nspr/nspr_s_position_on_abrupt_thread_termination.rst @@ -0,0 +1,88 @@ +NSPR's position on abrupt thread termination +============================================ + +This memo describes my position on a facility that is currently under +discussion for inclusion in the NetScape Portable Runtime (NSPR); the +ability of a thread to abruptly exit. I resist including this function +in NSPR because it results in bad programming practice and unsupportable +programs. + + *Threads are not processes.* + +Abrupt termination has been available in the UNIX/C environment for some +time (``exit()``), and I assume that the basic semantics defined there +are applicable here. In that environment, ``exit()`` may be called and +any time, and results in the calling thread's immediate termination. In +the situation where it was defined (UNIX), which has only a single +thread of execution, that is equivalent to terminating the process. The +process abstraction is then responsible for closing all open files and +reclaiming all storage that may have been allocated during the process' +lifetime. + +This practice does not extend to threads. Threads run within the +confines of a process (or similar abstractions in other environments). +Threads are lightweight because they do not maintain the full protection +domain provided by a process. So in a threaded environment, what is the +parallel to UNIX' ``exit()``? + +NSPR has defined a function, callable by any thread within a process at +any time, called ``PR_ProcessExit()``. This is identical to UNIX +``exit()`` and was so named in an effort to make the obvious even more +so. When called, the process exits, closing files and reclaiming the +process' storage. + +Certain people have been disappointed when NSPR did not provide a +functional equivalent to exit just a particular thread. Apparently they +have failed to consider the ramifications. If a thread was to abruptly +terminate, there is no recording of what resources it owns and should +therefore be reclaimed. Those resources are in fact, owned by the +process and shared by all the threads within the process. + +In the general course of events when programming with threads, it is +very advantageous for a thread to have resources that it and only it +knows about. In the natural course of events, these resources will be +allocated by a thread, used for some period of time, and then freed as +the stack unwinds. In these cases, the presence of the data is recorded +only on the stack, known only to the single thread (normally referred to +as *encapsulated*). + +The problem with abrupt termination is that it can happen at any time, +to a thread that is coded correctly to handle both normal and +exceptional situations, but will be unable to do so since it will be +denied the opportunity to complete execution. It can happen because it +called out of its own scope into some lazily implemented library. + +NSPR's answer to this is that there is no abrupt thread termination. All +threads must unwind and return from their root function. If they cannot, +because of some state corruption, then they must assume that the +corruption, like the state, is shared, and their only resource is for +the process to terminate. + +To make this solution work requires that a function that encounters an +error be designed such that it first repairs its immediate state, and +then reports that error to its caller. If the caller cannot deal with +the failure, it must do the same. This process continues until the +thread either recovers from the malady or returns from the root +function. This is not all that difficult (though having done it a number +of times to already existing code, I will admit it isn't much fun +either). + +The implementation of either strategy within the NSPR runtime is not +difficult. That is not what this memo is about. This is about providing +an API that coaxes people to do the right thing in as many ways as +possible. The existence of ``exit()`` in the UNIX/C environment is a +perfect example of how programmers will employ the most expediant +solution available. The definition of the language C is such that +returning from ``main()`` is a perfectly fine thing to do. But what +percentage of C programs actually bother? In UNIX, with its complex +definition of a protection domain, it happens to work (one might even +say it's more efficient) to exit from anywhere. But threads are not +processes. If threads have to maintain the same type of resource +knowledge as a process, they loose all of their benefit. + +Threads are an implementation strategy to provide the illusion of +concurrency within a process. They are alternatives to large state +machines with mostly non-blocking library functions. When the latter is +used to provide concurrency, calling ``exit()`` will terminate the +entire process. Why would anyone expect a thread to behave differently? +Threads are not processes. diff --git a/docs/nspr/optimizing_applications_for_nspr.rst b/docs/nspr/optimizing_applications_for_nspr.rst new file mode 100644 index 0000000000..1bced161a8 --- /dev/null +++ b/docs/nspr/optimizing_applications_for_nspr.rst @@ -0,0 +1,45 @@ +Optimizing applications for NSPR +================================ + +NetScape Portable Runtime (NSPR) tries to provide a consistent level of +service across the platforms it supports. This has proven to be quite +challenging, a challenge that was met to a large degree, but there is +always room for improvement. The casual client may not encounter a need +to know the details of the shortcomings to the level described here, but +if and when clients become more sophisticated, these issues will +certainly surface. + + *This memo is by no way complete.* + +Multiplatform +------------- + +- Do not call any blocking system call from a local thread. The only + exception to this rule is the <tt>select()</tt> and <tt>poll()</tt> + system calls on Unix, both of which NSPR has overridden to make sure + they are aware of the NSPR local threads. +- In the combined (MxN) model, which includes NT, IRIX (sprocs), and + pthreads-user, the primordial thread is always a local thread. + Therefore, if you call a blocking system call from the primordial + thread, it is going to block more than just the primordial thread and + the system may not function correctly. On NT, this problem is + especially obvious because the idle thread, which is in charge of + driving the asynch io completion port, is also blocked. Do not call + blocking system calls from the primordial thread. Create a global + thread and call the system call in that thread, and have the + primordial thread join that thread. +- NSPR uses timer signals to implement thread preemption for local + threads on some platforms. If all the software linked into the + application is not ported to the NSPR API, the application may fail + because of threads being preempted during critical sections. To + disable thread preemption call + <tt>PR_DisableClockInterrupts()</tt>during initialization. +- Interrupting threads (via <tt>PR_Interrupt()</tt>) on threads blocked + in I/O functions is implemented to various degrees on different + platforms. The UNIX based platforms all implement the function though + there may be up to a 5 second delay in processing the request. +- The mechanism used to implement <tt>PR_Interrupt()</tt> on the + *pthreads* versions of NSPR is flawed. No failure attributable to the + flaw has shown up in any tests or products - yet. The specific area + surrounding pthread's *continuation thread* has been both observed + and empirically proven faulty, and a correction identified. diff --git a/docs/nspr/platforms.rst b/docs/nspr/platforms.rst new file mode 100644 index 0000000000..6e251a4d71 --- /dev/null +++ b/docs/nspr/platforms.rst @@ -0,0 +1,145 @@ +NSPR platforms +============== + +Build System and Supported Platforms +------------------------------------ + +NSPR has been implemented on over 20 platforms. A platform may have +more than one implementation strategy of its multi threading and I/O +facilities. This article explains the NSPR build system and how to +specify a particular implementation strategy, compiler or compiler +switches, or the target OS for your build on each platform. + +Implementation Strategies +------------------------- + +Threads are at the core of NSPR, and the I/O functions are tied to the +multi threading facilities because many I/O functions may block the +calling threads. NSPR has multiple implementation strategies of its +multi threading and I/O functions. The various implementation strategies +can be organized into the hierarchy below: + +- **Classic NSPR** (This is our first code base, hence the term + "classic NSPR"): + +**Local threads only**: All threads are user-level threads implemented +by NSPR. +**Global threads only**: All threads are native threads supplied by the +OS vendor. For example, Solaris UI (Unix International) threads and +Win32 threads. +**Combined**: NSPR multiplexes user-level threads on top of native, +kernel-level threads. This is also called the MxN model. At present, +there are three implementations of the combined model. + +- IRIX: sprocs + NSPR user-level threads +- Windows NT: Win32 threads + NT fibers +- **Pthreads-user**: kernel-level pthreads + NSPR user-level threads + +**Pthreads**: All threads are pthreads. The relevant code is in +``mozilla/nsprpub/pr/src/pthreads`` (threads and I/O). +Classic NSPR and pthreads have relatively disjoint code bases in the +threads and I/O areas: + +- Classic NSPR: ``mozilla/nsprpub/pr/src/threads/combined`` (threads), + ``mozilla/nsprpub/pr/src/io`` (I/O) +- Pthreads: ``mozilla/nsprpub/pr/src/pthreads`` (threads and I/O) + +Note that some files under ``mozilla/nsprpub/pr/src/io`` are shared by +both classic NSPR and pthreads. Consult +``mozilla/nsprpub/pr/src/Makefile`` for the definitive list of files +used by each implementation strategy (see the definition of the makefile +variable ``OBJS``). + +Compilers +--------- + +For ease of integration with third-party libraries, which may use native +threads, NSPR uses the native threads whenever possible. As a result, +native compilers are used to build NSPR on most platforms because they +have better debugging support for native threads. The only exception is +Solaris, where both cc and gcc are used. + +NSPR Build System +----------------- + +NSPR build system is based on GNU make. +We use GNU make 3.74 on Unix, but our makefiles should +work fine under newer versions of GNU make. + +Every directory in NSPR has a makefile named ``Makefile``, which +includes the makefile fragments in ``mozilla/nsprpub/config``. NSPR +makefiles implement the common Makefile targets such as +``export``, ``libs``, and ``install``. However, some makefiles targets +are no-op in NSPR because they are not necessary for NSPR. + +To build NSPR, change directory to the root of our source tree +``cd mozilla/nsprpub`` +and then issue the command +``gmake`` +Make will recursively go into all the subdirectories and the right +things will happen. + +The table below lists the common NSPR makefile targets. + ++-----------------------------------+-----------------------------------+ +| ``all`` | The default target. Same as | +| | ``export`` ``libs`` ``install``. | ++-----------------------------------+-----------------------------------+ +| ``export`` | Do a complete build. | ++-----------------------------------+-----------------------------------+ +| ``libs`` | No-op. | ++-----------------------------------+-----------------------------------+ +| ``install`` | No-op. | ++-----------------------------------+-----------------------------------+ +| ``depend`` | No-op. **This means that NSPR | +| | makefiles do not have header file | +| | dependencies.** | ++-----------------------------------+-----------------------------------+ +| ``clean`` | Remove ``.o`` files. | ++-----------------------------------+-----------------------------------+ +| ``clobber`` | Remove ``.o`` files, libraries, | +| | and executable programs. | ++-----------------------------------+-----------------------------------+ +| ``realclean`` | Remove all generated files and | +| | directories. | ++-----------------------------------+-----------------------------------+ +| ``clobber_all`` | Same as ``realclean``. | ++-----------------------------------+-----------------------------------+ + +The table below lists common makefile variables that one can specify +on the command line to customize a build.. + ++-----------------------------------+-----------------------------------+ +| ``BUILD_OPT`` | Optimized build (default: debug | +| | build). | ++-----------------------------------+-----------------------------------+ +| ``OS_TARGET`` | Set to the target OS (``WIN95`` | +| | or ``WIN16``) when doing | +| | cross-compilation on NT (default: | +| | same as the host OS). | ++-----------------------------------+-----------------------------------+ +| ``NS_USE_GCC`` | Use gcc and g++ (default: native | +| | compilers). | ++-----------------------------------+-----------------------------------+ +| ``USE_PTHREADS`` | Build pthreads version. | ++-----------------------------------+-----------------------------------+ +| ``CLASSIC_NSPR`` | Build classic NSPR version | +| | (usually local threads only). | ++-----------------------------------+-----------------------------------+ +| ``PTHREADS_USER`` | Build pthreads-user version. | ++-----------------------------------+-----------------------------------+ +| ``LOCAL_THREADS_ONLY`` | Build local threads only version. | ++-----------------------------------+-----------------------------------+ +| ``USE_DEBUG_RTL`` | On Win32, compile with ``/MDd`` | +| | in the debug build (default: | +| | ``/MD``). Optimized build always | +| | uses ``/MD``. | ++-----------------------------------+-----------------------------------+ +| ``USE_N32`` | On IRIX, compile with ``-n32`` | +| | (default: ``-32``). | ++-----------------------------------+-----------------------------------+ +| ``USE_IPV6`` | Enable IPv6. | ++-----------------------------------+-----------------------------------+ +| ``MOZILLA_CLIENT`` | Adjust NSPR build system for | +| | Netscape Client (mozilla). | ++-----------------------------------+-----------------------------------+ diff --git a/docs/nspr/process_forking_in_nspr.rst b/docs/nspr/process_forking_in_nspr.rst new file mode 100644 index 0000000000..d73291edf0 --- /dev/null +++ b/docs/nspr/process_forking_in_nspr.rst @@ -0,0 +1,23 @@ +Process forking in NSPR +======================= + +The threads provided in NetScape Portable Runtime (NSPR) are implemented +using different mechanisms on the various platforms. On some platforms, +NSPR threads directly map one-to-one to the threads provided by the +platform vendor, on other platforms NSPR threads are basically +user-level threads within a single process (with no kernel threads) and +on still others NSPR threads are user-level threads implemented on top +of one or more kernel threads within single address space. + +NSPR does not override the fork function and so, when fork is called +from the NSPR thread the results are different on the various platforms. +All the threads present in the parent process may be replicated in the +child process, only the calling thread may be replicated in the child +process or only the calling kernel thread may be replicated. + +So, to be consistent across all platforms, it is suggested that when +using fork in a NSPR thread; + +#. The exec function should be called in the child process. +#. No NSPR functions should be called in the child process before the + exec call is made. 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..a13d0b3b74 --- /dev/null +++ b/docs/nspr/reference/i_o_functions.rst @@ -0,0 +1,240 @@ +I/O functions +============= + +This chapter describes the NSPR functions used to perform operations +such as system access, normal file I/O, and socket (network) I/O. + +For sample code that illustrates basic I/O operations, see :ref:`Introduction_to_NSPR>`. +For information about the types most +commonly used with the functions described in this chapter, see `I/O +Types <I%2fO_Types>`__. + +- `Functions that Operate on + Pathnames <#Functions_that_Operate_on_Pathnames>`__ +- `Functions that Act on File + Descriptors <#Functions_that_Act_on_File_Descriptors>`__ +- `Directory I/O Functions <#Directory_I/O_Functions>`__ +- `Socket Manipulation Functions <#Socket_Manipulation_Functions>`__ +- `Converting Between Host and Network + Addresses <#Converting_Between_Host_and_Network_Addresses>`__ +- `Memory-Mapped I/O Functions <#Memory-Mapped_I/O_Functions>`__ +- `Anonymous Pipe Function <#Anonymous_Pipe_Function>`__ +- `Polling Functions <#Polling_Functions>`__ +- `Pollable Events <#Pollable_Events>`__ +- `Manipulating Layers <#Manipulating_Layers>`__ + +.. _Functions_that_Operate_on_Pathnames: + +Functions that Operate on Pathnames +----------------------------------- + +A file or directory in a file system is specified by its pathname. NSPR +uses Unix-style pathnames, which are null-terminated character strings. +Only the ASCII character set is supported. The forward slash (/) +separates the directories in a pathname. NSPR converts the slashes in a +pathname to the directory separator of the native OS--for example, +backslash (\) on Windows and colon (:) on Mac OS--before passing it to +the native system calls. + +Some file systems also differentiate drives or volumes. + +- :ref:`PR_Open` +- :ref:`PR_Delete` +- :ref:`PR_GetFileInfo` +- :ref:`PR_GetFileInfo64` +- :ref:`PR_Rename` +- :ref:`PR_Access` + + - type :ref:`PRAccessHow` + +.. _Functions_that_Act_on_File_Descriptors: + +Functions that Act on File Descriptors +-------------------------------------- + +- :ref:`PR_Close` +- :ref:`PR_Read` +- :ref:`PR_Write` +- :ref:`PR_Writev` +- :ref:`PR_GetOpenFileInfo` +- :ref:`PR_GetOpenFileInfo64` +- :ref:`PR_Seek` +- :ref:`PR_Seek64` +- :ref:`PR_Available` +- :ref:`PR_Available64` +- :ref:`PR_Sync` +- :ref:`PR_GetDescType` +- :ref:`PR_GetSpecialFD` +- :ref:`PR_CreatePipe` + +.. _Directory_I.2FO_Functions: + +Directory I/O Functions +----------------------- + +- :ref:`PR_OpenDir` +- :ref:`PR_ReadDir` +- :ref:`PR_CloseDir` +- :ref:`PR_MkDir` +- :ref:`PR_RmDir` + +.. _Socket_Manipulation_Functions: + +Socket Manipulation Functions +----------------------------- + +The network programming interface presented here is a socket API modeled +after the popular Berkeley sockets. Differences include the following: + +- The blocking socket functions in NSPR take a timeout parameter. +- Two new functions, :ref:`PR_TransmitFile` and :ref:`PR_AcceptRead`, can + exploit the new system calls of some operating systems for higher + performance. + +List of functions: + +- :ref:`PR_OpenUDPSocket` +- :ref:`PR_NewUDPSocket` +- :ref:`PR_OpenTCPSocket` +- :ref:`PR_NewTCPSocket` +- :ref:`PR_ImportTCPSocket` +- :ref:`PR_Connect` +- :ref:`PR_ConnectContinue` +- :ref:`PR_Accept` +- :ref:`PR_Bind` +- :ref:`PR_Listen` +- :ref:`PR_Shutdown` +- :ref:`PR_Recv` +- :ref:`PR_Send` +- :ref:`PR_RecvFrom` +- :ref:`PR_SendTo` +- :ref:`PR_TransmitFile` +- :ref:`PR_AcceptRead` +- :ref:`PR_GetSockName` +- :ref:`PR_GetPeerName` +- :ref:`PR_GetSocketOption` +- :ref:`PR_SetSocketOption` + +.. _Converting_Between_Host_and_Network_Addresses: + +Converting Between Host and Network Addresses +--------------------------------------------- + +- :ref:`PR_ntohs` +- :ref:`PR_ntohl` +- :ref:`PR_htons` +- :ref:`PR_htonl` +- :ref:`PR_FamilyInet` + +.. _Memory-Mapped_I.2FO_Functions: + +Memory-Mapped I/O Functions +--------------------------- + +The memory-mapped I/O functions allow sections of a file to be mapped to +memory regions, allowing read-write accesses to the file to be +accomplished by normal memory accesses. + +Memory-mapped I/O functions are currently implemented for Unix, Linux, +Mac OS X, and Win32 only. + +- :ref:`PR_CreateFileMap` +- :ref:`PR_MemMap` +- :ref:`PR_MemUnmap` +- :ref:`PR_CloseFileMap` + +.. _Anonymous_Pipe_Function: + +Anonymous Pipe Function +----------------------- + +- :ref:`PR_CreatePipe` + +.. _Polling_Functions: + +Polling Functions +----------------- + +This section describes two of the most important polling functions +provided by NSPR: + +- :ref:`PR_Poll` +- :ref:`PR_GetConnectStatus` + +.. _Pollable_Events: + +Pollable Events +--------------- + +A pollable event is a special kind of file descriptor. The only I/O +operation you can perform on a pollable event is to poll it with the +:ref:`PR_POLL_READ` flag. You cannot read from or write to a pollable +event. + +The purpose of a pollable event is to combine event waiting with I/O +waiting in a single :ref:`PR_Poll` call. Pollable events are implemented +using a pipe or a pair of TCP sockets connected via the loopback +address, therefore setting and/or waiting for pollable events are +expensive operating system calls. Do not use pollable events for general +thread synchronization; use condition variables instead. + +A pollable event has two states: set and unset. Events are not queued, +so there is no notion of an event count. A pollable event is either set +or unset. + +- :ref:`PR_NewPollableEvent` +- :ref:`PR_DestroyPollableEvent` +- :ref:`PR_SetPollableEvent` +- :ref:`PR_WaitForPollableEvent` + +One can call :ref:`PR_Poll` with the :ref:`PR_POLL_READ` flag on a pollable +event. When the pollable event is set, :ref:`PR_Poll` returns the the +:ref:`PR_POLL_READ` flag set in the out_flags. + +.. _Manipulating_Layers: + +Manipulating Layers +------------------- + +File descriptors may be layered. For example, SSL is a layer on top of a +reliable bytestream layer such as TCP. + +Each type of layer has a unique identity, which is allocated by the +runtime. The layer implementor should associate the identity with all +layers of that type. It is then possible to scan the chain of layers and +find a layer that one recognizes and therefore predict that it will +implement a desired protocol. + +A layer can be pushed onto or popped from an existing stack of layers. +The file descriptor of the top layer can be passed to NSPR I/O +functions, which invoke the appropriate version of the I/O methods +polymorphically. + +NSPR defines three identities: + +.. code:: + + #define PR_INVALID_IO_LAYER (PRDescIdentity)-1 + #define PR_TOP_IO_LAYER (PRDescIdentity)-2 + #define PR_NSPR_IO_LAYER (PRDescIdentity)0 + +- :ref:`PR_INVALID_IO_LAYER`: An invalid layer identify (for error + return). +- :ref:`PR_TOP_IO_LAYER`: The identity of the top of the stack. +- :ref:`PR_NSPR_IO_LAYER`: The identity for the layer implemented by NSPR. + +:ref:`PR_TOP_IO_LAYER` may be used as a shorthand for identifying the +topmost layer of an existing stack. For example, the following lines of +code are equivalent: + +| ``rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);`` +| ``rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer);`` + +- :ref:`PR_GetUniqueIdentity` +- :ref:`PR_GetNameForIdentity` +- :ref:`PR_GetLayersIdentity` +- :ref:`PR_GetIdentitiesLayer` +- :ref:`PR_GetDefaultIOMethods` +- :ref:`PR_CreateIOLayerStub` +- :ref:`PR_PushIOLayer` +- :ref:`PR_PopIOLayer` 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..f1187d4ebe --- /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:: + + **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..78edfc19b0 --- /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:: + + **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..8c135f844e --- /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:: + + **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..c140f60c37 --- /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:: + + **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..b198ce1a6a --- /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:: + + **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..1dba4d6a56 --- /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:: + + **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..9f9ad2767f --- /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 implementor) 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..dc264d7d85 --- /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 implementor 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..8e50ae1781 --- /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 implementor 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. diff --git a/docs/nspr/running_nspr_tests.rst b/docs/nspr/running_nspr_tests.rst new file mode 100644 index 0000000000..d877aecf2d --- /dev/null +++ b/docs/nspr/running_nspr_tests.rst @@ -0,0 +1,95 @@ +Running NSPR tests +================== + +NSPR has a test suite in the ``mozilla/nsprpub/pr/tests`` directory. + +By default, we don't build the test programs. Running ``gmake`` in the +top-level directory (``mozilla/nsprpub``) only builds the NSPR +libraries. To build the test programs, you need to change directory to +``mozilla/nsprpub/pr/tests`` and run ``gmake``. Refer to :ref:`NSPR build +instructions` for details. + +To run the test suite, run the shell script +``mozilla/nsprpub/pr/tests/runtests.sh`` in the directory where the test +program binaries reside, for example, + +.. code:: + + cvs -q co -r NSPR_4_6_6_RTM mozilla/nsprpub + mkdir linux.debug + cd linux.debug + ../mozilla/nsprpub/configure + gmake + cd pr/tests + gmake + ../../../mozilla/nsprpub/pr/tests/runtests.sh + +The output of the test suite looks like this: + +.. code:: + + NSPR Test Results - tests + + BEGIN Mon Mar 12 11:44:41 PDT 2007 + NSPR_TEST_LOGFILE /dev/null + + Test Result + + accept Passed + acceptread Passed + acceptreademu Passed + affinity Passed + alarm Passed + anonfm Passed + atomic Passed + attach Passed + bigfile Passed + cleanup Passed + cltsrv Passed + concur Passed + cvar Passed + cvar2 Passed + ... + sprintf FAILED + ... + timetest Passed + tpd Passed + udpsrv Passed + vercheck Passed + version Passed + writev Passed + xnotify Passed + zerolen Passed + END Mon Mar 12 11:55:47 PDT 2007 + +.. _How_to_determine_if_the_test_suite_passed: + +How to determine if the test suite passed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If all the tests reported **Passed** as the results, the test suite +passed. + +What if some of the tests crashed or reported **FAILED** as the results? +It doesn't necessarily mean the test suite failed because some of the +test programs are known to fail. Until the test failures are fixed, you +should run NSPR tests against **a known good version of NSPR on the same +platform**, and save the test results as the benchmark. Then you can +detect regressions of the new version by comparing its test results with +the benchmark. + +.. _Known_issues: + +Known issues +~~~~~~~~~~~~ + +Other issues with the NSPR test suite are: + +#. Some of the test programs test the accuracy of the timeout of NSPR + functions. Since none of our operating systems is a real-time OS, + such test programs may fail when the test machine is heavily loaded. +#. Some tests, such as ``pipepong`` and ``sockpong``, should not be run + directly. They will be invoked by their companion test programs + (e.g., ``pipeping`` and ``sockping``). This is not an issue if you + run ``runtests.sh`` because ``runtests.sh`` knows not to run such + test programs directly. diff --git a/docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst b/docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst new file mode 100644 index 0000000000..9aaca06a1b --- /dev/null +++ b/docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst @@ -0,0 +1,131 @@ +This technical memo is a cautionary note on using NetScape Portable +Runtime's (NSPR) IO timeout and interrupt on Windows NT 3.51 and 4.0. +Due to a limitation of the present implementation of NSPR IO on NT, +programs must follow the following guideline: + +If a thread calls an NSPR IO function on a file descriptor and the IO +function fails with <tt>PR_IO_TIMEOUT_ERROR</tt> or +<tt>PR_PENDING_INTERRUPT_ERROR</tt>, the file descriptor must be closed +before the thread exits. + +In this memo we explain the problem this guideline is trying to work +around and discuss its limitations. + +.. _NSPR_IO_on_NT: + +NSPR IO on NT +------------- + +The IO model of NSPR 2.0 is synchronous and blocking. A thread calling +an IO function is blocked until the IO operation finishes, either due to +a successful IO completion or an error. If the IO operation cannot +complete before the specified timeout, the IO function returns with +<tt>PR_IO_TIMEOUT_ERROR</tt>. If the thread gets interrupted by another +thread's <tt>PR_Interrupt()</tt> call, the IO function returns with +<tt>PR_PENDING_INTERRUPT_ERROR</tt>. + +On Windows NT, NSPR IO is implemented using NT's *overlapped* (also +called *asynchronous*) *IO*. When a thread calls an IO function, the +thread issues an overlapped IO request using the overlapped buffer in +its <tt>PRThread</tt> structure. Then the thread is put to sleep. In the +meantime, there are dedicated internal threads (called the *idle +threads*) monitoring the IO completion port for completed IO requests. +If a completed IO request appears at the IO completion port, an idle +thread fetches it and wakes up the thread that issued the IO request +earlier. This is the normal way the thread is awakened. + +.. _IO_Timeout_and_Interrupt: + +IO Timeout and Interrupt +------------------------ + +However, NSPR may wake up the thread in two other situations: + +- if the overlapped IO request is not completed before the specified + timeout. (Note that we can't specify timeout on overlapped IO + requests, so the timeouts are all handled at the NSPR level.) In this + case, the error is <tt>PR_IO_TIMEOUT_ERROR</tt>. +- if the thread gets interrupted by another thread's + <tt>PR_Interrupt()</tt> call. In this case, the error is + <tt>PR_PENDING_INTERRUPT_ERROR</tt>. + +These two errors are generated by the NSPR layer, so the OS is oblivious +of what is going on and the overlapped IO request is still in progress. +The OS still has a pointer to the overlapped buffer in the thread's +<tt>PRThread</tt> structure. If the thread subsequently exists and its +<tt>PRThread</tt> structure gets deleted, the pointer to the overlapped +buffer will be pointing to freed memory. This is problematic. + +.. _Canceling_Overlapped_IO_by_Closing_the_File_Descriptor: + +Canceling Overlapped IO by Closing the File Descriptor +------------------------------------------------------ + +Therefore, we need to cancel the outstanding overlapped IO request +before the thread exits. NT's <tt>CancelIo()</tt> function would be +ideal for this purpose. Unfortunately, <tt>CancelIo()</tt> is not +available on NT 3.51. So we can't go this route as long as we are +supporting NT 3.51. The only reliable way to cancel outstanding +overlapped IO request that works on both NT 3.51 and 4.0 is to close the +file descriptor, hence the rule of thumb stated at the beginning of this +memo. + +.. _Limitations: + +Limitations +----------- + +This seemingly harsh way to force the completion of outstanding +overlapped IO request has the following limitations: + +- It is difficult for threads to shared a file descriptor. For example, + suppose thread A and thread B call <tt>PR_Accept()</tt> on the same + socket, and they time out at the same time. Following the rule of + thumb, both threads would close the socket. The first + <tt>PR_Close()</tt> would succeed, but the second <tt>PR_Close()</tt> + would be freeing freed memory. A solution that may work is to use a + lock to ensure only one thread can be using that socket at all times. +- Once there is a timeout or interrupt error, the file descriptor is no + longer usable. Suppose the file descriptor is intended to be used for + the life time of the process, for example, the logging file, this is + really not acceptable. A possible solution is to add a + <tt>PR_DisableInterrupt()</tt> function to turn off interrupts when + accessing such file descriptors. + +.. + + *A related known bug is that timeout and interrupt don't work for + <tt>PR_Connect()</tt> on NT. This bug is due to a different + limitation in our NT implementation.* + +.. _Conclusions: + +Conclusions +----------- + +As long as we need to support NT 3.51, we need to program under the +guideline that after an IO timeout or interrupt error, the thread must +make sure the file descriptor is closed before it exits. Programs should +also take care in sharing file descriptors and using IO timeout or +interrupt on files that need to stay open throughout the process. + +When we stop supporting NT 3.51, we can look into using NT 4's +<tt>CancelIo()</tt> function to cancel outstanding overlapped IO +requests when we get IO timeout or interrupt errors. If +<tt>CancelIo()</tt> really works as advertised, that should +fundamentally solve this problem. + +If these limitations with IO timeout and interrupt are not acceptable to +the needs of your programs, you can consider using the Win95 version of +NSPR. The Win95 version runs without trouble on NT, but you would lose +the better performance provided by NT fibers and asynchronous IO. + +| + +.. _Original_Document_Information: + +Original Document Information +----------------------------- + +- Author: larryh@netscape.com +- Last Updated Date: December 1, 2004 |