Interpret dtruss output like “psynch_cvwait(...) = -1 Err#316”

Question

dtruss appears to be a useful tool to analyze the (mis-)behaviour of applications on OS X. The closes thing I found to my beloved strace on linux. But interpreting its output requires an understanding of the syscalls it refers to, and sometimes the error conditions they might generate. Take for example the line

psynch_cvwait(0x6BE38D54, 0x100000100, 0x0)      = -1 Err#316

I'm interested in a source of documentation which would allow me to find out what this syscall is intended to do, what its parameters signify, and what this error code stands for. Pretty much like I'd expect from a libc function manpage. I'm asking for a reference which describes the above and similar syscalls, with the above and similar errors. So just take the line as an example for the kind of output I'd like to be able to understand.

What is the appropriate reference document to learn about OS X syscalls like this one?

The more syscalls your reference covers, the better.

Answer 1

The only documentation I've found on this is in the code itself.

It's the kernel side of pthread_cond_wait() and pthread_cond_timedwait().

In this case, it's the latter since the error code is #316. psync_cvcontinue sets two bits in the error code to indicate whether the wait timed out (0x100) or there were no waiters (0x200). Error #316 (0x13C) is the timed out bit bitwise OR'd with ETIMEDOUT (60).

https://github.com/apple/darwin-libpthread/blob/master/kern/kern_synch.c#L1216 https://github.com/apple/darwin-xnu/blob/master/bsd/sys/errno.h#L179

Answer 2

Based on an answer by Randy Howard, I had a look at the XNU source code for this. The file syscalls.master has the list of all syscalls. That file describes the signature of psynch_cvwait like this:

uint32_t
psynch_cvwait(
  user_addr_t cv,
  uint64_t cvlsgen,
  uint32_t cvugen,
  user_addr_t mutex,
  uint64_t mugen,
  uint32_t flags,
  int64_t sec,
  uint32_t nsec)

which doesn't appear to have much resemblance with the dtruss output quoted in the question. The actual implementation in pthread_support.c is more useful, though:

/*
 *  psynch_cvwait: This system call is used for psynch cvar waiters to block in kernel.
 */
int
psynch_cvwait(__unused proc_t p,
              struct psynch_cvwait_args * uap,
              uint32_t * retval)

This at least gives an idea as to what the arguments printed by dtruss are. Looks as if the second one might be a structure, its members descibed by the syscalls.master file. So the address would be of little use, and the actual members apparently aren't printed by dtruss at all. Tweaking dtruss it might perhaps be possible to get at the members of that structure, although I'm far from sure on this account, and wonder why noone has done so yet.

I've been less lucky in trying to associate any meaning at all with that Err#316 output. Even grepping the whole XNU source code both for the decimal and the hexadecimal representation of 316, I found no occurrence which didn't include other digits as well. The error code certainly isn't mentioned in the implementation of psynch_cvwait itself, but that implementation does forward error codes from other functions it calls. One would really need a kernel debugger to untangle that and trace the actual source of that value.

On the whole I'm now a very small step closer to understanding the dtruss output, but with a lot of work. So a proper reference document and any insight into the source of that error code would still be very much appreciated.

Answer 3

This might be a good starting point, just to get familiar with dtrace operation. http://www.mactech.com/articles/mactech/Vol.23/23.11/ExploringLeopardwithDTrace/index.html

As far as syscalls, you might start here. http://www.opensource.apple.com/source/xnu/xnu-1504.3.12/bsd/kern/syscalls.master

http://developer.apple.com and http://www.opensource.apple.com being places to find more details.

In book form, "Mac OS X Internals -- A Systems Approach" by Amit Singh is another useful thing to have around.