.TH SEGATTACH 2
.SH NAME
segattach, segdetach, segfree \- map/unmap a segment in virtual memory
.SH SYNOPSIS
.ta \w'\fLvoid* 'u
.B
int	segattach(int attr, char *class, void *va, ulong len)
.PP
.B
int	segdetach(void *addr)
.PP
.B
int	segfree(void *va, ulong len)
.PP
.SH DESCRIPTION
.I Segattach
creates a new memory segment and adds it
to the calling process's address space.
Segments are identified by system-dependent classes.
Segment classes
.B memory
(plain memory)
and
.B shared
(shared memory)
should be available on all systems.
.PP
Shared segments are inherited by the children of the attaching process
and remain untouched across a
.IR fork (2).
An
.IR exec (2)
will release a shared segment if it overlaps the segments
in the file being
.IR exec'ed ;
otherwise the segment will be inherited.
.PP
Some machines provide a segment class
.BR lock .
Lock segments allow access to special lock hardware provided
by some multiprocessors, in particular the SGI Power Series machines.
.PP
Systems may also provide interfaces to special hardware devices like
frame buffers through the
.I segattach
interface.
Device memory mapped by this method is typically uncached by default.
.PP
If the specified
.I class
is unknown,
.I segattach
draws an error.
.PP
.I Attr
specifies the new segment's attributes.
The only attribute implemented on all classes of segment is
.BR SG_RONLY ,
which allows only read access on the segment.
Specific devices may implement
attributes to control caching and allocation, but these will vary
between devices.
.PP
.I Va
and
.I len
specify the position of the segment in the process's address space.
.I Va
is rounded down to the nearest page boundary and
.IB va + len
is rounded up.
The system does not permit segments to overlap.
.PP
.I Segdetach
removes a segment from a process's address space. Memory used by
the segment is freed.
.I Addr
may be any address within the bounds of the segment.
.PP
The system will not permit the text and stack segments to be detached
from the address space.
.PP
.I Segfree
allows specific areas of a segment's memory to be freed.
.I Va
and
.I len
are interpreted as in
.I segattach
but need not refer to the entire segment.
.PP
To select a virtual address to which a segment can be attached,
the following algorithm is reliable.
Read the
.B segment
file of the current process
(see
.IR proc (3))
to find the base of the stack segment.  Subtract the
size of the new segment and use that address.
.PP
The MIPS R2000 and R3000 have no hardware instructions
to implement locks.  The following method can be used
to build them from software.
First, try to
.I segattach
a segment of class
.BR lock .
If this succeeds, the machine is an SGI Power Series and
the memory contains hardware locks.
Each 4096-byte page has 64
.B long
words at its beginning; each word implements
a test-and-set semaphore when read; the low bit of the word
is zero on success, one on failure.
If the
.I segattach
fails, there is no hardware support but the operating system
helps:
Any
.B COP3
instruction will be trapped by the kernel and interpreted
as a test-and-set.
In the trap,
.B R1
points to a
.BR long ;
on return,
.B R1
is greater or equal zero on success, negative on failure.
The following assembly language implements such a test-and-set.
.IP
.EX
.ta 8n +8n +8n +8n +8n +8n +8n
/*
 *	MIPS test and set
 */
	TEXT	tas(SB), $0
btas:
	MOVW	sema+0(FP), R1
	MOVB	R0, 1(R1)
	NOR	R0, R0, R0	/* NOP */
	WORD	$(023<<26)	/* MFC3 R0, R0 */
	BLTZ	R1, btas
	RET
.EE
.SH SEE ALSO
.IR segbrk (2),
.IR segflush (2)
.br
.BR /proc/*/segment
.SH DIAGNOSTICS
These functions set
.I errstr.