lockf_doc: a much better description of the lockf() function, based on

an eyeballing of the code.

Modules/fcntlmodule.c

@@ -262,10 +262,29 @@ fcntl_lockf(PyObject *self, PyObject *args)
 }
 
 static char lockf_doc [] =
-"lockf (fd, operation)\n\
-\n\
-This is a wrapper around the FCNTL.F_SETLK and FCNTL.F_SETLKW fcntl()\n\
-calls.  See the Unix manual for details.";
+"lockf (fd, operation, length=0, start=0, whence=0)
+
+This is essentially a wrapper around the fcntl() locking calls.  fd is the
+file descriptor of the file to lock or unlock, and operation is one of the
+following values:
+
+    LOCK_UN - unlock
+    LOCK_SH - acquire a shared lock
+    LOCK_EX - acquire an exclusive lock
+
+When operation is LOCK_SH or LOCK_EX, it can also be bit-wise OR'd with
+LOCK_NB to avoid blocking on lock acquisition.  If LOCK_NB is used and the
+lock cannot be acquired, an IOError will be raised and the exception will
+have an errno attribute set to EACCES or EAGAIN (depending on the operating
+system -- for portability, check for either value).
+
+length is the number of bytes to lock, with the default meaning to lock to
+EOF.  start is the byte offset, relative to whence, to that the lock
+starts.  whence is as with fileobj.seek(), specifically:
+
+    0 - relative to the start of the file (SEEK_SET)
+    1 - relative to the current buffer position (SEEK_CUR)
+    2 - relative to the end of the file (SEEK_END)";
 
 /* List of functions */