d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
2c9a33f557
freebsd-nq/lib/libc/sys/minherit.2

152 lines
4.6 KiB
Groff
Raw Normal View History

$Id$ -> $FreeBSD$
1999-08-28 00:22:10 +00:00
.\" $FreeBSD$
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.\"
.\" 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.
Renumber copyright clause 4 Renumber cluase 4 to 3, per what everybody else did when BSD granted them permission to remove clause 3. My insistance on keeping the same numbering for legal reasons is too pedantic, so give up on that point. Submitted by: Jan Schaumann <jschauma@stevens.edu> Pull Request: https://github.com/freebsd/freebsd/pull/96
2017-02-28 23:42:47 +00:00
.\" 3. Neither the name of the University nor the names of its contributors
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.\" 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.
.\"
.\" @(#)minherit.2 8.1 (Berkeley) 6/9/93
.\"
Implement INHERIT_ZERO for minherit(2). INHERIT_ZERO is an OpenBSD feature. When a page is marked as such, it would be zeroed upon fork(). This would be used in new arc4random(3) functions. PR: 182610 Reviewed by: kib (earlier version) MFC after: 1 month Differential Revision: https://reviews.freebsd.org/D427
2017-03-14 17:10:42 +00:00
.Dd March 15, 2017
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.Dt MINHERIT 2
.Os
.Sh NAME
.Nm minherit
.Nd control the inheritance of pages
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following.
2000-04-21 09:42:15 +00:00
.Sh LIBRARY
.Lb libc
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.Sh SYNOPSIS
mdoc(7) police: Use the new .In macro for #include statements.
2001-10-01 16:09:29 +00:00
.In sys/mman.h
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.Ft int
Convert caddr_t --> void * for sys/mman.h functions. mlock, mmap, mprotect, msync, munlock, and munmap are defined by POSIX as taking void *. The const modifier has been added to mlock, munlock, and mprotect as the standard dictates. minherit comes from OpenBSD and has been updated to conform with their recent change to void *. madvise and mincore are not defined by POSIX, but their arguments have been modified to be consistent with the POSIX-defined functions. mincore takes a const pointer, but madvise does not due to the MADV_FREE case. Discussed with: bde
1997-12-31 01:22:01 +00:00
.Fn minherit "void *addr" "size_t len" "int inherit"
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.Sh DESCRIPTION
The
.Fn minherit
system call
changes the specified pages to have the inheritance characteristic
.Fa inherit .
Not all implementations will guarantee that the inheritance characteristic
can be set on a page basis;
the granularity of changes may be as large as an entire region.
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
.Fx
is capable of adjusting inheritance characteristics on a page basis.
Inheritance only effects children created by
.Fn fork .
It has no effect on
.Fn exec .
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
exec'd processes replace their address space entirely.
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
This system call also
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
has no effect on the parent's address space (other than to potentially
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
share the address space with its children).
.Pp
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
Inheritance is a rather esoteric feature largely superseded by the
.Dv MAP_SHARED
feature of
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
.Fn mmap .
However, it is possible to use
.Fn minherit
to share a block of memory between parent and child that has been mapped
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
.Dv MAP_PRIVATE .
That is, modifications made by parent or child are shared but
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
the original underlying file is left untouched.
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
.Bl -tag -width ".Dv INHERIT_SHARE"
Ok, third time is the charm. VM_INHERIT_XXX -> INHERIT_XX (use the same semantics as PROT_XXX vs VM_PROT_XXX separating user-space defines from kernel defines).
2001-08-24 19:45:59 +00:00
.It Dv INHERIT_SHARE
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
This option causes the address space in question to be shared between
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
parent and child.
It has no effect on how the original underlying backing
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
store was mapped.
Ok, third time is the charm. VM_INHERIT_XXX -> INHERIT_XX (use the same semantics as PROT_XXX vs VM_PROT_XXX separating user-space defines from kernel defines).
2001-08-24 19:45:59 +00:00
.It Dv INHERIT_NONE
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
This option prevents the address space in question from being inherited
at all.
The address space will be unmapped in the child.
Ok, third time is the charm. VM_INHERIT_XXX -> INHERIT_XX (use the same semantics as PROT_XXX vs VM_PROT_XXX separating user-space defines from kernel defines).
2001-08-24 19:45:59 +00:00
.It Dv INHERIT_COPY
Oops, minherit() uses VM_INHERIT_XXX as the argument, not MAP_XXX. Properly document minherit().
2001-08-24 19:43:45 +00:00
This option causes the child to inherit the address space as copy-on-write.
This option also has an unfortunate side effect of causing the parent
mdoc(7) police: markup and spelling fixes.
2001-08-27 08:26:57 +00:00
address space to become copy-on-write when the parent forks.
If the original mapping was
.Dv MAP_SHARED ,
it will no longer be shared in the parent
after the parent forks and there is no way to get the previous
Oops, minherit() uses VM_INHERIT_XXX as the argument, not MAP_XXX. Properly document minherit().
2001-08-24 19:43:45 +00:00
shared-backing-store mapping without unmapping and remapping the address
space in the parent.
Implement INHERIT_ZERO for minherit(2). INHERIT_ZERO is an OpenBSD feature. When a page is marked as such, it would be zeroed upon fork(). This would be used in new arc4random(3) functions. PR: 182610 Reviewed by: kib (earlier version) MFC after: 1 month Differential Revision: https://reviews.freebsd.org/D427
2017-03-14 17:10:42 +00:00
.It Dv INHERIT_ZERO
This option causes the address space in question to be mapped as new
anonymous pages,
which would be initialized to all zero bytes,
in the child process.
Update the mmap.2 and minherit.2 manual pages. Add a short explanation and referal from mmap to minherit for MAP_INHERIT. Fully document the minherit.2 manual page (because frankly, my dear, however you think it currently works is almost certainly wrong!). I may soon re-implement MAP_COPY because I believe we can support it properly now, but I will have to call it something else and that is for a later time.
2001-08-24 19:28:00 +00:00
.El
Add missing RETURN VALUES/ERRORS sections.
1997-01-12 00:38:36 +00:00
.Sh RETURN VALUES
Use the ``.Rv -std'' mdoc(7) macro in appropriate cases. Reviewed by: ru
2001-08-09 13:32:13 +00:00
.Rv -std minherit
Add missing RETURN VALUES/ERRORS sections.
1997-01-12 00:38:36 +00:00
.Sh ERRORS
The
.Fn minherit
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
system call will fail if:
Add missing RETURN VALUES/ERRORS sections.
1997-01-12 00:38:36 +00:00
.Bl -tag -width Er
.It Bq Er EINVAL
The virtual address range specified by the
.Fa addr
and
.Fa len
arguments is not valid.
EACESS -> EACCES
1999-03-15 00:14:57 +00:00
.It Bq Er EACCES
Add missing RETURN VALUES/ERRORS sections.
1997-01-12 00:38:36 +00:00
The flags specified by the
.Fa inherit
argument were not valid for the pages specified
by the
.Fa addr
and
.Fa len
arguments.
.El
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.Sh SEE ALSO
.Xr fork 2 ,
Remove whitespace at EOL.
2001-07-15 07:53:42 +00:00
.Xr madvise 2 ,
.Xr mincore 2 ,
.Xr mprotect 2 ,
rfork/minherit glue in libc man pages adapted from OpenBSD's versions.
1996-02-23 19:56:55 +00:00
.Xr msync 2 ,
.Xr munmap 2 ,
.Xr rfork 2
.Sh HISTORY
The
.Fn minherit
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
system call first appeared in
Add FreeBSD history. Approved by: re(ken)
2007-09-21 14:05:26 +00:00
.Ox
and then in
The .Fx request doesn't recognize 2.2.0, so use ".Fx 2.2" MFC after: 3 days
2007-10-30 15:27:45 +00:00
.Fx 2.2 .
Implement INHERIT_ZERO for minherit(2). INHERIT_ZERO is an OpenBSD feature. When a page is marked as such, it would be zeroed upon fork(). This would be used in new arc4random(3) functions. PR: 182610 Reviewed by: kib (earlier version) MFC after: 1 month Differential Revision: https://reviews.freebsd.org/D427
2017-03-14 17:10:42 +00:00
.Pp
The
.Dv INHERIT_ZERO
support first appeared in
.Ox 5.6
and then in
.Fx 12.0 .
Sort sections.
2005-01-20 09:17:07 +00:00
.Sh BUGS
Once you set inheritance to
.Dv MAP_PRIVATE
or
.Dv MAP_SHARED ,
there is no way to recover the original copy-on-write semantics
short of unmapping and remapping the area.
Reference in New Issue Copy Permalink