Inside Macintosh: Processes

Chapter 2 - Process Manager

Summary of the Process Manager

Pascal Summary

Constants

CONST
      {Gestalt selector and response bits}
      gestaltOSAttr              = 'os  ';   {O/S attributes selector}
      gestaltLaunchCanReturn     = 1;        {can return from launch}
      gestaltLaunchFullFileSpec  = 2;        {LaunchApplication is available}
      gestaltLaunchControl       = 3;        {Process Manager is available}

      {process identification constants}
      kNoProcess                 = 0;        {process doesn't exist}
      kSystemProcess             = 1;        {process belongs to OS}
      kCurrentProcess            = 2;        {the current process}

      {launch control flags}
      launchContinue             = $4000;    {continue after launch}
      launchNoFileFlags          = $0800;    {ignore launchFileFlags}
      launchUseMinimum           = $0400;    {use minimum or greater size}
      launchDontSwitch           = $0200;    {launch app. in background}
      launchAllow24Bit           = $0100;    {reserved}
      launchInhibitDaemon        = $0080;    {don't launch background app.}
      
      {launch parameter block length and ID}
      extendedBlockLen           = sizeof(LaunchParamBlockRec) - 12;
      extendedBlock              = $4C43;    {extended block}
      
      {flags in processMode field}
      modeDeskAccessory          = $00020000;   {process is desk acc}
      modeMultiLaunch            = $00010000;   {from app file's flags}
      modeNeedSuspendResume      = $00004000;   {from 'SIZE' resource}
      modeCanBackground          = $00001000;   {from 'SIZE' resource}
      modeDoesActivateOnFGSwitch = $00000800;   {from 'SIZE' resource}
      modeOnlyBackground         = $00000400;   {from 'SIZE' resource}
      modeGetFrontClicks         = $00000200;   {from 'SIZE' resource}
      modeGetAppDiedMsg          = $00000100;   {from 'SIZE' resource}
      mode32BitCompatible        = $00000080;   {from 'SIZE' resource}
      modeHighLevelEventAware    = $00000040;   {from 'SIZE' resource}
      modeLocalAndRemoteHLEvents = $00000020;   {from 'SIZE' resource}
      modeStationeryAware        = $00000010;   {from 'SIZE' resource}
      modeUseTextEditServices    = $00000008;   {from 'SIZE' resource}

Data Types

Process Serial Number

TYPE 
   ProcessSerialNumber     = 
   RECORD
      highLongOfPSN:       LongInt;             {high-order 32 bits of psn}
      lowLongOfPSN:        LongInt;             {low-order 32 bits of psn}
   END;

   ProcessSerialNumberPtr  = ^ProcessSerialNumber;

Process Information Record

   ProcessInfoRec          =
   RECORD
      processInfoLength:   LongInt;             {length of record}
      processName:         StringPtr;           {name of process}
      processNumber:       ProcessSerialNumber; {psn of the process}
      processType:         LongInt;             {file type of app file}
      processSignature:    OSType;              {signature of app file}
      processMode:         LongInt;             {'SIZE' resource flags}
      processLocation:     Ptr;                 {address of partition}
      processSize:         LongInt;             {partition size}
      processFreeMem:      LongInt;             {free bytes in heap}
      processLauncher:     ProcessSerialNumber; {proc that launched this one}
      processLaunchDate:   LongInt;             {time when launched}
      processActiveTime:   LongInt;             {accumulated CPU time}
      processAppSpec:      FSSpecPtr;           {location of the file}
   END;

   ProcessInfoRecPtr       = ^ProcessInfoRec;

Application Parameters Record

   AppParameters           =
   RECORD
      theMsgEvent:         EventRecord;         {event (high-level)}
      eventRefCon:         LongInt;             {reference constant}
      messageLength:       LongInt;             {length of buffer}
      messageBuffer:       ARRAY [0..0] OF SignedByte;
   END;

   AppParametersPtr        =   ^AppParameters;

Launch Parameter Block

   LaunchFlags             =   Integer;
   LaunchParamBlockRec     = 
   RECORD
      reserved1:           LongInt;             {reserved}
      reserved2:           Integer;             {reserved}
      launchBlockID:       Integer;             {extended block}
      launchEPBLength:     LongInt;             {length of block}
      launchFileFlags:     Integer;             {app's Finder flags}
      launchControlFlags:  LaunchFlags;         {launch options}
      launchAppSpec:       FSSpecPtr;           {location of app's file}
      launchProcessSN:     ProcessSerialNumber; {returned psn}
      launchPreferredSize: LongInt;             {returned pref size}
      launchMinimumSize:   LongInt;             {returned min size}
      launchAvailableSize: LongInt;             {returned avail size}
      launchAppParameters: AppParametersPtr;    {high-level event}
   END;

   LaunchPBPtr             =  ^LaunchParamBlockRec;

Routines

Getting Process Information

FUNCTION GetCurrentProcess	(VAR PSN: ProcessSerialNumber): OSErr;
FUNCTION GetNextProcess		(VAR PSN: ProcessSerialNumber): OSErr;
FUNCTION GetProcessInformation
				(PSN: ProcessSerialNumber;
				VAR info: ProcessInfoRec): OSErr;
FUNCTION SameProcess		(PSN1: ProcessSerialNumber; 
				PSN2: ProcessSerialNumber; 
				VAR result: Boolean): OSErr;
FUNCTION GetFrontProcess	(VAR PSN: ProcessSerialNumber): OSErr;
FUNCTION SetFrontProcess	(PSN: ProcessSerialNumber): OSErr;
FUNCTION WakeUpProcess		(PSN: ProcessSerialNumber): OSErr;

Launching Applications and Desk Accessories

FUNCTION LaunchApplication	(LaunchParams: LaunchPBPtr): OSErr;
FUNCTION LaunchDeskAccessory	(pFileSpec: FSSpecPtr; pDAName: StringPtr): 
				OSErr;

Terminating a Process

PROCEDURE ExitToShell;

C Summary

Constants

/*Gestalt selector and response bits*/
#define gestaltOSAttr               'os  '   /*O/S attributes selector*/
#define gestaltLaunchCanReturn      1        /*can return from launch*/
#define gestaltLaunchFullFileSpec   2        /*LaunchApplication available*/
#define gestaltLaunchControl        3        /*Process Manager is available*/

/*process identification constants*/
enum {
      kNoProcess                    0,       /*process doesn't exist*/
      kSystemProcess                1,       /*process belongs to OS*/
      kCurrentProcess               2        /*the current process*/
};
/*launch control flags*/
enum {
      launchContinue             = 0x4000,   /*continue after launch*/
      launchNoFileFlags          = 0x0800,   /*ignore launchFileFlags*/
      launchUseMinimum           = 0x0400,   /*use minimum or greater size*/
      launchDontSwitch           = 0x0200,   /*launch app. in background*/
      launchAllow24Bit           = 0x0100,   /*reserved*/
      launchInhibitDaemon        = 0x0080    /*don't launch background app.*/
};
/*launch parameter block length and ID*/
#define extendedBlockLen            (sizeof(LaunchParamBlockRec) - 12)
#define extendedBlock               ((unsigned short)'LC')
      
/*flags in processMode field*/
enum {
      modeDeskAccessory          = 0x00020000,  /*process is desk acc*/
      modeMultiLaunch            = 0x00010000,  /*from app file's flags*/
      modeNeedSuspendResume      = 0x00004000,  /*from 'SIZE' resource*/
      modeCanBackground          = 0x00001000,  /*from 'SIZE' resource*/
      modeDoesActivateOnFGSwitch = 0x00000800,  /*from 'SIZE' resource*/
      modeOnlyBackground         = 0x00000400,  /*from 'SIZE' resource*/
      modeGetFrontClicks         = 0x00000200,  /*from 'SIZE' resource*/
      modeGetAppDiedMsg          = 0x00000100,  /*from 'SIZE' resource*/
      mode32BitCompatible        = 0x00000080,  /*from 'SIZE' resource*/
      modeHighLevelEventAware    = 0x00000040,  /*from 'SIZE' resource*/
      modeLocalAndRemoteHLEvents = 0x00000020,  /*from 'SIZE' resource*/
      modeStationeryAware        = 0x00000010,  /*from 'SIZE' resource*/
      modeUseTextEditServices    = 0x00000008   /*from 'SIZE' resource*/
};

Data Types

Process Serial Number

struct ProcessSerialNumber {
      unsigned long        highLongOfPSN;       /*high-order 32 bits of psn*/
      unsigned long        lowLongOfPSN;        /*low-order 32 bits of psn*/
};

typedef struct ProcessSerialNumber ProcessSerialNumber;
typedef ProcessSerialNumber *ProcessSerialNumberPtr;

Process Information Record

struct ProcessInfoRec {
      unsigned long        processInfoLength;   /*length of record*/
      StringPtr            processName;         /*name of process*/
      ProcessSerialNumber  processNumber;       /*psn of the process*/
      unsigned long        processType;         /*file type of app file*/
      OSType               processSignature;    /*signature of app file*/
      unsigned long        processMode;         /*'SIZE' resource flags*/
      Ptr                  processLocation;     /*address of partition*/
      unsigned long        processSize;         /*partition size*/
      unsigned long        processFreeMem;      /*free bytes in heap*/
      ProcessSerialNumber  processLauncher;     /*proc that launched this */
                                                /* one*/
      unsigned long        processLaunchDate;   /*time when launched*/
      unsigned long        processActiveTime;   /*accumulated CPU time*/
      FSSpecPtr            processAppSpec;      /*location of the file*/
};

typedef struct ProcessInfoRec ProcessInfoRec;
typedef ProcessInfoRec *ProcessInfoRecPtr;

Application Parameters Record

struct AppParameters {
      EventRecord          theMsgEvent;         /*event (high-level)*/
      unsigned long        eventRefCon;         /*reference constant*/
      unsigned long        messageLength;       /*length of buffer*/
};

typedef struct AppParameters AppParameters;
typedef AppParameters *AppParametersPtr;

Launch Parameter Block

typedef unsigned short LaunchFlags;
struct LaunchParamBlockRec {
      unsigned long        reserved1;           /*reserved*/
      unsigned short       reserved2;           /*reserved*/
      unsigned short       launchBlockID;       /*extended block*/
      unsigned long        launchEPBLength;     /*length of block*/
      unsigned short       launchFileFlags;     /*app's Finder flags*/
      LaunchFlags          launchControlFlags;  /*launch options*/
      FSSpecPtr            launchAppSpec;       /*location of app's file*/
      ProcessSerialNumber  launchProcessSN;     /*returned psn*/
      unsigned long        launchPreferredSize; /*returned pref size*/
      unsigned long        launchMinimumSize;   /*returned min size*/
      unsigned long        launchAvailableSize; /*returned avail size*/
      AppParametersPtr     launchAppParameters; /*high-level event*/
};

typedef struct LaunchParamBlockRec LaunchParamBlockRec;
typedef LaunchParamBlockRec *LaunchPBPtr;

Routines

Getting Process Information

pascal	OSErr	GetCurrentProcess		(ProcessSerialNumber *PSN);
pascal	OSErr	GetNextProcess			(ProcessSerialNumber *PSN);
pascal	OSErr	GetProcessInformation		(const ProcessSerialNumber *PSN,
						ProcessInfoRecPtr info);
pascal	OSErr	SameProcess			(const ProcessSerialNumber *PSN1, 
						const ProcessSerialNumber *PSN2, 
						Boolean *result);
pascal	OSErr	GetFrontProcess			(ProcessSerialNumber *PSN);
pascal	OSErr	SetFrontProcess			(const ProcessSerialNumber *PSN);
pascal	OSErr	WakeUpProcess			(const ProcessSerialNumber *PSN);

Launching Applications and Desk Accessories

pascal	OSErr	LaunchApplication		(const LaunchParamBlockRec *LaunchParams);
pascal	OSErr	LaunchDeskAccessory		(const FSSpec *pFileSpec,
						ConstStr255Param pDAName);

Terminating a Process

pascal	void	ExitToShell				(void);

Assembly-Language Summary

Data Structures

Process Serial Number

0	highLongOfPSN	long	high-order 32-bits of process serial number
4	lowLongOfPSN	long	low-order 32-bits of process serial number

Process Information Record

0	processInfoLength	long	length of this record
4	processName	long	name of process
8	processNumber	2 longs	process serial number of the process
16	processType	long	type of application file
20	processSignature	long	signature of application file
24	processMode	long	flags from 'SIZE' resource
28	processLocation	long	address of process partition
32	processSize	long	partition size (in bytes)
36	processFreeMem	long	amount of free memory in application heap
40	processLauncher	2 longs	process that launched this one
48	processLaunchDate	long	value of Ticks at time of launch
52	processActiveTime	long	total time spent using the CPU
56	processAppSpec	long	location of the file

Application Parameters Record

0	theMsgEvent	16 bytes	the high-level event record
16	eventRefCon	long	reference constant
20	messageLength	long	length of buffer
24	messageBuffer	byte	first byte of the message buffer

Launch Parameter Block

0	reserved1	long	reserved
4	reserved2	word	reserved
6	launchBlockID	word	specifies whether block is extended
8	launchEPBLength	long	length (in bytes) of rest of parameter block
12	launchFileFlags	word	the Finder flags for the application file
14	launchControlFlags	word	flags that specify launch options
16	launchAppSpec	long	address of FSSpec that specifies the application file to launch
20	launchProcessSN	2 longs	process serial number
28	launchPreferredSize	long	application's preferred partition size
32	launchMinimumSize	long	application's minimum partition size
36	launchAvailableSize	long	maximum partition size available
40	launchAppParameters	long	high-level event for launched application

Trap Macros

Trap Macro Names

Pascal name	Trap macro name
LaunchApplication	_Launch
ExitToShell	_ExitToShell

Trap Macros Requiring Routine Selectors

_OSDispatch

Selector	Routine
$0036	LaunchDeskAccessory
$0037	GetCurrentProcess
$0038	GetNextProcess
$0039	GetFrontProcess
$003A	GetProcessInformation
$003B	SetFrontProcess
$003C	WakeUpProcess
$003D	SameProcess

Result Codes

noErr	0	No error
paramErr	-50	Process serial number is invalid
memFullErr	-108	Not enough memory to allocate the partition size specified in the 'SIZE' resource
resNotFound	-192	Resource not found
procNotFound	-600	No eligible process with specified process serial number
memFragErr	-601	Not enough room to launch application with special requirements
appModeErr	-602	Addressing mode is 32-bit, but application is not 32-bit clean
appMemFullErr	-605	Partition size specified in 'SIZE' resource is not big enough for launch
appIsDaemon	-606	Application is background-only