OS Utilities Interfaces. More...

#include <MacTypes.h>
#include <MixedMode.h>
#include <MacMemory.h>
#include <Patches.h>
#include <DateTimeUtils.h>
#include <CFString.h>
#include <Endian.h>

Go to the source code of this file.

Data Structures
struct	SysParmType

struct	QElem

struct	QHdr

struct	DeferredTask

struct	MachineLocation

struct	SysEnvRec

Macros
#define	NewDeferredTaskUPP(userRoutine)

#define	DisposeDeferredTaskUPP(userUPP) DisposeRoutineDescriptor(userUPP)

#define	InvokeDeferredTaskUPP(dtParam, userUPP) CALL_ONE_PARAMETER_UPP((userUPP), uppDeferredTaskProcInfo, (dtParam))

#define	NewDeferredTaskProc(userRoutine) NewDeferredTaskUPP(userRoutine)

#define	CallDeferredTaskProc(userRoutine, dtParam) InvokeDeferredTaskUPP(dtParam, userRoutine)

#define	GetMMUMode() ((SInt8)true32b)

#define	SwapMMUMode(x) ((SInt8 )(x) = true32b)

Typedefs
typedef SignedByte	QTypes

typedef struct SysParmType	SysParmType

typedef SysParmType *	SysPPtr

typedef struct QElem	QElem

typedef QElem *	QElemPtr

typedef struct QHdr	QHdr

typedef QHdr *	QHdrPtr

typedef struct DeferredTask	DeferredTask

typedef DeferredTask *	DeferredTaskPtr

typedef struct MachineLocation	MachineLocation

typedef struct SysEnvRec	SysEnvRec

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

enum	{ false32b = 0 , true32b = 1 }

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

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

enum	{ uppDeferredTaskProcInfo = 0x0000B802 }

enum	{ curSysEnvVers = 2 }

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 }

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

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

Functions
typedef	CALLBACK_API_REGISTER68K (void, DeferredTaskProcPtr,(long dtParam))

typedef	REGISTER_UPP_TYPE (DeferredTaskProcPtr) DeferredTaskUPP

DeferredTaskUPP	NewDeferredTaskUPP (DeferredTaskProcPtr userRoutine)

void	DisposeDeferredTaskUPP (DeferredTaskUPP userUPP)

void	InvokeDeferredTaskUPP (long dtParam, DeferredTaskUPP userUPP)

Boolean	IsMetric (void)

SysPPtr	GetSysPPtr (void)
	Get address of start of Parameter RAM data. More...

OSErr	DTInstall (DeferredTaskPtr dtTaskPtr)
	Add a task to the deferred task queue. More...

void	Delay (unsigned long numTicks, unsigned long *finalTicks)
	Pause execution for a specified interval. More...

OSErr	WriteParam (void)
	Write Parameter RAM data to non-volatile RAM. More...

void	Enqueue (QElemPtr qElement, QHdrPtr qHeader)
	Add an element to the end of a queue. More...

OSErr	Dequeue (QElemPtr qElement, QHdrPtr qHeader)
	Remove an element from a queue. More...

long	SetCurrentA5 (void)
	Get the current value of A5. More...

long	SetA5 (long newA5)
	Set the current value of A5. More...

OSErr	InitUtil (void)
	Copy Parameter RAM to low-memory variables. More...

void	MakeDataExecutable (void *baseAddress, unsigned long length)

OSErr	FlushCodeCacheRange (void *address, unsigned long count)

void	ReadLocation (MachineLocation *loc)
	Where is this Macintosh and what time is it? More...

void	WriteLocation (const MachineLocation *loc)
	Store machine's location and time zone data in RAM. More...

UInt32	TickCount (void)

CFStringRef	CSCopyUserName (Boolean useShortName)

CFStringRef	CSCopyMachineName (void)

OSErr	SysEnvirons (short versionRequested, SysEnvRec *theWorld)
	Get ROM version, machine type, system version, etc. More...

Detailed Description

OS Utilities Interfaces.

Introduced In: Mac OS 9

Avaliable From: Universal Interfaces 3.4.1

Copyright: © 1985-2001 by Apple Computer, Inc., all rights reserved

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

Macro Definition Documentation

◆ NewDeferredTaskUPP

#define NewDeferredTaskUPP ( userRoutine )

Value:

  (DeferredTaskUPP)                                                         \
      NewRoutineDescriptor((ProcPtr)(userRoutine), uppDeferredTaskProcInfo, \
                           GetCurrentArchitecture())

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

NOTE: SysEnvirons is obsolete. You should be using Gestalt.

Function Documentation

◆ CSCopyMachineName()

CFStringRef CSCopyMachineName ( void )

CSCopyMachineName()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.5 and later

Mac OS X: in version 10.0 and later

◆ CSCopyUserName()

CFStringRef CSCopyUserName ( Boolean useShortName )

CSCopyUserName()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.5 and later

Mac OS X: in version 10.0 and later

◆ Delay()

void Delay	(	unsigned long	numTicks,
		unsigned long *	finalTicks
	)

Pause execution for a specified interval.

Delay enables interrupts and keeps control until a specified interval in ticks
(1/60-th second units) has elapsed.
duration specifies the desired duration of the delay, in 1/60-th second
(16.6 ms) units. For instance, if duration = 60, the delay will
last approx. 1 second.
finalTicks is the address of a 32-bit long. Upon return, it will contain the
value of Ticks (the number of ticks since system startup) as it was
when Delay returned control.

Returns

none

Note

Because of the possibility of interrupts being disabled or overridden for
short periods, Delay may last one or more ticks longer than you requested
in duration.  Thus, you should not rely on pinpoint accuracy here.
The finalTicks  parameter can be used as an accuracy gauge to see if you did
lose a tick or two.
The global variable Ticks is updated upon every vertical retrace. See
VInstall for related information.
Ticks are generally referred to as 1/60th of a second. It is actually
1/60.15 seconds. However, if you need this kind of accuracy, you should not
be using functions like TickCount and Delay.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ Dequeue()

OSErr Dequeue	(	QElemPtr	qElement,
		QHdrPtr	qHeader
	)

Remove an element from a queue.

Dequeue removes an element from a queue, adjusting the queue links to
bypass the element. The element itself is not deallocated.
qEntryis the address of a variable-length QElem structure whose size and
contents depend upon the type of queue. This must be the same as a
qEntry value used in a previous call to Enqueue .
theQueue is the address of a 10-byte QHdr structure. This structure contains
information about the queue-some type-specific flags and pointers to
the first and last element in the queue.

Returns

an OSErr; an integer Error Code . It will be one of:
noErr(0) No error
qErr(-1) Entry not in specified queue

Note

Dequeue is used to remove any element from a queue. The caller is
responsible for deallocating the space used by the queue element (if that
memory needs to be freed).
The Dequeue routine turns off interrupts for critical sections of its code.
This makes it ideal for queue management for interrupt-driven programs
which need to be concerned about simultaneous execution and deadlock.
An example of queue usage is contained in Enqueue .

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ DisposeDeferredTaskUPP()

void DisposeDeferredTaskUPP ( DeferredTaskUPP userUPP )

DisposeDeferredTaskUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ DTInstall()

OSErr DTInstall ( DeferredTaskPtr dtTaskPtr )

Add a task to the deferred task queue.

NOTE: SysBeep() has been moved to Sound.h. We could not automatically #include Sound.h in this file because Sound.h indirectly #include's OSUtils.h which would make a circular include.

DTInstall adds a task identified by a pointer to the deferred task queue.
dtTaskPtr is a pointer leading to data to be enqueued.

Returns

an OSErr; an integer Error Code . It will be one of:
noErr(0) No error
vTypeErr (-2) Invalid queue element

Note

DTInstall adds a lengthy task to a deferred task queue so that it can be
executed when all interrupts at the current interrupt level have been
serviced. These tasks are executed with interrupts enabled, but are subject
to the same restrictions regarding moving memory and preserving
registers as interrupt routines. The QElemPtr referenced by the dtTaskPtr
points to a DeferredTask record, which itself contains a pointer to the
task you want to add to the queue.
Most of the long tasks for which this call is best suited are initiated by
add-in cards. You would generally need this call, therefore, only if your
program has to deal with these kinds of interrupts.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ Enqueue()

void Enqueue	(	QElemPtr	qElement,
		QHdrPtr	qHeader
	)

Add an element to the end of a queue.

Enqueue adds an element to the end of a linked list known as a queue. The
element itself (and not a copy) is hooked into the queue.
qEntryis the address of a variable-length QElem structure whose size and
contents depend upon the type of queue. This packet contains a place
for the queue linkage, the queue type, and the data of the queue
element itself.
theQueue is the address of a 10-byte QHdr structure. This structure contains
information about the queue - some type-specific flags and pointers
to the first and last element in the queue.

Returns

none

Note

The Macintosh Operating System uses queues to store and track such items
as keyboard and mouse events, vertical retrace tasks, file I/O requests, and
so forth.
Enqueue causes theQueue ->qTail and the previously-last queue element's
qlink field to be updated to point to qEntry. The effect is that if you trace the
queue links from start to finish, you will see all queue elements, including
the newly-added element.
The Enqueue routine turns off interrupts for critical sections of its code.
This makes it ideal for queue management for interrupt-driven programs
which need to be concerned about simultaneous execution and deadlock.
For system-defined queues such as the event queue and vertical retrace
task queue, qEntry must be one of the following predefined data types:
Struct Name constant value Description
VBLTask vType 1vertical retrace task queue
ParamBlockRec ioQType 2file I/O or driver I/O queue
DrvQEl drvQType 3drive queue
EvQElevType 4event queue
VCBfsQType 5volume control-block queue
For custom queues, the queue element structure must begin with 10 bytes
space for a "next element" pointer and a type code. Otherwise, the size and
contents of the queue element are user-defined.
The following example uses Enqueue and Dequeue to manage a list of
"bullets" in an arcade-style game.  It initializes a queue header, adds some
bullets to the queue, and repeatedly calls a routine that goes down the list,
updating the screen positions of the bullets. When a bullet goes off-screen,

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ FlushCodeCacheRange()

OSErr FlushCodeCacheRange	(	void *	address,
		unsigned long	count
	)

FlushCodeCacheRange()

Non-Carbon CFM: in InterfaceLib 8.5 and later

Carbon Lib: not available

Mac OS X: not available

◆ GetSysPPtr()

SysPPtr GetSysPPtr ( void )

Get address of start of Parameter RAM data.

GetSysPPtr returns the address at which the Parameter RAM has been
copied; i.e., a SysParmType structure such information as the default speaker
volume, printer port configuration, etc.

Returns

a SysPPtr; the address of a 20-byte SysParmType structure. This
always returns 0x01F8.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ InitUtil()

OSErr InitUtil ( void )

Copy Parameter RAM to low-memory variables.

InitUtil reads the non-volatile RAM (Parameter RAM) and copies it to the
data area starting at SysParam (at 0x01F8). It also stores the "raw" seconds
into the variable Time (at 0x020C).

Returns

an OSErr; an integer Error Code . It will be one of:
noErr(0) No error
prInitErr (-88) Validity status was not 0xA8

Note

This function is called at system startup and will normally not be used by
application programs.
See SysParmType for the layout of the area to which the Parameter RAM is
copied.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ InvokeDeferredTaskUPP()

void InvokeDeferredTaskUPP	(	long	dtParam,
		DeferredTaskUPP	userUPP
	)

InvokeDeferredTaskUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ IsMetric()

Boolean IsMetric ( void )

IsMetric()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ MakeDataExecutable()

void MakeDataExecutable	(	void *	baseAddress,
		unsigned long	length
	)

MakeDataExecutable()

Non-Carbon CFM: in InterfaceLib 7.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ NewDeferredTaskUPP()

DeferredTaskUPP NewDeferredTaskUPP ( DeferredTaskProcPtr userRoutine )

NewDeferredTaskUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ ReadLocation()

void ReadLocation ( MachineLocation * loc )

Where is this Macintosh and what time is it?

ReadLocation accesses the stored geographic location of the Macintosh and
the time zone information from the parameter RAM  For more information see,
Macintosh Worldwide Development: Guide to System Software.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ SetA5()

long SetA5 ( long newA5 )

Set the current value of A5.

Use the SetA5 function to set the A5 register to the application's A5.
Calling SetA5 performs two tasks: It sets the A5 register to the address
specified as newA5, and it returns the address that is in register A5 before the
SetA5 is called.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ SetCurrentA5()

long SetCurrentA5 ( void )

Get the current value of A5.

Use SetCurrentA5 to get the current value of the system global variable
CurrentA5 .
The SetCurrentA5 function does two things: First, it gets your application's
A5 and returns it to your application. Second, SetCurrentA5 sets register A5
to the value of the application's low-memory global variable CurrentA5 .

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ SysEnvirons()

OSErr SysEnvirons	(	short	versionRequested,
		SysEnvRec *	theWorld
	)

Get ROM version, machine type, system version, etc.

SysEnvirons is no longer a recommended way of obtaining information
about the environment in which your code will run. Gestalt is now available
as glue in development environments so that there is no need to call Environs
or SysEnvirons , regardless of what machine or operating system you are
running on.
SysEnvirons fills a structure with information about the computer and
system on which the caller is executing.
verReqNo identifies which version of the SysEnvRec you wish to obtain. Use
the constant curSysEnvVers (currently version 2) to obtain the
basic 18-byte version described in the SysEnvRec topic.
theSysEnv is the address of an 18-byte SysEnvRec structure. Upon return, it
contains all the system environment information. See SysEnvRec for
details of the return values.

Returns

an OSErr; an integer Error Code . It will be one of:
noErr(0) No error
envNotPresent (-5500) _SysEnvirons trap not present
envBadVers (-5501) negative number used in verReqNo
envVersTooBig (-5502) verReqNo version not handled by this system

Note

SysEnvirons obtains the ROM version number, such as the CPU type,
whether or not color Quickdraw is present, keyboard type, and so forth.
Macintosh Technote #129 warns that values may be added to the acceptable
set of values for any field of the SysEnvRec without warning. Therefore, if
you are calling SysEnvirons you should be prepared to handle unexpected
values.
The constant curSysEnvVers contains the current version of
SysEnvirons . By using this constant rather than a hard coded version
number you can reduce the changes that may need to be made to your source
as SysEnvirons evolves. However, you should be prepared to handle
unexpected values and not make assumptions about functionality based on
current expectations. It is much safer to test for specific functionality with
Gestalt than rely on the future contents of SysEnvirons .
In future systems, the SysEnvRec structure may get longer, so the
following mechanism can be used to get the most up-to-date version of this
record:
•Set verReqNo to a value greater than curSysEnvVers (the SysEnvRec
version number you suspect might not be available).
•Set theSysEnv to point to the larger structure (i.e., some future

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ TickCount()

UInt32 TickCount ( void )

TickCount()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ WriteLocation()

void WriteLocation ( const MachineLocation * loc )

Store machine's location and time zone data in RAM.

WriteLocation function stores the geographic location of the Macintosh and
the time zone information in parameter RAM For more information see,
Macintosh Worldwide Development: Guide to System Software.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ WriteParam()

OSErr WriteParam ( void )

Write Parameter RAM data to non-volatile RAM.

WriteParam copies the 20 bytes of data starting at SysParam into the
non-volatile clock-chip memory. This can be used after modifying one or
more system parameters (such as the default speaker volume) to make those
parameters "permanent".

Returns

an OSErr; an integer Error Code . It will be one of:
noErr(0) No error
prWrErr (-87) Couldn't verify the write

Note

You can use GetSysPPtr and the SysParmType structure to modify
system parameters in memory, then use WriteParam to make those
values "permanent".
It is possible to alter the contents of the Parameter RAM so much that the
Mac won't start next time you boot. In that case, you can reset the
Parameter RAM by pulling the battery for about 5 minutes.
To zap the PRAM, hold down the cmd, shift and option keys and select the
Control Panel from the Apple menu.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NewDeferredTaskUPP

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ CSCopyMachineName()

◆ CSCopyUserName()

◆ Delay()

◆ Dequeue()

◆ DisposeDeferredTaskUPP()

◆ DTInstall()

◆ Enqueue()

◆ FlushCodeCacheRange()

◆ GetSysPPtr()

◆ InitUtil()

◆ InvokeDeferredTaskUPP()

◆ IsMetric()

◆ MakeDataExecutable()

◆ NewDeferredTaskUPP()

◆ ReadLocation()

◆ SetA5()

◆ SetCurrentA5()

◆ SysEnvirons()

◆ TickCount()

◆ WriteLocation()

◆ WriteParam()