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 );

Description:

This function spawns a new process and optionally installs a callback that's called when the child process terminates. The arguments are as follows:

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.

---

	Under QNX 4, PtSpawnOptions_t is the same as struct _qnx_spawn_globs (see qnx_spawn_options in the C Library Reference).
	Under Neutrino, PtSpawnOptions_t consists of: iov An fd-redirection array. options A structure of type inheritance (see spawn() in the Neutrino Library Reference).

---

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

extern const PtSpawnOptions_t PtSpawnDefaults;

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

cb and data

A callback to be called after the child process terminates, and data to pass to the callback. 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.

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.

---

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.

Classification:

Photon

See also:

PtSpawnSetCallback(), PtSpawnDeleteCallback(), PtSpawnWait()