document API better

gettimeofday isn't portable -- avoid it?
