Minix/minix
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Convert a few man pages to mandoc

Browse Source
This commit is contained in:
Thomas Veerman
2010-07-15 08:48:24 +00:00
parent 8a0c10fcb9
commit 3404e8e4e5
3 changed files with 694 additions and 509 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/man3/getcontext.3
+112 -72
View File
@@ -1,96 +1,136 @@
.TH GETCONTEXT 3 "Mar 2, 2010"
.SH NAME
getcontext, setcontext \- get and set current user context
.SH SYNOPSIS
.nf
.ft B
#include <ucontext.h>
int getcontext(ucontext\_t *\fIucp\fP)
int setcontext(const ucontext\_t *\fIoucp\fP)
.SH DESCRIPTION
.Dd Mar 2, 2010
.Dt GETCONTEXT 3
.Os
.Sh NAME
.Nm getcontext ,
.Nm setcontext
.Nd get and set current user context
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In ucontext.h
.Ft int
.Fn getcontext "ucontext_t *ucp"
.Ft int
.Fn setcontext "const ucontext_t *ucp"
.Sh DESCRIPTION
The
.BR makecontext (3)
.Xr makecontext 3
,
.BR swapcontext (3)
.Xr swapcontext 3
,
.BR getcontext (3)
.Xr getcontext 3
, and
.BR setcontext (3)
.Xr setcontext 3
together form a set of functions that allow user-level context switching between multiple threads of control within a process.
.PP
The \fIucontext_t\fP type is a structure that has at least the following members:
.in +4
.nf
.Pp
The
.Vt ucontext_t
type is a structure that has at least the following members:
.Bd -offset 4n -literal
typedef struct __ucontext {
ucontext_t *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
ucontext_t *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
} ucontext_t;
.Ed
.fi
.in
with \fIsigset_t\fP and \fIstack_t\fP defined in
.IR <signal.h> .
Here \fIuc_link\fP points to the context that will be resumed when the current context returns (if \fIuc_link\fP is NULL, the process exits), \fIsigset_t\fP is the set of signals blocks in this context, \fIuc_stack\fP is the stack used by this context (when the context was modified by
.BR makecontext (3)),
and \fIuc_mcontext\fP is the machine-specific representation of the saved context. The \fImcontext_t\fP type is machine-dependent and opaque.
.PP
MINIX 3 has an additional \fIuc_flags\fP member that supports the following flags:
.PP
.in +2
.nf
with
.Vt sigset_t
and
.Vt stack_t
defined in
.In signal.h .
Here
.Va uc_link
points to the context that will be resumed when the current context returns (if
.Va uc_link
is NULL, the process exits),
.Va uc_sigmask
is the set of signals blocked in this context,
.Va uc_stack
is the stack used by this context (when the context was modified by
.Xr makecontext 3 ),
and
.Va uc_mcontext
is the machine-specific representation of the saved context. The
.Vt mcontext_t
type is machine-dependent and opaque.
.Pp
MINIX 3 has an additional
.Va uc_flags
member that supports the following flags:
.Pp
.Bd -offset 4n -literal
UCF_IGNSIGM /* Current signal mask is not stored or restored */
UCF_IGNFPU /* FPU state is not stored or restored for this context */
.fi
.in
.PP
.Ed
.Pp
Not storing and restoring the signal mask and/or FPU state speeds up context switching considerably.
.PP
.Pp
The
.BR getcontext ()
function initializes the structure pointed to by \fIucp\fP to the current user context of the calling thread.
.PP
.Fn getcontext
function initializes the structure pointed to by
.Va ucp
to the current user context of the calling thread.
.Pp
The
.BR setcontext ()
function restores the user context pointed to by \fIucp\fP. A succesful call does not return; program execution resumes at the point specified by the \fIucp\fP argument passed to
.BR setcontext ().
The \fIucp\fP argument should be created either by a prior call to
.BR getcontext ()
.Fn setcontext
function restores the user context pointed to by
.Va ucp .
A succesful call does not return; program execution resumes at the point specified by the
.Va ucp
argument passed to
.Fn setcontext .
The
.Va ucp
argument should be created either by a prior call to
.Fn getcontext
or
.BR makecontext ().
If the \fIucp\fP argument was created with
.BR getcontext (),
.Fn makecontext .
If the
.Va ucp
argument was created with
.Fn getcontext ,
program execution continues as if the corresponding call of
.BR getcontext ()
had just returned. If the \fIucp\fP argument was created with
.BR makecontext (),
.Fn getcontext
had just returned. If the
.Va ucp
argument was created with
.Fn makecontext ,
program execution continues with the function passed to
.BR makecontext ().
.Fn makecontext .
.SH "RETURN VALUE"
.Sh RETURN VALUES
When successful,
.BR getcontext ()
.Fn getcontext
returns 0 and
.BR setcontext ()
.Fn setcontext
does not return. Otherwise, both return -1 and
.I errno
.Va errno
is set to indicate the error.
.SH "ERRORS"
.TP 15
[EINVAL]
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EINVAL
The context is not properly initialized.
.TP 15
[EFAULT]
\fIucp\fP is a NULL pointer.
.SH "SEE ALSO"
.BR makecontext (3).
.SH "AUTHORS"
.It Bq Er EFAULT
.Va ucp
is a NULL pointer.
.El
.Sh SEE ALSO
.Xr makecontext 3 ,
.Xr swapcontext 3
.Sh STANDARDS
The
.Fn getcontext ,
and
.Fn setcontext
functions conform to
.St -xsh5
and
.St -p1003.1-2001 .
.Sh AUTHORS
Thomas Veerman
man/man3/makecontext.3
+79 -57
View File
@@ -1,75 +1,97 @@
.TH MAKECONTEXT 3 "Mar 2, 2010"
.SH NAME
makecontext, swapcontext \- manipulate user contexts
.SH SYNOPSIS
.nf
.ft B
#include <ucontext.h>
void makecontext(ucontext\_t *\fIucp\fP, void \fI(*func)(void)\fP, int \fIargc\fP, ...)
int swapcontext(ucontext\_t *\fIoucp\fP, const ucontext\_t *\fIucp\fP)
.SH DESCRIPTION
.Dd Mar 2, 2010
.Dt MAKECONTEXT 3
.Os
.Sh NAME
.Nm makecontext ,
.Nm swapcontext
.Nd manipulate user contexts
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In ucontext.h
.Ft void
.Fn makecontext "ucontext_t *ucp" "void (*func)(void)" "int argc" ...
.Ft int
.Fn swapcontext "ucontext_t *oucp" "const ucontext_t *ucp"
.Sh DESCRIPTION
The
.BR makecontext (3)
,
.BR swapcontext (3)
,
.BR getcontext (3)
, and
.BR setcontext (3)
.Xr makecontext 3 ,
.Xr swapcontext 3 ,
.Xr getcontext 3 ,
and
.Xr setcontext 3
together form a set of functions that allow user-level context switching between multiple threads of control within a process.
.PP
.Pp
The
.BR makecontext ()
.Fn makecontext
function modifies the user thread pointed to by
.I ucp
.Va ucp
to continue execution by invoking function
.I func
.Va func
and passing that function a number of
.I argc
.Va argc
integer arguments. The value of
.I argc
.Va argc
must match the number of integer arguments passed to
.I func
, otherwise the behavior is undefined. Context
.I ucp
.Va func ,
otherwise the behavior is undefined. Context
.Va ucp
must have been initialized by a call to
.BR getcontext (3)
and have a stack allocated for it. The address of the stack must be assigned to \fIucp\->uc_stack.ss_sp\fP and the size of the stack to \fIucp\->uc_stack.ss_size\fP. The \fIucp\->uc_link\fP member is used to determine which successor context is run after the context modified by
.BR makecontext ()
returns. If left NULL, the process exits.
.PP
.Xr getcontext 3
and have a stack allocated for it. The address of the stack must be assigned to
.Va ucp->uc_stack.ss_sp
and the size of the stack to
.Va ucp->uc_stack.ss_size .
The
.BR swapcontext ()
.Va ucp->uc_link
member is used to determine which successor context is run after the context modified by
.Fn makecontext
returns. If left NULL, the process exits.
.Pp
The
.Fn swapcontext
function saves the current context in the context structure pointed to by
.I oucp
and sets the context to the context structure pointed to by \fIucp\fP.
.SH "RETURN VALUE"
.Va oucp
and sets the context to the context structure pointed to by
.Va ucp .
.Sh RETURN VALUES
When successful,
.BR swapcontext ()
.Fn swapcontext
returns 0. Otherwise, -1 is returned and
.I errno
.Va errno
is set to indicate the error. Note that a successful call to
.BR swapcontext ()
.Fn swapcontext
actually does not return. Only after returning to the context that called
.BR swapcontext ()
, it appears as if
.BR swapcontext ()
.Fn swapcontext ,
it appears as if
.Fn swapcontext
returned 0.
.SH "ERRORS"
.TP 15
[EFAULT]
Either the \fIucp\fP or \fIoucp\fP is a NULL pointer.
.TP 15
[EINVAL]
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EFAULT
Either the
.Va ucp
or
.Va oucp
is a NULL pointer.
.It Bq Er EINVAL
The context is not properly initialized.
.TP 15
[ENOMEM]
The \fIucp\fP argument does not have enough stack left to complete the operation.
.SH "SEE ALSO"
.BR getcontext (3).
.SH "AUTHORS"
.It Bq Er ENOMEM
The
.Va ucp
argument does not have enough stack left to complete the operation.
.El
.Sh SEE ALSO
.Xr getcontext 3 ,
.Xr setcontext 3
.Sh STANDARDS
The
.Fn makecontext ,
and
.Fn swapcontext
functions conform to
.St -xsh5
and
.St -p1003.1-2001 .
.Sh AUTHORS
Thomas Veerman