Overview

The Process Manager provides the cooperative multitasking environment for versions of Mac OS that preceded Mac OS X. The Process Manager controls access to shared resources and manages the scheduling and execution of applications.

You can use the Process Manager to control the execution of processes and to get information about processes, including your own. You can use the Process Manager routines to

• control the execution of your application

• get information about processes

• launch other applications

Some Process Manager functions access a ProcessInfoRec data structure, which contains fields that are no longer applicable in a preemptively scheduled environment (for example, the processLocation, processFreeMem, and processActiveTime fields). Your application should avoid accessing such fields. Changes to the memory model may also affect certain fields.

Carbon does not support Process Manager functions that deal with control panels or desk accessories.

Functions by Task

Getting Process Information

• CopyProcessName
• GetCurrentProcess
• GetFrontProcess
• GetNextProcess
• GetProcessBundleLocation
• GetProcessInformation
• ProcessInformationCopyDictionary
• GetProcessPID
• GetProcessForPID
• IsProcessVisible
• SameProcess

Starting and Terminating Processes

• LaunchApplication
• ExitToShell
• KillProcess

Modifying Processes

• SetFrontProcess
• SetFrontProcessWithOptions
• ShowHideProcess
• TransformProcessType
• WakeUpProcess

Functions

CopyProcessName

Gets a copy of the name of a process.

OSStatus CopyProcessName (
   const ProcessSerialNumber *psn,
   CFStringRef *name
);

ExitToShell

Terminates an application.

void ExitToShell (
   void
);

GetCurrentProcess

Gets information about the current process, if any.

OSErr GetCurrentProcess (
   ProcessSerialNumber * PSN
);

GetFrontProcess

Gets the process serial number of the front process.

OSErr GetFrontProcess (
   ProcessSerialNumber *PSN
);

GetNextProcess

Gets information about the next process, if any, in the Process Manager’s internal list of open processes.

OSErr GetNextProcess (
   ProcessSerialNumber *PSN
);

GetProcessBundleLocation

Retrieves the file system location of the application bundle (or executable file) associated with a process.

OSStatus GetProcessBundleLocation (
   const ProcessSerialNumber *psn,
   FSRef *location
);

GetProcessForPID

Obtains the process serial number from a Unix PID.

OSStatus GetProcessForPID (
   pid_t pid,
   ProcessSerialNumber *psn
);

GetProcessInformation

Get information about a specific process.

OSErr GetProcessInformation (
   const ProcessSerialNumber *PSN,
   ProcessInfoRec *info
);

GetProcessPID

Obtains the Unix PID from a process serial number.

OSStatus GetProcessPID (
   const ProcessSerialNumber *psn,
   pid_t *pid
);

IsProcessVisible

Determines the visiblility of the user interface for a process.

Boolean IsProcessVisible (
   const ProcessSerialNumber *psn
);

KillProcess

Terminates a process with the specified ID.

OSErr KillProcess (
   const ProcessSerialNumber *inProcess
);

LaunchApplication

Launches an application.

OSErr LaunchApplication (
   LaunchPBPtr LaunchParams
);

ProcessInformationCopyDictionary

Obtains a superset of GetProcessInformation in modern data types.

CFDictionaryRef ProcessInformationCopyDictionary (
   const ProcessSerialNumber *PSN,
   UInt32 infoToReturn
);

SameProcess

Determines whether two process serial numbers specify the same process.

OSErr SameProcess (
   const ProcessSerialNumber *PSN1,
   const ProcessSerialNumber *PSN2,
   Boolean *result
);

SetFrontProcess

Moves a process to the foreground.

OSErr SetFrontProcess (
   const ProcessSerialNumber *PSN
);

SetFrontProcessWithOptions

Brings a process to the front of the process list, and activates it.

OSStatus SetFrontProcessWithOptions (
   const ProcessSerialNumber *inProcess,
   OptionBits inOptions
);

ShowHideProcess

Shows or hides a given process.

OSErr ShowHideProcess (
   const ProcessSerialNumber *psn,
   Boolean visible
);

TransformProcessType

Changes the type of the specified process.

OSStatus TransformProcessType (
   const ProcessSerialNumber *psn,
   ProcessApplicationTransformState transformState
);

WakeUpProcess

Makes a suspended process eligible for CPU time.

OSErr WakeUpProcess (
   const ProcessSerialNumber *PSN
);

Data Types

AppParameters

Defines the first high-level event sent to a newly-launched application.

struct AppParameters {
   struct {
      UInt16 what;
      UInt32 message;
      UInt32 when;
      Point where;
      UInt16 modifiers;
   } theMsgEvent;
   unsigned long eventRefCon
   unsigned long messageLength
};
typedef struct AppParameters AppParameters;
   typedef AppParameters * AppParametersPtr;

LaunchParamBlockRec

Defines the required parameters when launching an application.

struct LaunchParamBlockRec {
   unsigned long reserved1;
   unsigned short reserved2;
   unsigned short launchBlockID;
   unsigned long launchEPBLength;
   unsigned short launchFileFlags;
   LaunchFlags launchControlFlags;
   FSSpecPtr launchAppSpec;
   ProcessSerialNumber launchProcessSN;
   unsigned long launchPreferredSize;
   unsigned long launchMinimumSize;
   unsigned long launchAvailableSize;
   AppParametersPtr launchAppParameters;
};
typedef struct LaunchParamBlockRec LaunchParamBlockRec;
   typedef LaunchParamBlockRec * LaunchPBPtr;

Fields

reserved1

Reserved.

reserved2

Reserved.

launchBlockID

A value that indicates whether you are using the fields following it in the launch parameter block. Specify the constant extendedBlock if you use the fields that follow it.

launchEPBLength

The length of the fields following this field in the launch parameter block. Use the constant extendedBlockLen to specify this value.

launchFileFlags

The Finder flags for the application file. Set the launchNoFileFlags constant in the launchControlFlags field if you want the LaunchApplication function to extract the Finder flags from the application file and to set the launchFileFlags field for you.

launchControlFlags

See “Launch Options” for a complete description of these flags.

launchAppSpec

A pointer to a file specification structure that gives the location of the application file to launch.

launchProcessSN

The process serial number returned to your application if the launch is successful. You can use this process serial number in other Process Manager functions to refer to the launched application.

launchPreferredSize

The preferred partition size for the launched application as specified in the launched application’s 'SIZE' resource. LaunchApplication sets this field to 0 if an error occurred or if the application is already open.

launchMinimumSize

The minimum partition size for the launched application as specified in the launched application’s 'SIZE' resource. LaunchApplication sets this field to 0 if an error occurred or if the application is already open.

launchAvailableSize

The maximum partition size that is available for allocation. This value is returned to your application only if the memFullErr result code is returned. If the application launch fails because of insufficient memory, you can use this value to determine if there is enough memory available to launch in the minimum size.

launchAppParameters

The first high-level event to send to the launched application. If you set this field to NULL, LaunchApplication creates and sends the Open Application Apple event to the launched application.

ProcessInfoRec

Defines the structure of a process information record.

struct ProcessInfoRec {
   unsigned long processInfoLength;
   StringPtr processName;
   ProcessSerialNumber processNumber;
   unsigned long processType;
   OSType processSignature;
   unsigned long processMode;
   Ptr processLocation;
   unsigned long processSize;
   unsigned long processFreeMem;
   ProcessSerialNumber processLauncher;
   unsigned long processLaunchDate;
   unsigned long processActiveTime;
   FSSpecPtr processAppSpec;
};
typedef struct ProcessInfoRec ProcessInfoRec;
   typedef ProcessInfoRec * ProcessInfoRecPtr;

Fields

processInfoLength

The number of bytes in the process information structure. For compatibility, you should specify the length of the structure in this field.

processName

The name of the application. This field contains the name of the application as designated by the user at the time the application was opened. For example, for foreground applications, the processName field contains the name as it appears in the Application menu. You must specify NULL in the processName field if you do not want the application name returned. Otherwise, you should allocate at least 32 bytes of storage for the string pointed to by the processName field. Note that the processName field specifies the name of the application, whereas the processAppSpec field specifies the location of the file.

processNumber

The process serial number.

processType

The file type of the application, generally 'APPL' for applications and 'appe' for background-only applications launched at startup.

processSignature

The signature (or creator) of the file containing the application.

processMode

Process mode flags. These flags indicate whether the process is an application or desk accessory. For applications, this field also returns information specified in the application’s 'SIZE' resource. This information is returned as flags.

On Mac OS X, some flags in processMode will not be set as they were on Mac OS 9, even for Classic applications. Mac OS X doesn't support applications which can't be sent into the background, so modeCanBackground will always be set. Similarly, Mac OS X applications will always have mode32BitCompatible and modeHighLevelEventAware set

processLocation

The beginning address of the application partition.

processSize

The number of bytes in the application partition (including the heap, stack, and A5 world).

processFreeMem

The number of free bytes in the application heap.

processLauncher

The process serial number of the process that launched the application or desk accessory. If the original launcher of the process is no longer open, the lowLongOfPSN field of the process serial number structure contains the constant kNoProcess.

processLaunchDate

The value of the Ticks global variable at the time that the process was launched.

processActiveTime

The accumulated time, in ticks, during which the process has used the CPU, including both foreground and background processing time.

processAppSpec

The address of a file specification structure that stores the location of the file containing the application or 'DRVR' resource. You should specify NULL in the processAppSpec field if you do not want the FSSpec structure of the file returned.

ProcessInfoExtendedRec

Defines an extended version of the process information record.

struct ProcessInfoExtendedRec {
   unsigned long processInfoLength;
   StringPtr processName;
   ProcessSerialNumber processNumber;
   unsigned long processType;
   OSType processSignature;
   unsigned long processMode;
   Ptr processLocation;
   unsigned long processSize;
   unsigned long processFreeMem;
   ProcessSerialNumber processLauncher;
   unsigned long processLaunchDate;
   unsigned long processActiveTime;
   FSSpecPtr processAppSpec;
   unsigned long processTempMemTotal;
   unsigned long processPurgeableTempMemTotal;
};
typedef struct ProcessInfoExtendedRec ProcessInfoExtendedRec;
   typedef ProcessInfoExtendedRec * ProcessInfoExtendedRecPtr;

ProcessSerialNumber

Defines the unique identifier for an open process.

struct ProcessSerialNumber {
   unsigned long highLongOfPSN;
   unsigned long lowLongOfPSN;
};
typedef struct ProcessSerialNumber ProcessSerialNumber;
   typedef ProcessSerialNumber * ProcessSerialNumberPtr;

Fields

highLongOfPSN

The high-order long integer of the process serial number.

lowLongOfPSN

The low-order long integer of the process serial number.

 ProcessSerialNumber psn = { 0, kCurrentProcess };

 SetFrontProcess( &psn );

SizeResourceRec

Defines a representation of the SIZE resource.

struct SizeResourceRec {
   unsigned short flags;
   unsigned long preferredHeapSize;
   unsigned long minimumHeapSize;
};
typedef struct SizeResourceRec SizeResourceRec;
   typedef SizeResourceRec * SizeResourceRecPtr;

Constants

Control Panel Result Codes

Specifies the values that a control panel can return.

Unsupported

enum {
   cdevGenErr = -1,
   cdevMemErr = 0,
   cdevResErr = 1,
   cdevUnset = 3
};

Extension Launch Codes

Specifies the values used when launching extensions.

enum {
   extendedBlock = 0x4C43,
   extendedBlockLen = sizeof(LaunchParamBlockRec) - 12
};

Control Panel Message Codes

Specifies the values for messages to a control panel.

enum {
   initDev = 0,
   hitDev = 1,
   closeDev = 2,
   nulDev = 3,
   updateDev = 4,
   activDev = 5,
   deactivDev = 6,
   keyEvtDev = 7,
   macDev = 8,
   undoDev = 9,
   cutDev = 10,
   copyDev = 11,
   pasteDev = 12,
   clearDev = 13,
   cursorDev = 14
};

Termination Options

Specifies masks to control the timing of application termination during system shutdown or restart.

enum {
   kQuitBeforeNormalTimeMask = 1,
   kQuitAtNormalTimeMask = 2,
   kQuitBeforeFBAsQuitMask = 4,
   kQuitBeforeShellQuitsMask = 8,
   kQuitBeforeTerminatorAppQuitsMask = 16,
   kQuitNeverMask = 32,
   kQuitOptionsMask = 0x7F,
   kQuitNotQuitDuringInstallMask = 0x0100,
   kQuitNotQuitDuringLogoutMask = 0x0200
};

Front Process Options

Specifies options for bringing windows forward when a process is activated.

enum {
   kSetFrontProcessFrontWindowOnly = (1 << 0)
};

Constants

kSetFrontProcessFrontWindowOnly

Activate the process, but bring only the frontmost non-floating window forward.

Available in Mac OS X version 10.2 and later.

Declared in Processes.h.

Launch Options

Specifies the valid launch options in the launchControlFlags field of the launch parameter block.

typedef unsigned short LaunchFlags;
enum {
   launchContinue                = 0x4000,
   launchNoFileFlags             = 0x0800,
   launchUseMinimum              = 0x0400,
   launchDontSwitch              = 0x0200,
   launchAllow24Bit              = 0x0100,
   launchInhibitDaemon           = 0x0080
};

Constants

launchContinue

Set this flag if you want your application to continue after the specified application is launched. If you do not set this flag, LaunchApplication terminates your application after launching the specified application, even if the launch fails.

Available in OS X v10.0 and later.

Declared in Processes.h.

launchNoFileFlags

Set this flag if you want the LaunchApplication function to ignore any value specified in the launchFileFlags field. If you set the launchNoFileFlags flag, the LaunchApplication function extracts the Finder flags from the application file for you. If you want to supply the file flags, clear the launchNoFileFlags flag and specify the Finder flags in the launchFileFlags field of the launch parameter block.

Available in OS X v10.0 and later.

Declared in Processes.h.

launchUseMinimum

Clear this flag if you want the LaunchApplication function to attempt to launch the application in the preferred size (as specified in the application’s 'SIZE' resource). If you set the launchUseMinimum flag, the LaunchApplication function attempts to launch the application using the largest available size greater than or equal to the minimum size but less than the preferred size. If the LaunchApplication function returns the result code memFullErr or memFragErr, the application cannot be launched under the current memory conditions.

Available in OS X v10.0 and later.

Declared in Processes.h.

launchDontSwitch

Set this flag if you do not want the launched application brought to the front. If you set this flag, the launched application runs in the background until the user brings the application to the front—for example, by clicking in one of the application’s windows. Note that most applications expect to be launched in the foreground. If you clear the launchDontSwitch flag, the launched application is brought to the front, and your application is sent to the background.

Available in OS X v10.0 and later.

Declared in Processes.h.

launchAllow24Bit

Available in OS X v10.0 and later.

Declared in Processes.h.

launchInhibitDaemon

Set this flag if you do not want LaunchApplication to launch a background-only application. (A background-only application has the onlyBackground flag set in its 'SIZE' resource.)

Available in OS X v10.0 and later.

Declared in Processes.h.

Process Mode Flags

Specifies the type of information returned in a process information record.

enum {
   modeReserved = 0x01000000,
   modeControlPanel = 0x00080000,
   modeLaunchDontSwitch = 0x00040000,
   modeDeskAccessory = 0x00020000,
   modeMultiLaunch = 0x00010000,
   modeNeedSuspendResume = 0x00004000,
   modeCanBackground = 0x00001000,
   modeDoesActivateOnFGSwitch = 0x00000800,
   modeOnlyBackground = 0x00000400,
   modeGetFrontClicks = 0x00000200,
   modeGetAppDiedMsg = 0x00000100,
   mode32BitCompatible = 0x00000080,
   modeHighLevelEventAware = 0x00000040,
   modeLocalAndRemoteHLEvents = 0x00000020,
   modeStationeryAware = 0x00000010,
   modeUseTextEditServices = 0x00000008,
   modeDisplayManagerAware = 0x00000004
};

Process Identification Constants

Specifies constants used instead of a process serial number to identify a process.

enum {
   kNoProcess = 0,
   kSystemProcess = 1,
   kCurrentProcess = 2
};

Constants

kNoProcess

Identifies a process that doesn’t exist.

Available in OS X v10.0 and later.

Declared in Processes.h.

kSystemProcess

Identifies a process that belongs to the Operating System.

Available in OS X v10.0 and later.

Declared in Processes.h.

kCurrentProcess

Identifies the current process.

Available in OS X v10.0 and later.

Declared in Processes.h.

 ProcessSerialNumber psn = { 0, kCurrentProcess };

 SetFrontProcess( &psn );

Process Transformation Constant

Specify tranformation types to be applied when calling TransformProcessType.

enum {
   kProcessTransformToForegroundApplication = 1L
};
typedef UInt32 ProcessApplicationTransformState;

Constants

kProcessTransformToForegroundApplication

Use to convert a background-only application to a foreground application.

Available in OS X v10.3 and later.

Declared in Processes.h.

Result Codes

The table below lists the most common result codes returned by the Process Manager.