You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

Chapter 23   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 Functions

Process Management Types and Constants

The types defined for process management are:

PRProcess
PRProcessAttr

PRProcess

Represents a process.


Syntax 
#include <prproces.h>


typedef struct PRProcess PRProcess;


Description
A pointer to the opaque PRProcess structure identifies a process.

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 PRProcessAttr into PR_CreateProcess when you create a new process, specifying information such as standard input/output redirection and file descriptor inheritance.

Process Management Functions

The process manipulation function fall into these categories:

Setting the Attributes of a New Process
Creating and Managing Processes

Setting the Attributes of a New Process

The functions that create and manipulate attribute sets of new processes are:

PR_NewProcessAttr
PR_ResetProcessAttr
PR_DestroyProcessAttr
PR_ProcessAttrSetStdioRedirect
PR_ProcessAttrSetCurrentDirectory
PR_ProcessAttrSetInheritableFD

PR_NewProcessAttr

Creates a process attributes structure.


Syntax 
#include <prproces.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 PRProcessAttr structure that specifies the attributes of a new process, then returns a pointer to the structure. The new 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.

PR_ResetProcessAttr

Reinitializes a process attributes structure.


Syntax 
#include <prproces.h>

void PR_ResetProcessAttr(PRProcessAttr *attr);


Parameters
The function has this parameter:

attr

A pointer to the process attributes structure to be reset.


Returns
Nothing.


Description
This function initializes the specified process attributes structure to the default attributes. A PRProcessAttr structure can be reused to create many new processes. Before using it to create a different process, re-initialize the structure with a call to PR_ResetProcessAttr.

PR_DestroyProcessAttr

Destroys a process attributes structure.


Syntax 
#include <prproces.h>

void PR_DestroyProcessAttr(PRProcessAttr *attr);


Parameters
The function has this parameter:

attr

A pointer to the process attributes structure to be destroyed.


Returns
Nothing.


Description
This function frees the memory associated with the specified process attributes structure. On return, the value of attr becomes an invalid pointer and should not be passed to other functions.

PR_ProcessAttrSetStdioRedirect

Sets the standard I/O redirection attribute in a process attributes structure.


Syntax 
#include <prproces.h>


void PR_ProcessAttrSetStdioRedirect (
   PRProcessAttr *attr, 
   PRInt32 stdioFd, 
   PRFileDesc *redirectFd);


Parameters
The function has these parameters:

attr

A pointer to the process attributes structure.

stdioFd 

A standard I/O stream. Possible values are:

 PR_StandardInput
 PR_StandardOutput
 PR_StandardError

redirectFd

A pointer to a file descriptor.


Returns
Nothing.


Description
This function redirects the specified standard I/O stream of a process created with the specified process attributes to the specified file descriptor.

PR_ProcessAttrSetCurrentDirectory

Specifies the current working directory for a new process.


Syntax 
#include <prproces.h>


PrStatus PR_ProcessAttrSetCurrentDirectory (
   PRProcess *attr,
   const char *dir);


Parameters
The function has these parameters:

attr

A pointer to the process attributes structure.

dir

The pathname of the current working directory for the new process.


Returns
If successful, PR_SUCCESS; otherwise, PR_FAILURE. Retrieve the reason for the failure by calling PR_GetError.


Description
This function sets the current working directory of the specified process attributes structure to the specified pathname. If this function is not used to set the current working directory, the new process inherits the current working directory of the parent process.

The runtime copies the pathname and maintains the copy. The function fails and the error PR_OUT_OF_MEMORY_ERROR occurs when NSPR cannot make a copy of the string dir.

PR_ProcessAttrSetInheritableFD

Sets the inheritable file descriptor in a process attributes structure.


Syntax 
#include <prproces.h>


void PR_ProcessAttrSetInheritableFD(
   PRProcess *attr, 
   PRFileDesc *fd, 
   const char *name);


Parameters
The function has these parameters: 

attr

A pointer to the process attributes structure. 

fd

A pointer to the file descriptor to be inherited by the process. 

name

A pointer to the name for the inherited file descriptor.


Returns
Nothing.


Description
The new process will inherit the file descriptor fd, which is given the string name name. The new process can get the inherited file descriptor by specifying the string name to PR_GetInheritedFileDesc.

Creating and Managing Processes

The functions that create and manage processes are:

PR_CreateProcess
PR_DetachProcess
PR_WaitProcess
PR_KillProcess

PR_CreateProcess

Creates a new process.


Syntax 
#include <prproces.h>


PRProcess *PR_CreateProcess(
    const char *path,
    char *const *argv,
    char *const *envp,
    const PRProcessAttr *attr


Parameters
The function has these parameters:

path

Pathname of an executable file.

argv

A null-terminated array of character strings specifying the command-line arguments. The first argument (argv[0]) is the name of the executable file.

envp

A null-terminated array of character strings specifying the environment strings. Each string in the array is of the form: 
    name=value 

If NULL, the new process inherits the environment of the parent process.

attr

A pointer to a PRProcessAttr structure that describes the attributes of the new process.

If NULL, the new process has the default attributes.


Returns
On success, returns a pointer to a PRProcess structure representing the new process. On failure, returns NULL. Retrieve the reason for the failure by calling PR_GetError.


Description
PR_CreateProcess() creates a new process that executes the file specified in argv[0], with the specified commmand-line arguments and environment. The specified attribute structure determines the I/O redirection and file descriptor inheritance of the new process.

The newly-created process must be either detached (PR_DetachProcess) or reaped (PR_WaitProcess), otherwise the memory for its PRProcess structure is not reclaimed and results in memory leaks.

This function can fail due to illegal access (permissions), invalid arguments, or insufficient resources.

PR_DetachProcess

Detaches a child process.


Syntax 
#include <prproces.h>


PRStatus PR_DetachProcess(PRProcess *process);


Parameters
The function has this parameter:

process

A pointer to the nondetached process to be detached.


Returns
If successful, PR_SUCCESS; otherwise, PR_FAILURE. Retrieve the reason for the failure by calling PR_GetError.


Description
This function detaches the specified process. A detached process does not need to be and cannot be reaped. On return, the value of process becomes an invalid pointer and should not be passed to other functions.

PR_WaitProcess

Waits for a process to terminate.


Syntax 
#include <prproces.h>


PRStatus PR_WaitProcess (
   PRProcess *process,
   PRInt32 *exitCode);


Parameters
The function has these parameters:

process

A pointer to the nondetached process whose termination you want to wait for.

exitCode

A pointer to a pre-allocated location to contain the exit code of the process. Can be NULL.


Returns
If successful, PR_SUCCESS; otherwise, PR_FAILURE. Retrieve the reason for the failure by calling PR_GetError.


Description
This function blocks the calling thread until the specified nondetached process has terminated. On successful completion, the function returns PR_SUCCESS. If exitCode is not NULL, the variable to which it points contains the exit status code of process.

PR_KillProcess

Terminates a process.


Syntax 
#include <prproces.h>


PRStatus PR_KillProcess(PRProcess *process);


Parameters
The function has this parameter:

process

A pointer to the process to be killed.


Returns
If successful, PR_SUCCESS; otherwise, PR_FAILURE. Retrieve the reason for the failure by calling PR_GetError.


Description
Terminates the specified process.

NOTE: It is not clear whether this function is useful, or that it can be implemented everywhere.

PR_GetInheritedFD

<<In Mozilla version, but can't find in header>>


Syntax 
PRFileDesc * PR_GetInheritedFD(const char *name);

From Mozilla:

The newly created process can use PR_GetInheritedFileDesc to get the inherited file descriptor with the name name. The name is given by its parent process. The parent and child must have some prearranged agreement on the names of inherited file descriptors. <<

Previous     Contents     Next     

Last Updated May 18, 2001