Process Manager Reference (Not Recommended)

Framework
Carbon/Carbon.h
Declared in
MacTypes.h
Processes.h

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

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

Starting and Terminating Processes

Modifying Processes

Functions

TransformProcessType

Changes the type of the specified process.

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

The serial number of the process you want to transform. You can also use the constant kCurrentProcess to refer to the current process. See ProcessSerialNumber for more information.

transformState

A constant indicating the type of transformation you want. See “Process Transformation Constant.” Currently you can pass only kProcessTransformToForegroundApplication.

Return Value

A result code. See “Process Manager Result Codes.”

Discussion

You can use this call to transform a background-only application into a foreground application. A foreground application appears in the Dock (and in the Force Quit dialog) and contains a menu bar. This function does not cause the application to be brought to the front; you must call SetFrontProcess to do so.

Availability
  • Available in OS X v10.3 and later.
Declared In
Processes.h

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;
Discussion

The application parameters structure is used in the launchAppParameters field of the launch parameter block, LaunchParamBlockRec , whose address is passed to the LaunchApplication function.

Availability
  • Available in OS X v10.0 and later.
Declared In
Processes.h

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.

Discussion

You specify a launch parameter block as a parameter to the LaunchApplication function.

Availability
  • Available in OS X v10.0 and later.
Declared In
Processes.h

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.

Discussion

A process information record is returned by the GetProcessInformation function.

Availability
  • Available in OS X v10.0 and later.
Declared In
Processes.h

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;
Discussion

See ProcessInfoRec for more information.

Availability
  • Available in OS X v10.0 and later.
Declared In
Processes.h

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.

Discussion

All applications (defined as things which can appear in the Dock that are not documents and are launched by the Finder or Dock) on Mac OS X have a unique process serial number. This number is created when the application launches, and remains until the application quits. Other system services, like Apple events, use the ProcessSerialNumber structure to specify an application.

During launch, every application “checks in” with the Process Manager. Before this checkin, the application can not receive events or draw to the screen. Prior to Mac OS 10.2, this check in occurred before the applications's main function was entered. In Mac OS 10.2 and later, this check in does not occur until the first time the application calls a Process Manager function, or until it enters CFRunLoopRun for the main event loop. This allows tools and other executables which do not need to receive events to link against more of the higher level toolbox frameworks, but may cause a problem if the application expects to be able to retrieve events or use CoreGraphics services before this checkin has occurred. An application can force the connection to the Process Manager to be set up by calling any Process Manager routine, but the recommended way to do this is to call GetCurrentProcess to ask for the current application's PSN. Doing so initializes the connection to the Process Manager if it has not already been set up and ”check in“ the application with the system.

You should not make any assumptions about the meaning of the bits in a process serial number. To compare two process serial numbers, you should use the function SameProcess.

You can obtain a process serial number in one of the following ways:

If you want to specify a process using the “Process Identification Constants,” you must populate a process serial number structure, passing 0 in highLongOfPSN and the appropriate constant (such as kCurrentProcess) in lowLongOfPSN. For example, to bring the current process forward, you can use the following code:

 ProcessSerialNumber psn = { 0, kCurrentProcess };
 SetFrontProcess( &psn );
Availability
  • Available in OS X v10.0 and later.
Declared In
MacTypes.h

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;
Availability
  • Available in OS X v10.0 and later.
Declared In
Processes.h

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
};
Discussion

Applications and background applications can control when they are asked to quit by the system at restart and shutdown by setting these bits in a 'quit'(0) resource located in the resource fork.

Applications without this resource are terminated at kQuitAtNormalTime.

Availability
  • Available in CarbonLib 1.0 and later. Not available in Mac OS X version 10.0 and later.

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.

Discussion

For more information, see LaunchApplication and LaunchParamBlockRec.

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
};
Discussion

These constants indicate, in the processMode field of the ProcessInfoRec structure, whether the process is an application or a desk accessory. If the process is an application, these flags return information about the application’s ‘SIZE’ resource.

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.

Discussion

If you want to use these constants to specify a process, you must populate a process serial number structure (ProcessSerialNumber), passing 0 in the highLongOfPSN field and the appropriate constant (such as kCurrentProcess) in the lowLongOfPSN. For example, to bring the current process forward, you can use the following code:

 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.

Result CodeValueDescription
procNotFound -600

No eligible process with specified process serial number.

Available in OS X v10.0 and later.

memFragErr -601

Not enough room to launch application with special requirements.

Available in OS X v10.0 and later.

appModeErr -602

Addressing mode is 32-bit, but application is not 32-bit clean.

Available in OS X v10.0 and later.

protocolErr -603

app made module calls in improper order

Available in OS X v10.0 and later.

hardwareConfigErr -604

Hardware configuration not supported.

Available in OS X v10.0 and later.

appMemFullErr -605

Partition size specified in SIZE resource is not big enough for launch.

Available in OS X v10.0 and later.

appIsDaemon -606

Application runs in background only.

Available in OS X v10.0 and later.

wrongApplicationPlatform -875

The application could not launch because the required platform is not available.

Available in OS X v10.0 and later.

appVersionTooOld -876

The application's creator and version are incompatible with the current version of Mac OS.

Available in OS X v10.0 and later.

notAppropriateForClassic -877

This application will not (or should not) run in Classic.

Available in OS X v10.0 and later.