Overview

Applications can use the Memory Management Utilities to

• ensure that their callback routines, interrupt tasks, and stand-alone code could access application global variables or QuickDraw global variables

• add elements to and remove them from an operating-system queue

• ensure that they function properly in both 24- and 32-bit modes

• ensure that data or instructions in the microprocessor’s internal caches remain consistent with data or instructions in RAM

While Carbon supports most of the Memory Management Utilities, there are changes to functions that assume a 68K runtime environment.

• Functions that flush caches on 68K processors (such as FlushInstructionCache, FlushDataCache, and FlushCodeCacheRange) are no longer supported.

• Functions such as SetA5 or SetCurrentA5 do nothing when running in Mac OS X. However, these functions should work normally when running in Mac OS 8 or 9.

• The functions GetMMUMode and SwapMMUMode are not supported because all PowerPC applications use 32-bit addressing, even if they are not Carbon-compliant.

• The SysEnvirons function is no longer supported since the Gestalt Manager can provide the same information. You should call the functions FindFolder and Gestalt instead.

For a list of unsupported functions, see the Carbon Specification.

Functions by Task

Determining the Measurement System

• IsMetric Deprecated in OS X v10.7

Reading and Writing Location Data

• ReadLocation Deprecated in OS X v10.8
• WriteLocation Deprecated in OS X v10.1

Setting and Restoring the A5 Register

• SetA5 Deprecated in OS X v10.4
• SetCurrentA5 Deprecated in OS X v10.4

Getting the User and Computer Name

• CSCopyMachineName Deprecated in OS X v10.8
• CSCopyUserName Deprecated in OS X v10.8

Managing a Queue

• DTInstall Deprecated in OS X v10.4
• DTUninstall Deprecated in OS X v10.4
• Dequeue Deprecated in OS X v10.8
• Enqueue Deprecated in OS X v10.8

Working With Parameter RAM

• InitUtil Deprecated in OS X v10.3
• GetSysPPtr Deprecated in OS X v10.4
• WriteParam Deprecated in OS X v10.4

Miscellaneous

• Delay Deprecated in OS X v10.8
• MakeDataExecutable Deprecated in OS X v10.8
• TickCount Deprecated in OS X v10.8

Working With Universal Procedure Pointers

• DisposeDeferredTaskUPP Deprecated in OS X v10.8
• InvokeDeferredTaskUPP Deprecated in OS X v10.8
• NewDeferredTaskUPP Deprecated in OS X v10.8

Callbacks

DeferredTaskProcPtr

Defines a pointer to a deferred-task callback.

typedef void (*DeferredTaskProcPtr) (
   long dtParam
);

If you name your function MyDeferredTaskProc, you would declare it like this:

void MyDeferredTaskProc (
   long dtParam
);

Data Types

DeferredTask

Contains information related to a deferred task.

struct DeferredTask {
   volatile QElemPtr qLink;
   short qType;
   volatile short dtFlags;
   DeferredTaskUPP dtAddr;
   long dtParam;
   long dtReserved;
};
typedef struct DeferredTask DeferredTask;
   typedef DeferredTask * DeferredTaskPtr;

DeferredTaskUPP

Defines a universal procedure pointer to a deferred-task callback.

typedef DeferredTaskProcPtr DeferredTaskUPP;

MachineLocation

Contains information about the geographical location of a computer.

struct MachineLocation {
   Fract latitude
   Fract longitude
   union {
      #if TARGET_RT_BIG_ENDIAN
      SInt8 dlsDelta;
      #endif
      long gmDelta;
      struct {
         #if TARGET_RT_LITTLE_ENDIAN
         SInt8 pad[3];
         #endif
         SInt8 Delta;
      } dls;
   } u;
};
typedef struct MachineLocation MachineLocation;

Fields

latitude

The location’s latitude, in fractions of a great circle. For example, Copenhagen, Denmark is at 55.43 degrees north latitude. When writing the latitude to extended parameter RAM with the WriteLocation procedure, you must convert this value to a Fract data type. (For example, a Fract value of 1.0 equals 90 degrees –1.0 equals –90 degrees and –2.0 equals –180 degrees.) For more information on the Fract data type, see Mathematical and Logical Utilities.

longitude

The location’s longitude, in fractions of a great circle. For example, Copenhagen, Denmark is at 12.34 degrees east longitude. When writing the longitude to extended parameter RAM with the WriteLocation procedure, you must convert this value to a Fract data type. (For example, a Fract value of 1.0 equals 90 degrees –1.0 equals –90 degrees and –2.0 equals –180 degrees.

dlsDelta

A value that represents the current state of daylight savings time.

gmDelta

pad

delta

A signed byte value representing the hour offset for daylight saving time. This field is a 1-byte value contained in a long word. It should be preserved when writing gmtDelta.

MachineLocation.u.dlsDelta = 1;

MachineLocation.u.dls.Delta = 1;

MachineLocation.u.dls.Delta = 0xAA;         // u = 0xAAGGGGGG; G=Garbage

MachineLocation.u.gmtDelta = 0xBBBBBB;      // u = 0x00BBBBBB;

MachineLocation.u.gmtDelta = 0xBBBBBB;      // u = 0x00BBBBB;

MachineLocation.u.dls.Delta = 0xAA;         // u = 0xAABBBBBB;

QElem

Contains information about a queue element.

struct QElem {
   QElem * qLink;
   short qType;
   short qData[1];
};
typedef struct QElem QElem;
   typedef QElem * QElemPtr;

Fields

qLink

The type of the queue element. For a description of the values which you can use in this field, see “Queue Types.”

qType

A variable array of data. The type of data and the length depend upon the queue type, specified in the qType field.

qData

QHdr

Contains information about the event queue.

struct QHdr {
   volatile short qFlags;
   volatile QElemPtr qHead;
   volatile QElemPtr qTail;
};
typedef struct QHdr QHdr;
   typedef QHdr * QHdrPtr;

Fields

qFlags

Queue flags.

qHead

First queue entry.

qTail

Last queue entry.

SysEnvRec

Contains information about the system environment.

struct SysEnvRec {
   short environsVersion;
   short machineType;
   short systemVersion;
   short processor;
   Boolean hasFPU;
   Boolean hasColorQD;
   short keyBoardType;
   short atDrvrVersNum;
   short sysVRefNum;
};
typedef struct SysEnvRec SysEnvRec;

Fields

environsVersion

The version number of the SysEnvirons function that was used to fill in the record.

When you call the SysEnvirons function, you specify a version number to ensure that you receive a system environment record that matches your expectations. If you request a more recent version of SysEnvirons than is available, SysEnvirons places its own version number in the environsVersion field and returns a function result envVersTooBig.

machineType

A code for the Macintosh model. See “Macintosh Model Codes.” Use the Gestalt function to obtain information about machine types not listed among these constants.

systemVersion

The version number of the current System file, represented as two byte-long numbers with one or more implied decimal points. The value $0410, for example, represents system software version 4.1.

If you call SysEnvirons when a system earlier than 4.1 is running, the MPW glue places $0 in this field and returns a result code of envNotPresent.

processor

A code for the microprocessor. See “Microprocessor Codes.”

hasFPU

A Boolean value that indicates whether hardware floating-point processing is available.

hasColorQD

A Boolean value that indicates whether Color QuickDraw is present. This field says nothing about the presence of a color monitor.

keyBoardType

A code for the keyboard type. See “Keyboard Constants.” Use the Gestalt function to obtain information about keyboard types not listed among these constants.

If the Apple Desktop Bus is in use, this field returns the keyboard type of the keyboard on which the last keystroke was made.

atDrvrVersNum

The version number of the AppleTalk driver (specifically, the .MPP driver) currently installed. If AppleTalk is not loaded, this field is 0.

sysVRefNum

The working-directory reference number of the folder or volume that holds the open System file.

SysParmType

Contains settings used by the system at startup.

struct SysParmType {
   UInt8 valid;
   UInt8 aTalkA;
   UInt8 aTalkB;
   UInt8 config;
   short portA;
   short portB;
   long alarm;
   short font;
   short kbdPrint;
   short volClik;
   short misc;
};
typedef struct SysParmType SysParmType;
   typedef SysParmType * SysPPtr;

Constants

Addressing Errors

Specify a type of addressing error.

enum {
   false32b = 0,
   true32b = 1
};

Constants

false32b

Indicates a 24-bit addressing error.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

true32b

Indicates a 32-bit addressing error.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

Keyboard Constants

Specify keyboard types.

enum {
   envUnknownKbd = 0,
   envMacKbd = 1,
   envMacAndPad = 2,
   envMacPlusKbd = 3,
   envAExtendKbd = 4,
   envStandADBKbd = 5,
   envPrtblADBKbd = 6,
   envPrtblISOKbd = 7,
   envStdISOADBKbd = 8,
   envExtISOADBKbd = 9
};

Macintosh Model Codes

Specify models of Macintosh computers.

enum {
   envMac = -1,
   envXL = -2,
   envMachUnknown = 0,
   env512KE = 1,
   envMacPlus = 2,
   envSE = 3,
   envMacII = 4,
   envMacIIx = 5,
   envMacIIcx = 6,
   envSE30 = 7,
   envPortable = 8,
   envMacIIci = 9,
   envMacIIfx = 11
};

Microprocessor Codes

Specify types of microprocessors.

enum {
   envCPUUnknown = 0,
   env68000 = 1,
   env68010 = 2,
   env68020 = 3,
   env68030 = 4,
   env68040 = 5
};

Queue Types

Specifies queue types.

enum {
   dummyType = 0,
   vType = 1,
   ioQType = 2,
   drvQType = 3,
   evType = 4,
   fsQType = 5,
   sIQType = 6,
   dtQType = 7,
   nmType = 8
};
typedef SignedByte QTypes;

Constants

dummyType

Reserved.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

vType

Specifies a vertical retrace queue type. See the Vertical Retrace Manager for more information.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

ioQType

Specifies a file I/O or driver I/O queue type.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

drvQType

Specifies a drive queue type.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

evType

Specifies an event queue type. See the Event Manager for more information.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

fsQType

Specifies a volume-control-block queue type.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

sIQType

Specifies a slot interrupt queue type. See the Slot Manager for more information.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

dtQType

Specifies a deferred task queue type. See Memory Management Utilities for more information.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

nmType

Specifies a notification queue type. See the Notification Manager for more information.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

Sorting Constants

Specify the result types for the function RelString.

enum {
   sortsBefore = -1,
   sortsEqual = 0,
   sortsAfter = 1
};

Constants

sortsBefore

Indicates the first string is less than the second string.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

sortsEqual

Indicates the first string is equivalent to the second string.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

sortsAfter

Indicates the first string is greater than the second string.

Available in OS X v10.0 and later.

Declared in OSUtils.h.

Assorted Use Constants

Defines constants to indicate use of various things, such as to use MIDE or AppleTalk.

enum {
   useFree = 0,
   useATalk = 1,
   useAsync = 2,
   useExtClk = 3,
   useMIDI = 4
};

Version Number

Specifies the version of the current system environment.

enum {
   curSysEnvVers = 2
};

Result Codes

The most common result codes returned by Memory Management Utilities are listed in the table below. Memory Management Utilities may also return the following errors:

• noErr (0)

• paramErr (-50)

• prWrErr (-87)

• prInitErr (-88)

• memROZErr (-99)

• memFullErr (-108)

• nilHandleErr (-109)

• memWZErr (-111)

• memPurErr (-112)

• memBCErr (-115)

• memLockedErr (-117)

• notEnoughMemoryErr (-620)

• notHeldErr (-621)

• cannotMakeContiguousErr (-622)

• notLockedErr (-623)

• interruptsMaskedErr (-624)

• cannotDeferErr (-625)