enhance and document tail follow support
Currently, our tail
f does not pick up a truncation of the file. That is, if you're doing a tail -f of /tmp/foo, and /tmp/foo gets truncated and subsequently written to, your tail won't print any output until the size of /tmp/foo exceeds the size of the seek offset at the time of truncation (and even then, you'll be missing the new contents of the file before that point). This seems busted - and it's not the way that either BSD tail or GNU tail behave.
BSD (including OS X) tail
f takes the approach of using kevent(2) in such a way that it can determine when the file has been truncated, adjusting its seek pointer appropriately. (It can only do this when using the USE_PORT action - which is why ours is busted.) This means that BSD tail -f essentially always does the Right Thing: it will catch file truncation and print the new contents, and if you truncate the file and overwrite it with a size larger than the old size, it will
correctly print all of the new contents.
Implementing the BSD approach takes us back to using event ports (which we ripped out as part of #535), and we have been mindful of the issues raised in #535. In particular, we use PORT_SOURCE_FILE, not PORT_SOURCE_FD. Even still, our existing functionality for PORT_SOURCE_FILE wasn't quite enough to get us there: PORT_SOURCE_FILE as it is today will tell us that a file has been modified, but not that it's been truncated. However, it's a relatively simple change to add a FILE_TRUNC event to the PORT_SOURCE_FILE events -- allowing our tail -f (and not to mention, any other PORT_SOURCE_FILE event port consumer) to exactly match the BSD behavior.
POSIX (not surprisingly) says nothing on the subject of file truncation, dedicating many more words to discussing the rationale for having -f be ignored if the input is a pipe. (POSIX does, however, explicitly encourage using superior mechanisms to sleeping on new data: "The -f option has been implemented as a loop that sleeps for 1 second and copies any bytes that are available. This is sufficient, but if more efficient methods of determining when new data are available are developed, implementations are encouraged to use them.")
This enhancement includes some fixes to the tail(1) manual page, including the documentation of the extant -F flag for Follow named file.
NB: This fix/RFE mirrors Joyent OS-1438, OS-1451 and OS-1429.