This is /home/pdm/install/Python-2.1/Doc/lib/python-lib.info, produced by makeinfo version 4.0 from lib.texi. April 15, 2001 2.1  File: python-lib.info, Node: fileinput, Next: xreadlines, Prev: ConfigParser, Up: Miscellaneous Services Iterate over lines from multiple input streams ============================================== This module was documented by Guido van Rossum . This section was written by Fred L. Drake, Jr. . Perl-like iteration over lines from multiple input streams, with "save in place" capability. This module implements a helper class and functions to quickly write a loop over standard input or a list of files. The typical use is: import fileinput for line in fileinput.input(): process(line) This iterates over the lines of all files listed in `sys.argv[1:]', defaulting to `sys.stdin' if the list is empty. If a filename is `'-'', it is also replaced by `sys.stdin'. To specify an alternative list of filenames, pass it as the first argument to `input()'. A single file name is also allowed. All files are opened in text mode. If an I/O error occurs during opening or reading a file, `IOError' is raised. If `sys.stdin' is used more than once, the second and further use will return no lines, except perhaps for interactive use, or if it has been explicitly reset (e.g. using `sys.stdin.seek(0)'). Empty files are opened and immediately closed; the only time their presence in the list of filenames is noticeable at all is when the last file opened is empty. It is possible that the last line of a file does not end in a newline character; lines are returned including the trailing newline when it is present. The following function is the primary interface of this module: `input([files[, inplace[, backup]]])' Create an instance of the `FileInput' class. The instance will be used as global state for the functions of this module, and is also returned to use during iteration. The following functions use the global state created by `input()'; if there is no active state, `RuntimeError' is raised. `filename()' Return the name of the file currently being read. Before the first line has been read, returns `None'. `lineno()' Return the cumulative line number of the line that has just been read. Before the first line has been read, returns `0'. After the last line of the last file has been read, returns the line number of that line. `filelineno()' Return the line number in the current file. Before the first line has been read, returns `0'. After the last line of the last file has been read, returns the line number of that line within the file. `isfirstline()' Returns true the line just read is the first line of its file, otherwise returns false. `isstdin()' Returns true if the last line was read from `sys.stdin', otherwise returns false. `nextfile()' Close the current file so that the next iteration will read the first line from the next file (if any); lines not read from the file will not count towards the cumulative line count. The filename is not changed until after the first line of the next file has been read. Before the first line has been read, this function has no effect; it cannot be used to skip the first file. After the last line of the last file has been read, this function has no effect. `close()' Close the sequence. The class which implements the sequence behavior provided by the module is available for subclassing as well: `FileInput([files[, inplace[, backup]]])' Class `FileInput' is the implementation; its methods `filename()', `lineno()', `fileline()', `isfirstline()', `isstdin()', `nextfile()' and `close()' correspond to the functions of the same name in the module. In addition it has a `readline()' method which returns the next input line, and a `__getitem__()' method which implements the sequence behavior. The sequence must be accessed in strictly sequential order; random access and `readline()' cannot be mixed. *Optional in-place filtering:* if the keyword argument `INPLACE=1' is passed to `input()' or to the `FileInput' constructor, the file is moved to a backup file and standard output is directed to the input file. This makes it possible to write a filter that rewrites its input file in place. If the keyword argument `BACKUP='.'' is also given, it specifies the extension for the backup file, and the backup file remains around; by default, the extension is `'.bak'' and it is deleted when the output file is closed. In-place filtering is disabled when standard input is read. *Caveat:* The current implementation does not work for MS-DOS 8+3 filesystems.  File: python-lib.info, Node: xreadlines, Next: calendar, Prev: fileinput, Up: Miscellaneous Services Efficient iteration over a file =============================== Efficient iteration over the lines of a file. _Added in Python version 2.1_ This module defines a new object type which can efficiently iterate over the lines of a file. An xreadlines object is a sequence type which implements simple in-order indexing beginning at `0', as required by `for' statement or the `filter()' function. Thus, the code import xreadlines, sys for line in xreadlines.xreadlines(sys.stdin): pass has approximately the same speed and memory consumption as while 1: lines = sys.stdin.readlines(8*1024) if not lines: break for line in lines: pass except the clarity of the `for' statement is retained in the former case. `xreadlines(fileobj)' Return a new xreadlines object which will iterate over the contents of FILEOBJ. FILEOBJ must have a `readlines()' method that supports the SIZEHINT parameter. An xreadlines object S supports the following sequence operation: Operation Result ------ ----- S[I] I'th line of S If successive values of I are not sequential starting from `0', this code will raise `RuntimeError'. After the last line of the file is read, this code will raise an `IndexError'.  File: python-lib.info, Node: calendar, Next: cmd, Prev: xreadlines, Up: Miscellaneous Services General calendar-related functions ================================== General functions for working with the calendar, including some emulation of the UNIX `cal' program. This section was written by Drew Csillag . This module allows you to output calendars like the UNIX `cal' program, and provides additional useful functions related to the calendar. By default, these calendars have Monday as the first day of the week, and Sunday as the last (the European convention). Use `setfirstweekday()' to set the first day of the week to Sunday (6) or to any other weekday. `setfirstweekday(weekday)' Sets the weekday (`0' is Monday, `6' is Sunday) to start each week. The values `MONDAY', `TUESDAY', `WEDNESDAY', `THURSDAY', `FRIDAY', `SATURDAY', and `SUNDAY' are provided for convenience. For example, to set the first weekday to Sunday: import calendar calendar.setfirstweekday(calendar.SUNDAY) `firstweekday()' Returns the current setting for the weekday to start each week. `isleap(year)' Returns true if YEAR is a leap year. `leapdays(y1, y2)' Returns the number of leap years in the range [Y1...Y2). `weekday(year, month, day)' Returns the day of the week (`0' is Monday) for YEAR (`1970'-...), MONTH (`1'-`12'), DAY (`1'-`31'). `monthrange(year, month)' Returns weekday of first day of the month and number of days in month, for the specified YEAR and MONTH. `monthcalendar(year, month)' Returns a matrix representing a month's calendar. Each row represents a week; days outside of the month a represented by zeros. Each week begins with Monday unless set by `setfirstweekday()'. `prmonth(theyear, themonth[, w[, l]])' Prints a month's calendar as returned by `month()'. `month(theyear, themonth[, w[, l]])' Returns a month's calendar in a multi-line string. If W is provided, it specifies the width of the date columns, which are centered. If L is given, it specifies the number of lines that each week will use. Depends on the first weekday as set by `setfirstweekday()'. `prcal(year[, w[, l[c]]])' Prints the calendar for an entire year as returned by `calendar()'. `calendar(year[, w[, l[c]]])' Returns a 3-column calendar for an entire year as a multi-line string. Optional parameters W, L, and C are for date column width, lines per week, and number of spaces between month columns, respectively. Depends on the first weekday as set by `setfirstweekday()'. `timegm(tuple)' An unrelated but handy function that takes a time tuple such as returned by the `gmtime()' function in the `time' module, and returns the corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In fact, `time.gmtime()' and `timegm()' are each others' inverse. See also: *Note time:: Low-level time related functions.  File: python-lib.info, Node: cmd, Next: shlex, Prev: calendar, Up: Miscellaneous Services Support for line-oriented command interpreters ============================================== This section was written by Eric S. Raymond . Build line-oriented command interpreters. The `Cmd' class provides a simple framework for writing line-oriented command interpreters. These are often useful for test harnesses, administrative tools, and prototypes that will later be wrapped in a more sophisticated interface. `Cmd()' A `Cmd' instance or subclass instance is a line-oriented interpreter framework. There is no good reason to instantiate `Cmd' itself; rather, it's useful as a superclass of an interpreter class you define yourself in order to inherit `Cmd''s methods and encapsulate action methods. * Menu: * Cmd Objects::  File: python-lib.info, Node: Cmd Objects, Prev: cmd, Up: cmd Cmd Objects ----------- A `Cmd' instance has the following methods: `cmdloop([intro])' Repeatedly issue a prompt, accept input, parse an initial prefix off the received input, and dispatch to action methods, passing them the remainder of the line as argument. The optional argument is a banner or intro string to be issued before the first prompt (this overrides the `intro' class member). If the `readline' module is loaded, input will automatically inherit `bash'-like history-list editing (e.g. scrolls back to the last command, forward to the next one, moves the cursor to the right non-destructively, moves the cursor to the left non-destructively, etc.). An end-of-file on input is passed back as the string `'EOF''. An interpreter instance will recognize a command name `foo' if and only if it has a method `do_foo()'. As a special case, a line beginning with the character `?' is dispatched to the method `do_help()'. As another special case, a line beginning with the character `!' is dispatched to the method `do_shell' (if such a method is defined). All subclasses of `Cmd' inherit a predefined `do_help'. This method, called with an argument `bar', invokes the corresponding method `help_bar()'. With no argument, `do_help()' lists all available help topics (that is, all commands with corresponding `help_*()' methods), and also lists any undocumented commands. `onecmd(str)' Interpret the argument as though it had been typed in in response to the prompt. `emptyline()' Method called when an empty line is entered in response to the prompt. If this method is not overridden, it repeats the last nonempty command entered. `default(line)' Method called on an input line when the command prefix is not recognized. If this method is not overridden, it prints an error message and returns. `precmd()' Hook method executed just before the input prompt is issued. This method is a stub in `Cmd'; it exists to be overridden by subclasses. `postcmd()' Hook method executed just after a command dispatch is finished. This method is a stub in `Cmd'; it exists to be overridden by subclasses. `preloop()' Hook method executed once when `cmdloop()' is called. This method is a stub in `Cmd'; it exists to be overridden by subclasses. `postloop()' Hook method executed once when `cmdloop()' is about to return. This method is a stub in `Cmd'; it exists to be overridden by subclasses. Instances of `Cmd' subclasses have some public instance variables: `prompt' The prompt issued to solicit input. `identchars' The string of characters accepted for the command prefix. `lastcmd' The last nonempty command prefix seen. `intro' A string to issue as an intro or banner. May be overridden by giving the `cmdloop()' method an argument. `doc_header' The header to issue if the help output has a section for documented commands. `misc_header' The header to issue if the help output has a section for miscellaneous help topics (that is, there are `help_*()' methods without corresponding `do_*()' methods). `undoc_header' The header to issue if the help output has a section for undocumented commands (that is, there are `do_*()' methods without corresponding `help_*()' methods). `ruler' The character used to draw separator lines under the help-message headers. If empty, no ruler line is drawn. It defaults to `='. `use_rawinput' A flag, defaulting to true. If true, `cmdloop()' uses `raw_input()' to display a prompt and read the next command; if false, `sys.stdout.write()' and `sys.stdin.readline()' are used.  File: python-lib.info, Node: shlex, Prev: cmd, Up: Miscellaneous Services Simple lexical analysis ======================= Simple lexical analysis for UNIX shell-like languages. This module was documented by Eric S. Raymond . This section was written by Eric S. Raymond . _Added in Python version 1.5.2_ The `shlex' class makes it easy to write lexical analyzers for simple syntaxes resembling that of the UNIX shell. This will often be useful for writing minilanguages, e.g. in run control files for Python applications. `shlex([stream[, file]])' A `shlex' instance or subclass instance is a lexical analyzer object. The initialization argument, if present, specifies where to read characters from. It must be a file- or stream-like object with `read()' and `readline()' methods. If no argument is given, input will be taken from `sys.stdin'. The second optional argument is a filename string, which sets the initial value of the `infile' member. If the stream argument is omitted or equal to `sys.stdin', this second argument defaults to "stdin". See also: *Note ConfigParser:: Parser for configuration files similar to the Windows `.ini' files. * Menu: * shlex Objects::  File: python-lib.info, Node: shlex Objects, Prev: shlex, Up: shlex shlex Objects ------------- A `shlex' instance has the following methods: `get_token()' Return a token. If tokens have been stacked using `push_token()', pop a token off the stack. Otherwise, read one from the input stream. If reading encounters an immediate end-of-file, an empty string is returned. `push_token(str)' Push the argument onto the token stack. `read_token()' Read a raw token. Ignore the pushback stack, and do not interpret source requests. (This is not ordinarily a useful entry point, and is documented here only for the sake of completeness.) `sourcehook(filename)' When `shlex' detects a source request (see `source' below) this method is given the following token as argument, and expected to return a tuple consisting of a filename and an open file-like object. Normally, this method first strips any quotes off the argument. If the result is an absolute pathname, or there was no previous source request in effect, or the previous source was a stream (e.g. `sys.stdin'), the result is left alone. Otherwise, if the result is a relative pathname, the directory part of the name of the file immediately before it on the source inclusion stack is prepended (this behavior is like the way the C preprocessor handles `#include "file.h"'). The result of the manipulations is treated as a filename, and returned as the first component of the tuple, with `open()' called on it to yield the second component. (Note: this is the reverse of the order of arguments in instance initialization!) This hook is exposed so that you can use it to implement directory search paths, addition of file extensions, and other namespace hacks. There is no corresponding `close' hook, but a shlex instance will call the `close()' method of the sourced input stream when it returns `EOF'. For more explicit control of source stacking, use the `push_source()' and `pop_source()' methods. `push_source(stream[, filename])' Push an input source stream onto the input stack. If the filename argument is specified it will later be available for use in error messages. This is the same method used internally by the `sourcehook' method. _Added in Python version 2.1_ `pop_source()' Pop the last-pushed input source from the input stack. This is the same method used internally when the lexer reaches `EOF'on a stacked input stream. _Added in Python version 2.1_ `error_leader([file[, line]])' This method generates an error message leader in the format of a UNIX C compiler error label; the format is `'"%s", line %d: '', where the `%s' is replaced with the name of the current source file and the `%d' with the current input line number (the optional arguments can be used to override these). This convenience is provided to encourage `shlex' users to generate error messages in the standard, parseable format understood by Emacs and other UNIX tools. Instances of `shlex' subclasses have some public instance variables which either control lexical analysis or can be used for debugging: `commenters' The string of characters that are recognized as comment beginners. All characters from the comment beginner to end of line are ignored. Includes just `#' by default. `wordchars' The string of characters that will accumulate into multi-character tokens. By default, includes all ASCII alphanumerics and underscore. `whitespace' Characters that will be considered whitespace and skipped. Whitespace bounds tokens. By default, includes space, tab, linefeed and carriage-return. `quotes' Characters that will be considered string quotes. The token accumulates until the same quote is encountered again (thus, different quote types protect each other as in the shell.) By default, includes ASCII single and double quotes. `infile' The name of the current input file, as initially set at class instantiation time or stacked by later source requests. It may be useful to examine this when constructing error messages. `instream' The input stream from which this `shlex' instance is reading characters. `source' This member is `None' by default. If you assign a string to it, that string will be recognized as a lexical-level inclusion request similar to the `source' keyword in various shells. That is, the immediately following token will opened as a filename and input taken from that stream until `EOF', at which point the `close()' method of that stream will be called and the input source will again become the original input stream. Source requests may be stacked any number of levels deep. `debug' If this member is numeric and `1' or more, a `shlex' instance will print verbose progress output on its behavior. If you need to use this, you can read the module source code to learn the details. Note that any character not declared to be a word character, whitespace, or a quote will be returned as a single-character token. Quote and comment characters are not recognized within words. Thus, the bare words `ain't' and `ain#t' would be returned as single tokens by the default parser. `lineno' Source line number (count of newlines seen so far plus one). `token' The token buffer. It may be useful to examine this when catching exceptions.  File: python-lib.info, Node: Generic Operating System Services, Next: Optional Operating System Services, Prev: Miscellaneous Services, Up: Top Generic Operating System Services ********************************* The modules described in this chapter provide interfaces to operating system features that are available on (almost) all operating systems, such as files and a clock. The interfaces are generally modeled after the UNIX or C interfaces, but they are available on most other systems as well. Here's an overview: * Menu: * os:: * os.path:: * dircache:: * stat:: * statcache:: * statvfs:: * filecmp:: * popen2:: * time:: * sched:: * mutex:: * getpass:: * curses:: * curses.textpad:: * curses.wrapper:: * curses.ascii:: * curses.panel:: * getopt:: * tempfile:: * errno:: * glob:: * fnmatch:: * shutil:: * locale:: * gettext::  File: python-lib.info, Node: os, Next: os.path, Prev: Generic Operating System Services, Up: Generic Operating System Services Miscellaneous OS interfaces =========================== Miscellaneous OS interfaces. This module provides a more portable way of using operating system (OS) dependent functionality than importing an OS dependent built-in module like `posix' or `nt'. This module searches for an OS dependent built-in module like `mac' or `posix' and exports the same functions and data as found there. The design of all Python's built-in OS dependent modules is such that as long as the same functionality is available, it uses the same interface; e.g., the function `os.stat(PATH)' returns stat information about PATH in the same format (which happens to have originated with the POSIX interface). Extensions peculiar to a particular OS are also available through the `os' module, but using them is of course a threat to portability! Note that after the first time `os' is imported, there is _no_ performance penalty in using functions from `os' instead of directly from the OS dependent built-in module, so there should be _no_ reason not to use `os'! The `os' module contains many functions and data values. The items below and in the following sub-sections are all available directly from the `os' module. `error' This exception is raised when a function returns a system-related error (e.g., not for illegal argument types). This is also known as the built-in exception `OSError'. The accompanying value is a pair containing the numeric error code from `errno' and the corresponding string, as would be printed by the C function `perror()'. See the module `errno', which contains names for the error codes defined by the underlying operating system. When exceptions are classes, this exception carries two attributes, `errno' and `strerror'. The first holds the value of the C `errno' variable, and the latter holds the corresponding error message from `strerror()'. For exceptions that involve a file system path (e.g. `chdir()' or `unlink()'), the exception instance will contain a third attribute, `filename', which is the file name passed to the function. When exceptions are strings, the string for the exception is `'OSError''. `name' The name of the OS dependent module imported. The following names have currently been registered: `'posix'', `'nt'', `'dos'', `'mac'', `'os2'', `'ce'', `'java''. `path' The corresponding OS dependent standard module for pathname operations, e.g., `posixpath' or `macpath'. Thus, given the proper imports, `os.path.split(FILE)' is equivalent to but more portable than `posixpath.split(FILE)'. Note that this is also a valid module: it may be imported directly as `os.path'. * Menu: * Process Parameters:: * File Object Creation:: * File Descriptor Operations:: * Files and Directories:: * Process Management:: * Miscellaneous System Information::  File: python-lib.info, Node: Process Parameters, Next: File Object Creation, Prev: os, Up: os Process Parameters ------------------ These functions and data items provide information and operate on the current process and user. `environ' A mapping object representing the string environment. For example, `environ['HOME']' is the pathname of your home directory (on some platforms), and is equivalent to `getenv("HOME")' in C. If the platform supports the `putenv()' function, this mapping may be used to modify the environment as well as query the environment. `putenv()' will be called automatically when the mapping is modified. If `putenv()' is not provided, this mapping may be passed to the appropriate process-creation functions to cause child processes to use a modified environment. `chdir(path)' `getcwd' These functions are described in "Files and Directories" (section *Note Files and Directories::). `ctermid()' Return the filename corresponding to the controlling terminal of the process. Availability: UNIX. `getegid()' Return the current process' effective group id. Availability: UNIX. `geteuid()' Return the current process' effective user id. Availability: UNIX. `getgid()' Return the current process' group id. Availability: UNIX. `getgroups()' Return list of supplemental group ids associated with the current process. Availability: UNIX. `getlogin()' Return the actual login name for the current process, even if there are multiple login names which map to the same user id. Availability: UNIX. `getpgrp()' Return the current process group id. Availability: UNIX. `getpid()' Return the current process id. Availability: UNIX, Windows. `getppid()' Return the parent's process id. Availability: UNIX. `getuid()' Return the current process' user id. Availability: UNIX. `putenv(varname, value)' Set the environment variable named VARNAME to the string VALUE. Such changes to the environment affect subprocesses started with `os.system()', `popen()' or `fork()' and `execv()'. Availability: most flavors of UNIX, Windows. When `putenv()' is supported, assignments to items in `os.environ' are automatically translated into corresponding calls to `putenv()'; however, calls to `putenv()' don't update `os.environ', so it is actually preferable to assign to items of `os.environ'. `setegid(egid)' Set the current process's effective group id. Availability: UNIX. `seteuid(euid)' Set the current process's effective user id. Availability: UNIX. `setgid(gid)' Set the current process' group id. Availability: UNIX. `setpgrp()' Calls the system call `setpgrp()' or `setpgrp(0, 0)' depending on which version is implemented (if any). See the UNIX manual for the semantics. Availability: UNIX. `setpgid(pid, pgrp)' Calls the system call `setpgid()'. See the UNIX manual for the semantics. Availability: UNIX. `setreuid(ruid, euid)' Set the current process's real and effective user ids. Availability: UNIX. `setregid(rgid, egid)' Set the current process's real and effective group ids. Availability: UNIX. `setsid()' Calls the system call `setsid()'. See the UNIX manual for the semantics. Availability: UNIX. `setuid(uid)' Set the current process' user id. Availability: UNIX. `strerror(code)' Return the error message corresponding to the error code in CODE. Availability: UNIX, Windows. `umask(mask)' Set the current numeric umask and returns the previous umask. Availability: UNIX, Windows. `uname()' Return a 5-tuple containing information identifying the current operating system. The tuple contains 5 strings: `(SYSNAME, NODENAME, RELEASE, VERSION, MACHINE)'. Some systems truncate the nodename to 8 characters or to the leading component; a better way to get the hostname is `socket.gethostname()' or even `socket.gethostbyaddr(socket.gethostname())'. Availability: recent flavors of UNIX.  File: python-lib.info, Node: File Object Creation, Next: File Descriptor Operations, Prev: Process Parameters, Up: os File Object Creation -------------------- These functions create new file objects. `fdopen(fd[, mode[, bufsize]])' Return an open file object connected to the file descriptor FD. The MODE and BUFSIZE arguments have the same meaning as the corresponding arguments to the built-in `open()' function. Availability: Macintosh, UNIX, Windows. `popen(command[, mode[, bufsize]])' Open a pipe to or from COMMAND. The return value is an open file object connected to the pipe, which can be read or written depending on whether MODE is `'r'' (default) or `'w''. The BUFSIZE argument has the same meaning as the corresponding argument to the built-in `open()' function. The exit status of the command (encoded in the format specified for `wait()') is available as the return value of the `close()' method of the file object, except that when the exit status is zero (termination without errors), `None' is returned. Availability: UNIX, Windows. _Changed in Python version 2.0_ `tmpfile()' Return a new file object opened in update mode (`w+'). The file has no directory entries associated with it and will be automatically deleted once there are no file descriptors for the file. Availability: UNIX. For each of these `popen()' variants, if BUFSIZE is specified, it specifies the buffer size for the I/O pipes. MODE, if provided, should be the string `'b'' or `'t''; on Windows this is needed to determine whether the file objects should be opened in binary or text mode. The default value for MODE is `'t''. `popen2(cmd[, bufsize[, mode]])' Executes CMD as a sub-process. Returns the file objects `(CHILD_STDIN, CHILD_STDOUT)'. _Added in Python version 2.0_ `popen3(cmd[, bufsize[, mode]])' Executes CMD as a sub-process. Returns the file objects `(CHILD_STDIN, CHILD_STDOUT, CHILD_STDERR)'. _Added in Python version 2.0_ `popen4(cmd[, bufsize[, mode]])' Executes CMD as a sub-process. Returns the file objects `(CHILD_STDIN, CHILD_STDOUT_AND_STDERR)'. _Added in Python version 2.0_ This functionality is also available in the `popen2' module using functions of the same names, but the return values of those functions have a different order.  File: python-lib.info, Node: File Descriptor Operations, Next: Files and Directories, Prev: File Object Creation, Up: os File Descriptor Operations -------------------------- These functions operate on I/O streams referred to using file descriptors. `close(fd)' Close file descriptor FD. Availability: Macintosh, UNIX, Windows. Note: this function is intended for low-level I/O and must be applied to a file descriptor as returned by `open()' or `pipe()'. To close a "file object" returned by the built-in function `open()' or by `popen()' or `fdopen()', use its `close()' method. `dup(fd)' Return a duplicate of file descriptor FD. Availability: Macintosh, UNIX, Windows. `dup2(fd, fd2)' Duplicate file descriptor FD to FD2, closing the latter first if necessary. Availability: UNIX, Windows. `fpathconf(fd, name)' Return system configuration information relevant to an open file. NAME specifies the configuration value to retrieve; it may be a string which is the name of a defined system value; these names are specified in a number of standards (POSIX.1, Unix95, Unix98, and others). Some platforms define additional names as well. The names known to the host operating system are given in the `pathconf_names' dictionary. For configuration variables not included in that mapping, passing an integer for NAME is also accepted. Availability: UNIX. If NAME is a string and is not known, `ValueError' is raised. If a specific value for NAME is not supported by the host system, even if it is included in `pathconf_names', an `OSError' is raised with `errno.EINVAL' for the error number. `fstat(fd)' Return status for file descriptor FD, like `stat()'. Availability: UNIX, Windows. `fstatvfs(fd)' Return information about the filesystem containing the file associated with file descriptor FD, like `statvfs()'. Availability: UNIX. `ftruncate(fd, length)' Truncate the file corresponding to file descriptor FD, so that it is at most LENGTH bytes in size. Availability: UNIX. `isatty(fd)' Return `1' if the file descriptor FD is open and connected to a tty(-like) device, else `0'. Availability: UNIX `lseek(fd, pos, how)' Set the current position of file descriptor FD to position POS, modified by HOW: `0' to set the position relative to the beginning of the file; `1' to set it relative to the current position; `2' to set it relative to the end of the file. Availability: Macintosh, UNIX, Windows. `open(file, flags[, mode])' Open the file FILE and set various flags according to FLAGS and possibly its mode according to MODE. The default MODE is `0777' (octal), and the current umask value is first masked out. Return the file descriptor for the newly opened file. Availability: Macintosh, UNIX, Windows. For a description of the flag and mode values, see the C run-time documentation; flag constants (like `O_RDONLY' and `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 `open()', which returns a "file object" with `read()' and `write()' methods (and many more). `openpty()' Open a new pseudo-terminal pair. Return a pair of file descriptors `(MASTER, SLAVE)' for the pty and the tty, respectively. For a (slightly) more portable approach, use the `pty' module. Availability: Some flavors of UNIX `pipe()' Create a pipe. Return a pair of file descriptors `(R, W)' usable for reading and writing, respectively. Availability: UNIX, Windows. `read(fd, n)' Read at most N bytes from file descriptor FD. Return a string containing the bytes read. Availability: Macintosh, UNIX, Windows. Note: this function is intended for low-level I/O and must be applied to a file descriptor as returned by `open()' or `pipe()'. To read a "file object" returned by the built-in function `open()' or by `popen()' or `fdopen()', or `sys.stdin', use its `read()' or `readline()' methods. `tcgetpgrp(fd)' Return the process group associated with the terminal given by FD (an open file descriptor as returned by `open()'). Availability: UNIX. `tcsetpgrp(fd, pg)' Set the process group associated with the terminal given by FD (an open file descriptor as returned by `open()') to PG. Availability: UNIX. `ttyname(fd)' Return a string which specifies the terminal device associated with file-descriptor FD. If FD is not associated with a terminal device, an exception is raised. Availability: UNIX. `write(fd, str)' Write the string STR to file descriptor FD. Return the number of bytes actually written. Availability: Macintosh, UNIX, Windows. Note: this function is intended for low-level I/O and must be applied to a file descriptor as returned by `open()' or `pipe()'. To write a "file object" returned by the built-in function `open()' or by `popen()' or `fdopen()', or `sys.stdout' or `sys.stderr', use its `write()' method. The following data items are available for use in constructing the FLAGS parameter to the `open()' function. `O_RDONLY' `O_WRONLY' `O_RDWR' `O_NDELAY' `O_NONBLOCK' `O_APPEND' `O_DSYNC' `O_RSYNC' `O_SYNC' `O_NOCTTY' `O_CREAT' `O_EXCL' `O_TRUNC' Options for the FLAG argument to the `open()' function. These can be bit-wise OR'd together. Availability: Macintosh, UNIX, Windows. `O_BINARY' Option for the FLAG argument to the `open()' function. This can be bit-wise OR'd together with those listed above. Availability: Macintosh, Windows.  File: python-lib.info, Node: Files and Directories, Next: Process Management, Prev: File Descriptor Operations, Up: os Files and Directories --------------------- `access(path, mode)' Check read/write/execute permissions for this process or existence of file PATH. MODE should be `F_OK' to test the existence of PATH, or it can be the inclusive OR of one or more of `R_OK', `W_OK', and `X_OK' to test permissions. Return `1' if access is allowed, `0' if not. See the UNIX man page `access(2)' for more information. Availability: UNIX, Windows. `F_OK' Value to pass as the MODE parameter of `access()' to test the existence of PATH. `R_OK' Value to include in the MODE parameter of `access()' to test the readability of PATH. `W_OK' Value to include in the MODE parameter of `access()' to test the writability of PATH. `X_OK' Value to include in the MODE parameter of `access()' to determine if PATH can be executed. `chdir(path)' Change the current working directory to PATH. Availability: Macintosh, UNIX, Windows. `getcwd()' Return a string representing the current working directory. Availability: Macintosh, UNIX, Windows. `chmod(path, mode)' Change the mode of PATH to the numeric MODE. Availability: UNIX, Windows. `chown(path, uid, gid)' Change the owner and group id of PATH to the numeric UID and GID. Availability: UNIX. `link(src, dst)' Create a hard link pointing to SRC named DST. Availability: UNIX. `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 `'.'' and `'..'' even if they are present in the directory. Availability: Macintosh, UNIX, Windows. `lstat(path)' Like `stat()', but do not follow symbolic links. Availability: UNIX. `mkfifo(path[, mode])' Create a FIFO (a named pipe) named PATH with numeric mode MODE. The default MODE is `0666' (octal). The current umask value is first masked out from the mode. Availability: UNIX. FIFOs are pipes that can be accessed like regular files. FIFOs exist until they are deleted (for example with `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 `mkfifo()' doesn't open the FIFO -- it just creates the rendezvous point. `mkdir(path[, mode])' Create a directory named PATH with numeric mode MODE. The default MODE is `0777' (octal). On some systems, MODE is ignored. Where it is used, the current umask value is first masked out. Availability: Macintosh, UNIX, Windows. `makedirs(path[, mode])' Recursive directory creation function. Like `mkdir()', but makes all intermediate-level directories needed to contain the leaf directory. Throws an `error' exception if the leaf directory already exists or cannot be created. The default MODE is `0777' (octal). _Added in Python version 1.5.2_ `pathconf(path, name)' Return system configuration information relevant to a named file. NAME specifies the configuration value to retrieve; it may be a string which is the name of a defined system value; these names are specified in a number of standards (POSIX.1, Unix95, Unix98, and others). Some platforms define additional names as well. The names known to the host operating system are given in the `pathconf_names' dictionary. For configuration variables not included in that mapping, passing an integer for NAME is also accepted. Availability: UNIX. If NAME is a string and is not known, `ValueError' is raised. If a specific value for NAME is not supported by the host system, even if it is included in `pathconf_names', an `OSError' is raised with `errno.EINVAL' for the error number. `pathconf_names' Dictionary mapping names accepted by `pathconf()' and `fpathconf()' to the integer values defined for those names by the host operating system. This can be used to determine the set of names known to the system. Availability: UNIX. `readlink(path)' Return a string representing the path to which the symbolic link points. Availability: UNIX. `remove(path)' Remove the file PATH. See `rmdir()' below to remove a directory. This is identical to the `unlink()' function documented below. Availability: Macintosh, UNIX, Windows. `removedirs(path)' Recursive directory removal function. Works like `rmdir()' except that, if the leaf directory is successfully removed, directories corresponding to rightmost path segments will be pruned way until either the whole path is consumed or an error is raised (which is ignored, because it generally means that a parent directory is not empty). Throws an `error' exception if the leaf directory could not be successfully removed. _Added in Python version 1.5.2_ `rename(src, dst)' Rename the file or directory SRC to DST. Availability: Macintosh, UNIX, Windows. `renames(old, new)' Recursive directory or file renaming function. Works like `rename()', except creation of any intermediate directories needed to make the new pathname good is attempted first. After the rename, directories corresponding to rightmost path segments of the old name will be pruned away using `removedirs()'. Note: this function can fail with the new directory structure made if you lack permissions needed to remove the leaf directory or file. _Added in Python version 1.5.2_ `rmdir(path)' Remove the directory PATH. Availability: Macintosh, UNIX, Windows. `stat(path)' Perform a `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 _stat_ structure, in the order `st_mode', `st_ino', `st_dev', `st_nlink', `st_uid', `st_gid', `st_size', `st_atime', `st_mtime', `st_ctime'. More items may be added at the end by some implementations. Note that on the Macintosh, the time values are floating point values, like all time values on the Macintosh. (On MS Windows, some items are filled with dummy values.) Availability: Macintosh, UNIX, Windows. Note: The standard module `stat' defines functions and constants that are useful for extracting information from a `stat' structure. `statvfs(path)' Perform a `statvfs()' system call on the given path. The return value is a tuple of 10 integers giving the most common members of the `statvfs' structure, in the order `f_bsize', `f_frsize', `f_blocks', `f_bfree', `f_bavail', `f_files', `f_ffree', `f_favail', `f_flag', `f_namemax'. Availability: UNIX. Note: The standard module `statvfs'defines constants that are useful for extracting information from a `statvfs' structure. `symlink(src, dst)' Create a symbolic link pointing to SRC named DST. Availability: UNIX. `tempnam([dir[, prefix]])' Return a unique path name that is reasonable for creating a temporary file. This will be an absolute path that names a potential directory entry in the directory DIR or a common location for temporary files if DIR is omitted or `None'. If given and not `None', PREFIX is used to provide a short prefix to the filename. Applications are responsible for properly creating and managing files created using paths returned by `tempnam()'; no automatic cleanup is provided. `tmpnam()' Return a unique path name that is reasonable for creating a temporary file. This will be an absolute path that names a potential directory entry in a common location for temporary files. Applications are responsible for properly creating and managing files created using paths returned by `tmpnam()'; no automatic cleanup is provided. `TMP_MAX' The maximum number of unique names that `tmpnam()' will generate before reusing names. `unlink(path)' Remove the file PATH. This is the same function as `remove()'; the `unlink()' name is its traditional UNIX name. Availability: Macintosh, UNIX, Windows. `utime(path, times)' Set the access and modified times of the file specified by PATH. If TIMES is `None', then the file's access and modified times are set to the current time. Otherwise, TIMES must be a 2-tuple of numbers, of the form `(ATIME, MTIME)' which is used to set the access and modified times, respectively. _Changed in Python version 2.0_ Availability: Macintosh, UNIX, Windows.