5.3. Built-in Module posix

Errors are reported as exceptions; the usual exceptions are given for type errors, while errors reported by the system calls raise posix.error, described below.

Module posix defines the following data items:

environ -- data of module posix

A dictionary representing the string environment at the time the interpreter was started. (Modifying this dictionary does not affect the string environment of the interpreter.) For example, posix.environ['HOME'] is the pathname of your home directory, equivalent to getenv("HOME") in C.

error -- exception of module posix

This exception is raised when an POSIX function returns a POSIX-related error (e.g., not for illegal argument types). Its string value is 'posix.error'. 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().

chdir (path) -- function of module posix

Change the current working directory to path.

chmod (path, mode) -- function of module posix

Change the mode of path to the numeric mode.

close (fd) -- function of module posix

Close file descriptor fd.

dup (fd) -- function of module posix

Return a duplicate of file descriptor fd.

dup2 (fd, fd2) -- function of module posix

Duplicate file descriptor fd to fd2, closing the latter first if necessary. Return None.

execv (path, args) -- function of module posix

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. (Not on MS-DOS.)

execve (path, args, env) -- function of module posix

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. (Not on MS-DOS.)

_exit (n) -- function of module posix

Exit to the system with status n, without calling cleanup handlers, flushing stdio buffers, etc. (Not on MS-DOS.)

Note: the standard way to exit is sys.exit(n). posix._exit() should normally only be used in the child process after a fork().

fdopen (fd, mode) -- function of module posix

Return an open file object connected to the file descriptor fd, open for reading and/or writing according to the mode string (which has the same meaning as the mode argument to the built-in open() function.

fork () -- function of module posix

Fork a child process. Return 0 in the child, the child's process id in the parent. (Not on MS-DOS.)

fstat (fd) -- function of module posix

Return status for file descriptor fd, like stat().

getcwd () -- function of module posix

Return a string representing the current working directory.

getegid () -- function of module posix

Return the current process's effective group id. (Not on MS-DOS.)

geteuid () -- function of module posix

Return the current process's effective user id. (Not on MS-DOS.)

getgid () -- function of module posix

Return the current process's group id. (Not on MS-DOS.)

getpid () -- function of module posix

Return the current process id. (Not on MS-DOS.)

getppid () -- function of module posix

Return the parent's process id. (Not on MS-DOS.)

getuid () -- function of module posix

Return the current process's user id. (Not on MS-DOS.)

kill (pid, sig) -- function of module posix

Kill the process pid with signal sig. (Not on MS-DOS.)

link (src, dst) -- function of module posix

Create a hard link pointing to src named dst. (Not on MS-DOS.)

listdir (path) -- function of module posix

Return a list containing the names of the entries in the directory. The list is in arbitrary order. It includes the special entries '.' and '..' if they are present in the directory.

lseek (fd, pos, how) -- function of module posix

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.

lstat (path) -- function of module posix

Like stat(), but do not follow symbolic links. (On systems without symbolic links, this is identical to posix.stat.)

mkdir (path, mode) -- function of module posix

Create a directory named path with numeric mode mode.

nice (increment) -- function of module posix

Add incr to the process' ``niceness''. Return the new niceness. (Not on MS-DOS.)

open (file, flags, mode) -- function of module posix

Open the file file and set various flags according to flags and possibly its mode according to mode. Return the file descriptor for the newly opened file.

pipe () -- function of module posix

Create a pipe. Return a pair of file descriptors (r, w) usable for reading and writing, respectively. (Not on MS-DOS.)

popen (command, mode) -- function of module posix

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' or 'w'. (Not on MS-DOS.)

read (fd, n) -- function of module posix

Read at most n bytes from file descriptor fd. Return a string containing the bytes read.

readlink (path) -- function of module posix

Return a string representing the path to which the symbolic link points. (On systems without symbolic links, this always raises posix.error.)

rename (src, dst) -- function of module posix

Rename the file or directory src to dst.

rmdir (path) -- function of module posix

Remove the directory path.

setgid (gid) -- function of module posix

Set the current process's group id. (Not on MS-DOS.)

setuid (uid) -- function of module posix

Set the current process's user id. (Not on MS-DOS.)

stat (path) -- function of module posix

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-DOS, some items are filled with dummy values.)

Note: The standard module stat defines functions and constants that are useful for extracting information from a stat structure.

symlink (src, dst) -- function of module posix

Create a symbolic link pointing to src named dst. (On systems without symbolic links, this always raises posix.error.)

system (command) -- function of module posix

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 as returned by Standard C system().

times () -- function of module posix

Return a 4-tuple of floating point numbers indicating accumulated CPU times, in seconds. The items are: user time, system time, children's user time, and children's system time, in that order. See the UNIX manual page times(2). (Not on MS-DOS.)

umask (mask) -- function of module posix

Set the current numeric umask and returns the previous umask. (Not on MS-DOS.)

uname () -- function of module posix

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; an better way to get the hostname is socket.gethostname(). (Not on MS-DOS, nor on older UNIX systems.)

unlink (path) -- function of module posix

Unlink path.

utime (path, (atime, mtime)) -- function of module posix

Set the access and modified time of the file to the given values. (The second argument is a tuple of two items.)

wait () -- function of module posix

Wait for completion of a child process, and return a tuple containing its pid and exit status indication (encoded as by UNIX). (Not on MS-DOS.)

waitpid (pid, options) -- function of module posix

Wait for completion of a child process given by proces id, and return a tuple containing its pid and exit status indication (encoded as by UNIX). The semantics of the call are affected by the value of the integer options, which should be 0 for normal operation. (If the system does not support waitpid(), this always raises posix.error. Not on MS-DOS.)

write (fd, str) -- function of module posix

Write the string str to file descriptor fd. Return the number of bytes actually written.