BSD 4_4 release

[unix-history] / usr / src / share / doc / psd / 05.sysman / 1.2.t

diff --git a/usr/src/share/doc/psd/05.sysman/1.2.t b/usr/src/share/doc/psd/05.sysman/1.2.t
index 3337372..c0a3b17 100644 (file)
--- a/usr/src/share/doc/psd/05.sysman/1.2.t
+++ b/usr/src/share/doc/psd/05.sysman/1.2.t
@@ -1,8 +1,35 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)1.2.t       6.4 (Berkeley) %G%
+.\" 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.
+.\"
+.\"    @(#)1.2.t       8.1 (Berkeley) 6/8/93

 .\"
 .sh "Memory management\(dg
 .NH 3
 .\"
 .sh "Memory management\(dg
 .NH 3


@@ -41,27 +68,33 @@ pages may be \fIshared\fP with other processes or \fIprivate\fP
 to the process.
 Protection and sharing options are defined in \fI<sys/mman.h>\fP as:
 .DS
 to the process.
 Protection and sharing options are defined in \fI<sys/mman.h>\fP as:
 .DS

-._d
+.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u

 /* protections are chosen from these bits, or-ed together */
 #define        PROT_READ       0x04    /* pages can be read */
 #define        PROT_WRITE      0x02    /* pages can be written */
 #define        PROT_EXEC       0x01    /* pages can be executed */
 /* protections are chosen from these bits, or-ed together */
 #define        PROT_READ       0x04    /* pages can be read */
 #define        PROT_WRITE      0x02    /* pages can be written */
 #define        PROT_EXEC       0x01    /* pages can be executed */

-
+.DE
+.DS
+.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u

 /* flags contain mapping type, sharing type and options */
 /* mapping type; choose one */
 #define MAP_FILE       0x0001  /* mapped from a file or device */
 #define MAP_ANON       0x0002  /* allocated from memory, swap space */
 #define MAP_TYPE       0x000f  /* mask for type field */
 /* flags contain mapping type, sharing type and options */
 /* mapping type; choose one */
 #define MAP_FILE       0x0001  /* mapped from a file or device */
 #define MAP_ANON       0x0002  /* allocated from memory, swap space */
 #define MAP_TYPE       0x000f  /* mask for type field */

-
+.DE
+.DS
+.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u

 /* sharing types; choose one */
 #define        MAP_SHARED      0x0010  /* share changes */
 #define        MAP_PRIVATE     0x0000  /* changes are private */
 /* sharing types; choose one */
 #define        MAP_SHARED      0x0010  /* share changes */
 #define        MAP_PRIVATE     0x0000  /* changes are private */

-
+.DE
+.DS
+.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u

 /* other flags */
 #define MAP_FIXED      0x0020  /* map addr must be exactly as requested */
 /* other flags */
 #define MAP_FIXED      0x0020  /* map addr must be exactly as requested */

-#define MAP_NOEXTEND   0x0040  /* for MAP_FILE, don't change file size */
-#define MAP_HASSEMPHORE        0x0080  /* region may contain semaphores */
-#define MAP_INHERIT    0x0100  /* region is retained after exec */
+#define MAP_INHERIT    0x0040  /* region is retained after exec */
+#define MAP_HASSEMAPHORE       0x0080  /* region may contain semaphores */
+#define MAP_NOPREALLOC 0x0100  /* do not preallocate space */

 .DE
 The cpu-dependent size of a page is returned by the
 \fIgetpagesize\fP system call:
 .DE
 The cpu-dependent size of a page is returned by the
 \fIgetpagesize\fP system call:


@@ -69,7 +102,7 @@ The cpu-dependent size of a page is returned by the
 pagesize = getpagesize();
 result int pagesize;
 .DE
 pagesize = getpagesize();
 result int pagesize;
 .DE

-.PP
+.LP

 The call:
 .DS
 maddr = mmap(addr, len, prot, flags, fd, pos);
 The call:
 .DS
 maddr = mmap(addr, len, prot, flags, fd, pos);


@@ -80,12 +113,14 @@ for at most \fIlen\fP bytes to be mapped from the object represented by
 descriptor \fIfd\fP, starting at byte offset \fIpos\fP.
 The starting address of the region is returned;
 for the convenience of the system,
 descriptor \fIfd\fP, starting at byte offset \fIpos\fP.
 The starting address of the region is returned;
 for the convenience of the system,

-it may be different than that supplied
+it may differ from that supplied

 unless the MAP_FIXED flag is given,
 in which case the exact address will be used or the call will fail.
 The actual amount mapped is returned in \fIlen\fP.
 The \fIaddr\fP, \fIlen\fP, and \fIpos\fP parameters
 must all be multiples of the pagesize.
 unless the MAP_FIXED flag is given,
 in which case the exact address will be used or the call will fail.
 The actual amount mapped is returned in \fIlen\fP.
 The \fIaddr\fP, \fIlen\fP, and \fIpos\fP parameters
 must all be multiples of the pagesize.

+A successful \fImmap\fP will delete any previous mapping
+in the allocated address range.

 The parameter \fIprot\fP specifies the accessibility
 of the mapped pages.
 The parameter \fIflags\fP specifies
 The parameter \fIprot\fP specifies the accessibility
 of the mapped pages.
 The parameter \fIflags\fP specifies


@@ -99,32 +134,51 @@ Possible types include MAP_FILE,
 mapping a regular file or character-special device memory,
 and MAP_ANON, which maps memory not associated with any specific file.
 The file descriptor used for creating MAP_ANON regions is used only
 mapping a regular file or character-special device memory,
 and MAP_ANON, which maps memory not associated with any specific file.
 The file descriptor used for creating MAP_ANON regions is used only

-for naming, and may be given as -1 if no name is associated with the region.
-The MAP_NOEXTEND flag prevents the mapped file from being extended
-despite rounding due to the granularity of mapping.
-Other flags allow special handling for regions that may contain semaphores
-or that may be inherited after an \fIexec\fP.
+for naming, and may be given as \-1 if no name
+is associated with the region.\(dd
+.FS
+\(dd The current design does not allow a process
+to specify the location of swap space.
+In the future we may define an additional mapping type, MAP_SWAP,
+in which the file descriptor argument specifies a file
+or device to which swapping should be done.
+.FE
+The MAP_INHERIT flag allows a region to be inherited after an \fIexec\fP.
+The MAP_HASSEMAPHORE flag allows special handling for
+regions that may contain semaphores.
+The MAP_NOPREALLOC flag allows processes to allocate regions whose
+virtual address space, if fully allocated,
+would exceed the available memory plus swap resources.
+Such regions may get a SIGSEGV signal if they page fault and resources
+are not available to service their request;
+typically they would free up some resources via \fIunmap\fP so that
+when they return from the signal the page
+fault could be successfully completed.

 .PP
 A facility is provided to synchronize a mapped region with the file
 it maps; the call
 .DS
 msync(addr, len);
 caddr_t addr; int len;
 .PP
 A facility is provided to synchronize a mapped region with the file
 it maps; the call
 .DS
 msync(addr, len);
 caddr_t addr; int len;

+.DE

 writes any modified pages back to the filesystem and updates
 the file modification time.
 If \fIlen\fP is 0, all modified pages within the region containing \fIaddr\fP
 will be flushed;
 if \fIlen\fP is non-zero, only the pages containing \fIaddr\fP and \fIlen\fP
 succeeding locations will be examined.
 writes any modified pages back to the filesystem and updates
 the file modification time.
 If \fIlen\fP is 0, all modified pages within the region containing \fIaddr\fP
 will be flushed;
 if \fIlen\fP is non-zero, only the pages containing \fIaddr\fP and \fIlen\fP
 succeeding locations will be examined.

-Any required invalidation of memory caches will also take place at this time.
+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 \fImsync\fP.

 .PP
 A mapping can be removed by the call
 .DS
 .PP
 A mapping can be removed by the call
 .DS

-munmap(addr);
-caddr_t addr;
+munmap(addr, len);
+caddr_t addr; int len;

 .DE
 .DE

-This call deletes the region containing the address given,
-and causes further references to addresses within the region
+This call deletes the mappings for the specified address range,
+and causes further references to addresses within the range

 to generate invalid memory references.
 .NH 3
 Page protection control
 to generate invalid memory references.
 .NH 3
 Page protection control


@@ -147,14 +201,15 @@ madvise(addr, len, behav);
 caddr_t addr; int len, behav;
 .DE
 \fIBehav\fP describes expected behavior, as given
 caddr_t addr; int len, behav;
 .DE
 \fIBehav\fP describes expected behavior, as given

-in <mman.h>:
+in \fI<sys/mman.h>\fP:

 .DS
 .DS

-._d
+.ta \w'#define\ \ 'u +\w'MADV_SEQUENTIAL\ \ 'u +\w'00\ \ \ \ 'u

 #define        MADV_NORMAL     0       /* no further special treatment */
 #define        MADV_RANDOM     1       /* expect random page references */
 #define        MADV_SEQUENTIAL 2       /* expect sequential references */
 #define        MADV_WILLNEED   3       /* will need these pages */
 #define        MADV_DONTNEED   4       /* don't need these pages */
 #define        MADV_NORMAL     0       /* no further special treatment */
 #define        MADV_RANDOM     1       /* expect random page references */
 #define        MADV_SEQUENTIAL 2       /* expect sequential references */
 #define        MADV_WILLNEED   3       /* will need these pages */
 #define        MADV_DONTNEED   4       /* don't need these pages */

+#define        MADV_SPACEAVAIL 5       /* insure that resources are reserved */

 .DE
 Finally, a process may obtain information about whether pages are
 core resident by using the call
 .DE
 Finally, a process may obtain information about whether pages are
 core resident by using the call


@@ -168,37 +223,10 @@ that the page is in-core.
 .NH 3
 Synchronization primitives
 .PP
 .NH 3
 Synchronization primitives
 .PP

-.if \n(sw=0 .ig sw
-Two routines provide services analogous to the kernel
-\fIsleep\fP and \fIwakeup\fP functions interpreted in the domain of
-shared memory.
-A process may relinquish the processor by calling \fImsleep\fP:
-.DS
-msleep(sem)
-semaphore *sem;
-.DE
-\fISem\fP must lie within a MAP_SHARED region with at least modes
-PROT_READ and PROT_WRITE.
-The MAP_HASSEMAPHORE flag must have been specified when the region was created.
-The process will remain in a sleeping state
-until some other process issues an \fImwakeup\fP for the same semaphore
-within the region using the call:
-.DS
-mwakeup(sem)
-semaphore *sem;
-.DE
-An \fImwakeup\fP may awaken all sleepers on the semaphore,
-or may awaken only the next sleeper on a queue.
-.PP
-To avoid system calls for the usual case of an uncontested lock,
-routines are provided to acquire and release locks.
-.sw
-.if \n(sw .ig sw

 Primitives are provided for synchronization using semaphores in shared memory.
 Semaphores must lie within a MAP_SHARED region with at least modes
 PROT_READ and PROT_WRITE.
 The MAP_HASSEMAPHORE flag must have been specified when the region was created.
 Primitives are provided for synchronization using semaphores in shared memory.
 Semaphores must lie within a MAP_SHARED region with at least modes
 PROT_READ and PROT_WRITE.
 The MAP_HASSEMAPHORE flag must have been specified when the region was created.

-.sw

 To acquire a lock a process calls:
 .DS
 value = mset(sem, wait)
 To acquire a lock a process calls:
 .DS
 value = mset(sem, wait)


@@ -210,9 +238,7 @@ and \fImset\fP returns true immediately.
 Otherwise, if the \fIwait\fP flag is zero,
 failure is returned.
 If \fIwait\fP is true and the previous value is non-zero,
 Otherwise, if the \fIwait\fP flag is zero,
 failure is returned.
 If \fIwait\fP is true and the previous value is non-zero,

-the ``want'' flag is set and the test-and-set is retried;
-if the lock is still unavailable \fImset\fP relinquishes the processor
-until notified that it should retry.
+\fImset\fP relinquishes the processor until notified that it should retry.

 .LP
 To release a lock a process calls:
 .DS
 .LP
 To release a lock a process calls:
 .DS


@@ -220,7 +246,27 @@ mclear(sem)
 semaphore *sem;
 .DE
 \fIMclear\fP indivisibly tests and clears the semaphore \fIsem\fP.
 semaphore *sem;
 .DE
 \fIMclear\fP indivisibly tests and clears the semaphore \fIsem\fP.

-If the ``want'' flag is zero in the previous value,
+If the ``WANT'' flag is zero in the previous value,

 \fImclear\fP returns immediately.
 \fImclear\fP returns immediately.

-If the ``want'' flag is non-zero in the previous value,
+If the ``WANT'' flag is non-zero in the previous value,

 \fImclear\fP arranges for waiting processes to retry before returning.
 \fImclear\fP arranges for waiting processes to retry before returning.

+.PP
+Two routines provide services analogous to the kernel
+\fIsleep\fP and \fIwakeup\fP functions interpreted in the domain of
+shared memory.
+A process may relinquish the processor by calling \fImsleep\fP
+with a set semaphore:
+.DS
+msleep(sem)
+semaphore *sem;
+.DE
+If the semaphore is still set when it is checked by the kernel,
+the process will be put in a sleeping state
+until some other process issues an \fImwakeup\fP for the same semaphore
+within the region using the call:
+.DS
+mwakeup(sem)
+semaphore *sem;
+.DE
+An \fImwakeup\fP may awaken all sleepers on the semaphore,
+or may awaken only the next sleeper on a queue.