Memory-mapped file objects behave like bothbytearray and likefile objects. You can use mmap objects in most placeswherebytearray are expected; for example, you can use theremodule to search through a memory-mapped file. You can also change a singlebyte by doingobj[index]=97, or change a subsequence by assigning to aslice:obj[i1:i2]=b'...'. You can also read and write data starting atthe current file position, andseek() through the file to different positions.
A memory-mapped file is created by themmap constructor, which isdifferent on Unix and on Windows. In either case you must provide a filedescriptor for a file opened for update. If you wish to map an existing Pythonfile object, use itsfileno() method to obtain the correct value for thefileno parameter. Otherwise, you can open the file using theos.open() function, which returns a file descriptor directly (the filestill needs to be closed when done).
Note
If you want to create a memory-mapping for a writable, buffered file, youshouldflush() the file first. This is necessary to ensurethat local modifications to the buffers are actually available to themapping.
For both the Unix and Windows versions of the constructor,access may bespecified as an optional keyword parameter.access accepts one of threevalues:ACCESS_READ,ACCESS_WRITE, orACCESS_COPYto specify read-only, write-through or copy-on-write memory respectively.access can be used on both Unix and Windows. Ifaccess is not specified,Windows mmap returns a write-through mapping. The initial memory values forall three access types are taken from the specified file. Assignment to anACCESS_READ memory map raises aTypeError exception.Assignment to anACCESS_WRITE memory map affects both memory and theunderlying file. Assignment to anACCESS_COPY memory map affectsmemory but does not update the underlying file.
To map anonymous memory, -1 should be passed as the fileno along with the length.
(Windows version) Mapslength bytes from the file specified by thefile handlefileno, and creates a mmap object. Iflength is largerthan the current size of the file, the file is extended to containlengthbytes. Iflength is0, the maximum length of the map is the currentsize of the file, except that if the file is empty Windows raises anexception (you cannot create an empty mapping on Windows).
tagname, if specified and notNone, is a string giving a tag name forthe mapping. Windows allows you to have many different mappings againstthe same file. If you specify the name of an existing tag, that tag isopened, otherwise a new tag of this name is created. If this parameter isomitted orNone, the mapping is created without a name. Avoiding theuse of the tag parameter will assist in keeping your code portable betweenUnix and Windows.
offset may be specified as a non-negative integer offset. mmap referenceswill be relative to the offset from the beginning of the file.offsetdefaults to 0.offset must be a multiple of the ALLOCATIONGRANULARITY.
(Unix version) Mapslength bytes from the file specified by the filedescriptorfileno, and returns a mmap object. Iflength is0, themaximum length of the map will be the current size of the file whenmmap is called.
flags specifies the nature of the mapping.MAP_PRIVATE creates aprivate copy-on-write mapping, so changes to the contents of the mmapobject will be private to this process, andMAP_SHARED creates amapping that’s shared with all other processes mapping the same areas ofthe file. The default value isMAP_SHARED.
prot, if specified, gives the desired memory protection; the two mostuseful values arePROT_READ andPROT_WRITE, to specifythat the pages may be read or written.prot defaults toPROT_READ|PROT_WRITE.
access may be specified in lieu offlags andprot as an optionalkeyword parameter. It is an error to specify bothflags,prot andaccess. See the description ofaccess above for information on how touse this parameter.
offset may be specified as a non-negative integer offset. mmap referenceswill be relative to the offset from the beginning of the file.offsetdefaults to 0.offset must be a multiple of the PAGESIZE orALLOCATIONGRANULARITY.
To ensure validity of the created memory mapping the file specifiedby the descriptorfileno is internally automatically synchronizedwith physical backing store on Mac OS X and OpenVMS.
This example shows a simple way of usingmmap:
importmmap# write a simple example filewithopen("hello.txt","wb")asf:f.write(b"Hello Python!\n")withopen("hello.txt","r+b")asf:# memory-map the file, size 0 means whole filemm=mmap.mmap(f.fileno(),0)# read content via standard file methodsprint(mm.readline())# prints b"Hello Python!\n"# read content via slice notationprint(mm[:5])# prints b"Hello"# update content using slice notation;# note that new content must have same sizemm[6:]=b" world!\n"# ... and read again using standard file methodsmm.seek(0)print(mm.readline())# prints b"Hello world!\n"# close the mapmm.close()
mmap can also be used as a context manager in awithstatement.:
importmmapwithmmap.mmap(-1,13)asmm:mm.write("Hello world!")
New in version 3.2:Context manager support.
The next example demonstrates how to create an anonymous map and exchangedata between the parent and child processes:
importmmapimportosmm=mmap.mmap(-1,13)mm.write(b"Hello world!")pid=os.fork()ifpid==0:# In a child processmm.seek(0)print(mm.readline())mm.close()
Memory-mapped file objects support the following methods:
Closes the mmap. Subsequent calls to other methods of the object willresult in a ValueError exception being raised. This will not closethe open file.
True if the file is closed.
New in version 3.2.
Returns the lowest index in the object where the subsequencesub isfound, such thatsub is contained in the range [start,end].Optional argumentsstart andend are interpreted as in slice notation.Returns-1 on failure.
Flushes changes made to the in-memory copy of a file back to disk. Withoutuse of this call there is no guarantee that changes are written back beforethe object is destroyed. Ifoffset andsize are specified, onlychanges to the given range of bytes will be flushed to disk; otherwise, thewhole extent of the mapping is flushed.
(Windows version) A nonzero value returned indicates success; zeroindicates failure.
(Unix version) A zero value is returned to indicate success. Anexception is raised when the call failed.
Copy thecount bytes starting at offsetsrc to the destination indexdest. If the mmap was created withACCESS_READ, then calls tomove will raise aTypeError exception.
Return abytes containing up ton bytes starting from thecurrent file position. If the argument is omitted,None or negative,return all bytes from the current file position to the end of themapping. The file position is updated to point after the bytes that werereturned.
Changed in version 3.3:Argument can be omitted orNone.
Returns a byte at the current file position as an integer, and advancesthe file position by 1.
Returns a single line, starting at the current file position and up to thenext newline.
Resizes the map and the underlying file, if any. If the mmap was createdwithACCESS_READ orACCESS_COPY, resizing the map willraise aTypeError exception.
Returns the highest index in the object where the subsequencesub isfound, such thatsub is contained in the range [start,end].Optional argumentsstart andend are interpreted as in slice notation.Returns-1 on failure.
Set the file’s current position.whence argument is optional anddefaults toos.SEEK_SET or0 (absolute file positioning); othervalues areos.SEEK_CUR or1 (seek relative to the currentposition) andos.SEEK_END or2 (seek relative to the file’s end).
Return the length of the file, which can be larger than the size of thememory-mapped area.
Returns the current position of the file pointer.
18.5.signal — Set handlers for asynchronous events
Enter search terms or a module, class or function name.
