The problem is that the man pages for pthread_cleanup_push(3) and pthread_cleanup_pop(3) do not state the following facts: They must be paired at the same lexicographical scope within code block within the same function. The macros, when expanded, adds a { for pthread_cleanup_push(3) and a } for pthread_cleanup_pop(3) in the current implementation. Failing to pair these will cause compilation errors. That last sentence should probably be highlighted. This is on FreeBSD 9.3-RELEASE r270190.
Edit: The line "They must be paired at the same lexicographical scope within code block within the same function." should read as follows: "They must be paired at the same lexicographical scope within the same code block within the same function."
I went with language similar to that of POSIX: The pthread_cleanup_push() function is implemented as a macro that opens a new block. Invocations of this function must appear as standalone statements that are paired with a later call of pthread_cleanup_pop(3) in the same lexical scope. for push and The pthread_cleanup_push() function is implemented as a macro that closes a block. Invocations of this function must appear as standalone state- ments that are paired with an earlier call of pthread_cleanup_push(3) in the same lexical scope. "same lexical scope" already implies same code block in same function. I don't know that we need to explicitly call out the that using the API incorrectly will result in compile errors. The same is true of any number of other APIs (e.g. trying to pass a pointer to the getchar() or putchar() "functions" (which are also macros).
The wording is fine. Hopefully, it will save someone else three hours of work trying to find a bug in their program.
A commit references this bug: Author: jhb Date: Sat Oct 25 19:31:35 UTC 2014 New revision: 273644 URL: https://svnweb.freebsd.org/changeset/base/273644 Log: Clarify that pthread_cleanup_push()/pop() are implemented as macros that create a new code block and thus must be balanced at the same lexical scope. (This is also a requirement in POSIX.) PR: 194280 Submitted by: dr2867.business@pacbell.net MFC after: 1 week Changes: head/share/man/man3/pthread_cleanup_pop.3 head/share/man/man3/pthread_cleanup_push.3
A commit references this bug: Author: jhb Date: Sun Nov 2 23:22:25 UTC 2014 New revision: 273996 URL: https://svnweb.freebsd.org/changeset/base/273996 Log: MFC 273644,273738: Clarify that pthread_cleanup_push()/pop() are implemented as macros that create a new code block and thus must be balanced at the same lexical scope. (This is also a requirement in POSIX.) PR: 194280 Submitted by: dr2867.business@pacbell.net Changes: _U stable/10/ stable/10/share/man/man3/pthread_cleanup_pop.3 stable/10/share/man/man3/pthread_cleanup_push.3 _U stable/8/share/man/man3/ stable/8/share/man/man3/pthread_cleanup_pop.3 stable/8/share/man/man3/pthread_cleanup_push.3 _U stable/9/share/man/man3/ stable/9/share/man/man3/pthread_cleanup_pop.3 stable/9/share/man/man3/pthread_cleanup_push.3