.th K_build_segment II 4/21/86
.sh NAME
K_build_segment - create and map a virtual memory segment
.sh "MODULA SYNOPSIS"
.nh
.na
 CONST status: seg_stat_block;
.br
 CONST da: discr_access;
.br
 VAR   segSeid: seid;
.br
 VAR   segDes: seg_des;
.br
 VAR   stat: K_err_num;
.br
 . . .
.br
 stat := NK_build_segment(status, da, segSeid, segDes);
.br
.hy
.ad
.sp
.sh "C SYNOPSIS"
.nh
.na
 seg_stat_block status;
.br
 discr_access da;
.br
 seid segSeid;
.br
 seg_des segDes;
.br
 int stat;
.br
 . . .
.br
 stat = K_build_segment (&status, da, &segSeid, &segDes);
.br
.hy
.ad
.sh "DESCRIPTION"
K_build_segment creates a new process segment and maps it into the
process' virtual address space.  Its operation includes the following
actions:
.lp 9 3
*	A global segment descriptor is allocated and swap space is
allocated.
.lp 9 3
*	A process-local segment descriptor is allocated and
associated with the created segment.
.lp 9 3
*	Page registers for the process are chosen according to the
address range specified for the segment, and are partially initialized.
.lp 9 3
*	Physical memory is allocated for the segment and the physical
memory address of the segment is set up in its page registers.  The
segment's memory is guaranteed to be all zeros.
.i0
.s1
Information needed to build the segment is taken from the
parameters.
From
status
(see seg_stat_block(IIa)) are taken:
.lp 18 11
mem_lock	whether to lock the segment in memory; the privilege
privLockSeg is required for this action.  For information on privileges
see PCE(VIII).
.lp 18 11
mem_advise	whether the segment may be locked in memory, particularly
by I/O operations
.lp 18 11
swap_lock	whether to lock the segment in swap space; the privilege
privStickySeg is required for this action
.lp 18 11
sharable	whether to allow sharing of the segment with other processes
.lp 18 11
growth	segment's direction of growth
.lp 18 11
stat_size	size of the segment in bytes
.lp 18 11
stat_acc	access the calling process shall have to the segment
.lp 18 11
stat_loc	virtual location of the segment in the process'
address space
.i0
.s1
The da parameter supplies the discretionary access for the segment, to
be placed in its type-independent information (see tii_struct(IIa)).
The access to the segment allowed by the stat_acc field of the status
parameter must be a subset of the access allowed by the owner part of
the da parameter.  Write-only access (write without read) may not be
specified in either the stat_acc field or the da parameter.  The
remaining fields of the type-independent information for the segment
are taken from those of the calling process.
.s1
Values produced by the call are returned in segSeid (the SEID created
for the segment) and segDes (the process-local segment number).
.s1
Segments may be shared between processes providing that the security,
integrity and discretionary access checks would allow such sharing.
Sharing of segments requires that the first process to desire to share
the segment create it.  Subsequent to creation, the segment SEID must
be made available to processes wishing to share the segment, typically
either via placing it in a mutually agreed upon file, or by passing it
via an IPC message.  The other processes would then issue
K_rendezvous_segment calls to gain access to the segment.
.s1
It is the responsibility of the processes sharing the segment to see to
it that it is properly initialized, either by the Kernel guarantee of
all zeros, or by explicit initialization.  The initialization may
require cooperation or mutual exclusion to be completed successfully.
This is particularly true in the case of shared pure text segments
which are to be resident in the Instruction Space on the PDP-11/70.
Since such segments cannot be written into, they must be created as
writable segments, initialized from the appropriate image file, and
then have their status changed to make them reside in the correct space
and be non-writable.  Care should be taken in the design of programs
like the Process Bootstrapper which perform such initializations to
assure that duplicate initialization attempts or multiple copies of the
same shared text segment do not occur.
.s1
The virtual address and domain parameters shall be for the calling
process only.  Other processes sharing the segment may map it into
their virtual address spaces as desired through their use of the
K_rendezvous_segment calls.  Of course, some segments, e.g.  text
segments, may operate correctly only if mapped starting at a specific
virtual address.
.sh "EXCEPTIONS"
.lp 22 15
XbSgRng	Bad segment range:  set of addresses specified
for the segment would lie outside a 64K address space.
.lp 22 15
XbSgSz	Bad segment size:  segment size of zero specified
.lp 22 15
XnPgSg	No page in segment:  segment address range 
does not cross or is not adjacent to some
multiple of 8K (address range must include
an 8K multiple or have a top address that
is one less than an 8K multiple).
.lp 22 15
XnPvLkSg	No privilege to lock segment:  mem_lock 
specified, but without necessary privilege
.lp 22 15
XnPvStkSg	No privilege to make sticky segment:  swap_lock
specified, but without necessary privilege
.lp 22 15
XncnDo	Cannot do:  global resource exhaustion
.lp 22 15
XpostEh	Process open segment table exhaustion:  too 
many process segments
.lp 22 15
XvrtMmCfl	Virtual memory conflict:  some subset of the 
address range of this segment would use a page 
register(s) already in use by an existing 
segment (high-order three bits the same).
.lp 22 15
XwOnlSg	Write-only segment:  attempt to create write-
only segment
.i0
.sh "SEE ALSO"
K_get_segment_status(II),
K_set_segment_status(II),
K_release_segment(II),
K_rendezvous_segment(II),
priv_struct(IIa),
PCE(VIII),
seg_stat_block(IIa)
