[Previous]
[Up]
[Next]
NSTask
Authors
- Richard Frith-Macdonald
-
Version: $Revision$
Date: $Date$
Declared in: Foundation/NSTask.h
Inherits from: NSObject
Conforms to: NSObject
The NSTask class provides a mechanism to run separate tasks
under (limited) control of your program.
Instance Variables
Methods
Class Methods
+ (NSTask*) launchedTaskWithLaunchPath: (NSString*)path arguments: (NSArray*)arguments;
Creates and launches a task, returning an autoreleased task object.
Supplies the path to the executable and an array of argument.
The task inherits the parents environment and I/O.
Instances Methods
- (NSArray*) arguments;
Returns the arguments set for the task.
- (NSString*) currentDirectoryPath;
Returns the working directory set for the task.
- (NSDictionary*) environment;
Returns the environment set for the task.
- (void) interrupt;
Sends an interrupt signal to the receiver and any subtasks.
If the task has not been launched, raises an
NSInvalidArgumentException.
Has no effect on a task that has already terminated.
This is rather like the terminate method, but the child
process may not choose to terminate in response to an interrupt.
- (BOOL) isRunning;
Checks to see if the task is currently running.
- (void) launch;
Launches the task.
Raises an NSInvalidArgumentException if the launch path is not
set or if the subtask cannot be started for some reason
(eg. the executable does not exist).
- (NSString*) launchPath;
Returns the launch path set for the task.
- (int) processIdentifer;
Returns the number identifying the child process on this system.
- (void) setArguments: (NSArray*)arguments;
Sets an array of arguments to be supplied to the task when it
is launched. The default is an empty array. This method cannot
be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (void) setCurrentDirectoryPath: (NSString*)path;
Sets the home directory in which the task is to be run.
The default is the parent processes directory.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (void) setEnvironment: (NSDictionary*)environmentDictionary;
Sets the environment variables for the task to be run.
The default is the parent processes environment.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (void) setLaunchPath: (NSString*)path;
Sets the path to the executable file to be run.
There is no default for this - you must set the launch path.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (void) setStandardError: (id)file;
Sets the standard error stream for the task.
This is normally a writable NSFileHandle object.
If this is an NSPipe, the write end of the pipe is
automatically closed on launching.
The default behavior is to inherit the parent processes
stderr output.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (void) setStandardInput: (id)file;
Sets the standard input stream for the task.
This is normally a readable NSFileHandle object.
If this is an NSPipe, the read end of the pipe is
automatically closed on launching.
The default behavior is to inherit the parent processes
stdin stream.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (void) setStandardOutput: (id)file;
Sets the standard output stream for the task.
This is normally a writable NSFileHandle object.
If this is an NSPipe, the write end of the pipe is
automatically closed on launching.
The default behavior is to inherit the parent processes
stdout stream.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
- (id) standardError;
Returns the standard error stream for the task - an NSFileHandle
unless an NSPipe was passed to setStandardError:
- (id) standardInput;
Returns the standard input stream for the task - an NSFileHandle
unless an NSPipe was passed to setStandardInput:
- (id) standardOutput;
Returns the standard output stream for the task - an NSFileHandle
unless an NSPipe was passed to setStandardOutput:
- (BOOL) resume;
Sends a cont signal to the receiver and any subtasks.
If the task has not been launched, raises an
NSInvalidArgumentException.
- (BOOL) suspend;
Sends a stop signal to the receiver and any subtasks.
If the task has not been launched, raises an
NSInvalidArgumentException.
- (void) terminate;
Sends a terminate signal to the receiver and any subtasks.
If the task has not been launched, raises an
NSInvalidArgumentException.
Has no effect on a task that has already terminated.
When a task temrinates, either due to this method being called,
or normal termination, an NSTaskDidTerminateNotification is
posted.
- (int) terminationStatus;
Returns the termination status of the task.
If the task has not completed running, raises an
NSInvalidArgumentException.
- (BOOL) usePseudoTerminal;
Standards: GNUstep NotMacOS-X NotOpenStep
If the system supports it, this method sets the standard
input, output, and error streams to a pseudo-terminal so
that, when launched, the child task will act as if it was
running interactively on a terminal. The file handles
can then be used to communicate with the child.
This method cannot be used after a task is launched ...
it raises an NSInvalidArgumentException.
The standard input, output and error streams cannot be
changed after calling this method.
The method returns YES on success, NO on failure.
- (void) waitUntilExit;
Suspends the current thread until the task terminates, by
waiting in NSRunLoop (NSDefaultRunLoopMode) for the task
termination.
Returns immediately if the task is not running.