Up

NSTask class reference

Authors

Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 35503

Date: 2012-09-03 14:36:45 +0100 (Mon, 03 Sep 2012)

Copyright: (C) 1998,1999 Free Software Foundation, Inc.

Software documentation for the NSTask class

NSTask : NSObject

Declared in:
Foundation/NSTask.h
Availability: OpenStep

The NSTask class provides a mechanism to run separate tasks under (limited) control of your program.

Instance Variables

Method summary

launchedTaskWithLaunchPath: arguments: 

+ (NSTask*) launchedTaskWithLaunchPath: (NSString*)path arguments: (NSArray*)args;
Availability: OpenStep

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.

arguments 

- (NSArray*) arguments;
Availability: OpenStep

Returns the arguments set for the task.

currentDirectoryPath 

- (NSString*) currentDirectoryPath;
Availability: OpenStep

Returns the working directory set for the task.

environment 

- (NSDictionary*) environment;
Availability: OpenStep

Returns the environment set for the task.

interrupt 

- (void) interrupt;
Availability: OpenStep

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.

isRunning 

- (BOOL) isRunning;
Availability: OpenStep

Checks to see if the task is currently running.

launch 

- (void) launch;
Availability: OpenStep

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 or the task has already been launched).

launchPath 

- (NSString*) launchPath;
Availability: OpenStep

Returns the launch path set for the task.

processIdentifier 

- (int) processIdentifier;
Availability: MacOS-X 10.0.0

Returns the number identifying the child process on this system.

resume 

- (BOOL) resume;
Availability: MacOS-X 10.0.0

Sends a cont signal to the receiver and any subtasks.
If the task has not been launched, raises an NSInvalidArgumentException.

setArguments: 

- (void) setArguments: (NSArray*)args;
Availability: OpenStep

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.

setCurrentDirectoryPath: 

- (void) setCurrentDirectoryPath: (NSString*)path;
Availability: OpenStep

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.

setEnvironment: 

- (void) setEnvironment: (NSDictionary*)env;
Availability: OpenStep

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.

setLaunchPath: 

- (void) setLaunchPath: (NSString*)path;
Availability: OpenStep

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.

setStandardError: 

- (void) setStandardError: (id)hdl;
Availability: OpenStep

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.

setStandardInput: 

- (void) setStandardInput: (id)hdl;
Availability: OpenStep

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.

setStandardOutput: 

- (void) setStandardOutput: (id)hdl;
Availability: OpenStep

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.

standardError 

- (id) standardError;
Availability: OpenStep

Returns the standard error stream for the task - an NSFileHandle unless an NSPipe was passed to -setStandardError:

standardInput 

- (id) standardInput;
Availability: OpenStep

Returns the standard input stream for the task - an NSFileHandle unless an NSPipe was passed to -setStandardInput:

standardOutput 

- (id) standardOutput;
Availability: OpenStep

Returns the standard output stream for the task - an NSFileHandle unless an NSPipe was passed to -setStandardOutput:

suspend 

- (BOOL) suspend;
Availability: MacOS-X 10.0.0

Sends a stop signal to the receiver and any subtasks.
If the task has not been launched, raises an NSInvalidArgumentException.

terminate 

- (void) terminate;
Availability: OpenStep

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 terminates, either due to this method being called, or normal termination, an NSTaskDidTerminateNotification is posted.

terminationStatus 

- (int) terminationStatus;
Availability: OpenStep

Returns the termination status of the task.
If the task has not completed running, raises an NSInvalidArgumentException.

usePseudoTerminal 

- (BOOL) usePseudoTerminal;
Availability: Not in OpenStep/MacOS-X

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.

validatedLaunchPath 

- (NSString*) validatedLaunchPath;
Availability: Not in OpenStep/MacOS-X

Returns a validated launch path or nil .
Allows for the GNUstep host/operating system, and library combination subdirectories in a path, appending them as necessary to try to locate the actual binary to be used.
Checks that the binary file exists and is executable.
Even tries searching the directories in the PATH environment variable to locate a binary if the original launch path set was not absolute.
We need this to be native windows format, and some of the standardisation above may have left unix style separators in the string.

waitUntilExit 

- (void) waitUntilExit;
Availability: OpenStep

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.



Instance Variables for NSTask Class

_arguments

@protected NSArray* _arguments;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_currentDirectoryPath

@protected NSString* _currentDirectoryPath;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_environment

@protected NSDictionary* _environment;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_hasCollected

@protected BOOL _hasCollected;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_hasLaunched

@protected BOOL _hasLaunched;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_hasNotified

@protected BOOL _hasNotified;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_hasTerminated

@protected BOOL _hasTerminated;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_launchPath

@protected NSString* _launchPath;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_standardError

@protected id _standardError;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_standardInput

@protected id _standardInput;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_standardOutput

@protected id _standardOutput;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_taskId

@protected int _taskId;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_terminationStatus

@protected int _terminationStatus;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.





Up