Class

NSTask

An object representing a subprocess of the current process.

Overview

Using the NSTask class, your program can run another program as a subprocess and can monitor that program’s execution. A NSTask object creates a separate executable entity; it differs from NSThread in that it does not share memory space with the process that creates it.

A process operates within an environment defined by the current values for several items: the current directory, standard input, standard output, standard error, and the values of any environment variables. By default, an NSTask object inherits its environment from the process that launches it. If there are any values that should be different for the process, for example, if the current directory should change, you must change the value before you launch it. A process's environment cannot be changed while it is running.

An NSTask object can only be run once. Subsequent attempts raise an error.

Topics

Creating and Initializing an NSTask Object

launchedTaskWithLaunchPath:arguments:

Creates and launches a task with a specified executable and arguments.

Deprecated
init

Returns an initialized NSTask object with the environment of the current process.

Returning Task Information

arguments

Sets the command arguments that should be used to launch the executable.

currentDirectoryPath

Sets the current directory for the receiver.

Deprecated
environment

Sets the environment for the receiver.

launchPath

Sets the receiver’s executable.

Deprecated
processIdentifier

Returns the receiver’s process identifier.

standardError

Sets the standard error for the receiver.

standardInput

Sets the standard input for the receiver.

standardOutput

Sets the standard output for the receiver.

Running and Stopping a Task

interrupt

Sends an interrupt signal to the receiver and all of its subtasks.

launch

Launches the task represented by the receiver.

Deprecated
resume

Resumes execution of the receiver task that had previously been suspended with a suspend message.

suspend

Suspends execution of the receiver task.

terminate

Sends a terminate signal to the receiver and all of its subtasks.

waitUntilExit

Block until the receiver is finished.

Querying the Task State

running

Returns whether the receiver is still running.

terminationStatus

Returns the exit status returned by the receiver’s executable.

terminationReason

Returns the reason the task was terminated.

Configuring an NSTask Object

arguments

Sets the command arguments that should be used to launch the executable.

currentDirectoryPath

Sets the current directory for the receiver.

Deprecated
environment

Sets the environment for the receiver.

launchPath

Sets the receiver’s executable.

Deprecated
standardError

Sets the standard error for the receiver.

standardInput

Sets the standard input for the receiver.

standardOutput

Sets the standard output for the receiver.

Task Termination Handler

terminationHandler

Invoked when the task is completed.

Constants

NSTaskTerminationReason

These constants specify the values that are returned by terminationReason.

NSQualityOfService

Used to indicate the nature and importance of work to the system. Work with higher quality of service classes receive more resources than work with lower quality of service classes whenever there is resource contention.

Notifications

NSTaskDidTerminateNotification

Posted when the task has stopped execution. This notification can be posted either when the task has exited normally or as a result of terminate being sent to the NSTask object. If the NSTask object gets released, however, this notification will not get sent, as the port the message would have been sent on was released as part of the task release. The observer method can use terminationStatus to determine why the task died. See Ending an NSTask for an example.

Instance Methods

Relationships

Inherits From

See Also

Tasks and Pipes

NSPipe

A one-way communications channel between related processes.