NSPR 2.0: Process management and interprocess communication

A process is an instance of a program. NSPR 2.0 provides routines to create a new process and to wait for the termination of another process. NSPR 2.0 does not provide an equivalent of the Unix fork(). The newly-created process starts its execution from the beginning of its program.

A new process can inherit specified file descriptors from its parent, and the parent can redirect the standard IO streams of the child process to specified file descriptors.

Types and constants

#include <prinit.h>

typedef struct PRProcess PRProcess;

A process is identified by a pointer to the opaque PRProcess structure.

typedef struct PRProcessAttr PRProcessAttr;

The attributes of a process to be created is described by the opaque PRProcessAttr structure. A pointer to PRProcessAttr is passed into PR_CreateProcess when a new process is created, specifying information such as input/output redirection and file descriptor inheritance.

Functions

Specifying the attributes of a new process

When creating a process, one can use a PRProcessAttr structure to specify the attributes of the new process.

PRProcessAttr *PR_NewProcessAttr(void);

PR_NewProcessAttr creates a new PRProcessAttr structure and returns a pointer to it. The new PRProcessAttr structure is initialized to the default attributes listed below:

The standard IO streams 0-2 (standard input, standard output, and standard error) are not redirected
No file descriptors are inherited by the new process.

void PR_ResetProcessAttr(PRProcessAttr *attr);

PR_ResetProcessAttr initializes the PRProcessAttr structure pointed to by attr to the default attributes. A PRProcessAttr structure can be reused to create many new processes. Before creating a different process, one has to re-initialize the PRProcessAttr structure with a call to PR_ResetProcessAttr.

void PR_DestroyProcessAttr(PRProcessAttr *attr);

PR_DestroyProcessAttr destroys the PRProcessAttr structure pointed to by attr. On return, the value of attr becomes an invalid pointer and should not be passed to other functions.

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

The standard IO stream stdioFd (must be 0, 1, or 2) of the new process will be redirected to the file descriptor redirectFd.

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

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 a new process

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

`path`	Pathname of the executable file.
`argv`	A null-terminated array of character strings (the command-line arguments).
`envp`	A null-terminated array of character strings (the environment strings). Each string in the `envp` array is of the form: `name=value` `envp` can be `NULL`.
`attr`	A pointer to a `PRProcessAttr` structure that describes the attributes of the new process. `attr` can be `NULL`, which means the new process will have the default attributes.

PR_CreateProcess() creates a new process that executes the program path, passing it the commmand-line arguments argv and environment envp. If envp is NULL, the new process inherits the environment of the parent process. The PRPRocessAttr structure attr specifies the IO 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.

On success, PR_CreateProcess returns a pointer to a PRProcess structure representing the new process. On failure, PR_CreateProcess returns NULL. Call PR_GetError() to retrieve error information.

Detaching a child process

PRStatus PR_DetachProcess(PRProcess *process);

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

Waiting for a process to terminate

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

`process`	the identifier for the non-detached process whose termination we want to wait for
`exitCode`	a pointer to a `PRInt32` variable for holding the exit code of the process. Can be `NULL`.

PR_WaitProcess() blocks the calling thread until the non-detached process identified by process has terminated. On a successful completion, PR_WaitProcess() returns PR_SUCCESS. If exitCode is not NULL, *exitCode contains the exit status code of process. On failure, PR_WaitProcess() returns PR_FAILURE. Call PR_GetError() to retrieve error information.

Killing a process

PRStatus PR_KillProcess(PRProcess *process);

It is not clear whether this function is useful or it can be implemented everywhere.

Obtaining inherited file descriptors

PRFileDesc * PR_GetInheritedFileDesc(const char *name);

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.

[Contents] [Previous] [Next] [Last]

Last updated: Wed Jul 15 09:52:17 PDT 1998

Chapter 25 Process Management and Interprocess Communication