If you try to use your freshly built gdb, you will get an error message such as:

Starting program: /x/y/foo
Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5).
 (please check gdb is codesigned - see taskgated(8))

This is because the Darwin kernel will refuse to allow gdb to debug another process if you don't have special rights, since debugging a process means having full control over that process, and that isn't allowed by default since it would be exploitable by malware. (The kernel won't refuse if you are root, but of course you don't want to be root to debug.)

1. Method for Mac OS X 10.5 (Leopard) and later

The most up to date and secure method to allow gdb to control another process is to sign it with any system-trusted code signing authority.



Create a certificate in the System Keychain

security find-certificate -c gdb-codesign |grep System.keychain
security find-certificate -p -c gdb-cert | openssl x509 -checkend 0

Trust the certificate for code signing

security dump-trust-settings -d

Sign and entitle gdb using the certificate

codesign -vv $(which gdb)
codesign -d --entitlements - $(which gdb)|grep -a com.apple.security.cs.debugger (10.14 and later)

Refresh the system's certificates and code-signing data

None known (besides checking that your gdb now works)

Try gdb again

Still no luck? See Troubleshooting

1.1. Create a certificate in the System Keychain

Start Keychain Access application (/Applications/Utilities/Keychain Access.app)

Open the menu item /Keychain Access/Certificate Assistant/Create a Certificate...

Choose a name (gdb-cert in the example), set Identity Type to Self Signed Root, set Certificate Type to Code Signing and select the Let me override defaults. Click several times on Continue until you get to the Specify a Location For The Certificate screen, then set Keychain to System.

💡 If you cannot store the certificate in the System keychain: create it in the login keychain instead, then export it. You can then import it into the System keychain.

Finally, quit the Keychain Access application to refresh the certificate store.

Control: in the terminal type

security find-certificate -c gdb-cert

This should display some details about your newly minted certificate, e.g.

keychain: "/Library/Keychains/System.keychain"
version: 256
class: 0x80001000 

Make sure that keychain: is the System keychain, as shown.

Also, make sure that your certificate is not expired yet:

security find-certificate -p -c gdb-cert | openssl x509 -checkend 0

💡If you want to inspect the entire X509 data structure, you can type

security find-certificate -p -c gdb-cert |openssl x509 -noout -text

1.2. Trust the certificate for code signing

Start Keychain Access again. Using the contextual menu for the certificate, select Get Info, open the Trust item, and set Code Signing to Always Trust.

Finally, quit the Keychain Access application once more to refresh the certificate store.

Control: in the terminal type

security dump-trust-settings -d

This should show the gdb-cert certificate (perhaps among others) and its trust settings, including Code Signing.

1.3. Sign and entitle the gdb binary

  1. (Mac OS X 10.14 and later) Create a gdb-entitlement.xml file containing the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
  2. If the certificate you generated in the previous section is known as gdb-cert, use:

    codesign --entitlements gdb-entitlement.xml -fs gdb-cert $(which gdb)

    or before Mojave (10.14), just

    codesign -fs gdb-cert $(which gdb)

💡 You may have to prepend this command with sudo if the gdb binary is located in a place that is not writable by regular users.

If you plan to build gdb frequently, this step can be automated by passing --enable-codesign=gdb-cert (assuming, again, that gdb-cert is the name of the certificate) to configure.

Control: in the terminal type

codesign -vv $(which gdb)

And for 10.14 (Mojave) onwards, also check the entitlements:

codesign -d --entitlements - $(which gdb)

1.4. Refresh the system's certificates and code-signing data

The most reliable way is to reboot your system.

A less invasive way is to and restart taskgated service by killing the current running taskgated process (at any time in the process, but no later than before trying to run gdb again):

sudo killall taskgated

However, sometimes the taskgated service will not restart successfully after killing it, so ensure that it is alive after this step by checking e.g. ps $(pgrep -f taskgated). Or just reboot your system, as mentioned above.

2. Troubleshooting / further diagnosis

If you used the code-signing method and you still get the (os/kern) failure (0x5) error, one of the following items may pinpoint you to the cause.

$ chmod 755 gdb
$ chgrp admin gdb

(possibly prepended with sudo if the gdb binary is located in a place that cannot be modified by regular users or if you do not belong to the admin group, and replacing gdb with the full path to the gdb binary)

2.1. Watch Logs

On Mojave (version 10.14) and later, the following command will stream the log messages pertaining to taskgated and code-signing issues:

log stream --predicate 'process = "taskgated" OR (process = "kernel" AND eventMessage CONTAINS "macOSTaskPolicy")' --info

3. Old method

Warning: do not combine (part of) these instructions with the code signing method, because they interfere with each other. See the troubleshooting section in case you (possibly) did mix them to fix up any potential issues. In general, following the instructions in this section is strongly discouraged if you are using Mac OS X 10.6 (Snow Leopard) or later.

In Mac OS X 10.4 (Tiger), the kernel would accept processes whose primary effective group is procmod or procview. That meant that making gdb setgid procmod worked.

Later versions of Darwin still accept this convention provided that taskgated (the daemon that controls the access) is invoked with option '-p'. This daemon is configured by /System/Library/LaunchDaemons/com.apple.taskgated.plist, which is where you can add this '-p' option. On OS X 10.11 (El Capitan) and later, this requires (temporarily) disabling rootless mode, otherwise that file cannot be modified.

On OS X 10.10 (Yosemite) and later, you also need to be a member of the Unix group _developer for this method to work. In case your use name is Jack, you can do this with the following command:

$ sudo dscl . merge /Groups/_developer GroupMembership Jack

Follow the instructions above to refresh all subsystems that need to know about this group change.

None: PermissionsDarwin (last edited 2019-01-02 16:22:04 by DomQ)

All content (C) 2008 Free Software Foundation. For terms of use, redistribution, and modification, please see the WikiLicense page.