Memory Management Utilities Reference (Legacy)

Framework
CoreServices/CoreServices.h
Declared in
OSUtils.h

Overview

Applications can use the Memory Management Utilities to

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

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

Functions by Task

Determining the Measurement System

Reading and Writing Location Data

Setting and Restoring the A5 Register

Getting the User and Computer Name

Managing a Queue

Working With Parameter RAM

Miscellaneous

Working With Universal Procedure Pointers

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

Parameters
dtParam
Availability
  • Available in OS X v10.0 and later.
Declared In
OSUtils.h

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

DeferredTaskUPP

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

typedef DeferredTaskProcPtr DeferredTaskUPP;
Discussion

For more information, see the description of the DeferredTaskProcPtr callback function.

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

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.

Discussion

The geographic location and time-zone information of a Macintosh computer are stored in extended parameter RAM. The MachineLocation data type defines the format for the geographic location record.

The ReadLocation and WriteLocation procedures use the geographic location record to read and store the geographic location and time zone information in extended parameter RAM. If the geographic location record has never been set, all fields contain 0.

In order for MachineLocation to be endian-safe, a new member has been added to the 'u' union in the structure. You are encouraged to use the new member instead of the old one.

If your code looked like this:

MachineLocation.u.dlsDelta = 1;

you should change it to this:

MachineLocation.u.dls.Delta = 1;

to be endian safe. The gmtDelta remains the same; the low 24-bits are used. Remember that order of assignment DOES matter.

This will overwrite results:

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

when in fact reversing the assignment would have preserved the values:

MachineLocation.u.gmtDelta = 0xBBBBBB;      // u = 0x00BBBBB;
MachineLocation.u.dls.Delta = 0xAA;         // u = 0xAABBBBBB;
Availability
  • Available in OS X v10.0 and later.
Declared In
OSUtils.h

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
Discussion

A queue element is a single entry in a queue. Each operating-system queue created and maintained by the Macintosh Operating System consists of a queue header and a linked list of queue elements. The exact structure of an element in an operating-system queue depends on the type of the queue. The QElem data type defines the available queue elements.

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

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.

Discussion

The event queue consists of a header followed by the actual entries in the queue. The event queue has the same header as all standard Macintosh Operating System queues. The Qhdr structure defines the queue header.

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

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.

Discussion

The SysEnvirons function fills in a system environment record, which describes some aspects of the software and hardware environment.

Availability
  • Available in OS X v10.0 through OS X v10.3.
Declared In
OSUtils.h

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;
Availability
  • Available in OS X v10.0 through OS X v10.3.
Declared In
OSUtils.h

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.

Discussion

The different queue types that are accessible to your application are defined by the QTypes data type. Each of these enumerated queue types determines a different type of queue element. These constants are used in the qtype field of the QElem structure.

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:

Result CodeValueDescription
qErr -1

Queue element not found during deletion.

Available in OS X v10.0 and later.

vTypErr -2

Invalid queue element.

Available in OS X v10.0 and later.

corErr -3

Core routine number out of range

Available in OS X v10.0 and later.

unimpErr -4

Unimplemented core routine.

Available in OS X v10.0 and later.

SlpTypeErr -5

Invalid queue element.

Available in OS X v10.0 and later.

hwParamErr -502

Processor does not support flushing a range.

Available in OS X v10.0 and later.