2000-03-05 17:39:33 +00:00
|
|
|
<html><head>
|
2000-09-22 13:45:58 +00:00
|
|
|
<title>NSTask</title>
|
2000-03-05 17:39:33 +00:00
|
|
|
</head>
|
|
|
|
|
<body>
|
2001-04-25 14:19:57 +00:00
|
|
|
<a href ="NSString.html">[Previous] </a>
|
|
|
|
|
<a href ="Base.html">[Up] </a>
|
|
|
|
|
<a href ="NSThread.html">[Next] </a>
|
2000-03-05 17:39:33 +00:00
|
|
|
<h1>NSTask</h1>
|
2000-09-22 13:45:58 +00:00
|
|
|
<h3>Authors </h3>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
|
2000-03-05 17:39:33 +00:00
|
|
|
<dd>
|
|
|
|
|
</dl>
|
2001-03-03 10:00:31 +00:00
|
|
|
<p>Version: $Revision$</p>
|
|
|
|
|
<p>Date: $Date$</p>
|
2000-09-22 13:45:58 +00:00
|
|
|
<h2><a name ="cont-0">NSTask</a></h2>
|
|
|
|
|
<h2><a name ="NSTask">NSTask</a></h2>
|
|
|
|
|
<p><b>Declared in: </b> Foundation/NSTask.h</p>
|
|
|
|
|
<p><b>Inherits from: </b> NSObject</p>
|
|
|
|
|
<p><b>Conforms to: </b> NSObject
|
2000-03-05 17:39:33 +00:00
|
|
|
</p>
|
|
|
|
|
<hr>
|
|
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
The NSTask class provides a mechanism to run separate tasks
|
|
|
|
|
under (limited) control of your program.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<h2>Instance Variables </h2>
|
2000-09-15 19:56:39 +00:00
|
|
|
<ul>
|
|
|
|
|
</ul>
|
2000-09-22 13:45:58 +00:00
|
|
|
<h2>Methods </h2>
|
2000-03-05 17:39:33 +00:00
|
|
|
<ul>
|
2001-04-25 14:19:57 +00:00
|
|
|
<li ><a href ="NSTask.html#method-0">+launchedTaskWithLaunchPath:arguments:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-1">-arguments</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-2">-currentDirectoryPath</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-3">-environment</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-4">-interrupt</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-5">-isRunning</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-6">-launch</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-7">-launchPath</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-8">-setArguments:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-9">-setCurrentDirectoryPath:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-10">-setEnvironment:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-11">-setLaunchPath:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-12">-setStandardError:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-13">-setStandardInput:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-14">-setStandardOutput:</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-15">-standardError</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-16">-standardInput</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-17">-standardOutput</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-18">-terminate</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-19">-terminationStatus</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-20">-usePseudoTerminal</a>
|
|
|
|
|
<li ><a href ="NSTask.html#method-21">-waitUntilExit</a>
|
2000-03-05 17:39:33 +00:00
|
|
|
</ul>
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr><h2>Class Methods </h2>
|
|
|
|
|
<h3><a name ="method-0">launchedTaskWithLaunchPath:arguments:</a></h3>
|
|
|
|
|
+ (NSTask*) <b>launchedTaskWithLaunchPath:</b> (NSString*)path <b>arguments:</b> (NSArray*)arguments;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
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.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
|
|
|
|
<hr><h2>Instances Methods </h2>
|
|
|
|
|
<h3><a name ="method-1">arguments</a></h3>
|
|
|
|
|
- (NSArray*) <b>arguments</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the arguments set for the task.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-2">currentDirectoryPath</a></h3>
|
|
|
|
|
- (NSString*) <b>currentDirectoryPath</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the working directory set for the task.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-3">environment</a></h3>
|
|
|
|
|
- (NSDictionary*) <b>environment</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the environment set for the task.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-4">interrupt</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>interrupt</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Sends an interrupt signal to the receiver and any subtasks.<br>
|
|
|
|
|
If the task has not been launched, raises an
|
|
|
|
|
NSInvalidArgumentException.<br>
|
|
|
|
|
Has no effect on a task that has already terminated.<br>
|
|
|
|
|
This is rather like the terminate method, but the child
|
|
|
|
|
process may not choose to terminate in response to an interrupt.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-5">isRunning</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (BOOL) <b>isRunning</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Checks to see if the task is currently running.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-6">launch</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>launch</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Launches the task.<br>
|
|
|
|
|
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).
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-7">launchPath</a></h3>
|
2000-09-22 13:45:58 +00:00
|
|
|
- (NSString*) <b>launchPath</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the launch path set for the task.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-8">setArguments:</a></h3>
|
2000-09-22 13:45:58 +00:00
|
|
|
- (void) <b>setArguments:</b> (NSArray*)arguments;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
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.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-9">setCurrentDirectoryPath:</a></h3>
|
2000-09-22 13:45:58 +00:00
|
|
|
- (void) <b>setCurrentDirectoryPath:</b> (NSString*)path;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
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.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-10">setEnvironment:</a></h3>
|
2000-09-22 13:45:58 +00:00
|
|
|
- (void) <b>setEnvironment:</b> (NSDictionary*)environmentDictionary;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
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.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-11">setLaunchPath:</a></h3>
|
2000-09-22 13:45:58 +00:00
|
|
|
- (void) <b>setLaunchPath:</b> (NSString*)path;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
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.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-12">setStandardError:</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>setStandardError:</b> (id)file;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Sets the standard error stream for the task.<br>
|
|
|
|
|
This is normally a writable NSFileHandle object.
|
|
|
|
|
If this is an NSPipe, the write end of the pipe is
|
|
|
|
|
automatically closed on launching.<br>
|
|
|
|
|
The default behavior is to inherit the parent processes
|
|
|
|
|
stderr output.<br>
|
|
|
|
|
This method cannot be used after a task is launched ...
|
|
|
|
|
it raises an NSInvalidArgumentException.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-13">setStandardInput:</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>setStandardInput:</b> (id)file;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Sets the standard input stream for the task.<br>
|
|
|
|
|
This is normally a readable NSFileHandle object.
|
|
|
|
|
If this is an NSPipe, the read end of the pipe is
|
|
|
|
|
automatically closed on launching.<br>
|
|
|
|
|
The default behavior is to inherit the parent processes
|
|
|
|
|
stdin stream.<br>
|
|
|
|
|
This method cannot be used after a task is launched ...
|
|
|
|
|
it raises an NSInvalidArgumentException.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-14">setStandardOutput:</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>setStandardOutput:</b> (id)file;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Sets the standard output stream for the task.<br>
|
|
|
|
|
This is normally a writable NSFileHandle object.
|
|
|
|
|
If this is an NSPipe, the write end of the pipe is
|
|
|
|
|
automatically closed on launching.<br>
|
|
|
|
|
The default behavior is to inherit the parent processes
|
|
|
|
|
stdout stream.<br>
|
|
|
|
|
This method cannot be used after a task is launched ...
|
|
|
|
|
it raises an NSInvalidArgumentException.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-15">standardError</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (id) <b>standardError</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the standard error stream for the task - an NSFileHandle
|
|
|
|
|
unless an NSPipe was passed to setStandardError:
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-16">standardInput</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (id) <b>standardInput</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the standard input stream for the task - an NSFileHandle
|
|
|
|
|
unless an NSPipe was passed to setStandardInput:
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-17">standardOutput</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (id) <b>standardOutput</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the standard output stream for the task - an NSFileHandle
|
|
|
|
|
unless an NSPipe was passed to setStandardOutput:
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-18">terminate</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>terminate</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Sends a terminate signal to the receiver and any subtasks.<br>
|
|
|
|
|
If the task has not been launched, raises an
|
|
|
|
|
NSInvalidArgumentException.<br>
|
|
|
|
|
Has no effect on a task that has already terminated.<br>
|
|
|
|
|
When a task temrinates, either due to this method being called,
|
|
|
|
|
or normal termination, an NSTaskDidTerminateNotification is
|
|
|
|
|
posted.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2001-04-19 09:21:59 +00:00
|
|
|
<h3><a name ="method-19">terminationStatus</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (int) <b>terminationStatus</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Returns the termination status of the task.<br>
|
|
|
|
|
If the task has not completed running, raises an
|
|
|
|
|
NSInvalidArgumentException.
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-20">usePseudoTerminal</a></h3>
|
|
|
|
|
- (BOOL) <b>usePseudoTerminal</b>;<br>
|
|
|
|
|
Standards: GNUstep NotMacOS-X NotOpenStep<br>
|
|
|
|
|
|
|
|
|
|
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.<br>
|
|
|
|
|
This method cannot be used after a task is launched ...
|
|
|
|
|
it raises an NSInvalidArgumentException.<br>
|
|
|
|
|
The standard input, output and error streams cannot be
|
|
|
|
|
changed after calling this method.<br>
|
|
|
|
|
The method returns YES on success, NO on failure.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-21">waitUntilExit</a></h3>
|
2000-07-04 19:53:39 +00:00
|
|
|
- (void) <b>waitUntilExit</b>;<br>
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2001-04-19 09:21:59 +00:00
|
|
|
Suspends the current thread until the task terminates, by
|
|
|
|
|
waiting in NSRunLoop (NSDefaultRunLoopMode) for the task
|
|
|
|
|
termination.<br>
|
|
|
|
|
Returns immediately if the task is not running.
|
2000-03-05 17:39:33 +00:00
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
<hr>
|
2000-03-05 17:39:33 +00:00
|
|
|
</body>
|
|
|
|
|
|
2000-09-22 13:45:58 +00:00
|
|
|
</html>
|
