open_file = open("file.txt", "r+b")
file_map = mmap.mmap(open_file, 0)
file_map.seek(offset)
file_map.write("foobar") # success
file_map.flush() # success
file_map.flush(offset, len("foobar")) # Fails with "errno 22"

This example passes correct arguments to mmap.flush(), yet it fails with errno 22. So the arguments are not valid on linux. If the bug cannot be fixed, then all reference to those two arguments should be removed from the code and documentation related to Linux.

offset must be a multiple of pagesize. This is a known but undocumented restriction on some platforms, see http://man7.org/linux/man-pages/man2/msync.2.html

I'm marking this as a low priority and simple documentation bug. The mmap module exposes the page size of the architecture as mmap.PAGESIZE.

Couldn't the implementation check the page size and throw a better error (for relevant platforms)? Or better yet, adjust the offset to the nearest inclusive page boundary.

Actually documented: 

http://man7.org/linux/man-pages/man2/msync.2.html

EINVAL: addr is not a multiple of PAGESIZE;

One thing to note is the behaviour seems fit implementation detail. POSIX doesn't requires this for both mmap and msync, it's optional:

The mmap( ) function may fail if:
[EINVAL] The addr argument (if MAP_FIXED was specified) or off is not a multiple of the page size as returned

The msync( ) function may fail if:
[EINVAL] The value of addr is not a multiple of the page size as returned by sysconf( ).

By the way, there is a note in the "Change History" section of the msync() documentation at http://pubs.opengroup.org/onlinepubs/9699919799/

    The second [EINVAL] error condition is made mandatory.

The second EINVAL error condition they mention is:

    [EINVAL] The value of addr is not a multiple of the page size as returned by sysconf().

So unless I'm missing something obvious, the "the msync() function may fail if" part may now be outdated?

Also, I noticed that we don't have tests for mm.flush(offset) and mm.flush(offset, size) cases. It would be nice to add some tests even if we decide to not merge the documentation PR.

New changeset 027664a3d5ebad575aafe5fcc572e3b05f7f24e5 by Victor Stinner (Pablo Galindo) in branch 'master':
bpo-32798: Add restriction on the offset parameter for mmap.flush in the docs (#5621)
https://github.com/python/cpython/commit/027664a3d5ebad575aafe5fcc572e3b05f7f24e5

New changeset 75ee130c39e73730535d94923fd8322ef616cb83 by Miss Islington (bot) in branch '3.6':
bpo-32798: Add restriction on the offset parameter for mmap.flush in the docs (GH-5621)
https://github.com/python/cpython/commit/75ee130c39e73730535d94923fd8322ef616cb83

New changeset 557a68789b97bf281aa7b7e96f083982c01a5f7e by Miss Islington (bot) in branch '3.7':
bpo-32798: Add restriction on the offset parameter for mmap.flush in the docs (GH-5621)
https://github.com/python/cpython/commit/557a68789b97bf281aa7b7e96f083982c01a5f7e

New changeset 2bad7acdfebb87a6eef238a7acca636cfb648a02 by Miss Islington (bot) in branch '2.7':
bpo-32798: Add restriction on the offset parameter for mmap.flush in the docs (GH-5621)
https://github.com/python/cpython/commit/2bad7acdfebb87a6eef238a7acca636cfb648a02

The documentation has been clarified, thanks Pablo Galindo!