Read Me About BootstrapDump

===========================

1.2

BootstrapDump is a small program that does two useful things:

o It will print the Mach bootstrap namespace for a specified process.  This is helpful when debugging programs that register with the bootstrap server, or that cross bootstrap contexts.

    Note: This feature is redundant on Mac OS X 10.5 and later, 

    where you can just use <x-man-page://1/launchctl>'s "bslist" 

    command.

o It will print a map of the hierarchy of Mach bootstrap namespaces on the system and shows which processes are in which namespaces.  This is useful when you want to understand the overall bootstrap namespace hierarchy.

For more information about Mach bootstrap namespaces, see DTS Technote 2083 "Daemons and Agents".

<http://developer.apple.com/technotes/tn2005/tn2083.html>

IMPORTANT: BootstrapDump is intended as a testing and debugging tool.  If you look at the code and find yourself thinking "perhaps I should copy this code into my project which I intend to deploy to thousands of users", please think again.  This program does stuff that is right on the edge of supportability: it might make sense to copy the code and use it in an internal debugging facility, but you should not ship the code to end users.  If you think you need to do that, please drop us a line at <dts@apple.com> and we'll try to suggest a better approach.

BootstrapDump was built and tested on Mac OS X 10.4.x and Mac OS X 10.5.x.  The sample, as it stands, will not work on systems prior to 10.3.9 because of build system requirements.  However, the theoretic limits are as follows:

o The bootstrap dump facility should work on Mac OS X 10.2 and later; pre-10.2 systems have a bug that prevents this from working.

o The bootstrap mapping facility requires Mac OS X 10.3 because it depends on a routine, bootstrap_parent, that was first implemented in that system.

Packing List

------------

The sample contains the following items:

o Read Me About BootstrapDump.txt -- This file.

o BootstrapDump.c -- C source code for the program.

o BootstrapDump.xcodeproj -- An Xcode 2.4.1 project for the program.

o build -- A folder containing a pre-built binary.

Using the Sample

----------------

To try out the sample for yourself, open a Terminal window, change into the "BootstrapDump" directory and run the command.

$ sudo build/Debug/BootstrapDump 

Bootstrap dump for 'self' (11388):

  "com.apple.KernelExtensionServer"

  "com.apple.AirPort.wps" by "/usr/libexec/wps" on demand

[...]

This prints the contents of the program's bootstrap namespace.

IMPORTANT: This may or may not require root privileges, depending on your CPU type and OS version.  In these examples I keep things simple by always using root privileges (via <x-man-page://8/sudo>).

You can also supply an argument that is the process name (or ID) of the process whose bootstrap port namespace you wish to dump.

$ sudo build/Debug/BootstrapDump Finder

Bootstrap dump for 'Finder' (318):

  "com.apple.KernelExtensionServer"

  "com.apple.AirPort.wps" by "/usr/libexec/wps" on demand

[...]

Finally, you can use the "MAP" argument to print the bootstrap namespace hierarchy:

$ sudo build/Debug/BootstrapDump MAP

0x113

  launchd (root, 1/0)

  dynamic_pager (root, 27/1)

  kextd (root, 31/1)

[...]

  sh (root, 9953/1)

  ssh (root, 9956/9953)

  0x1a03

    mdimport (quinn, 11060/1)

  0x1903

    CCacheServer (quinn, 4525/1)

  0x1803

    cupsd (root, 593/1)

  0x1703

    WindowServer (root, 299/1)

  0xf0b

    loginwindow (root, 297/1)

    pbs (quinn, 310/297)

    Dock (quinn, 316/299)

[...]

In this example, taken from Mac OS X 10.4.9, you can see launchd at the root of the hierarchy with loginwindow as its child.  For each bootstrap namespace, it prints the list of processes in that namespace (with the user name, process ID and parent process ID in parentheses).

Building the Sample

-------------------

The sample was built using Xcode 2.4.1 on Mac OS X 10.4.10.  You should be able to just open the project and choose Build from the Build menu.  This will build the BootstrapDump tool in the "build" directory.

How it Works

------------

To understand how the code works, look at the extensive comments in the code.

Credits and Version History

---------------------------

If you find any problems with this sample, mail <dts@apple.com> and I'll try to fix them up.

1.0b1 (Jan 2003) was sent out for internal review at Apple.

1.0b2 (Jan 2003) was the first shipping version.  We now dispose of Mach resources that we allocate, rather than relying on process termination to do so.  This change isn't necessary for this tool; it was made to prevent problems if someone decides to cut'n'paste the code into a larger program.

1.1 (Oct 2007) is a major update to add the hierarchy mapping feature.  Along the way I did a general tidy and made the final result a universal binary and tested on Mac OS X 10.5.

1.2 (Jun 2008) fixed a benign bug that was tripping an assert.

Share and Enjoy.

Apple Developer Technical Support

Core OS/Hardware

17 Jun 2008