iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSProcessInfo Class Reference

Options
Deployment Target:

On This Page
Language:

NSProcessInfo

The NSProcessInfo class provides methods to access information about the current process. Each process has a single, shared NSProcessInfo object, known as process information agent.

The process information agent can return such information as the arguments, environment variables, host name, or process name. The processInfo class method returns the shared agent for the current process—that is, the process whose object sent the message. For example, the following line returns the NSProcessInfo object, which then provides the name of the current process:

  1. NSString *processName = [[NSProcessInfo processInfo] processName];

The NSProcessInfo class also includes the operatingSystem method, which returns an enum constant identifying the operating system on which the process is executing.

NSProcessInfo objects attempt to interpret environment variables and command-line arguments in the user's default C string encoding if they cannot be converted to Unicode as UTF-8 strings. If neither conversion works, these values are ignored by the NSProcessInfo object.

Managing Activities

The system has heuristics to improve battery life, performance, and responsiveness of applications for the benefit of the user. You can use the following methods to manage activities that give hints to the system that your application has special requirements:

In response to creating an activity, the system will disable some or all of the heuristics so your application can finish quickly while still providing responsive behavior if the user needs it.

You use activities when your application is performing a long-running operation. If the activity can take different amounts of time (for example, calculating the next move in a chess game), it should use this API. This will ensure correct behavior when the amount of data or the capabilities of the user's computer varies. You should put your activity into one of two major categories:

  1. User initiated: These are finite length activities that the user has explicitly started. Examples include exporting or downloading a user specified file.

  2. Background: These are finite length activities that are part of the normal operation of your application but are not explicitly started by the user. Examples include autosaving, indexing, and automatic downloading of files.

In addition, if your application requires high priority I/O, you can include the NSActivityLatencyCritical flag (using a bitwise OR). You should only use this flag for activities like audio or video recording that really do require high priority.

If your activity takes place synchronously inside an event callback on the main thread, you do not need to use this API.

Be aware that failing to end these activities for an extended period of time can have significant negative impacts to the performance of your user's computer, so be sure to use only the minimum amount of time required. User preferences may override your application’s request.

You can also use this API to control automatic termination or sudden termination (see Sudden Termination). For example:

  1. id activity = [[NSProcessInfo processInfo] beginActivityWithOptions:NSActivityAutomaticTerminationDisabled reason:@"Good Reason"];
  2. // Perform some work.
  3. [[NSProcessInfo processInfo] endActivity:activity];

is equivalent to:

  1. [[NSProcessInfo processInfo] disableAutomaticTermination:@"Good Reason"];
  2. // Perform some work.
  3. [[NSProcessInfo processInfo] enableAutomaticTermination:@"Good Reason"];

Because this API returns an object, it may be easier to pair begins and ends than when using the automatic termination API—if the object is deallocated before the endActivity: call, the activity will be automatically ended.

This API also provides a mechanism to disable system-wide idle sleep and display idle sleep. These can have a large impact on the user experience, so be sure not to forget to end activities that disable sleep (including NSActivityUserInitiated).

Sudden Termination

OS X v10.6 and later includes a mechanism that allows the system to log out or shut down more quickly by, whenever possible, killing applications instead of requesting that they quit themselves.

Your application can enable this capability on a global basis and then manually override its availability during actions that could cause data corruption or a poor user experience by allowing sudden termination. Alternately, your application can just manually enable and disable this functionality.

The methods enableSuddenTermination and disableSuddenTermination decrement or increment, respectively, a counter whose value is 1 when the process is first created. When the counter's value is 0 the application is considered to be safely killable and may be killed by the system without any notification or event being sent to the process first.

Your application can support sudden termination upon launch by adding a key to the application’s Info.plist. If the NSSupportsSuddenTermination key exists in the Info.plist and has a value of YEStrue, it is the equivalent of calling enableSuddenTermination during your application launch. This renders the application process killable right away. You can still override this behavior by invoking disableSuddenTermination.

Typically, you disable sudden termination whenever your application defers work that must be done before the application terminates. If, for example, your application defers writing data to disk, and sudden termination is enabled, you should bracket the sensitive operations with a call to disableSuddenTermination, perform the necessary operations, and then send a balancing enableSuddenTermination message.

In agents or daemon executables that don't depend on AppKit you can manually invoke enableSuddenTermination right away. You can then use the enable and disable methods whenever the process has work it must do before it terminates.

Some AppKit functionality automatically disables sudden termination on a temporary basis to ensure data integrity.

  • NSUserDefaults temporarily disables sudden termination to prevent process killing between the time at which a default has been set and the time at which the preferences file including that default has been written to disk.

  • NSDocument temporarily disables sudden termination to prevent process killing between the time at which the user has made a change to a document and the time at which the user's change has been written to disk.

Thermal State and App Performance

Use the current thermal state to determine if your app should reduce system usage. On OS X v10.10.3 and later you can register for the NSProcessInfoThermalStateDidChangeNotification to be notified when the thermal state changes. Use thermalState to query the current state. Your app should reduce system usage at higher thermal states. For recommended actions, see NSProcessInfoThermalState.

  • Returns the process information agent for the process.

    Declaration

    Swift

    class func processInfo() -> NSProcessInfo

    Objective-C

    + (NSProcessInfo * nonnull)processInfo

    Return Value

    Shared process information agent for the process.

    Discussion

    An NSProcessInfo object is created the first time this method is invoked, and that same object is returned on each subsequent invocation.

    Availability

    Available in iOS 2.0 and later.

  • Array of strings with the command-line arguments for the process.

    Declaration

    Swift

    var arguments: [String] { get }

    Objective-C

    @property(readonly, copy) NSArray <NSString *> *arguments

    Discussion

    This array contains all the information passed in the argv array, including the executable name in the first element.

    Availability

    Available in iOS 2.0 and later.

  • The variable names (keys) and their values in the environment from which the process was launched.

    Declaration

    Swift

    var environment: [String : String] { get }

    Objective-C

    @property(readonly, copy) NSDictionary <NSString *,NSString *> *environment

    Availability

    Available in iOS 2.0 and later.

  • Global unique identifier for the process. (read-only)

    Declaration

    Swift

    var globallyUniqueString: String { get }

    Objective-C

    @property(readonly, copy) NSString *globallyUniqueString

    Discussion

    The global ID for the process includes the host name, process ID, and a time stamp, which ensures that the ID is unique for the network. This property generates a new string each time its getter is invoked, and it uses a counter to guarantee that strings created from the same process are unique.

    Availability

    Available in iOS 2.0 and later.

    See Also

    processName

  • The identifier of the process (often called process ID).

    Declaration

    Swift

    var processIdentifier: Int32 { get }

    Objective-C

    @property(readonly) int processIdentifier

    Availability

    Available in iOS 2.0 and later.

    See Also

    processName

  • The name of the process.

    Declaration

    Swift

    var processName: String

    Objective-C

    @property(copy) NSString *processName

    Discussion

    The process name is used to register application defaults and is used in error messages. It does not uniquely identify the process.

    Availability

    Available in iOS 2.0 and later.

  • The name of the host computer on which the process is executing. (read-only)

    Declaration

    Swift

    var hostName: String { get }

    Objective-C

    @property(readonly, copy) NSString *hostName

    Availability

    Available in iOS 2.0 and later.

  • Returns a constant to indicate the operating system on which the process is executing.

    Deprecation Statement

    Use operatingSystemVersion or isOperatingSystemAtLeastVersion: instead

    Declaration

    Swift

    func operatingSystem() -> Int

    Objective-C

    - (NSUInteger)operatingSystem

    Return Value

    Operating system identifier. See Constants for a list of possible values. In OS X, it’s NSMACHOperatingSystem.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • Returns a string containing the name of the operating system on which the process is executing.

    Deprecation Statement

    Use operatingSystemVersionString instead.

    Declaration

    Swift

    func operatingSystemName() -> String

    Objective-C

    - (NSString * nonnull)operatingSystemName

    Return Value

    Operating system name. In OS X, it’s @"NSMACHOperatingSystem"

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • A string containing the version of the operating system on which the process is executing. (read-only)

    Declaration

    Swift

    var operatingSystemVersionString: String { get }

    Objective-C

    @property(readonly, copy) NSString *operatingSystemVersionString

    Discussion

    The operating system version string is human readable, localized, and is appropriate for displaying to the user. This string is not appropriate for parsing.

    Availability

    Available in iOS 2.0 and later.

  • The version of the operating system on which the process is executing. (read-only)

    Declaration

    Swift

    var operatingSystemVersion: NSOperatingSystemVersion { get }

    Objective-C

    @property(readonly) NSOperatingSystemVersion operatingSystemVersion

    Availability

    Available in iOS 8.0 and later.

  • Returns a Boolean value indicating whether the version of the operating system on which the process is executing is the same or later than the given version.

    Declaration

    Swift

    func isOperatingSystemAtLeastVersion(_ version: NSOperatingSystemVersion) -> Bool

    Objective-C

    - (BOOL)isOperatingSystemAtLeastVersion:(NSOperatingSystemVersion)version

    Parameters

    version

    The operating system version to test against.

    Return Value

    YEStrue if the operating system on which the process is executing is the same or later than the given version; otherwise NOfalse.

    Discussion

    This method accounts for major, minor, and update versions of the operating system.

    Availability

    Available in iOS 8.0 and later.

  • Begin an activity using the given options and reason.

    Declaration

    Swift

    func beginActivityWithOptions(_ options: NSActivityOptions, reason reason: String) -> NSObjectProtocol

    Objective-C

    - (id<NSObject> nonnull)beginActivityWithOptions:(NSActivityOptions)options reason:(NSString * nonnull)reason

    Parameters

    options

    Options for the activity. See Activity Options for possible values.

    reason

    A string used in debugging to indicate the reason the activity began.

    Return Value

    An object token representing the activity.

    Discussion

    Indicate completion of the activity by calling endActivity: passing the returned object as the argument.

    Availability

    Available in iOS 7.0 and later.

  • Ends the given activity.

    Declaration

    Swift

    func endActivity(_ activity: NSObjectProtocol)

    Objective-C

    - (void)endActivity:(id<NSObject> nonnull)activity

    Parameters

    activity

    An activity object returned by beginActivityWithOptions:reason:.

    Availability

    Available in iOS 7.0 and later.

  • Synchronously perform an activity defined by a given block using the given options.

    Declaration

    Swift

    func performActivityWithOptions(_ options: NSActivityOptions, reason reason: String, usingBlock block: () -> Void)

    Objective-C

    - (void)performActivityWithOptions:(NSActivityOptions)options reason:(NSString * nonnull)reason usingBlock:(void (^ nonnull)(void))block

    Parameters

    options

    Options for the activity. See Activity Options for possible values.

    reason

    A string used in debugging to indicate the reason the activity began.

    block

    A block containing the work to be performed by the activity.

    Discussion

    The activity will be automatically ended after block returns.

    Availability

    Available in iOS 7.0 and later.

  • Performs the specified block asynchronously and notifies you if the process is about to be suspended.

    Declaration

    Swift

    func performExpiringActivityWithReason(_ reason: String, usingBlock block: (Bool) -> Void)

    Objective-C

    - (void)performExpiringActivityWithReason:(NSString * nonnull)reason usingBlock:(void (^ nonnull)(BOOL expired))block

    Parameters

    reason

    A string used in debugging to indicate the reason the activity began. This parameter must not be nil or an empty string.

    block

    A block containing the work to be performed by the activity. The block has no return value and takes the following parameter:

    expired

    A Boolean indicating whether the process is about to be suspended. If the value is YEStrue, the process is about to be suspended so you should take whatever steps are needed to stop in progress work. If it is NOfalse, start the planned tasks.

    Discussion

    Use this method to perform tasks when your process is executing in the background. This method queues block for asynchronous execution on a concurrent queue. When your process is in the background, the method tries to take a task assertion to ensure that your block has time to execute. If it is unable to take a task assertion, or if the time allotted for the task assertion expires, the system executes your block with the parameter set to YEStrue. If it is able to take the task assertion, it executes the block and passes NOfalse for the expired parameter.

    If your block is still executing and the system need to suspend the process, the system executes your block a second time with the expired parameter set to YEStrue. Your block must be prepared to handle this case. When the expired parameter is YEStrue, stop any in-progress tasks as quickly as possible.

    Availability

    Available in iOS 8.2 and later.

Data Types

  • Operating system version structure used with operatingSystemVersion and isOperatingSystemAtLeastVersion:.

    Declaration

    Swift

    struct NSOperatingSystemVersion { var majorVersion: Int var minorVersion: Int var patchVersion: Int init() init(majorVersion majorVersion: Int, minorVersion minorVersion: Int, patchVersion patchVersion: Int) }

    Objective-C

    typedef struct { NSInteger majorVersion; NSInteger minorVersion; NSInteger patchVersion; } NSOperatingSystemVersion;

    Constants

    • majorVersion

      The major release number, such as 10 in version 10.9.3.

    • minorVersion

      The minor release number, such as 9 in version 10.9.3.

    • patchVersion

      The update release number, such as 3 in version 10.9.3.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • Declaration

    Swift

    struct NSActivityOptions : OptionSetType { init(rawValue rawValue: UInt64) static var IdleDisplaySleepDisabled: NSActivityOptions { get } static var IdleSystemSleepDisabled: NSActivityOptions { get } static var SuddenTerminationDisabled: NSActivityOptions { get } static var AutomaticTerminationDisabled: NSActivityOptions { get } static var UserInitiated: NSActivityOptions { get } static var UserInitiatedAllowingIdleSystemSleep: NSActivityOptions { get } static var Background: NSActivityOptions { get } static var LatencyCritical: NSActivityOptions { get } }

    Objective-C

    typedef enum : uint64_t { NSActivityIdleDisplaySleepDisabled = (1ULL << 40), NSActivityIdleSystemSleepDisabled = (1ULL << 20), NSActivitySuddenTerminationDisabled = (1ULL << 14), NSActivityAutomaticTerminationDisabled = (1ULL << 15), NSActivityUserInitiated = (0x00FFFFFFULL | NSActivityIdleSystemSleepDisabled ), NSActivityUserInitiatedAllowingIdleSystemSleep = (NSActivityUserInitiated & ~NSActivityIdleSystemSleepDisabled ), NSActivityBackground = 0x000000FFULL, NSActivityLatencyCritical = 0xFF00000000ULL, } NSActivityOptions;

    Constants

    • IdleDisplaySleepDisabled

      NSActivityIdleDisplaySleepDisabled

      Flag to require the screen to stay powered on.

      Available in iOS 7.0 and later.

    • IdleSystemSleepDisabled

      NSActivityIdleSystemSleepDisabled

      Flag to prevent idle sleep.

      This is included in NSActivityUserInitiatedAllowingIdleSystemSleep.

      Available in iOS 7.0 and later.

    • SuddenTerminationDisabled

      NSActivitySuddenTerminationDisabled

      Flag to prevent sudden termination.

      This is included in NSActivityUserInitiatedAllowingIdleSystemSleep.

      Available in iOS 7.0 and later.

    • AutomaticTerminationDisabled

      NSActivityAutomaticTerminationDisabled

      Flag to prevent automatic termination.

      This is included in NSActivityUserInitiatedAllowingIdleSystemSleep.

      Available in iOS 7.0 and later.

    • UserInitiated

      NSActivityUserInitiated

      Flag to indicate the app is performing a user-requested action.

      Available in iOS 7.0 and later.

    • UserInitiatedAllowingIdleSystemSleep

      NSActivityUserInitiatedAllowingIdleSystemSleep

      Flag to indicate the app is performing a user-requested action, but that the system can sleep on idle.

      Available in iOS 7.0 and later.

    • Background

      NSActivityBackground

      Flag to indicate the app has initiated some kind of work, but not as the direct result of user request.

      Available in iOS 7.0 and later.

    • LatencyCritical

      NSActivityLatencyCritical

      Flag to indicate the activity requires the highest amount of timer and I/O precision available.

      Available in iOS 7.0 and later.

    Discussion

    To include one of these individual flags in one of the sets, use bitwise OR; for example, during a presentation you might use:

    1. NSActivityUserInitiated | NSActivityIdleDisplaySleepDisabled

    To exclude from one of the sets, use bitwise AND with NOT; for example, during a user initiated action that may be safely terminated with no application interaction in case of logout you might use:

    1. NSActivityUserInitiated & ~NSActivitySuddenTerminationDisabled

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • The following constants are provided by the NSProcessInfo class as return values for operatingSystem.

    Declaration

    Swift

    var NSHPUXOperatingSystem: Int { get } var NSMACHOperatingSystem: Int { get } var NSOSF1OperatingSystem: Int { get } var NSSolarisOperatingSystem: Int { get } var NSSunOSOperatingSystem: Int { get } var NSWindows95OperatingSystem: Int { get } var NSWindowsNTOperatingSystem: Int { get }

    Objective-C

    enum { NSWindowsNTOperatingSystem = 1, NSWindows95OperatingSystem, NSSolarisOperatingSystem, NSHPUXOperatingSystem, NSMACHOperatingSystem, NSSunOSOperatingSystem, NSOSF1OperatingSystem };

    Constants

    • NSHPUXOperatingSystem

      NSHPUXOperatingSystem

      Indicates the HP UX operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSMACHOperatingSystem

      NSMACHOperatingSystem

      Indicates the OS X operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSOSF1OperatingSystem

      NSOSF1OperatingSystem

      Indicates the OSF/1 operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSSolarisOperatingSystem

      NSSolarisOperatingSystem

      Indicates the Solaris operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSSunOSOperatingSystem

      NSSunOSOperatingSystem

      Indicates the Sun OS operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSWindows95OperatingSystem

      NSWindows95OperatingSystem

      Indicates the Windows 95 operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSWindowsNTOperatingSystem

      NSWindowsNTOperatingSystem

      Indicates the Windows NT operating system.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.