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

+ launchedTaskWithLaunchPath: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.

currentDirectoryPath

Sets the current directory for the receiver.

environment

Sets the environment for the receiver.

launchPath

Sets the receiver’s executable.

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.

- 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

- isRunning

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.

environment

Sets the environment for the receiver.

launchPath

Sets the receiver’s executable.

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.

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 Properties

Relationships

Inherits From