Class

NSTask

Using the NSTask class, your program can run another program as a subprocess and can monitor that program’s execution. An 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.

Overview

A task 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 task, for example, if the current directory should change, you must change the value before you launch the task. A task’s environment cannot be changed while it is running.

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

Symbols

Creating and Initializing an NSTask Object

+ launched​Task​With​Launch​Path:​​arguments:​​

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

- 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.

current​Directory​Path

Sets the current directory for the receiver.

environment

Sets the environment for the receiver.

launch​Path

Sets the receiver’s executable.

process​Identifier

Returns the receiver’s process identifier.

standard​Error

Sets the standard error for the receiver.

standard​Input

Sets the standard input for the receiver.

standard​Output

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.

- 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.

- wait​Until​Exit

Block until the receiver is finished.

Querying the Task State

- is​Running

Returns whether the receiver is still running.

termination​Status

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

termination​Reason

Returns the reason the task was terminated.

Configuring an NSTask Object

arguments

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

current​Directory​Path

Sets the current directory for the receiver.

environment

Sets the environment for the receiver.

launch​Path

Sets the receiver’s executable.

standard​Error

Sets the standard error for the receiver.

standard​Input

Sets the standard input for the receiver.

standard​Output

Sets the standard output for the receiver.

Task Termination Handler

termination​Handler

Invoked when the task is completed.

Constants

NSTask​Termination​Reason

These constants specify the values that are returned by termination​Reason.

Notifications

NSTask​Did​Terminate​Notification

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 termination​Status to determine why the task died. See Ending an NSTask for an example.

Relationships

Inherits From