Mac Developer Library

Developer

Foundation Framework Reference NSTask Class Reference

Options
Deployment Target:

On This Page
Language:

NSTask

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.

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.

  • Creates and launches a task with a specified executable and arguments.

    Declaration

    Swift

    class func launchedTaskWithLaunchPath(_ path: String, arguments arguments: [AnyObject]) -> NSTask

    Objective-C

    + (NSTask *)launchedTaskWithLaunchPath:(NSString *)path arguments:(NSArray *)arguments

    Parameters

    path

    The path to the executable.

    arguments

    An array of NSString objects that supplies the arguments to the task. If arguments is nil, an NSInvalidArgumentException is 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – init

  • init() - init Designated Initializer

    Returns an initialized NSTask object with the environment of the current process.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the arguments used when the receiver was launched.

    Declaration

    Swift

    var arguments: [AnyObject]

    Objective-C

    @property(copy) NSArray *arguments

    Return Value

    An array of NSString objects containing the arguments used when the receiver was launched.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the task’s current directory.

    Declaration

    Swift

    var currentDirectoryPath: String

    Objective-C

    @property(copy) NSString *currentDirectoryPath

    Return Value

    The task's current working directory.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a dictionary of variables for the environment from which the receiver was launched.

    Declaration

    Swift

    var environment: [NSObject : AnyObject]

    Objective-C

    @property(copy) NSDictionary *environment

    Return Value

    A dictionary of variables for the environment from which the receiver was launched. The dictionary keys are the environment variable names.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setEnvironment:
    environment (NSProcessInfo)

  • Returns the path of the receiver’s executable.

    Declaration

    Swift

    var launchPath: String

    Objective-C

    @property(copy) NSString *launchPath

    Return Value

    The path of the receiver’s executable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s process identifier.

    Declaration

    Swift

    var processIdentifier: Int32 { get }

    Objective-C

    @property(readonly) int processIdentifier

    Return Value

    The receiver’s process identifier.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the standard error file used by the receiver.

    Declaration

    Swift

    var standardError: AnyObject

    Objective-C

    @property(retain) id standardError

    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:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the standard input file used by the receiver.

    Declaration

    Swift

    var standardInput: AnyObject

    Objective-C

    @property(retain) id standardInput

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the standard output file used by the receiver.

    Declaration

    Swift

    var standardOutput: AnyObject

    Objective-C

    @property(retain) id standardOutput

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sends an interrupt signal to the receiver and all of its subtasks.

    Declaration

    Swift

    func interrupt()

    Objective-C

    - (void)interrupt

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Launches the task represented by the receiver.

    Declaration

    Swift

    func launch()

    Objective-C

    - (void)launch

    Discussion

    Raises an NSInvalidArgumentException if the launch path has not been set or is invalid or if it fails to create a process.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Resumes execution of the receiver task that had previously been suspended with a suspend message.

    Declaration

    Swift

    func resume() -> Bool

    Objective-C

    - (BOOL)resume

    Return Value

    YEStrue if the receiver was able to resume execution, NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Suspends execution of the receiver task.

    Declaration

    Swift

    func suspend() -> Bool

    Objective-C

    - (BOOL)suspend

    Return Value

    YEStrue if the receiver was successfully suspended, NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sends a terminate signal to the receiver and all of its subtasks.

    Declaration

    Swift

    func terminate()

    Objective-C

    - (void)terminate

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Block until the receiver is finished.

    Declaration

    Swift

    func waitUntilExit()

    Objective-C

    - (void)waitUntilExit

    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.");

    waitUntilExit does not guarantee that the terminationHandler block has been fully executed before waitUntilExit returns.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • isRunning - isRunning Available in OS X v10.0 through OS X v10.9

    Returns whether the receiver is still running.

    Declaration

    Objective-C

    - (BOOL)isRunning

    Return Value

    YEStrue if the receiver is still running, otherwise NOfalse. NOfalse means either the receiver could not run or it has terminated.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Returns the exit status returned by the receiver’s executable.

    Declaration

    Swift

    var terminationStatus: Int32 { get }

    Objective-C

    @property(readonly) int terminationStatus

    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.");
    • }

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the reason the task was terminated.

    Declaration

    Swift

    var terminationReason: NSTaskTerminationReason { get }

    Objective-C

    @property(readonly) NSTaskTerminationReason terminationReason

    Return Value

    The termination status. The possible values are described in NSTaskTerminationReason.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Sets the command arguments that should be used to launch the executable.

    Declaration

    Swift

    var arguments: [AnyObject]

    Objective-C

    @property(copy) NSArray *arguments

    Parameters

    arguments

    An array of NSString objects that supplies the arguments to the task. If arguments is nil, an NSInvalidArgumentException is 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – arguments

  • Sets the current directory for the receiver.

    Declaration

    Swift

    var currentDirectoryPath: String

    Objective-C

    @property(copy) NSString *currentDirectoryPath

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the environment for the receiver.

    Declaration

    Swift

    var environment: [NSObject : AnyObject]

    Objective-C

    @property(copy) NSDictionary *environment

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – environment

  • Sets the receiver’s executable.

    Declaration

    Swift

    var launchPath: String

    Objective-C

    @property(copy) NSString *launchPath

    Parameters

    path

    The path to the executable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – launchPath

  • Sets the standard error for the receiver.

    Declaration

    Swift

    var standardError: AnyObject

    Objective-C

    @property(retain) id standardError

    Parameters

    file

    The standard error for the receiver, which can be either an NSFileHandle or an NSPipe object.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the standard input for the receiver.

    Declaration

    Swift

    var standardInput: AnyObject

    Objective-C

    @property(retain) id standardInput

    Parameters

    file

    The standard input for the receiver, which can be either an NSFileHandle or an NSPipe object.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the standard output for the receiver.

    Declaration

    Swift

    var standardOutput: AnyObject

    Objective-C

    @property(retain) id standardOutput

    Parameters

    file

    The standard output for the receiver, which can be either an NSFileHandle or an NSPipe object.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Invoked when the task is completed.

    Declaration

    Swift

    var terminationHandler: ((NSTask!) -> Void)?

    Objective-C

    @property(copy) void (^terminationHandler)( NSTask *)

    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.

    This block is not guaranteed to be fully executed prior to waitUntilExit returning.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • These constants specify the values that are returned by terminationReason.

    Declaration

    Swift

    enum NSTaskTerminationReason : Int { case Exit case UncaughtSignal }

    Objective-C

    enum { NSTaskTerminationReasonExit = 1, NSTaskTerminationReasonUncaughtSignal = 2 }; typedef NSInteger NSTaskTerminationReason;

    Constants

    • Exit

      NSTaskTerminationReasonExit

      The task exited normally.

      Available in OS X v10.6 and later.

    • UncaughtSignal

      NSTaskTerminationReasonUncaughtSignal

      The task exited due to an uncaught signal.

      Available in OS X v10.6 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Posted when the task has stopped execution. This notification can be posted either when the task has exited normally or as a result of 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.