NSTask Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | Interacting with the Operating System |
| Declared in | NSTask.h |
Overview
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.
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.
Tasks
Creating and Initializing an NSTask Object
Returning Task Information
-
– arguments -
– currentDirectoryPath -
– environment -
– launchPath -
– processIdentifier -
– standardError -
– standardInput -
– standardOutput
Running and Stopping a Task
Querying the Task State
Configuring an NSTask Object
-
– setArguments: -
– setCurrentDirectoryPath: -
– setEnvironment: -
– setLaunchPath: -
– setStandardError: -
– setStandardInput: -
– setStandardOutput:
Task Termination Handler
-
terminationHandlerproperty
Properties
terminationHandler
Invoked when the task is completed.
Discussion
The completion Block is invoked when the task has completed. The task object is passed to the Block to allow access to the task parameters, for example to determine if the task completed successfully.
Availability
- Available in OS X v10.7 and later.
Declared In
NSTask.hClass Methods
launchedTaskWithLaunchPath:arguments:
Creates and launches a task with a specified executable and arguments.
Parameters
- path
The path to the executable.
- arguments
An array of
NSStringobjects that supplies the arguments to the task. If arguments isnil, anNSInvalidArgumentExceptionis raised.
Discussion
The task inherits its environment from the process that invokes this method.
The NSTask object converts both path and the strings in arguments to appropriate C-style strings (using fileSystemRepresentation) before passing them to the task via argv[]) . The strings in arguments do not undergo shell expansion, so you do not need to do special quoting, and shell variables, such as $PWD, are not resolved.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hInstance Methods
arguments
Returns the arguments used when the receiver was launched.
Return Value
An array of NSString objects containing the arguments used when the receiver was launched.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hcurrentDirectoryPath
Returns the task’s current directory.
Return Value
The task's current working directory.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.henvironment
Returns a dictionary of variables for the environment from which the receiver was launched.
Return Value
A dictionary of variables for the environment from which the receiver was launched. The dictionary keys are the environment variable names.
Availability
- Available in OS X v10.0 and later.
See Also
-
– setEnvironment: -
environment(NSProcessInfo)
Declared In
NSTask.hinit
Returns an initialized NSTask object with the environment of the current process.
Return Value
An initialized NSTask object with the environment of the current process.
Discussion
If you need to modify the environment of a task, use alloc and init, and then set up the environment before launching the new task. Otherwise, just use the class method launchedTaskWithLaunchPath:arguments: to create and run the task.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hinterrupt
Sends an interrupt signal to the receiver and all of its subtasks.
Discussion
If the task terminates as a result, which is the default behavior, an NSTaskDidTerminateNotification gets sent to the default notification center. This method has no effect if the receiver was already launched and has already finished executing. If the receiver has not been launched yet, this method raises an NSInvalidArgumentException.
It is not always possible to interrupt the receiver because it might be ignoring the interrupt signal. interrupt sends SIGINT.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hisRunning
Returns whether the receiver is still running.
Return Value
YES if the receiver is still running, otherwise NO. NO means either the receiver could not run or it has terminated.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hlaunch
Launches the task represented by the receiver.
Discussion
Raises an NSInvalidArgumentException if the launch path has not been set or is invalid or if it fails to create a process.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hlaunchPath
Returns the path of the receiver’s executable.
Return Value
The path of the receiver’s executable.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hprocessIdentifier
Returns the receiver’s process identifier.
Return Value
The receiver’s process identifier.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hresume
Resumes execution of the receiver task that had previously been suspended with a suspend message.
Return Value
YES if the receiver was able to resume execution, NO otherwise.
Discussion
If multiple suspend messages were sent to the receiver, an equal number of resume messages must be sent before the task resumes execution.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hsetArguments:
Sets the command arguments that should be used to launch the executable.
Parameters
- arguments
An array of
NSStringobjects that supplies the arguments to the task. If arguments isnil, anNSInvalidArgumentExceptionis raised.
Discussion
The NSTask object converts both path and the strings in arguments to appropriate C-style strings (using fileSystemRepresentation) before passing them to the task via argv[] . The strings in arguments do not undergo shell expansion, so you do not need to do special quoting, and shell variables, such as $PWD, are not resolved.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsetCurrentDirectoryPath:
Sets the current directory for the receiver.
Parameters
- path
The current directory for the task.
Discussion
If this method isn’t used, the current directory is inherited from the process that created the receiver. This method raises an NSInvalidArgumentException if the receiver has already been launched.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsetEnvironment:
Sets the environment for the receiver.
Parameters
- environmentDictionary
A dictionary of environment variable values whose keys are the variable names.
Discussion
If this method isn’t used, the environment is inherited from the process that created the receiver. This method raises an NSInvalidArgumentException if the receiver has already been launched.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsetLaunchPath:
Sets the receiver’s executable.
Parameters
- path
The path to the executable.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsetStandardError:
Sets the standard error for the receiver.
Parameters
- file
The standard error for the receiver, which can be either an
NSFileHandleor anNSPipeobject.
Discussion
If file is an NSPipe object, launching the receiver automatically closes the write end of the pipe in the current task. Don’t create a handle for the pipe and pass that as the argument, or the write end of the pipe won’t be closed automatically.
If this method isn’t used, the standard error is inherited from the process that created the receiver. This method raises an NSInvalidArgumentException if the receiver has already been launched.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsetStandardInput:
Sets the standard input for the receiver.
Parameters
- file
The standard input for the receiver, which can be either an
NSFileHandleor anNSPipeobject.
Discussion
If file is an NSPipe object, launching the receiver automatically closes the read end of the pipe in the current task. Don’t create a handle for the pipe and pass that as the argument, or the read end of the pipe won’t be closed automatically.
If this method isn’t used, the standard input is inherited from the process that created the receiver. This method raises an NSInvalidArgumentException if the receiver has already been launched.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsetStandardOutput:
Sets the standard output for the receiver.
Parameters
- file
The standard output for the receiver, which can be either an
NSFileHandleor anNSPipeobject.
Discussion
If file is an NSPipe object, launching the receiver automatically closes the write end of the pipe in the current task. Don’t create a handle for the pipe and pass that as the argument, or the write end of the pipe won’t be closed automatically.
If this method isn’t used, the standard output is inherited from the process that created the receiver. This method raises an NSInvalidArgumentException if the receiver has already been launched.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hstandardError
Returns the standard error file used by the receiver.
Return Value
The standard error file used by the receiver.
Discussion
Standard error is where all diagnostic messages are sent. The object returned is either an NSFileHandle or an NSPipe instance, depending on what type of object was passed to setStandardError:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hstandardInput
Returns the standard input file used by the receiver.
Return Value
The standard input file used by the receiver.
Discussion
Standard input is where the receiver takes its input from unless otherwise specified. The object returned is either an NSFileHandle or an NSPipe instance, depending on what type of object was passed to the setStandardInput: method.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hstandardOutput
Returns the standard output file used by the receiver.
Return Value
The standard output file used by the receiver.
Discussion
Standard output is where the receiver displays its output. The object returned is either an NSFileHandle or an NSPipe instance, depending on what type of object was passed to the setStandardOutput: method.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hsuspend
Suspends execution of the receiver task.
Return Value
YES if the receiver was successfully suspended, NO otherwise.
Discussion
Multiple suspend messages can be sent, but they must be balanced with an equal number of resume messages before the task resumes execution.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hterminate
Sends a terminate signal to the receiver and all of its subtasks.
Discussion
If the task terminates as a result, which is the default behavior, an NSTaskDidTerminateNotification gets sent to the default notification center. This method has no effect if the receiver was already launched and has already finished executing. If the receiver has not been launched yet, this method raises an NSInvalidArgumentException.
It is not always possible to terminate the receiver because it might be ignoring the terminate signal. terminate sends SIGTERM.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.hterminationReason
Returns the reason the task was terminated.
Return Value
The termination status. The possible values are described in “NSTaskTerminationReason.”
Availability
- Available in OS X v10.6 and later.
Declared In
NSTask.hterminationStatus
Returns the exit status returned by the receiver’s executable.
Return Value
The exit status returned by the receiver’s executable.
Discussion
Each task defines and documents how its return value should be interpreted. For example, many commands return 0 if they complete successfully or an error code if they don’t. You’ll need to look at the documentation for that task to learn what values it returns under what circumstances.
This method raises an NSInvalidArgumentException if the receiver is still running. Verify that the receiver is not running before you use it.
if (![aTask isRunning]) { |
int status = [aTask terminationStatus]; |
if (status == ATASK_SUCCESS_VALUE) |
NSLog(@"Task succeeded."); |
else |
NSLog(@"Task failed."); |
} |
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hwaitUntilExit
Block until the receiver is finished.
Discussion
This method first checks to see if the receiver is still running using isRunning. Then it polls the current run loop using NSDefaultRunLoopMode until the task completes.
[aTask launch]; |
[aTask waitUntilExit]; |
int status = [aTask terminationStatus]; |
if (status == ATASK_SUCCESS_VALUE) |
NSLog(@"Task succeeded."); |
else |
NSLog(@"Task failed."); |
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSTask.hConstants
NSTaskTerminationReason
These constants specify the values that are returned by terminationReason.
enum {
NSTaskTerminationReasonExit = 1,
NSTaskTerminationReasonUncaughtSignal = 2
};
typedef NSInteger NSTaskTerminationReason;
Constants
Notifications
NSTaskDidTerminateNotification
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.The notification object is the NSTask object that was terminated. This notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.0 and later.
Declared In
NSTask.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-01-09)