[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / lib / module-mmap.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-anydbm.html" />
<link rel="prev" href="module-Queue.html" />
<link rel="parent" href="someos.html" />
<link rel="next" href="module-anydbm.html" />
<meta name='aesop' content='information' />
<title>7.9 mmap --
Memory-mapped file support</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.8.1 Queue Objects"
  href="QueueObjects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7. Optional Operating System"
  href="someos.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.10 anydbm  "
  href="module-anydbm.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="QueueObjects.html">7.8.1 Queue Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-anydbm.html">7.10 anydbm  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION009900000000000000000">
7.9 <tt class="module">mmap</tt> --
Memory-mapped file support</A>
</H1>

<P>
<A NAME="module-mmap"></A>

<P>
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 <tt class="module">re</tt> module to
search through a memory-mapped file.  Since they're mutable, you can
change a single character by doing <code>obj[<var>index</var>] = 'a'</code>, or
change a substring by assigning to a slice:
<code>obj[<var>i1</var>:<var>i2</var>] = '...'</code>.  You can also read and write
data starting at the current file position, and <tt class="method">seek()</tt>
through the file to different positions.

<P>
A memory-mapped file is created by the <tt class="function">mmap()</tt> function,
which is different on <span class="Unix">Unix</span> 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
<tt class="method">fileno()</tt> method to obtain the correct value for the
<var>fileno</var> parameter.  Otherwise, you can open the file using the
<tt class="function">os.open()</tt> function, which returns a file descriptor
directly (the file still needs to be closed when done).

<P>
For both the <span class="Unix">Unix</span> and Windows versions of the function,
<var>access</var> may be specified as an optional keyword parameter.
<var>access</var> accepts one of three values: <tt class="constant">ACCESS_READ</tt>,
<tt class="constant">ACCESS_WRITE</tt>, or <tt class="constant">ACCESS_COPY</tt> to specify
readonly, write-through or copy-on-write memory respectively.
<var>access</var> can be used on both <span class="Unix">Unix</span> and Windows.  If
<var>access</var> 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
<tt class="constant">ACCESS_READ</tt> memory map raises a <tt class="exception">TypeError</tt>
exception.  Assignment to an <tt class="constant">ACCESS_WRITE</tt> memory map
affects both memory and the underlying file.  Assignment to an
<tt class="constant">ACCESS_COPY</tt> memory map affects memory but does not update
the underlying file.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2763' xml:id='l2h-2763' class="function">mmap</tt></b>(</nobr></td>
  <td><var>fileno, length</var><big>[</big><var>, tagname</var><big>[</big><var>, access</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  <strong>(Windows version)</strong> Maps <var>length</var> bytes from the file
  specified by the file handle <var>fileno</var>, and returns a mmap
  object.  If <var>length</var> is larger than the current size of the file,
  the file is extended to contain <var>length</var> bytes.  If <var>length</var>
  is <code>0</code>, 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).

<P>
<var>tagname</var>, if specified and not <code>None</code>, 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</code>, the
  mapping is created without a name.  Avoiding the use of the tag
  parameter will assist in keeping your code portable between <span class="Unix">Unix</span>
  and Windows.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt class="function">mmap</tt></b>(</nobr></td>
  <td><var>fileno, length</var><big>[</big><var>, flags</var><big>[</big><var>,
                         prot</var><big>[</big><var>, access</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  <strong>(<span class="Unix">Unix</span> version)</strong> Maps <var>length</var> bytes from the file
  specified by the file descriptor <var>fileno</var>, and returns a mmap
  object.

<P>
<var>flags</var> specifies the nature of the mapping.
  <tt class="constant">MAP_PRIVATE</tt> creates a private copy-on-write mapping, so
  changes to the contents of the mmap object will be private to this
  process, and <tt class="constant">MAP_SHARED</tt> creates a mapping that's shared
  with all other processes mapping the same areas of the file.  The
  default value is <tt class="constant">MAP_SHARED</tt>.

<P>
<var>prot</var>, if specified, gives the desired memory protection; the
  two most useful values are <tt class="constant">PROT_READ</tt> and
  <tt class="constant">PROT_WRITE</tt>, to specify that the pages may be read or
  written.  <var>prot</var> defaults to <tt class="constant">PROT_READ | PROT_WRITE</tt>.

<P>
<var>access</var> may be specified in lieu of <var>flags</var> and <var>prot</var>
  as an optional keyword parameter.  It is an error to specify both
  <var>flags</var>, <var>prot</var> and <var>access</var>.  See the description of
  <var>access</var> above for information on how to use this parameter.
</dl>

<P>
Memory-mapped file objects support the following methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2764' xml:id='l2h-2764' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Close the file.  Subsequent calls to other methods of the object
  will result in an exception being raised.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2765' xml:id='l2h-2765' class="method">find</tt></b>(</nobr></td>
  <td><var>string</var><big>[</big><var>, start</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Returns the lowest index in the object where the substring
  <var>string</var> is found.  Returns <code>-1</code> on failure.  <var>start</var>
  is the index at which the search begins, and defaults to zero.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2766' xml:id='l2h-2766' class="method">flush</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>offset, size</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  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</var> and
  <var>size</var> are specified, only changes to the given range of bytes
  will be flushed to disk; otherwise, the whole extent of the mapping
  is flushed.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2767' xml:id='l2h-2767' class="method">move</tt></b>(</nobr></td>
  <td><var><var>dest</var>, <var>src</var>, <var>count</var></var>)</td></tr></table></dt>
<dd>
  Copy the <var>count</var> bytes starting at offset <var>src</var> to the
  destination index <var>dest</var>.  If the mmap was created with
  <tt class="constant">ACCESS_READ</tt>, then calls to move will throw a
  <tt class="exception">TypeError</tt> exception.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2768' xml:id='l2h-2768' class="method">read</tt></b>(</nobr></td>
  <td><var><var>num</var></var>)</td></tr></table></dt>
<dd>
  Return a string containing up to <var>num</var> bytes starting from the
  current file position; the file position is updated to point after the
  bytes that were returned.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2769' xml:id='l2h-2769' class="method">read_byte</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Returns a string of length 1 containing the character at the current
  file position, and advances the file position by 1.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2770' xml:id='l2h-2770' class="method">readline</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Returns a single line, starting at the current file position and up to
  the next newline.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2771' xml:id='l2h-2771' class="method">resize</tt></b>(</nobr></td>
  <td><var><var>newsize</var></var>)</td></tr></table></dt>
<dd>
  Resizes the map and the underlying file, if any.
  If the mmap was created with <tt class="constant">ACCESS_READ</tt> or
  <tt class="constant">ACCESS_COPY</tt>, resizing the map will throw a <tt class="exception">TypeError</tt> exception.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2772' xml:id='l2h-2772' class="method">seek</tt></b>(</nobr></td>
  <td><var>pos</var><big>[</big><var>, whence</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Set the file's current position.  <var>whence</var> argument is optional
  and defaults to <code>0</code> (absolute file positioning); other values
  are <code>1</code> (seek relative to the current position) and <code>2</code>
  (seek relative to the file's end).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2773' xml:id='l2h-2773' class="method">size</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the length of the file, which can be larger than the size of
  the memory-mapped area.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2774' xml:id='l2h-2774' class="method">tell</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Returns the current position of the file pointer.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2775' xml:id='l2h-2775' class="method">write</tt></b>(</nobr></td>
  <td><var><var>string</var></var>)</td></tr></table></dt>
<dd>
  Write the bytes in <var>string</var> 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
  <tt class="constant">ACCESS_READ</tt>, then writing to it will throw a
  <tt class="exception">TypeError</tt> exception.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2776' xml:id='l2h-2776' class="method">write_byte</tt></b>(</nobr></td>
  <td><var><var>byte</var></var>)</td></tr></table></dt>
<dd>
  Write the single-character string <var>byte</var> into memory at the
  current position of the file pointer; the file position is advanced
  by <code>1</code>.If the mmap was created with <tt class="constant">ACCESS_READ</tt>,
  then writing to it will throw a <tt class="exception">TypeError</tt> exception.
</dl>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.8.1 Queue Objects"
  href="QueueObjects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7. Optional Operating System"
  href="someos.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.10 anydbm  "
  href="module-anydbm.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="QueueObjects.html">7.8.1 Queue Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-anydbm.html">7.10 anydbm  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="module-anydbm.html" />
	13	<link rel="prev" href="module-Queue.html" />
	14	<link rel="parent" href="someos.html" />
	15	<link rel="next" href="module-anydbm.html" />
	16	<meta name='aesop' content='information' />
	17	<title>7.9 mmap --
	18	Memory-mapped file support</title>
	19	</head>
	20	<body>
	21	<DIV CLASS="navigation">
	22	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	23	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	24	<tr>
	25	<td class='online-navigation'><a rel="prev" title="7.8.1 Queue Objects"
	26	href="QueueObjects.html"><img src='../icons/previous.png'
	27	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	28	<td class='online-navigation'><a rel="parent" title="7. Optional Operating System"
	29	href="someos.html"><img src='../icons/up.png'
	30	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	31	<td class='online-navigation'><a rel="next" title="7.10 anydbm "
	32	href="module-anydbm.html"><img src='../icons/next.png'
	33	border='0' height='32' alt='Next Page' width='32' /></A></td>
	34	<td align="center" width="100%">Python Library Reference</td>
	35	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	36	href="contents.html"><img src='../icons/contents.png'
	37	border='0' height='32' alt='Contents' width='32' /></A></td>
	38	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	39	border='0' height='32' alt='Module Index' width='32' /></a></td>
	40	<td class='online-navigation'><a rel="index" title="Index"
	41	href="genindex.html"><img src='../icons/index.png'
	42	border='0' height='32' alt='Index' width='32' /></A></td>
	43	</tr></table>
	44	<div class='online-navigation'>
	45	<b class="navlabel">Previous:</b>
	46	<a class="sectref" rel="prev" href="QueueObjects.html">7.8.1 Queue Objects</A>
	47	<b class="navlabel">Up:</b>
	48	<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
	49	<b class="navlabel">Next:</b>
	50	<a class="sectref" rel="next" href="module-anydbm.html">7.10 anydbm </A>
	51	</div>
	52	<hr /></div>
	53	</DIV>
	54	<!--End of Navigation Panel-->
	55
	56	<H1><A NAME="SECTION009900000000000000000">
	57	7.9 <tt class="module">mmap</tt> --
	58	Memory-mapped file support</A>
	59	</H1>
	60
	61	<P>
	62	<A NAME="module-mmap"></A>
	63
	64	<P>
65	Memory-mapped file objects behave like both strings and like
66	file objects. Unlike normal string objects, however, these are
67	mutable. You can use mmap objects in most places where strings
68	are expected; for example, you can use the <tt class="module">re</tt> module to
69	search through a memory-mapped file. Since they're mutable, you can
70	change a single character by doing <code>obj[<var>index</var>] = 'a'</code>, or
71	change a substring by assigning to a slice:
72	<code>obj[<var>i1</var>:<var>i2</var>] = '...'</code>. You can also read and write
73	data starting at the current file position, and <tt class="method">seek()</tt>
74	through the file to different positions.
75
76	<P>
77	A memory-mapped file is created by the <tt class="function">mmap()</tt> function,
78	which is different on <span class="Unix">Unix</span> and on Windows. In either case you must
79	provide a file descriptor for a file opened for update.
80	If you wish to map an existing Python file object, use its
81	<tt class="method">fileno()</tt> method to obtain the correct value for the
82	<var>fileno</var> parameter. Otherwise, you can open the file using the
83	<tt class="function">os.open()</tt> function, which returns a file descriptor
84	directly (the file still needs to be closed when done).
85
86	<P>
87	For both the <span class="Unix">Unix</span> and Windows versions of the function,
88	<var>access</var> may be specified as an optional keyword parameter.
89	<var>access</var> accepts one of three values: <tt class="constant">ACCESS_READ</tt>,
90	<tt class="constant">ACCESS_WRITE</tt>, or <tt class="constant">ACCESS_COPY</tt> to specify
91	readonly, write-through or copy-on-write memory respectively.
92	<var>access</var> can be used on both <span class="Unix">Unix</span> and Windows. If
93	<var>access</var> is not specified, Windows mmap returns a write-through
94	mapping. The initial memory values for all three access types are
95	taken from the specified file. Assignment to an
96	<tt class="constant">ACCESS_READ</tt> memory map raises a <tt class="exception">TypeError</tt>
97	exception. Assignment to an <tt class="constant">ACCESS_WRITE</tt> memory map
98	affects both memory and the underlying file. Assignment to an
99	<tt class="constant">ACCESS_COPY</tt> memory map affects memory but does not update
100	the underlying file.
101
102	<P>
103	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
104	<td><nobr><b><tt id='l2h-2763' xml:id='l2h-2763' class="function">mmap</tt></b>(</nobr></td>
105	<td><var>fileno, length</var><big>[</big><var>, tagname</var><big>[</big><var>, access</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
106	<dd>
107	<strong>(Windows version)</strong> Maps <var>length</var> bytes from the file
108	specified by the file handle <var>fileno</var>, and returns a mmap
109	object. If <var>length</var> is larger than the current size of the file,
110	the file is extended to contain <var>length</var> bytes. If <var>length</var>
111	is <code>0</code>, the maximum length of the map is the current size
112	of the file, except that if the file is empty Windows raises an
113	exception (you cannot create an empty mapping on Windows).
114
115	<P>
116	<var>tagname</var>, if specified and not <code>None</code>, is a string giving
117	a tag name for the mapping. Windows allows you to have many
118	different mappings against the same file. If you specify the name
119	of an existing tag, that tag is opened, otherwise a new tag of this
120	name is created. If this parameter is omitted or <code>None</code>, the
121	mapping is created without a name. Avoiding the use of the tag
122	parameter will assist in keeping your code portable between <span class="Unix">Unix</span>
123	and Windows.
124	</dl>
125
126	<P>
127	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
128	<td><nobr><b><tt class="function">mmap</tt></b>(</nobr></td>
129	<td><var>fileno, length</var><big>[</big><var>, flags</var><big>[</big><var>,
130	prot</var><big>[</big><var>, access</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
131	<dd>
132	<strong>(<span class="Unix">Unix</span> version)</strong> Maps <var>length</var> bytes from the file
133	specified by the file descriptor <var>fileno</var>, and returns a mmap
134	object.
135
136	<P>
137	<var>flags</var> specifies the nature of the mapping.
138	<tt class="constant">MAP_PRIVATE</tt> creates a private copy-on-write mapping, so
139	changes to the contents of the mmap object will be private to this
140	process, and <tt class="constant">MAP_SHARED</tt> creates a mapping that's shared
141	with all other processes mapping the same areas of the file. The
142	default value is <tt class="constant">MAP_SHARED</tt>.
143
144	<P>
145	<var>prot</var>, if specified, gives the desired memory protection; the
146	two most useful values are <tt class="constant">PROT_READ</tt> and
147	<tt class="constant">PROT_WRITE</tt>, to specify that the pages may be read or
148	written. <var>prot</var> defaults to <tt class="constant">PROT_READ \| PROT_WRITE</tt>.
149
150	<P>
151	<var>access</var> may be specified in lieu of <var>flags</var> and <var>prot</var>
152	as an optional keyword parameter. It is an error to specify both
153	<var>flags</var>, <var>prot</var> and <var>access</var>. See the description of
154	<var>access</var> above for information on how to use this parameter.
155	</dl>
156
157	<P>
158	Memory-mapped file objects support the following methods:
159
160	<P>
161	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
162	<td><nobr><b><tt id='l2h-2764' xml:id='l2h-2764' class="method">close</tt></b>(</nobr></td>
163	<td><var></var>)</td></tr></table></dt>
164	<dd>
165	Close the file. Subsequent calls to other methods of the object
166	will result in an exception being raised.
167	</dl>
168
169	<P>
170	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
171	<td><nobr><b><tt id='l2h-2765' xml:id='l2h-2765' class="method">find</tt></b>(</nobr></td>
172	<td><var>string</var><big>[</big><var>, start</var><big>]</big><var></var>)</td></tr></table></dt>
173	<dd>
174	Returns the lowest index in the object where the substring
175	<var>string</var> is found. Returns <code>-1</code> on failure. <var>start</var>
176	is the index at which the search begins, and defaults to zero.
177	</dl>
178
179	<P>
180	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
181	<td><nobr><b><tt id='l2h-2766' xml:id='l2h-2766' class="method">flush</tt></b>(</nobr></td>
182	<td><var></var><big>[</big><var>offset, size</var><big>]</big><var></var>)</td></tr></table></dt>
183	<dd>
184	Flushes changes made to the in-memory copy of a file back to disk.
185	Without use of this call there is no guarantee that changes are
186	written back before the object is destroyed. If <var>offset</var> and
187	<var>size</var> are specified, only changes to the given range of bytes
188	will be flushed to disk; otherwise, the whole extent of the mapping
189	is flushed.
190	</dl>
191
192	<P>
193	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
194	<td><nobr><b><tt id='l2h-2767' xml:id='l2h-2767' class="method">move</tt></b>(</nobr></td>
195	<td><var><var>dest</var>, <var>src</var>, <var>count</var></var>)</td></tr></table></dt>
196	<dd>
197	Copy the <var>count</var> bytes starting at offset <var>src</var> to the
198	destination index <var>dest</var>. If the mmap was created with
199	<tt class="constant">ACCESS_READ</tt>, then calls to move will throw a
200	<tt class="exception">TypeError</tt> exception.
201	</dl>
202
203	<P>
204	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
205	<td><nobr><b><tt id='l2h-2768' xml:id='l2h-2768' class="method">read</tt></b>(</nobr></td>
206	<td><var><var>num</var></var>)</td></tr></table></dt>
207	<dd>
208	Return a string containing up to <var>num</var> bytes starting from the
209	current file position; the file position is updated to point after the
210	bytes that were returned.
211	</dl>
212
213	<P>
214	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
215	<td><nobr><b><tt id='l2h-2769' xml:id='l2h-2769' class="method">read_byte</tt></b>(</nobr></td>
216	<td><var></var>)</td></tr></table></dt>
217	<dd>
218	Returns a string of length 1 containing the character at the current
219	file position, and advances the file position by 1.
220	</dl>
221
222	<P>
223	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
224	<td><nobr><b><tt id='l2h-2770' xml:id='l2h-2770' class="method">readline</tt></b>(</nobr></td>
225	<td><var></var>)</td></tr></table></dt>
226	<dd>
227	Returns a single line, starting at the current file position and up to
228	the next newline.
229	</dl>
230
231	<P>
232	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
233	<td><nobr><b><tt id='l2h-2771' xml:id='l2h-2771' class="method">resize</tt></b>(</nobr></td>
234	<td><var><var>newsize</var></var>)</td></tr></table></dt>
235	<dd>
236	Resizes the map and the underlying file, if any.
237	If the mmap was created with <tt class="constant">ACCESS_READ</tt> or
238	<tt class="constant">ACCESS_COPY</tt>, resizing the map will throw a <tt class="exception">TypeError</tt> exception.
239	</dl>
240
241	<P>
242	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
243	<td><nobr><b><tt id='l2h-2772' xml:id='l2h-2772' class="method">seek</tt></b>(</nobr></td>
244	<td><var>pos</var><big>[</big><var>, whence</var><big>]</big><var></var>)</td></tr></table></dt>
245	<dd>
246	Set the file's current position. <var>whence</var> argument is optional
247	and defaults to <code>0</code> (absolute file positioning); other values
248	are <code>1</code> (seek relative to the current position) and <code>2</code>
249	(seek relative to the file's end).
250	</dl>
251
252	<P>
253	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
254	<td><nobr><b><tt id='l2h-2773' xml:id='l2h-2773' class="method">size</tt></b>(</nobr></td>
255	<td><var></var>)</td></tr></table></dt>
256	<dd>
257	Return the length of the file, which can be larger than the size of
258	the memory-mapped area.
259	</dl>
260
261	<P>
262	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
263	<td><nobr><b><tt id='l2h-2774' xml:id='l2h-2774' class="method">tell</tt></b>(</nobr></td>
264	<td><var></var>)</td></tr></table></dt>
265	<dd>
266	Returns the current position of the file pointer.
267	</dl>
268
269	<P>
270	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
271	<td><nobr><b><tt id='l2h-2775' xml:id='l2h-2775' class="method">write</tt></b>(</nobr></td>
272	<td><var><var>string</var></var>)</td></tr></table></dt>
273	<dd>
274	Write the bytes in <var>string</var> into memory at the current position
275	of the file pointer; the file position is updated to point after the
276	bytes that were written. If the mmap was created with
277	<tt class="constant">ACCESS_READ</tt>, then writing to it will throw a
278	<tt class="exception">TypeError</tt> exception.
279	</dl>
280
281	<P>
282	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
283	<td><nobr><b><tt id='l2h-2776' xml:id='l2h-2776' class="method">write_byte</tt></b>(</nobr></td>
284	<td><var><var>byte</var></var>)</td></tr></table></dt>
285	<dd>
286	Write the single-character string <var>byte</var> into memory at the
287	current position of the file pointer; the file position is advanced
288	by <code>1</code>.If the mmap was created with <tt class="constant">ACCESS_READ</tt>,
289	then writing to it will throw a <tt class="exception">TypeError</tt> exception.
290	</dl>
291
292	<DIV CLASS="navigation">
293	<div class='online-navigation'>
294	<p></p><hr />
295	<table align="center" width="100%" cellpadding="0" cellspacing="2">
296	<tr>
297	<td class='online-navigation'><a rel="prev" title="7.8.1 Queue Objects"
298	href="QueueObjects.html"><img src='../icons/previous.png'
299	border='0' height='32' alt='Previous Page' width='32' /></A></td>
300	<td class='online-navigation'><a rel="parent" title="7. Optional Operating System"
301	href="someos.html"><img src='../icons/up.png'
302	border='0' height='32' alt='Up One Level' width='32' /></A></td>
303	<td class='online-navigation'><a rel="next" title="7.10 anydbm "
304	href="module-anydbm.html"><img src='../icons/next.png'
305	border='0' height='32' alt='Next Page' width='32' /></A></td>
306	<td align="center" width="100%">Python Library Reference</td>
307	<td class='online-navigation'><a rel="contents" title="Table of Contents"
308	href="contents.html"><img src='../icons/contents.png'
309	border='0' height='32' alt='Contents' width='32' /></A></td>
310	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
311	border='0' height='32' alt='Module Index' width='32' /></a></td>
312	<td class='online-navigation'><a rel="index" title="Index"
313	href="genindex.html"><img src='../icons/index.png'
314	border='0' height='32' alt='Index' width='32' /></A></td>
315	</tr></table>
316	<div class='online-navigation'>
317	<b class="navlabel">Previous:</b>
318	<a class="sectref" rel="prev" href="QueueObjects.html">7.8.1 Queue Objects</A>
319	<b class="navlabel">Up:</b>
320	<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
321	<b class="navlabel">Next:</b>
322	<a class="sectref" rel="next" href="module-anydbm.html">7.10 anydbm </A>
323	</div>
324	</div>
325	<hr />
326	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
327	</DIV>
328	<!--End of Navigation Panel-->
329	<ADDRESS>
330	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
331	</ADDRESS>
332	</BODY>
333	</HTML>