NetBSD/lib/libc/sys/msync.2

.\"	$NetBSD: msync.2,v 1.20 2003/04/16 13:34:55 wiz Exp $
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)msync.2	8.2 (Berkeley) 6/21/94
.\"
.Dd August 11, 2002
.Dt MSYNC 2
.Os
.Sh NAME
.Nm msync
.Nd synchronize a mapped region
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/mman.h
.Ft int
.Fn msync "void *addr" "size_t len" "int flags"
.Sh DESCRIPTION
The
.Fn msync
system call writes all pages with shared modifications
in the specified
region of the process's address space back to permanent
storage, and, if requested, invalidates cached data mapped
in the region.
If
.Fa len
is 0, all modified pages within the region containing
.Fa addr
will be flushed;
if
.Fa len
is non-zero, only modified pages containing
.Fa addr
and
.Fa len
succeeding locations will be flushed.
Any required synchronization of memory caches
will also take place at this time.
Filesystem operations on a file that is mapped for shared modifications
are unpredictable except after an
.Fn msync .
.Pp
The
.Fa flags
argument is formed by
.Em or Ns 'ing
the following values
.Pp
.Bl -column -offset indent -compact MS_INVALIDATE
.It Dv MS_ASYNC Ta Perform asynchronous writes.
.It Dv MS_SYNC Ta Perform synchronous writes.
.It Dv MS_INVALIDATE Ta Invalidate cached data after writing.
.El
.Sh RETURN VALUES
Upon successful completion,
a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The following errors may be reported:
.Bl -tag -width Er
.It Bq Er EBUSY
The
.Dv MS_INVALIDATE
flag was specified and a portion of the specified region
was locked with
.Xr mlock 2 .
.It Bq Er EINVAL
The specified
.Fa flags
argument was invalid.
.It Bq Er EINVAL
The
.Fa addr
parameter was not page aligned.
.It Bq Er EINVAL
The
.Fa addr
parameter did not specify an address part of a mapped region.
.It Bq Er EINVAL
The
.Fa len
parameter was negative.
.It Bq Er EIO
An I/O error occurred while writing to the file system.
.It Bq Er ENOMEM
Addresses in the specified region are outside the range allowed
for the address space of the process, or specify one or more pages
which are unmapped.
.El
.Sh SEE ALSO
.Xr mlock 2 ,
.Xr mmap 2 ,
.Xr munlock 2
.Sh HISTORY
The
.Fn msync
function first appeared in
.Bx 4.4 .
It was modified to conform to
.St -p1003.1b-93
in
.Nx 1.3 .
.Sh BUGS
Writes are currently done synchronously even if the
.Dv MS_ASYNC
flag is specified.
Use .In header.h instead of .Fd #include \[Lt]header.h\[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross. 2003-04-16 17:34:34 +04:00			`.\" $NetBSD: msync.2,v 1.20 2003/04/16 13:34:55 wiz Exp $`
clean up RCS Id's 1995-02-27 13:41:36 +03:00			`.\"`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`.\" Copyright (c) 1991, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
initial import of 386bsd-0.1 sources 1993-03-21 12:45:37 +03:00			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
			`.\" 3. All advertising materials mentioning features or use of this software`
			`.\" must display the following acknowledgement:`
			`.\" This product includes software developed by the University of`
			`.\" California, Berkeley and its contributors.`
			`.\" 4. Neither the name of the University nor the names of its contributors`
			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
			`.\"`
merge lite-2 1998-02-02 08:20:24 +03:00			`.\" @(#)msync.2 8.2 (Berkeley) 6/21/94`
initial import of 386bsd-0.1 sources 1993-03-21 12:45:37 +03:00			`.\"`
add RETURN VALUES section. from OpenBSD. 2002-08-11 18:44:33 +04:00			`.Dd August 11, 2002`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Dt MSYNC 2`
Last of the .Os cleanups. .Os is defined in the tmac.doc-common file, so we shouldn't override it with versions in the manpages. Wheee! 1999-03-22 22:44:33 +03:00			`.Os`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Sh NAME`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`.Nm msync`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Nd synchronize a mapped region`
Add a LIBRARY section to system call manual pages. While it's clear that the libraries contain stubs only (with minor exceptions a la pipe(2)), the purpose of this section is to provide linkage information. 1999-12-03 00:42:35 +03:00			`.Sh LIBRARY`
			`.Lb libc`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Sh SYNOPSIS`
Use .In header.h instead of .Fd #include \[Lt]header.h\[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross. 2003-04-16 17:34:34 +04:00			`.In sys/mman.h`
Manpage fixes from Jochen Pohl. Aligns the prototypes in the SYNOPSIS section with the actual function declarations. See PR #1589 for details. 1995-10-12 18:40:27 +03:00			`.Ft int`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.Fn msync "void *addr" "size_t len" "int flags"`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Sh DESCRIPTION`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`The`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fn msync`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`system call writes all pages with shared modifications`
			`in the specified`
			`region of the process's address space back to permanent`
			`storage, and, if requested, invalidates cached data mapped`
			`in the region.`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`If`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fa len`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`is 0, all modified pages within the region containing`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fa addr`
initial import of 386bsd-0.1 sources 1993-03-21 12:45:37 +03:00			`will be flushed;`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`if`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fa len`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`is non-zero, only modified pages containing`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fa addr`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`and`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fa len`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`succeeding locations will be flushed.`
initial import of 386bsd-0.1 sources 1993-03-21 12:45:37 +03:00			`Any required synchronization of memory caches`
			`will also take place at this time.`
			`Filesystem operations on a file that is mapped for shared modifications`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`are unpredictable except after an`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Fn msync .`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.Pp`
			`The`
			`.Fa flags`
			`argument is formed by`
			`.Em or Ns 'ing`
			`the following values`
			`.Pp`
Missing .El. Rewrite cheap .Bd -literal as a nice .Bl -column. 1999-03-09 06:49:46 +03:00			`.Bl -column -offset indent -compact MS_INVALIDATE`
			`.It Dv MS_ASYNC Ta Perform asynchronous writes.`
			`.It Dv MS_SYNC Ta Perform synchronous writes.`
			`.It Dv MS_INVALIDATE Ta Invalidate cached data after writing.`
			`.El`
add RETURN VALUES section. from OpenBSD. 2002-08-11 18:44:33 +04:00			`.Sh RETURN VALUES`
			`Upon successful completion,`
			`a value of 0 is returned.`
			`Otherwise, a value of -1 is returned and`
			`.Va errno`
			`is set to indicate the error.`
Changes by Thorsten Lockert and myself (though my role was only minor) to document msync's error returns. 1994-06-21 08:49:04 +04:00			`.Sh ERRORS`
			`The following errors may be reported:`
			`.Bl -tag -width Er`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.It Bq Er EBUSY`
Changes by Thorsten Lockert and myself (though my role was only minor) to document msync's error returns. 1994-06-21 08:49:04 +04:00			`The`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.Dv MS_INVALIDATE`
			`flag was specified and a portion of the specified region`
			`was locked with`
			`.Xr mlock 2 .`
Changes by Thorsten Lockert and myself (though my role was only minor) to document msync's error returns. 1994-06-21 08:49:04 +04:00			`.It Bq Er EINVAL`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`The specified`
			`.Fa flags`
			`argument was invalid.`
Changes by Thorsten Lockert and myself (though my role was only minor) to document msync's error returns. 1994-06-21 08:49:04 +04:00			`.It Bq Er EINVAL`
			`The`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.Fa addr`
			`parameter was not page aligned.`
merge lite-2 1998-02-02 08:20:24 +03:00			`.It Bq Er EINVAL`
			`The`
			`.Fa addr`
			`parameter did not specify an address part of a mapped region.`
			`.It Bq Er EINVAL`
			`The`
			`.Fa len`
			`parameter was negative.`
Changes by Thorsten Lockert and myself (though my role was only minor) to document msync's error returns. 1994-06-21 08:49:04 +04:00			`.It Bq Er EIO`
Spell occurred correctly. 2001-04-25 06:19:48 +04:00			`An I/O error occurred while writing to the file system.`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.It Bq Er ENOMEM`
			`Addresses in the specified region are outside the range allowed`
			`for the address space of the process, or specify one or more pages`
			`which are unmapped.`
Missing .El. Rewrite cheap .Bd -literal as a nice .Bl -column. 1999-03-09 06:49:46 +03:00			`.El`
update manpage to -mandoc macros 1993-08-06 01:31:41 +04:00			`.Sh SEE ALSO`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`.Xr mlock 2 ,`
			`.Xr mmap 2 ,`
			`.Xr munlock 2`
clean up import, rcsid 1994-06-21 08:24:53 +04:00			`.Sh HISTORY`
			`The`
			`.Fn msync`
caddr_t -> void * PR/4269: Chris Demetriou: Add MS_* to msync() 1997-10-17 03:21:47 +04:00			`function first appeared in`
			`.Bx 4.4 .`
			`It was modified to conform to`
			`.St -p1003.1b-93`
			`in`
			`.Nx 1.3 .`
Sort sections, sort SEE ALSO, punctuation and miscellanous fixes. 2001-09-16 06:13:26 +04:00			`.Sh BUGS`
			`Writes are currently done synchronously even if the`
			`.Dv MS_ASYNC`
			`flag is specified.`