TweetFollow Us on Twitter

Universal Headers Gotcha
Volume Number:11
Issue Number:5
Column Tag:Compiler Settings

The Devil’s In The Details

Don’t get surprised by the Universal Headers

By Bill Karsh, billKarsh@aol.com

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

There is a particularly insidious problem in Apple’s Universal Headers. Whether you are affected at all, and how devastating it is, depends upon how you use their headers in your projects. Fortunately, the problem only affects 68K code generation. Here are the details, and what you can do as a work-around until new headers become available.

Which Header Versions?

The problem appears in the headers I got with Think C/C++ version 7, although these headers themselves do not seem to have a version number. The problem persists through the latest headers I got with MetroWerks CodeWarrior 5. These are version 2.0a3. Undoubtedly, you are using an affected version (I think they all are).

Structure Alignment Problem

The problem is a structure alignment conflict. Most compilers today let you apply some options regarding how structures are defined, throughout the whole of a project, or while certain pragmas are in effect. For example, you find a pop-up menu in CodeWarrior’s Processor Preferences panel, that let’s you select options called “68K,” “68K 4-byte,” or “PowerPC.” You can also use pragma statements like these:

#pragma options align=mac68k
#pragma options align=mac68k4byte
#pragma options align=native
#pragma options align=power
#pragma options align=reset

These can be used to override a globally set option. I believe that the last option stays in effect until either the next alignment statement, or the end-of-file is encountered.

In Symantec C++, the Compiler Settings page has a radio button group called “Struct Field Alignment,” that sets alignment options for a project.

Generally, the chosen alignment determines how much padding (extra space) is inserted into structures between fields, and how much padding is appended to the end of structures. Deciding which option you would want is a matter of trading-off between compactness of the data (less space) and higher performance (fields aligned on natural addresses for the field’s data-type). We won’t go into those decisions here. What is immediately essential is understanding two things.

First, these options are available to you (settable in an options page or by pragma statements) independently of whether you are generating PowerPC (ppc) code or 68K code.

Second, structures defined by the Mac OS, that is, defined in Apple’s headers, must have no extra padding in them. When the compiler comes across the definition of any Mac OS structure, like GrafPort, BitMap, or whatever, the current alignment option must be mac68k. If the current setting were anything else, your code, and the system software, would disagree on the offsets to various fields in a GrafPort, for example. That’s a disaster.

Inside Mac Headers

If you look inside virtually any Apple header, you will see one of the following examples near the top of the file:

#if defined(powerc) || defined (__powerc)
#pragma options align=mac68k
#endif

or

#if GENERATINGPOWERPC
#pragma options align=mac68k
#endif

Near the bottom you will see one of:

#if defined(powerc) || defined (__powerc)
#pragma options align=reset
#endif

or

#if GENERATINGPOWERPC
#pragma options align=reset
#endif

The intent here is to force the alignment type to mac68k while any Mac OS structures are defined. Then, align=reset puts the alignment back to whatever was in effect before. Can you see the problem? The pragma statements are made conditional upon what type of code is being generated, ppc or 68K. If you are generating ppc code only, there is no problem. If you are generating 68K code, the pragmas are not executed. You’ve got a bad problem in 68K code if, when the headers are compiled, the current alignment option is not mac68k. The pragma statements in the Apple headers were not supposed to be conditional upon anything. I’m guessing here, but it looks like a clear case of macro-mania-a-go-go.

Why Didn’t I See That?

I know, right now you are saying “how can any of my code work at all if this is true? Why didn’t I catch this immediately!?” There are several sneaky ways this problem might have escaped your notice thus far. For one thing, 68K compilers typically ship with mac68k as the default alignment option. If you never changed that, you would have been spared. Another possibility involves precompiled headers.

Your environment was shipped with precompiled headers. That is, many, but not all, of the Apple headers were precompiled at the factory into a giant header called MacHeaders68K (CW) or MacHeaders (Think), or something similar. Such a file is usually included in a global preferences dialog. That would be the Language panel in CW, or the Prefix page in Think’s dialog. There may be separate precompiled headers for C and C++. Again, chances are that you never removed it. Back at the factory, they compiled these precompiled files using the mac68k setting. Therefore, all the structures defined in there are fine. However, not all of the Apple headers are typically included in these things, only the most commonly used. This keeps symbol table sizes down, and speeds compile times.

Any time you find a need to explicitly include an Apple header in your sources, and it’s not among those precompiled at the factory, you are letting yourself in for it. You have to do something to make sure that when the compiler reads that included header, the alignment is mac68k. You have to take these steps yourself because the provision to do this automatically in the headers themselves is incorrectly coded.

What Do I Do?

If you understand what’s happening, you can choose whatever method you like to adjust for this; whatever works and is convenient. Let’s suppose you need Timer.h, and it’s not currently precompiled. Here are some possibilities:

Re-precompile MacHeaders68K, or whichever variant your project needs. Uncomment Timer.h in the source file that generates the precompiled header. Make sure the project’s global option is “68K” (CW) or “Align to 1 byte Boundary” (Think). Precompile a new MacHeaders, and include it in your working project’s preferences dialog.

Include Timer.h in a source file like this:

#pragma options align=mac68k
#include <Timer.h>
#pragma options align=reset

Repair the Apple header directly. Change this:

#if GENERATINGPOWERPC
#pragma options align=mac68k
#endif

to this:

#pragma options align=mac68k

Make the alignment options unconditional, as they were supposed to be. Do this for the reset lines too!

I know this will save you days of debugging and thousands of dollars of development costs. Could you send me just one dollar as a thank you? Worth a try.

 
AAPL
$97.23
Apple Inc.
-0.92
MSFT
$43.45
Microsoft Corpora
-0.13
GOOG
$583.21
Google Inc.
-4.21

MacTech Search:
Community Search:

Software Updates via MacUpdate

Knock 1.1.7 - Unlock your Mac by knockin...
Knock is a faster, safer way to sign in. You keep your iPhone with you all the time. Now you can use it as a password. You never have to open the app -- just knock on your phone twice, even when it's... Read more
Mellel 3.3.6 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Freeway Pro 7.0 - Drag-and-drop Web desi...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With it's user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more
Vitamin-R 2.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Toast Titanium 12.0 - The ultimate media...
Toast Titanium goes way beyond the very basic burning in the Mac OS and iLife software, and sets the standard for burning CDs, DVDs, and now Blu-ray discs on the Mac. Create superior sounding audio... Read more
OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more

Latest Forum Discussions

See All

Why Does It Spin? (Games)
Why Does It Spin? 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: THERE'S ONLY ONE RULE: DON'T TOUCH THE WALLS! Do you think you're able to follow this simple rule even if you would have to... | Read more »
Ice Wings Plus (Games)
Ice Wings Plus 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: THE GREAT ENDLESS RUNNER OF COMBAT JETS IS BACK !! With more than 680.000 downloads in the App Store, Ice Wings: Skies of Steel... | Read more »
Murl the Squirrel (Games)
Murl the Squirrel 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Meet Murl. He is teased by a group of flying squirrels because he can't fly. Determined to show them he's can fly, he meets... | Read more »
Celleste (Games)
Celleste 0.1 Device: iOS Universal Category: Games Price: $2.99, Version: 0.1 (iTunes) Description: Lots of cute action with amazing 3D graphics and a new type of gameplay! Take control over the forces of the universe to help a group... | Read more »
Super Heavy Sword (Games)
Super Heavy Sword 0.0.1 Device: iOS Universal Category: Games Price: $.99, Version: 0.0.1 (iTunes) Description: Get Ready to Get HEAVY! Monster Robot Studios presents SUPER Heavy Sword! The sequel to the smash hit HEAVY sword which... | Read more »
Angels In The Sky (Games)
Angels In The Sky 1.00 Device: iOS Universal Category: Games Price: $6.99, Version: 1.00 (iTunes) Description: - A.I.S will only run smoothly on iPhone 5s. It's NOT compatible with iPad, iPhone 5 or earlier devices.- In order to... | Read more »
80 Days (Games)
80 Days 1.0.2 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.2 (iTunes) Description: 1872, with a steampunk twist. Phileas Fogg has wagered he can circumnavigate the world in just eighty days. Choose your own route... | Read more »
Micromon (Games)
Micromon 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: 130+ Animated Monsters to Catch & Battle! No waiting, play at your own pace! Embark on an epic monster capture RPG like none... | Read more »
Empire Manager (Games)
Empire Manager 1.0 Device: iOS iPhone Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: Become ruler of an empire. Manage your economy, develop technology, hire an army and conquer the world in this addictive turn-... | Read more »
Empire Manager HD (Games)
Empire Manager HD 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Become ruler of an empire. Manage your economy, develop technology, hire an army and conquer the world in this addictive... | Read more »

Price Scanner via MacPrices.net

iPad Cannibalization Threat “Overblown”
Seeking Alpha’s Kevin Greenhalgh observes that while many commentators think Apple’s forthcoming 5.5-inch panel iPhone 6 will cannibalize iPad sales, in his estimation, these concerns are being... Read more
Primate Labs Releases July 2014 MacBook Pro P...
Primate Labs’ John Poole has posted Geekbench 3 results for most of the new MacBook Pro models that Apple released on Tuesday. Poole observes that overall performance improvements for the new MacBook... Read more
Apple Re-Releases Bugfixed MacBook Air EFI Fi...
Apple has posted a bugfixed version EFI Firmware Update 2.9 a for MacBook Air (Mid 2011) models. The update addresses an issue where systems may take longer to wake from sleep than expected, and... Read more
Save $50 on the 2.5GHz Mac mini, plus free sh...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $140 on an iPad Air with Apple ref...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
$250 price drop on leftover 15-inch Retina Ma...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2249, $250 off... Read more
More iPad Upgrade Musings – The ‘Book Mystiqu...
Much discussed recently, what with Apple reporting iPad sales shrinkage over two consecutive quarters, is that it had apparently been widely assumed that tablet users would follow a two-year hardware... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $999.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
Save up to $300 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
WaterField Unveils 15″ Outback Solo & 13″...
Hard on the heels of Apple’s refreshed MacBook Pro Retina laptops announcement, WaterField Designs has unveiled a 15-inch version of the waxed-canvas and leather Outback Solo and a 13-inch version of... Read more

Jobs Board

Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.