This is Info file /home/pdm/tmp/Python-1.5.2p1/Doc/lib/python-lib.info, produced by Makeinfo version 1.68 from the input file lib.texi. July 6, 1999 1.5.2  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. `chdir(path)' Change the current working directory to PATH. Availability: Macintosh, UNIX, Windows. `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. `getcwd()' Return a string representing the current working directory. Availability: Macintosh, UNIX, Windows. `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. `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'. `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. `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.  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. `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. `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). `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.  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 extance of file PATH. Return `1' if access is granted, `0' if not. See the UNIX manual for the semantics. Availability: UNIX. `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* `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. (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. `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, (atime, mtime))' Set the access and modified time of the file to the given values. (The second argument is a tuple of two items.) Availability: Macintosh, UNIX, Windows.  File: python-lib.info, Node: Process Management, Next: Miscellanenous System Data, Prev: Files and Directories, Up: os Process Management ------------------ These functions may be used to create and manage additional processes. `execl(path, arg0, arg1, ...)' This is equivalent to `execv(PATH, (ARG0, ARG1, ...))'. Availability: UNIX, Windows. `execle(path, arg0, arg1, ..., env)' This is equivalent to `execve(PATH, (ARG0, ARG1, ...), ENV)'. Availability: UNIX, Windows. `execlp(path, arg0, arg1, ...)' This is equivalent to `execvp(PATH, (ARG0, ARG1, ...))'. Availability: UNIX, Windows. `execv(path, args)' Execute the executable PATH with argument list ARGS, replacing the current process (i.e., the Python interpreter). The argument list may be a tuple or list of strings. Availability: UNIX, Windows. `execve(path, args, env)' Execute the executable PATH with argument list ARGS, and environment 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. Availability: UNIX, Windows. `execvp(path, args)' This is like `execv(PATH, ARGS)' but duplicates the shell's actions in searching for an executable file in a list of directories. The directory list is obtained from `environ['PATH']'. Availability: UNIX, Windows. `execvpe(path, args, env)' This is a cross between `execve()' and `execvp()'. The directory list is obtained from `ENV['PATH']'. Availability: UNIX, Windows. `_exit(n)' Exit to the system with status N, without calling cleanup handlers, flushing stdio buffers, etc. Availability: UNIX, Windows. Note: the standard way to exit is `sys.exit(N)'. `_exit()' should normally only be used in the child process after a `fork()'. `fork()' Fork a child process. Return `0' in the child, the child's process id in the parent. Availability: UNIX. `kill(pid, sig)' Kill the process PID with signal SIG. Availability: UNIX. `nice(increment)' Add INCREMENT to the process's "niceness". Return the new niceness. Availability: UNIX. `plock(op)' Lock program segments into memory. The value of OP (defined in `') determines which segments are locked. Availability: UNIX. `spawnv(mode, path, args)' Execute the program PATH in a new process, passing the arguments specified in ARGS as command-line parameters. ARGS may be a list or a tuple. MODE is a magic operational constant. See the Visual C++ Runtime Library documentation for further information; the constants are exposed to the Python programmer as listed below. Availability: Windows. *Added in Python version 1.5.2* `spawnve(mode, path, args, env)' Execute the program PATH in a new process, passing the arguments specified in ARGS as command-line parameters and the contents of the mapping ENV as the environment. ARGS may be a list or a tuple. MODE is a magic operational constant. See the Visual C++ Runtime Library documentation for further information; the constants are exposed to the Python programmer as listed below. Availability: Windows. *Added in Python version 1.5.2* `P_WAIT' `P_NOWAIT' `P_NOWAITO' `P_OVERLAY' `P_DETACH' Possible values for the MODE parameter to `spawnv()' and `spawnve()'. Availability: Windows. *Added in Python version 1.5.2* `system(command)' Execute the command (a string) in a subshell. This is implemented by calling the Standard C function `system()', and has the same limitations. Changes to `posix.environ', `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 `wait()', except on Windows 95 and 98, where it is always `0'. Note that POSIX does not specify the meaning of the return value of the C `system()' function, so the return value of the Python function is system-dependent. Availability: UNIX, Windows. `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 `times(2)' or the corresponding Windows Platform API documentation. Availability: UNIX, Windows. `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. Availability: UNIX. `waitpid(pid, options)' Wait for completion of a child process given by process id, and return a tuple containing its process id and exit status indication (encoded as for `wait()'). The semantics of the call are affected by the value of the integer OPTIONS, which should be `0' for normal operation. Availability: UNIX. `WNOHANG' The option for `waitpid()' to avoid hanging if no child process status is available immediately. Availability: UNIX. The following functions take a process stats code as returned by `waitpid()' as a parameter. They may be used to determine the disposition of a process. `WIFSTOPPED(status)' Return true if the process has been stopped. Availability: UNIX. `WIFSIGNALED(status)' Return true if the process exited due to a signal. Availability: UNIX. `WIFEXITED(status)' Return true if the process exited using the `exit(2)' system call. Availability: UNIX. `WEXITSTATUS(status)' If `WIFEXITED(STATUS)' is true, return the integer parameter to the `exit(2)' system call. Otherwise, the return value is meaningless. Availability: UNIX. `WSTOPSIG(status)' Return the signal which caused the process to stop. Availability: UNIX. `WTERMSIG(status)' Return the signal which caused the process to exit. Availability: UNIX.  File: python-lib.info, Node: Miscellanenous System Data, Prev: Process Management, Up: os Miscellanenous System Data -------------------------- The follow data values are used to support path manipulation operations. These are defined for all platforms. Higher-level operations on pathnames are defined in the `os.path' module. `curdir' The constant string used by the OS to refer to the current directory, e.g. `'.'' for POSIX or `':'' for the Macintosh. `pardir' The constant string used by the OS to refer to the parent directory, e.g. `'..'' for POSIX or `'::'' for the Macintosh. `sep' The character used by the OS to separate pathname components, e.g. `/' for POSIX or `:' for the Macintosh. Note that knowing this is not sufficient to be able to parse or concatenate pathnames -- use `os.path.split()' and `os.path.join()' -- but it is occasionally useful. `altsep' An alternative character used by the OS to separate pathname components, or `None' if only one separator character exists. This is set to `/' on DOS and Windows systems where `sep' is a backslash. `pathsep' The character conventionally used by the OS to separate search patch components (as in `PATH'), e.g. `:' for POSIX or `;' for DOS and Windows. `defpath' The default search path used by `exec*p*()' if the environment doesn't have a `'PATH'' key. `linesep' The string used to separate (or, rather, terminate) lines on the current platform. This may be a single character, e.g. `'\n'' for POSIX or `'\r'' for MacOS, or multiple characters, e.g. `'\r\n'' for MS-DOS and MS Windows.  File: python-lib.info, Node: os.path, Next: dircache, Prev: os, Up: Generic Operating System Services Common pathname manipulations ============================= Common pathname manipulations. This module implements some useful functions on pathnames. `abspath(path)' Return a normalized absolutized version of the pathname PATH. On most platforms, this is equivalent to `normpath(join(os.getcwd()), PATH)'. *Added in Python version 1.5.2* `basename(path)' Return the base name of pathname PATH. This is the second half of the pair returned by `split(PATH)'. `commonprefix(list)' Return the longest string that is a prefix of all strings in LIST. If LIST is empty, return the empty string (`'''). `dirname(path)' Return the directory name of pathname PATH. This is the first half of the pair returned by `split(PATH)'. `exists(path)' Return true if PATH refers to an existing path. `expanduser(path)' Return the argument with an initial component of `~' or `~USER' replaced by that USER's home directory. An initial `~{}' is replaced by the environment variable `HOME'; an initial `~USER' is looked up in the password directory through the built-in module `pwd'. If the expansion fails, or if the path does not begin with a tilde, the path is returned unchanged. On the Macintosh, this always returns PATH unchanged. `expandvars(path)' Return the argument with environment variables expanded. Substrings of the form `$NAME' or `${NAME}' are replaced by the value of environment variable NAME. Malformed variable names and references to non-existing variables are left unchanged. On the Macintosh, this always returns PATH unchanged. `getatime(path)' Return the time of last access of FILENAME. The return value is integer giving the number of seconds since the epoch (see the `time' module). Raise `os.error' if the file does not exist or is inaccessible. *Added in Python version 1.5.2* `getmtime(path)' Return the time of last modification of FILENAME. The return value is integer giving the number of seconds since the epoch (see the `time' module). Raise `os.error' if the file does not exist or is inaccessible. *Added in Python version 1.5.2* `getsize(path)' Return the size, in bytes, of FILENAME. Raise `os.error' if the file does not exist or is inaccessible. *Added in Python version 1.5.2* `isabs(path)' Return true if PATH is an absolute pathname (begins with a slash). `isfile(path)' Return true if PATH is an existing regular file. This follows symbolic links, so both `islink()' and `isfile()' can be true for the same path. `isdir(path)' Return true if PATH is an existing directory. This follows symbolic links, so both `islink()' and `isdir()' can be true for the same path. `islink(path)' Return true if PATH refers to a directory entry that is a symbolic link. Always false if symbolic links are not supported. `ismount(path)' Return true if pathname PATH is a "mount point": a point in a file system where a different file system has been mounted. The function checks whether PATH's parent, `PATH/..', is on a different device than PATH, or whether `PATH/..' and PATH point to the same i-node on the same device -- this should detect mount points for all UNIX and POSIX variants. `join(path1[, path2[, ...]])' Joins one or more path components intelligently. If any component is an absolute path, all previous components are thrown away, and joining continues. The return value is the concatenation of PATH1, and optionally PATH2, etc., with exactly one slash (`'/'') inserted between components, unless PATH is empty. `normcase(path)' Normalize the case of a pathname. On UNIX, this returns the path unchanged; on case-insensitive filesystems, it converts the path to lowercase. On Windows, it also converts forward slashes to backward slashes. `normpath(path)' Normalize a pathname. This collapses redundant separators and up-level references, e.g. `A//B', `A/./B' and `A/foo/../B' all become `A/B'. It does not normalize the case (use `normcase()' for that). On Windows, it does converts forward slashes to backward slashes. `samefile(path1, path2)' Return true if both pathname arguments refer to the same file or directory (as indicated by device number and i-node number). Raise an exception if a `os.stat()' call on either pathname fails. Availability: Macintosh, UNIX. `sameopenfile(fp1, fp2)' Return true if the file objects FP1 and FP2 refer to the same file. The two file objects may represent different file descriptors. Availability: Macintosh, UNIX. `samestat(stat1, stat2)' Return true if the stat tuples STAT1 and STAT2 refer to the same file. These structures may have been returned by `fstat()', `lstat()', or `stat()'. This function implements the underlying comparison used by `samefile()' and `sameopenfile()'. Availability: Macintosh, UNIX. `split(path)' Split the pathname PATH into a pair, `(HEAD, TAIL)' where TAIL is the last pathname component and HEAD is everything leading up to that. The TAIL part will never contain a slash; if PATH ends in a slash, TAIL will be empty. If there is no slash in PATH, HEAD will be empty. If PATH is empty, both HEAD and TAIL are empty. Trailing slashes are stripped from HEAD unless it is the root (one or more slashes only). In nearly all cases, `join(HEAD, TAIL)' equals PATH (the only exception being when there were multiple slashes separating HEAD from TAIL). `splitdrive(path)' Split the pathname PATH into a pair `(DRIVE, TAIL)' where DRIVE is either a drive specification or the empty string. On systems which do not use drive specifications, DRIVE will always be the empty string. In all cases, `DRIVE + TAIL' will be the same as PATH. `splitext(path)' Split the pathname PATH into a pair `(ROOT, EXT)' such that `ROOT + EXT == PATH', and EXT is empty or begins with a period and contains at most one period. `walk(path, visit, arg)' Calls the function VISIT with arguments `(ARG, DIRNAME, NAMES)' for each directory in the directory tree rooted at PATH (including PATH itself, if it is a directory). The argument DIRNAME specifies the visited directory, the argument NAMES lists the files in the directory (gotten from `os.listdir(DIRNAME)'). The VISIT function may modify NAMES to influence the set of directories visited below DIRNAME, e.g., to avoid visiting certain parts of the tree. (The object referred to by NAMES must be modified in place, using `del' or slice assignment.)  File: python-lib.info, Node: dircache, Next: stat, Prev: os.path, Up: Generic Operating System Services Cached directory listings ========================= This section was written by Moshe Zadka . Return directory listing, with cache mechanism. The `dircache' module defines a function for reading directory listing using a cache, and cache invalidation using the MTIME of the directory. Additionally, it defines a function to annotate directories by appending a slash. The `dircache' module defines the following functions: `listdir(path)' Return a directory listing of PATH, as gotten from `os.listdir()'. Note that unless PATH changes, further call to `listdir()' will not re-read the directory structure. Note that the list returned should be regarded as read-only. (Perhaps a future version should change it to return a tuple?) `opendir(path)' Same as `listdir()'. Defined for backwards compatability. `annotate(head, list)' Assume LIST is a list of pathes relative to HEAD, and append, in place, a `/' to each path which points to a directory. >>> import dircache >>> a=dircache.listdir('/') >>> a=a[:] # Copy the return value so we can change 'a' >>> a ['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+ found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz'] >>> dircache.annotate('/', a) >>> a ['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/ ', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm linuz']  File: python-lib.info, Node: stat, Next: statcache, Prev: dircache, Up: Generic Operating System Services Interpreting `stat()' results ============================= Utilities for interpreting the results of `os.stat()', `os.lstat()' and `os.fstat()'. This section was written by Skip Montanaro . The `stat' module defines constants and functions for interpreting the results of `os.stat()', `os.fstat()' and `os.lstat()' (if they exist). For complete details about the `stat()', `fstat()' and `lstat()' calls, consult the documentation for your system. The `stat' module defines the following functions to test for specific file types: `S_ISDIR(mode)' Return non-zero if the mode is from a directory. `S_ISCHR(mode)' Return non-zero if the mode is from a character special device file. `S_ISBLK(mode)' Return non-zero if the mode is from a block special device file. `S_ISREG(mode)' Return non-zero if the mode is from a regular file. `S_ISFIFO(mode)' Return non-zero if the mode is from a FIFO (named pipe). `S_ISLNK(mode)' Return non-zero if the mode is from a symbolic link. `S_ISSOCK(mode)' Return non-zero if the mode is from a socket. Two additional functions are defined for more general manipulation of the file's mode: `S_IMODE(mode)' Return the portion of the file's mode that can be set by `os.chmod()'--that is, the file's permission bits, plus the sticky bit, set-group-id, and set-user-id bits (on systems that support them). `S_IFMT(mode)' Return the portion of the file's mode that describes the file type (used by the `S_IS*()' functions above). Normally, you would use the `os.path.is*()' functions for testing the type of a file; the functions here are useful when you are doing multiple tests of the same file and wish to avoid the overhead of the `stat()' system call for each test. These are also useful when checking for information about a file that isn't handled by `os.path', like the tests for block and character devices. All the variables below are simply symbolic indexes into the 10-tuple returned by `os.stat()', `os.fstat()' or `os.lstat()'. `ST_MODE' Inode protection mode. `ST_INO' Inode number. `ST_DEV' Device inode resides on. `ST_NLINK' Number of links to the inode. `ST_UID' User id of the owner. `ST_GID' Group id of the owner. `ST_SIZE' File size in bytes. `ST_ATIME' Time of last access. `ST_MTIME' Time of last modification. `ST_CTIME' Time of last status change (see manual pages for details). Example: import os, sys from stat import * def process(dir, func): '''recursively descend the directory rooted at dir, calling func for each regular file''' for f in os.listdir(dir): mode = os.stat('%s/%s' % (dir, f))[ST_MODE] if S_ISDIR(mode): # recurse into directory process('%s/%s' % (dir, f), func) elif S_ISREG(mode): func('%s/%s' % (dir, f)) else: print 'Skipping %s/%s' % (dir, f) def f(file): print 'frobbed', file if __name__ == '__main__': process(sys.argv[1], f)  File: python-lib.info, Node: statcache, Next: statvfs, Prev: stat, Up: Generic Operating System Services An optimization of `os.stat()' ============================== This section was written by Moshe Zadka . Stat files, and remember results. The `statcache' module provides a simple optimization to `os.stat()': remembering the values of previous invocations. The `statcache' module defines the following functions: `stat(path)' This is the main module entry-point. Identical for `os.stat()', except for remembering the result for future invocations of the function. The rest of the functions are used to clear the cache, or parts of it. `reset()' Clear the cache: forget all results of previous `stat()' calls. `forget(path)' Forget the result of `stat(PATH)', if any. `forget_prefix(prefix)' Forget all results of `stat(PATH)' for PATH starting with PREFIX. `forget_dir(prefix)' Forget all results of `stat(PATH)' for PATH a file in the directory PREFIX, including `stat(PREFIX)'. `forget_except_prefix(prefix)' Similar to `forget_prefix()', but for all PATH values *not* starting with PREFIX. Example: >>> import os, statcache >>> statcache.stat('.') (16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777) >>> os.stat('.') (16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)  File: python-lib.info, Node: statvfs, Next: cmp, Prev: statcache, Up: Generic Operating System Services Constants used with `os.statvfs()' ================================== This section was written by Moshe Zadka . Constants for interpreting the result of `os.statvfs()'. The `statvfs' module defines constants so interpreting the result if `os.statvfs()', which returns a tuple, can be made without remembering "magic numbers." Each of the constants defined in this module is the *index* of the entry in the tuple returned by `os.statvfs()' that contains the specified information. `F_BSIZE' Preferred file system block size. `F_FRSIZE' Fundamental file system block size. `F_BFREE' Total number of free blocks. `F_BAVAIL' Free blocks available to non-super user. `F_FILES' Total number of file nodes. `F_FFREE' Total number of free file nodes. `F_FAVAIL' Free nodes available to non-superuser. `F_FLAG' Flags. System dependant: see `statvfs()' man page. `F_NAMEMAX' Maximum file name length.  File: python-lib.info, Node: cmp, Next: cmpcache, Prev: statvfs, Up: Generic Operating System Services File comparisons ================ This section was written by Moshe Zadka . Compare files very efficiently. The `cmp' module defines a function to compare files, taking all sort of short-cuts to make it a highly efficient operation. The `cmp' module defines the following function: `cmp(f1, f2)' Compare two files given as names. The following tricks are used to optimize the comparisons: * Files with identical type, size and mtime are assumed equal. * Files with different type or size are never equal. * The module only compares files it already compared if their signature (type, size and mtime) changed. * No external programs are called. Example: >>> import cmp >>> cmp.cmp('libundoc.tex', 'libundoc.tex') 1 >>> cmp.cmp('libundoc.tex', 'lib.tex') 0  File: python-lib.info, Node: cmpcache, Next: time, Prev: cmp, Up: Generic Operating System Services Efficient file comparisons ========================== This section was written by Moshe Zadka . Compare files very efficiently. The `cmpcache' module provides an identical interface and similar functionality as the `cmp' module, but can be a bit more efficient as it uses `statcache.stat()' instead of `os.stat()' (see the `statcache' module for information on the difference). *Note:* Using the `statcache' module to provide `stat()' information results in trashing the cache invalidation mechanism: results are not as reliable. To ensure "current" results, use `cmp.cmp()' instead of the version defined in this module, or use `statcache.forget()' to invalidate the appropriate entries.