NSPR Reference: Chapter 23 Process Management and Interprocess Communication
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

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