diff options
Diffstat (limited to 'Doc/lib/libposix.tex')
| -rw-r--r-- | Doc/lib/libposix.tex | 531 |
1 files changed, 15 insertions, 516 deletions
diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex index 834b934..8431599 100644 --- a/Doc/lib/libposix.tex +++ b/Doc/lib/libposix.tex @@ -7,7 +7,7 @@ via module \module{os}).} This module provides access to operating system functionality that is -standardized by the \C{} Standard and the \POSIX{} standard (a thinly +standardized by the C Standard and the \POSIX{} standard (a thinly disguised \UNIX{} interface). \strong{Do not import this module directly.} Instead, import the @@ -37,7 +37,7 @@ type errors, while errors reported by the system calls raise \sectionauthor{Steve Clift}{clift@mail.anacapa.net} Several operating systems (including AIX, HPUX, Irix and Solaris) -provide support for files that are larger than 2 Gb from a \C{} +provide support for files that are larger than 2 Gb from a C programming model where \ctype{int} and \ctype{long} are 32-bit values. This is typically accomplished by defining the relevant size and offset types as 64-bit values. Such files are sometimes referred @@ -60,13 +60,13 @@ CFLAGS="-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64" OPT="-g -O2 $CFLAGS" \ \subsection{\module{posix} Module Contents \label{posix-contents}} -Module \module{posix} defines the following data items: +Module \module{posix} defines the following data item: \begin{datadesc}{environ} -A dictionary or dictionary look-alike representing the string -environment at the time the interpreter was started. For example, -\code{posix.environ['HOME']} is the pathname of your home directory, -equivalent to \code{getenv("HOME")} in \C{}. +A dictionary representing the string environment at the time the +interpreter was started. For example, \code{environ['HOME']} is the +pathname of your home directory, equivalent to \code{getenv("HOME")} +in C. Modifying this dictionary does not affect the string environment passed on by \function{execv()}, \function{popen()} or @@ -75,514 +75,13 @@ passed on by \function{execv()}, \function{popen()} or export statements to the command string for \function{system()} or \function{popen()}. -\emph{However:} If you are using this module via the \module{os} -module (as you should -- see the introduction above), \code{environ} -is a a mapping object that behaves almost like a dictionary but -invokes \function{putenv()} automatically whenever an item is changed. +\strong{Note:} The \module{os} module provides an alternate +implementation of \code{environ} which updates the environment on +modification. Note also that updating \code{os.environ} will render +this dictionary obsolete. Use of the \module{os} for this is +recommended over direct access to the \module{posix} module. \end{datadesc} -\begin{excdesc}{error} -This exception is raised when a \POSIX{} function returns a -\POSIX{}-related error (e.g., not for illegal argument types). The -accompanying value is a pair containing the numeric error code from -\cdata{errno} and the corresponding string, as would be printed by the -\C{} function \cfunction{perror()}. See the module -\module{errno}\refbimodindex{errno}, which contains names for the -error codes defined by the underlying operating system. - -When exceptions are classes, this exception carries two attributes, -\member{errno} and \member{strerror}. The first holds the value of -the \C{} \cdata{errno} variable, and the latter holds the -corresponding error message from \cfunction{strerror()}. For -exceptions that involve a file system path (e.g. \code{chdir} or -\code{unlink}), the exception instance will contain a third attribute -\member{filename} which is the file name passed to the -function. - -When exceptions are strings, the string for the exception is -\code{'OSError'}. -\end{excdesc} - -It defines the following functions and constants when the operating -system provides them directly or provides the means to emulate them: - -\begin{funcdesc}{access}{path, mode} -Check read/write/execute permissions for this process or extance of file -\var{path}. Return \code{1} if access is granted, \code{0} if not. -See the \UNIX{} manual for the semantics. -\end{funcdesc} - -\begin{funcdesc}{chdir}{path} -Change the current working directory to \var{path}. -\end{funcdesc} - -\begin{funcdesc}{chmod}{path, mode} -Change the mode of \var{path} to the numeric \var{mode}. -\end{funcdesc} - -\begin{funcdesc}{chown}{path, uid, gid} -Change the owner and group id of \var{path} to the numeric \var{uid} -and \var{gid}. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{close}{fd} -Close file descriptor \var{fd}. - -Note: this function is intended for low-level I/O and must be applied -to a file descriptor as returned by \function{open()} or -\function{pipe()}. To close a ``file object'' returned by the -built-in function \function{open()} or by \function{popen()} or -\function{fdopen()}, use its \method{close()} method. -\end{funcdesc} - -\begin{funcdesc}{dup}{fd} -Return a duplicate of file descriptor \var{fd}. -\end{funcdesc} - -\begin{funcdesc}{dup2}{fd, fd2} -Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter -first if necessary. -\end{funcdesc} - -\begin{funcdesc}{execv}{path, args} -Execute the executable \var{path} with argument list \var{args}, -replacing the current process (i.e., the Python interpreter). -The argument list may be a tuple or list of strings. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{execve}{path, args, env} -Execute the executable \var{path} with argument list \var{args}, -and environment \var{env}, -replacing the current process (i.e., the Python interpreter). -The argument list may be a tuple or list of strings. -The environment must be a dictionary mapping strings to strings. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{_exit}{n} -Exit to the system with status \var{n}, without calling cleanup -handlers, flushing stdio buffers, etc. -(Not on MS-DOS.) - -Note: the standard way to exit is \code{sys.exit(\var{n})}. -\function{_exit()} should normally only be used in the child process -after a \function{fork()}. -\end{funcdesc} - -\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}} -Return an open file object connected to the file descriptor \var{fd}. -The \var{mode} and \var{bufsize} arguments have the same meaning as -the corresponding arguments to the built-in \function{open()} function. -\end{funcdesc} - -\begin{funcdesc}{fork}{} -Fork a child process. Return \code{0} in the child, the child's -process id in the parent. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{fstat}{fd} -Return status for file descriptor \var{fd}, like \function{stat()}. -\end{funcdesc} - -\begin{funcdesc}{fstatvfs}{fd} -Return information about the filesystem containing the file associated -with file descriptor \var{fd}, like \function{statvfs()}. -\end{funcdesc} - -\begin{funcdesc}{ftruncate}{fd, length} -Truncate the file corresponding to file descriptor \var{fd}, -so that it is at most \var{length} bytes in size. -\end{funcdesc} - -\begin{funcdesc}{getcwd}{} -Return a string representing the current working directory. -\end{funcdesc} - -\begin{funcdesc}{getegid}{} -Return the current process' effective group id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{geteuid}{} -Return the current process' effective user id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{getgid}{} -Return the current process' group id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{getpgrp}{} -\index{process!group} -Return the current process group id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{getpid}{} -\index{process!id} -Return the current process id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{getppid}{} -\index{process!id of parent} -Return the parent's process id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{getuid}{} -\index{user id} -Return the current process' user id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{kill}{pid, sig} -\index{process!killing} -\index{process!signalling} -Kill the process \var{pid} with signal \var{sig}. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{link}{src, dst} -Create a hard link pointing to \var{src} named \var{dst}. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{listdir}{path} -Return a list containing the names of the entries in the directory. -The list is in arbitrary order. It does not include the special -entries \code{'.'} and \code{'..'} even if they are present in the -directory. -\end{funcdesc} - -\begin{funcdesc}{lseek}{fd, pos, how} -Set the current position of file descriptor \var{fd} to position -\var{pos}, modified by \var{how}: \code{0} to set the position -relative to the beginning of the file; \code{1} to set it relative to -the current position; \code{2} to set it relative to the end of the -file. -\end{funcdesc} - -\begin{funcdesc}{lstat}{path} -Like \function{stat()}, but do not follow symbolic links. (On systems -without symbolic links, this is identical to \function{stat()}.) -\end{funcdesc} - -\begin{funcdesc}{mkfifo}{path\optional{, mode}} -Create a FIFO (a \POSIX{} named pipe) named \var{path} with numeric mode -\var{mode}. The default \var{mode} is \code{0666} (octal). The current -umask value is first masked out from the mode. -(Not on MS-DOS.) - -FIFOs are pipes that can be accessed like regular files. FIFOs exist -until they are deleted (for example with \function{os.unlink()}). -Generally, FIFOs are used as rendezvous between ``client'' and -``server'' type processes: the server opens the FIFO for reading, and -the client opens it for writing. Note that \function{mkfifo()} -doesn't open the FIFO --- it just creates the rendezvous point. -\end{funcdesc} - -\begin{funcdesc}{mkdir}{path\optional{, mode}} -Create a directory named \var{path} with numeric mode \var{mode}. -The default \var{mode} is \code{0777} (octal). On some systems, -\var{mode} is ignored. Where it is used, the current umask value is -first masked out. -\end{funcdesc} - -\begin{funcdesc}{nice}{increment} -Add \var{increment} to the process' ``niceness''. Return the new -niceness. (Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{open}{file, flags\optional{, mode}} -Open the file \var{file} and set various flags according to -\var{flags} and possibly its mode according to \var{mode}. -The default \var{mode} is \code{0777} (octal), and the current umask -value is first masked out. Return the file descriptor for the newly -opened file. - -For a description of the flag and mode values, see the \UNIX{} or \C{} -run-time documentation; flag constants (like \constant{O_RDONLY} and -\constant{O_WRONLY}) are defined in this module too (see below). - -Note: this function is intended for low-level I/O. For normal usage, -use the built-in function \function{open()}, which returns a ``file -object'' with \method{read()} and \method{write()} methods (and many -more). -\end{funcdesc} - -\begin{funcdesc}{pipe}{} -Create a pipe. Return a pair of file descriptors \code{(\var{r}, -\var{w})} usable for reading and writing, respectively. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{plock}{op} -Lock program segments into memory. The value of \var{op} -(defined in \code{<sys/lock.h>}) determines which segments are locked. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}} -Open a pipe to or from \var{command}. The return value is an open -file object connected to the pipe, which can be read or written -depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}. -The \var{bufsize} argument has the same meaning as the corresponding -argument to the built-in \function{open()} function. The exit status of -the command (encoded in the format specified for \function{wait()}) is -available as the return value of the \method{close()} method of the file -object, except that when the exit status is zero (termination without -errors), \code{None} is returned. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{putenv}{varname, value} -\index{environment variables!setting} -Set the environment variable named \var{varname} to the string -\var{value}. Such changes to the environment affect subprocesses -started with \function{os.system()}, \function{os.popen()} or -\function{os.fork()} and \function{os.execv()}. (Not on all systems.) - -When \function{putenv()} is -supported, assignments to items in \code{os.environ} are automatically -translated into corresponding calls to \function{putenv()}; however, -calls to \function{putenv()} don't update \code{os.environ}, so it is -actually preferable to assign to items of \code{os.environ}. -\end{funcdesc} - -\begin{funcdesc}{strerror}{code} -Return the error message corresponding to the error code in \var{code}. -\end{funcdesc} - -\begin{funcdesc}{ttyname}{fd} -Return a string which specifies the terminal device associated with -file-descriptor \var{fd}. If \var{fd} is not associated with a terminal -device, an exception is raised. -\end{funcdesc} - -\begin{funcdesc}{read}{fd, n} -Read at most \var{n} bytes from file descriptor \var{fd}. -Return a string containing the bytes read. - -Note: this function is intended for low-level I/O and must be applied -to a file descriptor as returned by \function{open()} or -\function{pipe()}. To read a ``file object'' returned by the -built-in function \function{open()} or by \function{popen()} or -\function{fdopen()}, or \code{sys.stdin}, use its -\method{read()} or \method{readline()} methods. -\end{funcdesc} - -\begin{funcdesc}{readlink}{path} -Return a string representing the path to which the symbolic link -points. (On systems without symbolic links, this always raises -\exception{error}.) -\end{funcdesc} - -\begin{funcdesc}{remove}{path} -Remove the file \var{path}. See \function{rmdir()} below to remove a -directory. This is identical to the \function{unlink()} function -documented below. -\end{funcdesc} - -\begin{funcdesc}{rename}{src, dst} -Rename the file or directory \var{src} to \var{dst}. -\end{funcdesc} - -\begin{funcdesc}{rmdir}{path} -Remove the directory \var{path}. -\end{funcdesc} - -\begin{funcdesc}{setgid}{gid} -Set the current process' group id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{setpgrp}{} -Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0, -0)} depending on which version is implemented (if any). See the -\UNIX{} manual for the semantics. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{setpgid}{pid, pgrp} -Calls the system call \cfunction{setpgid()}. See the \UNIX{} manual -for the semantics. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{setsid}{} -Calls the system call \cfunction{setsid()}. See the \UNIX{} manual -for the semantics. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{setuid}{uid} -Set the current process' user id. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{stat}{path} -Perform a \cfunction{stat()} system call on the given path. The -return value is a tuple of at least 10 integers giving the most -important (and portable) members of the \emph{stat} structure, in the -order -\code{st_mode}, -\code{st_ino}, -\code{st_dev}, -\code{st_nlink}, -\code{st_uid}, -\code{st_gid}, -\code{st_size}, -\code{st_atime}, -\code{st_mtime}, -\code{st_ctime}. -More items may be added at the end by some implementations. -(On MS-DOS, some items are filled with dummy values.) - -Note: The standard module \module{stat}\refstmodindex{stat} defines -functions and constants that are useful for extracting information -from a \ctype{stat} structure. -\end{funcdesc} - -\begin{funcdesc}{statvfs}{path} -Perform a \cfunction{statvfs()} system call on the given path. The -return value is a tuple of 11 integers giving the most common -members of the \ctype{statvfs} structure, in the order -\code{f_bsize}, -\code{f_frsize}, -\code{f_blocks}, -\code{f_bfree}, -\code{f_bavail}, -\code{f_files}, -\code{f_ffree}, -\code{f_favail}, -\code{f_fsid}, -\code{f_flag}, -\code{f_namemax}. - -Note: The standard module \module{statvfs}\refstmodindex{statvfs} -defines constants that are useful for extracting information -from a \ctype{statvfs} structure. -\end{funcdesc} - -\begin{funcdesc}{symlink}{src, dst} -Create a symbolic link pointing to \var{src} named \var{dst}. (On -systems without symbolic links, this always raises \exception{error}.) -\end{funcdesc} - -\begin{funcdesc}{system}{command} -Execute the command (a string) in a subshell. This is implemented by -calling the Standard \C{} function \cfunction{system()}, and has the -same limitations. Changes to \code{posix.environ}, \code{sys.stdin} -etc.\ are not reflected in the environment of the executed command. -The return value is the exit status of the process encoded in the -format specified for \function{wait()}. -\end{funcdesc} - -\begin{funcdesc}{tcgetpgrp}{fd} -Return the process group associated with the terminal given by -\var{fd} (an open file descriptor as returned by \function{open()}). -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{tcsetpgrp}{fd, pg} -Set the process group associated with the terminal given by -\var{fd} (an open file descriptor as returned by \function{open()}) -to \var{pg}. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{times}{} -Return a 5-tuple of floating point numbers indicating accumulated (CPU -or other) -times, in seconds. The items are: user time, system time, children's -user time, children's system time, and elapsed real time since a fixed -point in the past, in that order. See the \UNIX{} -manual page \manpage{times}{2}. (Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{umask}{mask} -Set the current numeric umask and returns the previous umask. -(Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{uname}{} -Return a 5-tuple containing information identifying the current -operating system. The tuple contains 5 strings: -\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version}, -\var{machine})}. Some systems truncate the nodename to 8 -characters or to the leading component; a better way to get the -hostname is \function{socket.gethostname()}% -\withsubitem{(in module socket)}{\ttindex{gethostname()}} -or even -\code{socket.gethostbyaddr(socket.gethostname())}% -\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}. -(Not on MS-DOS, nor on older \UNIX{} systems.) -\end{funcdesc} - -\begin{funcdesc}{unlink}{path} -Remove the file \var{path}. This is the same function as \code{remove}; -the \code{unlink} name is its traditional \UNIX{} name. -\end{funcdesc} - -\begin{funcdesc}{utime}{path, (atime, mtime)} -Set the access and modified time of the file to the given values. -(The second argument is a tuple of two items.) -\end{funcdesc} - -\begin{funcdesc}{wait}{} -Wait for completion of a child process, and return a tuple containing -its pid and exit status indication: a 16-bit number, whose low byte is -the signal number that killed the process, and whose high byte is the -exit status (if the signal number is zero); the high bit of the low -byte is set if a core file was produced. (Not on MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{waitpid}{pid, options} -Wait for completion of a child process given by proces id, and return -a tuple containing its pid and exit status indication (encoded as for -\function{wait()}). The semantics of the call are affected by the -value of the integer \var{options}, which should be \code{0} for -normal operation. (If the system does not support -\function{waitpid()}, this always raises \exception{error}. Not on -MS-DOS.) -\end{funcdesc} - -\begin{funcdesc}{write}{fd, str} -Write the string \var{str} to file descriptor \var{fd}. -Return the number of bytes actually written. - -Note: this function is intended for low-level I/O and must be applied -to a file descriptor as returned by \function{open()} or -\function{pipe()}. To write a ``file object'' returned by the -built-in function \function{open()} or by \function{popen()} or -\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use -its \method{write()} method. -\end{funcdesc} - -\begin{datadesc}{WNOHANG} -The option for \function{waitpid()} to avoid hanging if no child -process status is available immediately. -\end{datadesc} - - -\begin{datadesc}{O_RDONLY} -\dataline{O_WRONLY} -\dataline{O_RDWR} -\dataline{O_NDELAY} -\dataline{O_NONBLOCK} -\dataline{O_APPEND} -\dataline{O_DSYNC} -\dataline{O_RSYNC} -\dataline{O_SYNC} -\dataline{O_NOCTTY} -\dataline{O_CREAT} -\dataline{O_EXCL} -\dataline{O_TRUNC} -Options for the \code{flag} argument to the \function{open()} function. -These can be bit-wise OR'd together. -\end{datadesc} +Additional contents of this module should only be accessed via the +\module{os} module; refer to the documentation for that module for +further information. |