[docs] Improve the documentation in fcntl module (issue 18985)

sky.kok at speaklikeaking.com sky.kok at speaklikeaking.com
Sun Sep 15 11:31:12 CEST 2013


Reviewers: ezio.melotti,


http://bugs.python.org/review/18985/diff/9247/Modules/fcntlmodule.c
File Modules/fcntlmodule.c (right):

http://bugs.python.org/review/18985/diff/9247/Modules/fcntlmodule.c#newcode120
Modules/fcntlmodule.c:120: char buf[IOCTL_BUFSZ+1];  /* argument plus
NULL byte */
On 2013/09/13 23:10:07, ezio.melotti wrote:
> http://en.wikipedia.org/wiki/Null_character

Ah, sorry about that.

http://bugs.python.org/review/18985/diff/9247/Modules/fcntlmodule.c#newcode422
Modules/fcntlmodule.c:422: and ioctl() Unix routines.  File descriptors
can be obtained with the \n\
On 2013/09/13 23:10:07, ezio.melotti wrote:
> This sentence might be clearer.  Are they all Unix routines?  Are they
available
> on all systems except flock()?  On what systems is flock() available?

It is not clear why on some system flock is not available natively. But
the manual (http://linux.about.com/library/cmd/blcmdl2_flock.htm) and
the comment inside this file says:

A version of flock(2), possibly implemented in terms of fcntl(2),
appears on most Unices.

&

Perform the lock operation opt on file descriptor fd.  See the Unix \n\
manual page for flock(3) for details.  (On some systems, this function
is\n\
emulated using fcntl().)

Lockf is somewhat similar with flock.

On Linux, lockf() is just an interface on top of fcntl(2) locking.
       Many other systems implement lockf() in this way, but note that
       POSIX.1-2001 leaves the relationship between lockf() and fcntl(2)
       locks unspecified.

So in most (all?) cases, ioctl and fcntl are unix routines. But in most
(all?) cases, lockf is emulated around fcntl. And in some cases, flock
is emulated around fcntl, and in other cases, flock comes natively.



Please review this at http://bugs.python.org/review/18985/

Affected files:
  Modules/fcntlmodule.c


diff -r aff959a3ba13 Modules/fcntlmodule.c
--- a/Modules/fcntlmodule.c	Sun Sep 08 18:44:40 2013 -0500
+++ b/Modules/fcntlmodule.c	Mon Sep 09 18:21:53 2013 +0800
@@ -80,8 +80,8 @@
 "fcntl(fd, opt, [arg])\n\
 \n\
 Perform the requested operation on file descriptor fd.  The operation\n\
-is defined by op and is operating system dependent.  These constants are\n\
-available from the fcntl module.  The argument arg is optional, and\n\
+is defined by opt and is operating system dependent.  The possible values of\n\
+opt are available from the fcntl module.  The argument arg is optional, and\n\
 defaults to 0; it may be an int or a string.  If arg is given as a string,\n\
 the return value of fcntl is a string of that length, containing the\n\
 resulting value put in the arg buffer by the operating system.  The length\n\
@@ -104,7 +104,7 @@
        whereas the system expects it to be a 32bit bit field value
        regardless of it being passed as an int or unsigned long on
        various platforms.  See the termios.TIOCSWINSZ constant across
-       platforms for an example of thise.
+       platforms for an example of this.
 
        If any of the 64bit platforms ever decide to use more than 32bits
        in their unsigned long ioctl codes this will break and need
@@ -117,7 +117,7 @@
     char *str;
     Py_ssize_t len;
     int mutate_arg = 1;
-    char buf[IOCTL_BUFSZ+1];  /* argument plus NUL byte */
+    char buf[IOCTL_BUFSZ+1];  /* argument plus NULL byte */
 
     if (PyArg_ParseTuple(args, "O&Iw*|i:ioctl",
                          conv_descriptor, &fd, &code,
@@ -306,9 +306,9 @@
 }
 
 PyDoc_STRVAR(flock_doc,
-"flock(fd, operation)\n\
+"flock(fd, opt)\n\
 \n\
-Perform the lock operation op on file descriptor fd.  See the Unix \n\
+Perform the lock operation opt on file descriptor fd.  See the Unix \n\
 manual page for flock(3) for details.  (On some systems, this function is\n\
 emulated using fcntl().)");
 
@@ -418,9 +418,9 @@
 
 PyDoc_STRVAR(module_doc,
 "This module performs file control and I/O control on file \n\
-descriptors.  It is an interface to the fcntl() and ioctl() Unix\n\
-routines.  File descriptors can be obtained with the fileno() method of\n\
-a file or socket object.");
+descriptors.  It is an interface to the fcntl(), flock() (on some systems) \n\
+and ioctl() Unix routines.  File descriptors can be obtained with the \n\
+fileno() method of a file or socket object.");
 
 /* Module initialisation */
 




More information about the docs mailing list