Introduction to Carbon Porting Guide

The Carbon Porting Guide is intended to help experienced Macintosh developers convert existing Mac OS applications into Carbon applications that can run on Mac OS X as well as Mac OS 8 and 9. It contains detailed information about how to adapt and build your application using the Carbon API as well as step-by-step examples of the porting process.

To make the Carbon transition as smooth as possible, you should also be familiar with the following documents before beginning your port:

This chapter introduces Carbon and provides an overview of the changes you’ll need to be aware of as you convert your application.

What Is Carbon?

Carbon is the set of programming interfaces derived from earlier Mac OS APIs that can run on Mac OS X. Some of these APIs have been modified or extended to take advantage of Mac OS X features such as preemptive multitasking and protected memory.

In addition to being able to run on Mac OS X, Carbon applications built for Mac OS X can also run on Mac OS 8 and 9 when the CarbonLib system extension is installed. (As always, you should test for the existence of specific features before using them.)

Carbon includes about 70 percent of the existing Mac OS APIs, covering about 95 percent of the functions used by applications. Because it includes most of the functions you rely on today, converting to Carbon is a straightforward process. Apple provides tools and documentation to help you determine the changes you will need to make in your source code, as well as the header files and libraries necessary to build a Carbon application.

Mac OS X brings important new features and enhancements that developers have asked for, and Carbon allows you to take advantage of them while preserving your investment in Mac OS source code. As Apple moves the Mac OS forward, Carbon ensures you won’t be left behind.

What Are the Benefits of Carbon?

Carbon applications gain these benefits when running under Mac OS X:

What Is in Carbon Today?

The Carbon programming interface consists of the following types of APIs:

Currently, the Classic Mac OS APIs make up the largest proportion of Carbon APIs, as shown in Figure I-1. However, as Carbon evolves to take advantage of new features in Mac OS X, new Mac OS X-specific APIs will be added that enhance its capabilities.

Figure I-1  Current and future composition of the Carbon API
Current and future composition of the Carbon API

What’s Not in Carbon?

If Carbon does not support a Classic Mac OS function, it is generally for one of the following reasons:

In addition, certain Classic Mac OS programming practices are no longer allowed:

How Does Carbon Work?

Carbon lets you create one executable file that can run on both Mac OS X and Mac OS 8 and 9. You accomplish this by linking your application with a single stub library, CarbonLibStub, at build time. At runtime your application links with the appropriate Carbon implementation stored as shared libraries (sometimes referred to as DLLs).

On Mac OS X, your application links dynamically to the Carbon framework, which is a hierarchy of libraries and resources that contains the implementation of Carbon.

On Mac OS 8 and 9, the Carbon implementation is stored as a system extension named CarbonLib. This library contains two types of elements:

Figure I-2 shows Carbon functions called on Mac OS X and Mac OS 8 and 9.

Figure I-2  Calling Carbon functions on Mac OS X and Mac OS 8 and 9
Calling Carbon functions on Mac OS X and Mac OS 8 and 9

In general, for a pure Carbon application, the only library you should link against is CarbonLib. See Linking to Non-Carbon-Compliant Code for special cases where you may need to link to other libraries.

Carbon and the Mac OS Application Model

The Mac OS application model remains fundamentally unchanged in Carbon. Carbon applications employ system services in essentially the same manner for both Mac OS 8 and 9 and Mac OS X. But because Mac OS 8 and 9 and Mac OS X are built on different architectures, there will be slight differences in the way your application uses some system services. This section highlights the most important changes you need to be aware of. Preparing Your Code for Carbon provides more detailed information on each of these subjects.

Preemptive Scheduling and Application Threading

In Mac OS X, each Carbon application is scheduled preemptively against other Carbon applications. For calls to most low-level operating system services, Mac OS X also supports preemptive threading within an application. Because most Human Interface Toolbox functions are not reentrant, however, a multithreaded application will initially be able to call these functions only from cooperatively scheduled threads. Thread-based preemptive access to all system services—including the Human Interface Toolbox—is an important future direction for the Mac OS.

In both Mac OS 8 and 9 and Mac OS X, you can use the Multiprocessing Services API to create preemptively scheduled tasks.

Separate Application Address Spaces

In Mac OS X, each Carbon application runs in its own protected address space. An application can’t reference memory locations—or corrupt another application’s data—outside of its assigned address space. This separation of address spaces increases the reliability of the user’s system, but it may require small programming changes to applications that use zones, system memory, or temporary memory. For example, temporary memory allocations in Mac OS X will be allocated in the application’s address space, and Apple will define new functions for sharing memory between applications. Manage Memory Efficiently provides more detailed information about memory management for Carbon applications.

Virtual Memory

Mac OS X uses a dynamic and highly efficient virtual memory system that is always enabled. Your Carbon application must therefore assume that virtual memory is turned on at all times. In addition, the Mac OS X virtual memory system introduces a number of changes to the addressing model that are discussed in Manage Memory Efficiently.


Mac OS X supports traditional Resource Manager resources, but you should consider moving resources to the data fork of your application and accessing them using Core Foundation CFBundle APIs instead. Doing so will ensure that this information will not be lost if your application is copied by a method that does not recognize resource forks. See Move Resources to Data Fork–Based Files and Consider Using Bundles for more information.

Note that you can no longer store executable code in resources. See Move Custom Definition Procedures Out of Resources for more information.

Code Fragments and the Code Fragment Manager

Carbon fully supports the Code Fragment Manager, and the Mac OS X runtime environment supports code compiled into code fragments. For Mac OS X, however, all code fragments must contain only native PowerPC code. In addition, resource-based fragments are no longer allowed.

Mixed Mode Manager

While the Mixed Mode Manager is no longer needed to handle calls between PowerPC and 68K code, there may be instances where it must handle calls between CFM-based code and Mach-O code (the native executable format on Mac OS X). In any case, you must replace the macros for creating and disposing routine descriptors with new Carbon functions for creating, invoking, and disposing universal procedure pointers (UPPs). See Replace Macro Calls to the Mixed Mode Manager With UPP Accessor Functions for more information.


Carbon introduces a new Printing Manager that allows applications to print on Mac OS 9 using current printer drivers and on Mac OS X using new printer drivers. The functions and data types defined by the Carbon Printing Manager are contained in the header files PMApplication.h, PMCore.h, and PMDefinitions.h. Documentation for the Carbon Printing Manager is provided with the Mac OS X Developer Tools CD and at the following website:

Control Panels

Carbon does not support control panels. If possible, you should package your control panel as an application.

The Trap Table

The trap table is a 68K-specific mechanism for dispatching calls to Mac OS Toolbox functions. Because Mac OS X does not support 68K code, the Trap Manager is unavailable in Carbon, and your application should not dispatch calls through the trap table. Likewise, the Patch Manager is unsupported in Carbon, and your application should not attempt to patch the trap table or any operating system entry points. If your application relies on patches, please tell us why, so that we can help you remove this dependency.

Standard and Custom Definition Procedures

Carbon supports the standard Mac OS definition procedures (also known as defprocs) for such human interface elements as windows, menus, and controls. Custom definition procedures are also supported (as long as they are compiled as PowerPC code), but there are new procedures for creating and packaging them. These new functions are discussed in Move Custom Definition Procedures Out of Resources and Custom Definition Procedures.

Application-Defined Functions

Carbon supports most Mac OS application-defined (callback) functions. Mac OS X fully supports callback functions within an application’s address space. In Carbon, callback functions use native PowerPC conventions instead of 68K conventions, but Carbon doesn’t change these function definitions. As usual you should pass universal procedure pointers when specifying your callback functions.

Data Structure Access

So that future versions of Mac OS can support access to all system services through preemptive threads, Carbon limits direct application access to some Mac OS data structures. Carbon allows three levels of data structure access, depending on which is appropriate for a given structure:

  • Direct access—your application can read from and write to the data structure without restriction.

  • Direct access with notification—your application can read from and write to the data structure, but after modifying the structure your application must call a function to notify the operating system that the structure has been changed.

  • Indirect access—your application has no direct access to the data structure. Instead, your application can obtain and set values in the structure only by using accessor functions. Structures of this type are said to be “opaque” because their contents are not visible to applications.

Opaque data structures and the functions for using them are discussed in Functions for Accessing Opaque Data Structures.

Additional Information and Feedback

Apple is working hard to deliver the features and performance you expect from Carbon. You can keep abreast of current developments by visiting the Carbon website at

where you’ll find the complete Carbon Specification, preliminary documentation, and links to other useful information.

If you have comments or suggestions about Carbon, please send them to