From b2c4f4ae74d752a0bcd8d9b06e316c98bd3c4f6e Mon Sep 17 00:00:00 2001 From: archie Date: Wed, 11 Sep 2002 21:39:21 +0000 Subject: Add man pages for getcontext()/setcontext(), makecontext()/swapcontext(), and ucontext_t. Reviewed by: mini MFC after: 3 days --- lib/libc/gen/Makefile.inc | 12 +++-- lib/libc/gen/getcontext.3 | 119 +++++++++++++++++++++++++++++++++++++++++++++ lib/libc/gen/makecontext.3 | 107 ++++++++++++++++++++++++++++++++++++++++ lib/libc/gen/ucontext.3 | 98 +++++++++++++++++++++++++++++++++++++ 4 files changed, 331 insertions(+), 5 deletions(-) create mode 100644 lib/libc/gen/getcontext.3 create mode 100644 lib/libc/gen/makecontext.3 create mode 100644 lib/libc/gen/ucontext.3 (limited to 'lib/libc') diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc index f15f6e0..4364ab7 100644 --- a/lib/libc/gen/Makefile.inc +++ b/lib/libc/gen/Makefile.inc @@ -42,22 +42,22 @@ MAN+= alarm.3 arc4random.3 \ confstr.3 ctermid.3 daemon.3 \ devname.3 directory.3 dirname.3 dladdr.3 dllockinit.3 dlopen.3 \ err.3 exec.3 fmtcheck.3 fmtmsg.3 fnmatch.3 frexp.3 ftok.3 fts.3 \ - getbootfile.3 getbsize.3 getcap.3 getcwd.3 \ + getbootfile.3 getbsize.3 getcap.3 getcontext.3 getcwd.3 \ getdiskbyname.3 getdomainname.3 getfsent.3 \ getgrent.3 getgrouplist.3 gethostname.3 getloadavg.3 \ getmntinfo.3 getnetgrent.3 getobjformat.3 \ getpagesize.3 getpass.3 getpeereid.3 getprogname.3 getpwent.3 \ getttyent.3 getusershell.3 getvfsbyname.3 getvfsent.3 \ - glob.3 initgroups.3 isinf.3 \ - ldexp.3 lockf.3 modf.3 msgctl.3 msgget.3 msgrcv.3 msgsnd.3 \ + glob.3 initgroups.3 isinf.3 ldexp.3 lockf.3 makecontext.3 \ + modf.3 msgctl.3 msgget.3 msgrcv.3 msgsnd.3 \ nice.3 nlist.3 pause.3 popen.3 pselect.3 psignal.3 pwcache.3 \ raise.3 rand48.3 readpassphrase.3 rfork_thread.3 \ scandir.3 setjmp.3 setmode.3 setproctitle.3 shm_open.3 \ siginterrupt.3 signal.3 sigsetops.3 sleep.3 statvfs.3 stringlist.3 \ strtofflags.3 sysconf.3 sysctl.3 syslog.3 tcgetpgrp.3 \ tcsendbreak.3 tcsetattr.3 tcsetpgrp.3 time.3 times.3 timezone.3 \ - ttyname.3 tzset.3 ualarm.3 ulimit.3 uname.3 unvis.3 usleep.3 utime.3 \ - valloc.3 vis.3 + ttyname.3 tzset.3 ualarm.3 ucontext.3 ulimit.3 uname.3 \ + unvis.3 usleep.3 utime.3 valloc.3 vis.3 MLINKS+=arc4random.3 arc4random_addrandom.3 arc4random.3 arc4random_stir.3 MLINKS+=ctermid.3 ctermid_r.3 @@ -78,6 +78,7 @@ MLINKS+=getcap.3 cgetcap.3 getcap.3 cgetclose.3 getcap.3 cgetent.3 \ getcap.3 cgetnum.3 getcap.3 cgetset.3 getcap.3 cgetstr.3 \ getcap.3 cgetustr.3 MLINKS+=getcwd.3 getwd.3 +MLINKS+=getcontext.3 setcontext.3 MLINKS+=getdomainname.3 setdomainname.3 MLINKS+=getfsent.3 endfsent.3 getfsent.3 getfsfile.3 getfsent.3 getfsspec.3 \ getfsent.3 getfstype.3 getfsent.3 setfsent.3 @@ -98,6 +99,7 @@ MLINKS+=getvfsent.3 endvfsent.3 getvfsent.3 getvfsbytype.3 \ getvfsent.3 vfsload.3 MLINKS+=glob.3 globfree.3 MLINKS+=isinf.3 isnan.3 isinf.3 isnanf.3 +MLINKS+=makecontext.3 swapcontext.3 MLINKS+=popen.3 pclose.3 MLINKS+=psignal.3 strsignal.3 psignal.3 sys_siglist.3 psignal.3 sys_signame.3 MLINKS+=pwcache.3 group_from_gid.3 pwcache.3 user_from_uid.3 diff --git a/lib/libc/gen/getcontext.3 b/lib/libc/gen/getcontext.3 new file mode 100644 index 0000000..de1e4a4 --- /dev/null +++ b/lib/libc/gen/getcontext.3 @@ -0,0 +1,119 @@ +.\" Copyright (c) 2002 Packet Design, LLC. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, +.\" use and redistribution of this software, in source or object code +.\" forms, with or without modifications are expressly permitted by +.\" Packet Design; provided, however, that: +.\" +.\" (i) Any and all reproductions of the source or object code +.\" must include the copyright notice above and the following +.\" disclaimer of warranties; and +.\" (ii) No rights are granted, in any manner or form, to use +.\" Packet Design trademarks, including the mark "PACKET DESIGN" +.\" on advertising, endorsements, or otherwise except as such +.\" appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING +.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, +.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS +.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, +.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE +.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE +.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL +.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF +.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd Sep 10, 2002 +.Dt GETCONTEXT 3 +.Os +.Sh NAME +.Nm getcontext +.Nm setcontext +.Nd get and set user thread 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 +.Fn getcontext +saves the current thread's execution context in the structure pointed to by +.Fa "ucp" . +This saved context may then later be restored by calling +.Fn setcontext . +.Pp +.Fn setcontext +makes a previously saved thread context the current thread context, i.e., +the current context is lost and +.Fn setcontext +does not return. +Instead, execution continues in the context specified by +.Fa "ucp" , +which must have been previously initialized by a call to +.Fn setcontext , +.Fn makecontext , +or by being passed as an argument to a signal handler (see +.Xr sigaction 2) . +.Pp +If +.Fa ucp +was initialized by +.Fn getcontext , +then execution continues as if the original +.Fn getcontext +call had just returned (again). +.Pp +If +.Fa ucp +was initialized by +.Fn makecontext , +execution continues with the invocation of the function specified to +.Fn makecontext . +When that function returns, +.Fa "ucp->uc_link" +determines what happens next: +if +.Fa "ucp->uc_link" +is +.Dv NULL , +the process exits; +otherwise, +.Fn setcontext "ucp->uc_link" +is implicitly invoked. +.Pp +If +.Fa ucp +was initialized by the invocation of a signal handler, execution continues +at the point the thread was interrupted by the signal. +.Ed +.Sh RETURN VALUES +If successful, +.Fn getcontext +returns zero and +.Fn setcontext +does not return; otherwise -1 is returned. +.Sh ERRORS +No errors are defined for +.Fn getcontext +or +.Fn setcontext . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigaltstack 2 , +.Xr makecontext 3 , +.Xr ucontext 3 diff --git a/lib/libc/gen/makecontext.3 b/lib/libc/gen/makecontext.3 new file mode 100644 index 0000000..05159bc --- /dev/null +++ b/lib/libc/gen/makecontext.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2002 Packet Design, LLC. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, +.\" use and redistribution of this software, in source or object code +.\" forms, with or without modifications are expressly permitted by +.\" Packet Design; provided, however, that: +.\" +.\" (i) Any and all reproductions of the source or object code +.\" must include the copyright notice above and the following +.\" disclaimer of warranties; and +.\" (ii) No rights are granted, in any manner or form, to use +.\" Packet Design trademarks, including the mark "PACKET DESIGN" +.\" on advertising, endorsements, or otherwise except as such +.\" appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING +.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, +.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS +.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, +.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE +.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE +.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL +.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF +.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd Sep 10, 2002 +.Dt MAKECONTEXT 3 +.Os +.Sh NAME +.Nm makecontext +.Nm swapcontext +.Nd modify and exchange user thread contexts +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ucontext.h +.Ft void +.Fn makecontext "ucontext_t *ucp" "void (*func)()" "int argc" "..." +.Ft int +.Fn swapcontext "ucontext_t *oucp" "const ucontext_t *ucp" +.Sh DESCRIPTION +.Fn makecontext +modifies the user thread context pointed to by +.Fa ucp , +which must have previously been initialized by a call to +.Fn getcontext +and had a stack allocated for it. +The context is modified so that it will continue execution by invoking +.Fn func +with the arguments provided. +.Fa argc +must be equal to the number of additional arguments provided to +.Fn makecontext +and also equal to the number of parameters to +.Fn func , +or else the behavior is undefined. +.Pp +.Fa "ucp->uc_link" +must be initialized before calling +.Fn makecontext +and determines the action to take when +.Fn func +returns: +if equal to +.Dv NULL , +the process exits; +otherwise, +.Fn setcontext "ucp->uc_link" +is implicitly invoked. +.Pp +.Fn swapcontext +saves the current thread context in +.Fa "*oucp" +and makes +.Fa "*ucp" +the currently active context. +.Sh RETURN VALUES +If successful, +.Fn swapcontext +returns zero; +otherwise -1 is returned and +.Va errno +is set appropriately. +.Sh ERRORS +.Fn swapcontext +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +There is not enough stack space in +.Fa ucp +to complete the operation. +.El +.Sh SEE ALSO +.Xr setcontext 3 , +.Xr ucontext 3 diff --git a/lib/libc/gen/ucontext.3 b/lib/libc/gen/ucontext.3 new file mode 100644 index 0000000..f4fe86f --- /dev/null +++ b/lib/libc/gen/ucontext.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 2002 Packet Design, LLC. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, +.\" use and redistribution of this software, in source or object code +.\" forms, with or without modifications are expressly permitted by +.\" Packet Design; provided, however, that: +.\" +.\" (i) Any and all reproductions of the source or object code +.\" must include the copyright notice above and the following +.\" disclaimer of warranties; and +.\" (ii) No rights are granted, in any manner or form, to use +.\" Packet Design trademarks, including the mark "PACKET DESIGN" +.\" on advertising, endorsements, or otherwise except as such +.\" appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING +.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, +.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS +.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, +.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE +.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE +.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL +.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF +.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd Sep 10, 2002 +.Dt UCONTEXT 3 +.Os +.Sh NAME +.Nm ucontext +.Nd user thread context +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ucontext.h +.Sh DESCRIPTION +The +.Vt ucontext_t +type is a structure type suitable for holding the context for a user +thread of execution. +A thread's context includes its stack, saved registers, and list of +blocked signals. +.Pp +The +.Vt ucontext_t +structure contains at least these fields: +.Bl -tag -compact -offset 3n -width "mcontext_t uc_mcontext" +.Pp +.It "ucontext_t *uc_link" +Context to assume when this one returns +.It "sigset_t uc_sigmask" +Signals being blocked +.It "stack_t uc_stack" +Stack area +.It "mcontext_t uc_mcontext" +Saved registers +.El +.Pp +The +.Fa uc_link +field points to the context to resume when this context's entry point +function returns. +If +.Fa uc_link +is equal to +.Dv NULL , +then the process exits when this context returns. +.Pp +The +.Fa uc_mcontext +field is machine-dependent and should be treated as opaque by +portable applications. +.Pp +The following functions are defined to manipulate +.Vt ucontext_t +structures: +.Bd -literal -offset xxx +int getcontext(ucontext_t *); +int setcontext(const ucontext_t *); +void makecontext(ucontext_t *, void (*)(void), int, ...); +int swapcontext(ucontext_t *, const ucontext_t *); +.Ed +.Sh SEE ALSO +.Xr sigaltstack 2 , +.Xr getcontext 3 , +.Xr makecontext 3 -- cgit v1.1