PtSpawn()

Spawn a new process

Synopsis:

pid_t PtSpawn( const char *cmd,
               const char * const *argv,
               const char * const *env,
               const PtSpawnOptions_t *opt,
               PtSpawnCbF_t *cb,
               void *data,
               PtSpawnCbId_t **csp );

Arguments:

cmd

The program to be started. If it doesn't contain a slash, directories listed in the PATH environment variable are searched.

argv

A pointer to an argument vector. The last member of argv must be a NULL pointer.

env

Environment variables for the new process. If it's NULL, the value of the global variable extern char **environ is used.

opt

A pointer to a PtSpawnOptions_t structure that can be used to specify some extra details of how the child should be spawned; see “Options,” below.

cb, data

A callback to be called after the child process terminates, and data to pass to the callback. See “Callback function,” below.

csp

If non-NULL, the function stores in *csp a pointer to a control structure that can be later used to change or remove the callback. See PtSpawnSetCallback() and PtSpawnDeleteCallback().

---

This control structure exists only until the termination callback is called; don't call PtSpawnSetCallback() or PtSpawnDeleteCallback() after the callback has been called.

---

Library:

ph

Description:

This function spawns a new process and optionally installs a callback that's called when the child process terminates.

Options

Under QNX Neutrino, PtSpawnOptions_t consists of:

iov

An fd-redirection array.

options

A structure of type inheritance (see spawn() in the QNX Neutrino Library Reference).

If opt is NULL, the function uses the defaults specified in:

extern const PtSpawnOptions_t PtSpawnDefaults;

---

By default, the new process inherits all of the parent's valid file descriptors whose values are less than or equal to 9.

---

If you want to specify a non-NULL value for opt, it's a good idea to modify a copy of the default structure. For example:

PtSpawnOptions_t my_opts;
my_opts = PtSpawnDefaults;
my_opts.iov[1] = fd; // Redirect stdout

Callback function

PtSpawnCbF_t is a function type:

typedef void PtSpawnCbF_t( void *data, 
                           int status );

If cb isn't NULL, PtSpawn() attaches a signal handler for SIGCHLD that calls waitpid() to determine whether the child process has terminated. If waitpid() succeeds, the function specified by cb is called, and the signal handler is removed.

If cb is NULL, PtSpawn() doesn't attach any signal handlers or call waitpid().

If you don't need a callback but you also don't want to have to worry about zombie processes, specify cb as PtSpawnNoCb — it's an empty callback function defined in the library.

If cb is NULL but csp isn't, no callback is attached, and *csp is set to NULL.

Returns:

The process ID of the spawned process, or -1 on error.

Errors:

See spawn() in the QNX Neutrino Library Reference.

Classification:

Photon

See also:

PtSpawnSetCallback(), PtSpawnDeleteCallback(), PtSpawnWait()