From d0de57cfbb7001a15935d09bddf3ef696956b32a Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Wed, 9 May 2001 21:09:57 +0000 Subject: [PATCH] Update the fcntl module documentation. --- Doc/lib/libfcntl.tex | 56 ++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex index 7c357e6650f..d02eaa5eb5e 100644 --- a/Doc/lib/libfcntl.tex +++ b/Doc/lib/libfcntl.tex @@ -11,8 +11,12 @@ This module performs file control and I/O control on file descriptors. It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()} -\UNIX{} routines. File descriptors can be obtained with the -\method{fileno()} method of a file or socket object. +\UNIX{} routines. + +All functions in this module take a file descriptor \var{fd} as their +first argument. This can be an integer file descriptor, such as +returned by \code{sys.stdin.fileno()}, or a file object, such as +\code{sys.stdin} itself. The module defines the following functions: @@ -20,22 +24,22 @@ The module defines the following functions: \begin{funcdesc}{fcntl}{fd, op\optional{, arg}} Perform the requested operation on file descriptor \var{fd}. The operation is defined by \var{op} and is operating system - dependent. Typically these codes can be retrieved from the library - module \module{FCNTL}\refstmodindex{FCNTL}. The argument \var{arg} - is optional, and defaults to the integer value \code{0}. When - present, it can either be an integer value, or a string. With - the argument missing or an integer value, the return value of this - function is the integer return value of the C \cfunction{fcntl()} - call. When the argument is a string it represents a binary - structure, e.g.\ created by \function{struct.pack()}. The binary - data is copied to a buffer whose address is passed to the C - \cfunction{fcntl()} call. The return value after a successful call - is the contents of the buffer, converted to a string object. The length - of the returned string will be the same as the length of the \var{arg} - argument. This is limited to 1024 bytes. If the information returned - in the buffer by the operating system is larger than 1024 bytes, - this is most likely to result in a segmentation violation or a more - subtle data corruption. + dependent. These codes are also found in the \module{fcntl} + module. The argument \var{arg} is optional, and defaults to the + integer value \code{0}. When present, it can either be an integer + value, or a string. With the argument missing or an integer value, + the return value of this function is the integer return value of the + C \cfunction{fcntl()} call. When the argument is a string it + represents a binary structure, e.g.\ created by + \function{struct.pack()}. The binary data is copied to a buffer + whose address is passed to the C \cfunction{fcntl()} call. The + return value after a successful call is the contents of the buffer, + converted to a string object. The length of the returned string + will be the same as the length of the \var{arg} argument. This is + limited to 1024 bytes. If the information returned in the buffer by + the operating system is larger than 1024 bytes, this is most likely + to result in a segmentation violation or a more subtle data + corruption. If the \cfunction{fcntl()} fails, an \exception{IOError} is raised. @@ -90,26 +94,18 @@ The default for \var{start} is 0, which means to start at the beginning of the file. The default for \var{length} is 0 which means to lock to the end of the file. The default for \var{whence} is also 0. - \end{funcdesc} -If the library modules \module{FCNTL}\refstmodindex{FCNTL} or -\module{IOCTL}\refstmodindex{IOCTL} are missing, you can find the -opcodes in the C include files \code{} and -\code{}. You can create the modules yourself with the -\program{h2py} script, found in the \file{Tools/scripts/} directory. - - Examples (all on a SVR4 compliant system): \begin{verbatim} -import struct, fcntl, FCNTL +import struct, fcntl file = open(...) -rv = fcntl(file.fileno(), FCNTL.F_SETFL, FCNTL.O_NDELAY) +rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY) -lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0) -rv = fcntl.fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata) +lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) +rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata) \end{verbatim} Note that in the first example the return value variable \var{rv} will