- Inherits from:
- NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- Foundation/NSTask.h
Using NSTask, your program can run another program as a subprocess and can monitor that program's execution. NSTask 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 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.
There are two ways to create an NSTask. If it's sufficient for the task to run in the environment that it inherits from the process that creates it, use the class method launchedTaskWithLaunchPath:arguments:. This method both creates and executes (launches) the task. If you need to change the task's environment, create the task using alloc and init, use set... methods to change parts of the environment, then use the launch method to launch the task. For example, the following method runs tasks that take an input file and an output file as arguments. It reads these arguments, the task's executable, and the current directory from text fields before it launches the task:
- (void)runTask:(id)sender { NSTask *aTask = [[NSTask alloc] init]; NSMutableArray *args = [NSMutableArray array]; /* set arguments */ [args addObject:[[inputFile stringValue] lastPathComponent]]; [args addObject:[outputFile stringValue]]; [aTask setCurrentDirectoryPath:[[inputFile stringValue] stringByDeletingLastPathComponent]]; [aTask setLaunchPath:[taskField stringValue]]; [aTask setArguments:args]; [aTask launch]; }
If you create an NSTask object in this manner, you must be sure to set the executable name using setLaunchPath:. If you don't, an NSInvalidArgumentException is raised.
Normally, you want the task that you've launched to run to completion. When an NSTask exits, it posts an NSTaskDidTerminateNotification to the default notification center. You can add one of the custom objects in your program as an observer of the notification and check the task's exit status (using terminationStatus) in the observer method. For example:
-(id)init { self = [super init]; [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(checkATaskStatus:) name:NSTaskDidTerminateNotification object:nil]; return self; } - (void)checkATaskStatus:(NSNotification *)aNotification { int status = [[aNotification object] terminationStatus]; if (status == ATASK_SUCCESS_VALUE) NSLog(@"Task succeeded."); else NSLog(@"Task failed."); }
If you need to force a task to end execution, send terminate to the NSTask object. If the NSTask gets released, however, NSTaskDidTerminateNotification will not get sent, as the port the message would have been sent on was released as part of the task release.
- Creating and initializing an NSTask
- + launchedTaskWithLaunchPath:arguments:
- - init
- Returning task information
- - arguments
- - currentDirectoryPath
- - environment
- - launchPath
- - standardError
- - standardInput
- - standardOutput
- Running and stopping an NSTask
- - interrupt
- - launch
- - terminate
- - waitUntilExit
- Querying the NSTask state
- - isRunning
- - terminationStatus
- Setting up an NSTask
- - setArguments:
- - setCurrentDirectoryPath:
- - setEnvironment:
- - setLaunchPath:
- - setStandardError:
- - setStandardInput:
- - setStandardOutput:
+ (NSTask *)launchedTaskWithLaunchPath:(NSString
*)path
arguments:(NSArray *)arguments
See Also: - init
- (NSArray *)arguments
See Also: - setArguments:
- (NSString *)currentDirectoryPath
See Also: - setCurrentDirectoryPath:
- (NSDictionary *)environment
See Also: - setEnvironment:, - environment (NSProcessInfo)
- (id)init
- (void)interrupt
SIGINT
.- (BOOL)isRunning
See Also: - launch, - terminate, - waitUntilExit
- (void)launch
See Also: - launchPath, - setLaunchPath:, - terminate, - waitUntilExit
- (NSString *)launchPath
See Also: + launchedTaskWithLaunchPath:arguments:, - setLaunchPath:
- (void)setArguments:(NSArray
*)arguments
See Also: - arguments
- (void)setCurrentDirectoryPath:(NSString
*)path
See Also: - currentDirectoryPath
- (void)setEnvironment:(NSDictionary
*)environmentDictionary
See Also: - environment
- (void)setLaunchPath:(NSString
*)path
See Also: - launchPath
- (void)setStandardError:(id)file
If this method isn't used, the standard error is inherited from the process that created the receiver. You cannot use this method if the task has already been launched. If you do, it raises an NSInvalidArgumentException.
See Also: - standardError
- (void)setStandardInput:(id)file
If this method isn't used, the standard input is inherited from the process that created the receiver. You cannot use this method if the receiver has already been launched. If you do, it raises an NSInvalidArgumentException.
See Also: - standardInput
- (void)setStandardOutput:(id)file
If this method isn't used, the current standard output is inherited from the process that created the receiver. You cannot use this method if the receiver has already been launched. If you do, it raises an NSInvalidArgumentException.
See Also: - standardOutput
- (id)standardError
See Also: - setStandardError:
- (id)standardInput
See Also: - setStandardInput:
- (id)standardOutput
See Also: - setStandardOutput:
- (void)terminate
terminate
signal
to the receiver and all of its subtasks, posting a NSTaskDidTerminateNotification
to the default notification center. This method
has no effect if the receiver was already launched and has already
finished executing. If the receiver hasn't 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
.
See Also: + launchedTaskWithLaunchPath:arguments:, - launch, - terminationStatus, - waitUntilExit
- (int)terminationStatus
if (![aTask isRunning]) { int return = [aTask terminationStatus]; if (status == ATASK_SUCCESS_VALUE) NSLog(@"Task succeeded."); else NSLog(@"Task failed."); }
See Also: - terminate, - waitUntilExit
- (void)waitUntilExit
NSDefaultRunLoopMode
until the
task completes. (See the NSRunLoop class specification for more
information on run loops and run loop modes.)int return = [aTask terminationStatus]; [aTask launch]; [aTask waitUntilExit]; return = [aTask terminationStatus]; if (status == ATASK_SUCCESS_VALUE) NSLog(@"Task succeeded."); else NSLog(@"Task failed.");
See Also: - launch, - terminate
Posted when the task has stopped execution. This can be posted either when the task has exited normally or as a result of terminate being sent to the NSTask. If the NSTask 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 the class description for an example.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSTask that was terminated.