Date: Mon, 14 Jan 2002 12:59:58 +0200 From: Ruslan Ermilov <ru@FreeBSD.ORG> To: Dan Eischen <eischen@vigrid.com> Cc: doc@FreeBSD.ORG Subject: Re: Review needed for man pages Message-ID: <20020114125958.A7207@sunbay.com> In-Reply-To: <3C3AFEFE.D2418A7F@vigrid.com> References: <3C3AFEFE.D2418A7F@vigrid.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--2fHTh5uZTiUOsy+g Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On Tue, Jan 08, 2002 at 09:15:26AM -0500, Dan Eischen wrote: > Can someone review these man pages: > > http://people.freebsd.org/~deischen/ucontext/getcontext.3 > http://people.freebsd.org/~deischen/ucontext/makecontext.3 > Please see patch attached. Non markup-related changes in the patch: - Removed "shall" POSIXism -- FreeBSD is an implementor, and should document the actual implementation behavior. - Fixed return type of makecontext() in SYNOPSIS. > Also, the content was taken directly from the IEEE ratified > Austin Draft 7. Are we allowed to do that? > I'm affraid not. Please see http://www.opengroup.org/onlinepubs/terms.htm for details. Cheers, -- Ruslan Ermilov Oracle Developer/DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age --2fHTh5uZTiUOsy+g Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename=p --- getcontext.3~ Tue Jan 8 16:01:39 2002 +++ getcontext.3 Mon Jan 14 12:30:17 2002 @@ -2,11 +2,10 @@ .\" $FreeBSD$ .\" .Dd January 6, 2002 -.Os FreeBSD 5.0 +.Os .Dt GETCONTEXT 3 .Sh NAME -.Nm getcontext , -.Nm setcontext +.Nm getcontext , setcontext .Nd get and set current user context .Sh LIBRARY .Lb libc @@ -19,9 +18,10 @@ .Sh DESCRIPTION The .Fn getcontext -function shall initialize the structure pointed to by +function initializes the structure pointed to by .Fa ucp -to the current user context of the calling thread. The +to the current user context of the calling thread. +The .Vt ucontext_t type that .Fa ucp @@ -31,11 +31,11 @@ .Pp The .Fn setcontext -function shall restore the user context pointed to by +function restores the user context pointed to by .Fa ucp . A successful call to .Fn setcontext -shall not return; program execution resumes at the point specified by the +does not return; program execution resumes at the point specified by the .Fa ucp argument passed to .Fn setcontext . @@ -44,7 +44,7 @@ argument should be created either by a prior call to .Fn getcontext or -.Fn makecontext , +.Xr makecontext 3 , or by being passed as an argument to a signal handler. If the .Fa ucp @@ -56,43 +56,43 @@ If the .Fa ucp argument was created with -.Fn makecontext , +.Xr makecontext 3 , program execution continues with the function passed to -.Fn makecontext . -When that function returns, the thread shall continue as if after a call to +.Xr makecontext 3 . +When that function returns, the thread continues as if after a call to .Fn setcontext with the .Fa ucp argument that was input to -.Fn makecontext . +.Xr makecontext 3 . If the -.Vt uc_link +.Va uc_link member of the .Vt ucontext_t structure pointed to by the .Fa ucp argument is equal to 0, then this context is the main context, and the thread -shall exit when this context returns. +exits when this context returns. The effects of passing a .Fa ucp argument obtained from any other source are unspecified. .Sh RETURN VALUES Upon successful completion, .Fn setcontext -shall not return and +does not return and .Fn getcontext -shall return 0; otherwse, a value of -1 shall be returned. +returns 0; otherwise, a value of \-1 is returned. .Sh EXAMPLES Refer to -.Fn makecontext . +.Xr makecontext 3 . .Sh ERRORS No errors are defined. .Sh SEE ALSO -.Xr makecontext 3 , -.Xr setjmp 3 , .Xr sigaction 2 , .Xr sigaltstack 2 , .Xr sigprocmask 2 , +.Xr makecontext 3 , +.Xr setjmp 3 , .Xr sigsetjmp 3 .Sh STANDARDS The @@ -102,4 +102,4 @@ functions are expected to conform to .St -susv2 and -.St -p1003.1-2001 +.St -p1003.1-2001 . --- makecontext.3~ Tue Jan 8 16:01:49 2002 +++ makecontext.3 Mon Jan 14 12:30:17 2002 @@ -2,32 +2,31 @@ .\" $FreeBSD$ .\" .Dd January 6, 2002 -.Os FreeBSD 5.0 +.Os .Dt MAKECONTEXT 3 .Sh NAME -.Nm makecontext , -.Nm swapcontext +.Nm makecontext , swapcontext .Nd manipulate user contexts .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ucontext.h +.Ft void +.Fn makecontext "ucontext_t *ucp" "void \*(lp*func\*(rp\*(lpvoid\*(rp" "int argc" ... .Ft int -.Fn makecontext "ucontext_t *ucp, void (*func)(void), int argc, ..." -.Ft int -.Fn swapcontext "ucontext_t *oucp, const ucontext_t *ucp" +.Fn swapcontext "ucontext_t *oucp" "const ucontext_t *ucp" .Sh DESCRIPTION The .Fn makecontext -function shall modify the context specified by +function modifies the context specified by .Fa ucp , which has been initialized using -.Fn getcontext . +.Xr getcontext 3 . When this context is resumed using .Fn swapcontext or -.Fn setcontext , -program execution shall continue by calling +.Xr setcontext 3 , +program execution continues by calling .Fa func , passing it the arguments that follow .Fa argc @@ -46,28 +45,24 @@ otherwise, the behavior is undefined. .Pp The -.Vt uc_link +.Va uc_link member is used to determine the context that shall be resumed when the context being modified by .Fn makecontext returns. The application shall ensure that the -.Vt uc_link +.Va uc_link member is initialized prior to the call to .Fn makecontext . .Pp The .Fn swapcontext -function shall save the current context in the context structure pointed to by +function saves the current context in the context structure pointed to by .Fa oucp -and shall set the context to the context structure pointed to by +and sets the context to the context structure pointed to by .Fa ucp . .Sh RETURN VALUES -Upon successful completion, -.Fn swapcontext -shall return 0. Otherwise, -1 shall be returned and -.Va errno -set to indicate the error. +.Rv -std swapcontext .Sh EXAMPLES The following example illustrates the use of .Fn makecontext . @@ -117,7 +112,7 @@ .Sh ERRORS The .Fn swapcontext -function shall fail if: +function fails if: .Bl -tag -width Er .It Bq Er ENOMEM The @@ -125,10 +120,10 @@ argument does not have enough stack left to complete the operation. .El .Sh SEE ALSO -.Xr exit 3 , -.Xr getcontext 3 , .Xr sigaction 2 , -.Xr sigprocmask 2 +.Xr sigprocmask 2 , +.Xr exit 3 , +.Xr getcontext 3 .Sh STANDARDS The .Fn makecontext --2fHTh5uZTiUOsy+g-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020114125958.A7207>