add hg and python

1 files changed, 171 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libmmap.tex b/sys/src/cmd/python/Doc/lib/libmmap.tex
new file mode 100644
index 000000000..3763d4f84
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libmmap.tex
@@ -0,0 +1,171 @@
+\section{\module{mmap} ---
+Memory-mapped file support}
+
+\declaremodule{builtin}{mmap}
+\modulesynopsis{Interface to memory-mapped files for \UNIX\ and Windows.}
+
+Memory-mapped file objects behave like both strings and like
+file objects.  Unlike normal string objects, however, these are
+mutable.  You can use mmap objects in most places where strings
+are expected; for example, you can use the \module{re} module to
+search through a memory-mapped file.  Since they're mutable, you can
+change a single character by doing \code{obj[\var{index}] = 'a'}, or
+change a substring by assigning to a slice:
+\code{obj[\var{i1}:\var{i2}] = '...'}.  You can also read and write
+data starting at the current file position, and \method{seek()}
+through the file to different positions.
+
+A memory-mapped file is created by the \function{mmap()} function,
+which is different on \UNIX{} and on Windows.  In either case you must
+provide a file descriptor for a file opened for update.
+If you wish to map an existing Python file object, use its
+\method{fileno()} method to obtain the correct value for the
+\var{fileno} parameter.  Otherwise, you can open the file using the
+\function{os.open()} function, which returns a file descriptor
+directly (the file still needs to be closed when done).
+
+For both the \UNIX{} and Windows versions of the function,
+\var{access} may be specified as an optional keyword parameter.
+\var{access} accepts one of three values: \constant{ACCESS_READ},
+\constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify
+readonly, write-through or copy-on-write memory respectively.
+\var{access} can be used on both \UNIX{} and Windows.  If
+\var{access} is not specified, Windows mmap returns a write-through
+mapping.  The initial memory values for all three access types are
+taken from the specified file.  Assignment to an
+\constant{ACCESS_READ} memory map raises a \exception{TypeError}
+exception.  Assignment to an \constant{ACCESS_WRITE} memory map
+affects both memory and the underlying file.  Assignment to an
+\constant{ACCESS_COPY} memory map affects memory but does not update
+the underlying file.  \versionchanged[To map anonymous memory,
+-1 should be passed as the fileno along with the length]{2.5}
+
+\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
+  \strong{(Windows version)} Maps \var{length} bytes from the file
+  specified by the file handle \var{fileno}, and returns a mmap
+  object.  If \var{length} is larger than the current size of the file,
+  the file is extended to contain \var{length} bytes.  If \var{length}
+  is \code{0}, the maximum length of the map is the current size
+  of the file, except that if the file is empty Windows raises an
+  exception (you cannot create an empty mapping on Windows).
+
+  \var{tagname}, if specified and not \code{None}, is a string giving
+  a tag name for the mapping.  Windows allows you to have many
+  different mappings against the same file.  If you specify the name
+  of an existing tag, that tag is opened, otherwise a new tag of this
+  name is created.  If this parameter is omitted or \code{None}, the
+  mapping is created without a name.  Avoiding the use of the tag
+  parameter will assist in keeping your code portable between \UNIX{}
+  and Windows.
+\end{funcdesc}
+
+\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
+                         prot\optional{, access}}}}
+  \strong{(\UNIX{} version)} Maps \var{length} bytes from the file
+  specified by the file descriptor \var{fileno}, and returns a mmap
+  object.  If \var{length} is \code{0}, the maximum length of the map
+  will be the current size of the file when \function{mmap()} is
+  called.
+  
+  \var{flags} specifies the nature of the mapping.
+  \constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
+  changes to the contents of the mmap object will be private to this
+  process, and \constant{MAP_SHARED} creates a mapping that's shared
+  with all other processes mapping the same areas of the file.  The
+  default value is \constant{MAP_SHARED}.
+
+  \var{prot}, if specified, gives the desired memory protection; the
+  two most useful values are \constant{PROT_READ} and
+  \constant{PROT_WRITE}, to specify that the pages may be read or
+  written.  \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
+
+  \var{access} may be specified in lieu of \var{flags} and \var{prot}
+  as an optional keyword parameter.  It is an error to specify both
+  \var{flags}, \var{prot} and \var{access}.  See the description of
+  \var{access} above for information on how to use this parameter.
+\end{funcdescni}
+
+
+Memory-mapped file objects support the following methods:
+
+
+\begin{methoddesc}{close}{}
+  Close the file.  Subsequent calls to other methods of the object
+  will result in an exception being raised.
+\end{methoddesc}
+
+\begin{methoddesc}{find}{string\optional{, start}}
+  Returns the lowest index in the object where the substring
+  \var{string} is found.  Returns \code{-1} on failure.  \var{start}
+  is the index at which the search begins, and defaults to zero.
+\end{methoddesc}
+
+\begin{methoddesc}{flush}{\optional{offset, size}}
+  Flushes changes made to the in-memory copy of a file back to disk.
+  Without use of this call there is no guarantee that changes are
+  written back before the object is destroyed.  If \var{offset} and
+  \var{size} are specified, only changes to the given range of bytes
+  will be flushed to disk; otherwise, the whole extent of the mapping
+  is flushed.
+\end{methoddesc}
+
+\begin{methoddesc}{move}{\var{dest}, \var{src}, \var{count}}
+  Copy the \var{count} bytes starting at offset \var{src} to the
+  destination index \var{dest}.  If the mmap was created with
+  \constant{ACCESS_READ}, then calls to move will throw a
+  \exception{TypeError} exception.
+\end{methoddesc}
+
+\begin{methoddesc}{read}{\var{num}}
+  Return a string containing up to \var{num} bytes starting from the
+  current file position; the file position is updated to point after the
+  bytes that were returned.
+\end{methoddesc}
+
+\begin{methoddesc}{read_byte}{}
+  Returns a string of length 1 containing the character at the current
+  file position, and advances the file position by 1.
+\end{methoddesc}
+
+\begin{methoddesc}{readline}{}
+  Returns a single line, starting at the current file position and up to
+  the next newline.
+\end{methoddesc}
+
+\begin{methoddesc}{resize}{\var{newsize}}
+  Resizes the map and the underlying file, if any.
+  If the mmap was created with \constant{ACCESS_READ} or
+  \constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
+\end{methoddesc}
+
+\begin{methoddesc}{seek}{pos\optional{, whence}}
+  Set the file's current position.  \var{whence} argument is optional
+  and defaults to \code{os.SEEK_SET} or \code{0} (absolute file
+  positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek
+  relative to the current position) and \code{os.SEEK_END} or \code{2}
+  (seek relative to the file's end).
+\end{methoddesc}
+
+\begin{methoddesc}{size}{}
+  Return the length of the file, which can be larger than the size of
+  the memory-mapped area.
+\end{methoddesc}
+
+\begin{methoddesc}{tell}{}
+  Returns the current position of the file pointer.
+\end{methoddesc}
+
+\begin{methoddesc}{write}{\var{string}}
+  Write the bytes in \var{string} into memory at the current position
+  of the file pointer; the file position is updated to point after the
+  bytes that were written. If the mmap was created with
+  \constant{ACCESS_READ}, then writing to it will throw a
+  \exception{TypeError} exception.
+\end{methoddesc}
+
+\begin{methoddesc}{write_byte}{\var{byte}}
+  Write the single-character string \var{byte} into memory at the
+  current position of the file pointer; the file position is advanced
+  by \code{1}. If the mmap was created with \constant{ACCESS_READ},
+  then writing to it will throw a \exception{TypeError} exception.
+\end{methoddesc}