Deprecated Memory Management Utilities Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.1

WriteLocation

Changes the geographic location or time-zone information stored in extended parameter RAM. (Deprecated in OS X v10.1. There is no replacement because you cannot set this information in Mac OS X.)

void WriteLocation (
   const MachineLocation *loc
);
Parameters
loc

The geographic location and time-zone information to write to the extended parameter RAM.

Discussion

The latitude and longitude are stored in the geographic location structure as Fract values, giving accuracy to within 1 foot. For example, a Fract value of 1.0 equals 90 degrees –1.0 equals –90 degrees and –2.0 equals –180 degrees.

Use the functions Long2Fix and Fix2Fract to convert longitude and latitude values to the Fixed data type and then to the Fract data type for storage.

Use the daylight savings time value signed byte value to specify the offset for the hour field—whether to add one hour, subtract one hour, or make no change at all.

The Greenwich mean time value is in seconds east of GMT. For example, San Francisco is at –28,800 seconds (8 hours * 3,600 seconds per hour) east of GMT.The gmtDelta field is a 3-byte value contained in a long word. When writing gmtDelta, mask off the top byte because it is reserved. Preserve the value of dlsDelta.

The WriteLocation function was previously available with the Script Manager.

For more information on the geographic location record, see MachineLocation.

For more information on the Fract data type and the conversion routines Long2Fix, Fix2Fract, Fract2Fix, and Fix2Long, see Mathematical and Logical Utilities.

Special Considerations

Do not call the WriteLocation function at interrupt time.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.1.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

Deprecated in OS X v10.3

InitUtil

Copies the contents of parameter RAM into low memory. (Deprecated in OS X v10.3. There is no replacement because Mac OS X doesn’t require this initialization.)

OSErr InitUtil (
   void
);
Return Value

A result code. See “Memory Management Utilities Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.3.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

Deprecated in OS X v10.4

DTInstall

Adds the specified task record to the deferred-task queue. (Deprecated in OS X v10.4. You should restructure your application to use threads, such as those supplied by Multiprocessing Services.)

OSErr DTInstall (
   DeferredTaskPtr dtTaskPtr
);
Parameters
dtTaskPtr
Return Value

A result code. See “Memory Management Utilities Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Related Sample Code
Declared In
OSUtils.h

DTUninstall

(Deprecated in OS X v10.4. You should restructure your application to use threads, such as those supplied by Multiprocessing Services.)

OSErr DTUninstall (
   DeferredTaskPtr dtTaskPtr
);
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

GetSysPPtr

Returns a pointer to the low-memory copy of parameter RAM. (Deprecated in OS X v10.4. There is no replacement; this function always returns NULL in Mac OS X.)

SysPPtr GetSysPPtr (
   void
);
Return Value

See the description of the SysPPtr data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

SetA5

Sets the A5 register to the address specified. (Deprecated in OS X v10.4. There is no replacement because Mac OS X doesn’t use the A5 variable.)

long SetA5 (
   long newA5
);
Parameters
newA5

The value to which the A5 register is to be changed.

Return Value

The value in the A5 register before SetA5 changes it to newA5.

Discussion

In interrupt code that accesses application global variables, use the SetA5 function first to restore a value previously saved using SetCurrentA5, and then, at the end of the code, to restore the A5 register to the value it had before the first call to SetA5.

Carbon Porting Notes

68K-specific. Does nothing in PowerPC native code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

SetCurrentA5

Sets the value in register A5 to the value of the low-memory global variable CurrentA5. (Deprecated in OS X v10.4. There is no replacement because Mac OS X doesn’t use the A5 variable.)

long SetCurrentA5 (
   void
);
Return Value

The value in the A5 register before SetCurrentA5 changes it to the value of the low-memory global variable CurrentA5.

Discussion

The CurrentA5 variable points to the boundary between the parameters and global variables of the current application.

You cannot reliably call SetCurrentA5 in code that executes at interrupt time unless you first guarantee that your application is the current process (for example, by calling the Process Manager function GetCurrentProcess). In general, you should call SetCurrentA5 at noninterrupt time and then pass the returned value to the interrupt code.

Carbon Porting Notes

68K-specific. Does nothing in PowerPC native code.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

WriteParam

Write the modified values in the system parameters data structure to parameter RAM. (Deprecated in OS X v10.4. There is no replacement, because this function does nothing in Mac OS X.)

OSErr WriteParam (
   void
);
Return Value

A result code. See “Memory Management Utilities Result Codes.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
  • Not available to 64-bit applications.
Declared In
OSUtils.h

Deprecated in OS X v10.7

IsMetric

Verifies whether the current script system is using the metric system or the English system of measurement. (Deprecated in OS X v10.7.)

Boolean IsMetric (
   void
);
Return Value

TRUE if the metric system is being used; FALSE if the English system is being used.

Discussion

The IsMetric function examines the metricSys field of the numeric-format resource (resource type 'itl0') to determine if the current script is using the metric system. A value of 255 in the metricSys field indicates that the metric system (centimeters, kilometers, milligrams, degrees Celsius, and so on) is being used. A value of 0 in the metricSys field indicates that the English system of measurement (inches, miles, ounces, degrees Fahrenheit, and so on) is used.

If you want to use units of measurement different from that of the current script, you need to override the value of the metricSys field in the current numeric-format resource. You can do this by using your own version of the numeric-format resource instead of the current script system’s default international resource.

The IsMetric function is the same as the IUMetric function, which was previously available with the International Utilities Package.

Special Considerations

The IsMetric function may move or purge blocks in the heap calling it may cause problems if you’ve dereferenced a handle. Do not call this function from within interrupt code, such as in a completion function or a VBL task.

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

Deprecated in OS X v10.8

CSCopyMachineName

Returns a reference to the CFString that represents the computer name. (Deprecated in OS X v10.8.)

CFStringRef CSCopyMachineName (
   void
);
Return Value

A CFStringRef. See the Base Services documentation for a description of the CFStringRef data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
OSUtils.h

CSCopyUserName

Returns a reference to the CFString that represents the user name. (Deprecated in OS X v10.8.)

CFStringRef CSCopyUserName (
   Boolean useShortName
);
Parameters
useShortName

A Boolean value that specifies whether to return the short name or full name of the user.

Return Value

A CFStringRef. See the Base Services documentation for a description of the CFStringRef data type.

Discussion

The function CSCopyUserName returns a CFStringRef based on the read UID (RUID, as returned by getuid) of the calling process. This can result in unexpected behavior (that is, CSCopyUserName returning different results than SCDynamicStoreCopyConsoleUser) for processes that manipulate their UID.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
OSUtils.h

Delay

Delays execture for the specified amount of time. (Deprecated in OS X v10.8.)

void Delay (
   unsigned long numTicks,
   unsigned long *finalTicks
);
Parameters
numTicks
finalTicks
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
OSUtils.h

Dequeue

Removes a queue element directly from an operating-system queue or from a queue that you have created. (Deprecated in OS X v10.8.)

OSErr Dequeue (
   QElemPtr qElement,
   QHdrPtr qHeader
);
Parameters
qElement

A pointer to a queue element to remove from a queue.

qHeader

A pointer to a queue header.

Return Value

A result code. See “Memory Management Utilities Result Codes.”

Discussion

The Dequeue function attempts to find the queue element specified by the qElement parameter in the queue specified by the qHeader parameter. If Dequeue finds the element, it removes the element from the queue, adjusts the other elements in the queue accordingly, and returns noErr. Otherwise, it returns qErr, indicating that it could not find the element in the queue. The Dequeue function does not deallocate the memory occupied by the queue element.

For a description of the QElem record, see QElem; for a description of the QHdr record, see QHdr.

The Dequeue function disables interrupts as it searches through the queue for the element to be removed. The time during which interrupts are disabled depends on the length of the queue and the position of the entry in the queue. The Dequeue function can be called at interrupt time. However, the Dequeue function is ordinarily used only by system software and, whenever possible, you should manipulate an operating-system queue indirectly, by calling special-purpose removal functions. You can use the Queue Utilities functions for directly manipulating queues that you create. Use the following functions instead of Dequeue:

  • SlotVRemove

    Removes a slot-based VBL task. This function is available with the Vertical Retrace Manager.

  • VRemove

    Removes a system-based VBL task. This function is available with the Vertical Retrace Manager.

  • WaitNextEvent

    Removes an Event. This function is available with the Event manager.

  • SIntRemove

    Removes a slot interrupt task. This function is available with the Slot Manager.

  • NMRemove

    Removes a Notification request. This function is available with the Notification Manager.

  • SleepQRemove

    Removes a Sleep task. This function is available with the Power Manager.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
OSUtils.h

DisposeDeferredTaskUPP

Disposes of a universal procedure pointer (UPP) to a deferred-task callback. (Deprecated in OS X v10.8.)

void DisposeDeferredTaskUPP (
   DeferredTaskUPP userUPP
);
Parameters
userUPP

The universal procedure pointer.

Discussion

See the callback DeferredTaskProcPtr for more information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
OSUtils.h

Enqueue

Adds elements directly to an operating-system queue or a queue that you create. (Deprecated in OS X v10.8.)

void Enqueue (
   QElemPtr qElement,
   QHdrPtr qHeader
);
Parameters
qElement

A pointer to the queue element to add to a queue.

qHeader

A pointer to a queue header.

Discussion

The Enqueue function adds the queue element specified by the qElement parameter to the end of the queue specified by the qHeader parameter. The specified queue header is updated to reflect the new queue element.

For a description of the QElem record, see QElem; for a description of the QHdr record, see QHdr.

Because interrupt functions are likely to manipulate operating-system queues, interrupts are disabled for a short time while the specified queue is updated. You can call the Enqueue function at interrupt time. However, the Enqueue function is ordinarily used only by system software. Whenever possible, you should manipulate an operating-system queue indirectly, by calling special-purpose functions whenever possible, instead of the Enqueue function. You can use the Queue Utilities functions for directly manipulating queues that you create. Use the following functions instead of Enqueue:

  • SlotVInstall

    Installs a slot-based VBL task. This function is available with the Vertical Retrace Manager.

  • VInstall

    Installs a system-based VBL task. This function is available with the Vertical Retrace Manager.

  • AddDrive

    Adds a disk drive. This function is available with the Device Manager.

  • PPostEvent and PostEvent

    Installs an Event. This function is available with the Event manager.

  • DTInstall

    Installs a deferred task. This function is available with the Memory Management Utilities.

  • SIntInstall

    Installs a slot interrupt task. This function is available with the Slot Manager.

  • NMInstall

    Installs a Notification request. This function is available with the Notification Manager.

  • SleepQInstall

    Installs a Sleep task. This function is available with the Power Manager.

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

InvokeDeferredTaskUPP

Calls a deferred-task callback. (Deprecated in OS X v10.8.)

void InvokeDeferredTaskUPP (
   long dtParam,
   DeferredTaskUPP userUPP
);
Discussion

You should not need to use the function InvokeDeferredTaskUPP, as the system calls your deferred-task callback for you. See the callback DeferredTaskProcPtr for more information.

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

MakeDataExecutable

Notifies the system that the specified data is subject to execution. (Deprecated in OS X v10.8.)

void MakeDataExecutable (
   void *baseAddress,
   unsigned long length
);
Parameters
baseAddress

The starting address of the data to be flushed.

length

The length of the data pointed to by the baseAddress parameter.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
  • Not available to 64-bit applications.
Related Sample Code
Declared In
OSUtils.h

NewDeferredTaskUPP

Creates a new universal procedure pointer (UPP) to a deferred-task callback. (Deprecated in OS X v10.8.)

DeferredTaskUPP NewDeferredTaskUPP (
   DeferredTaskProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your deferred-task callback.

Return Value

On return, a UPP to a deferred-task callback. See the description of the DeferredTaskUPP data type.

Discussion

See the callback DeferredTaskProcPtr for more information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
OSUtils.h

ReadLocation

Obtains information about a geographic location or time zone. (Deprecated in OS X v10.8.)

void ReadLocation (
   MachineLocation *loc
);
Parameters
loc

On return, the fields of the geographic location structure containing the geographic location and the time-zone information.The ReadLocation procedure reads the stored geographic location and time zone of the Macintosh computer from extended parameter RAM.

You can get values for the latitude, longitude, daylight savings time (DST), or Greenwich mean time (GMT). If the geographic location record has never been set, all fields contain 0.

Discussion

The latitude and longitude are stored as Fract values, giving accuracy to within one foot. For example, a Fract value of 1.0 equals 90 degrees –1.0 equals –90 degrees and –2.0 equals –180 degrees.

To convert these values to a degrees format, you need to convert the Fract values first to the Fixed data type, then to the LongInt data type. Use the Mathematical and Logical Utilities functions Fract2Fix and Fix2Long to accomplish this task.

The DST value is a signed byte value that specifies the offset for the hour field—whether to add one hour, subtract one hour, or make no change at all.

The GMT value is in seconds east of GMT. For example, San Francisco is at –28,800 seconds (8 hours * 3,600 seconds per hour) east of GMT. The gmtDelta field is a 3-byte value contained in a long word, so you must take care to get it properly.

The ReadLocation function was previously available with the Script Manager.

For more information on the geographic location record, see MachineLocation.

For more information on the Fract data type and the conversion routines Long2Fix, Fix2Fract, Fract2Fix, and Fix2Long, see Mathematical and Logical Utilities.

Special Considerations

Do not call the ReadLocation function at interrupt time.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
OSUtils.h

TickCount

Obtains the current number of ticks (a tick is approximately 1/60 of a second) since the system last started up. (Deprecated in OS X v10.8.)

UInt32 TickCount (
   void
);
Discussion

The TickCount function returns an unsigned 32-bit integer that indicates the current number of ticks since the system last started up. You can use this value to compare the number of ticks that have elapsed since a given event or other action occurred. For example, you could compare the current value returned by TickCount with the value of the when field of an event structure.

The tick count is incremented during the vertical retrace interrupt, but this interrupt can be disabled. Your application should not rely on the tick count to increment with absolute precision. Your application also should not assume that the tick count always increments by 1 an interrupt task might keep control for more than one tick. If your application keeps track of the previous tick count and then compares this value with the current tick count, your application should compare the two values by checking for a “greater than or equal” condition rather than “equal to previous tick count plus 1.”

Do not rely on the tick count being exact; it is usually accurate to within one tick, but this level of accuracy is not guaranteed.

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