Print this page
Ensured various XPG7 stuff are declared properly in sys/stat.h (and cleanup)
New documentation for wcslen, wcsnlen, wcscasecmp (and friends), wcsdup.
Various other tweaks and markup improvements.
More markup tweaks.
Minor markup tweaks (Sy instead of Nm).
fix incorrect standard citations
first round of POSIX 2008 stuff

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3c/makecontext.3c
          +++ new/usr/src/man/man3c/makecontext.3c
   1      -'\" te
        1 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2    2  .\" Copyright 1989 AT&T.  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.  Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
   3    3  .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4    4  .\" http://www.opengroup.org/bookstore/.
   5    5  .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   6    6  .\"  This notice shall appear on any product containing this material.
   7    7  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8    8  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9    9  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10      -.TH MAKECONTEXT 3C "Mar 8, 2004"
  11      -.SH NAME
  12      -makecontext, swapcontext \- manipulate user contexts
  13      -.SH SYNOPSIS
  14      -.LP
  15      -.nf
  16      -#include <ucontext.h>
  17      -
  18      -\fBvoid\fR \fBmakecontext\fR(\fBucontext_t *\fR\fIucp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIargc\fR...);
  19      -.fi
  20      -
  21      -.LP
  22      -.nf
  23      -\fBint\fR \fBswapcontext\fR(\fBucontext_t *restrict\fR \fIoucp\fR,
  24      -     \fBconst ucontext_t *restrict\fR \fIucp\fR);
  25      -.fi
  26      -
  27      -.SH DESCRIPTION
  28      -.sp
  29      -.LP
  30      -The \fBmakecontext()\fR function modifies the context specified by \fIucp\fR,
  31      -which has been initialized using \fBgetcontext\fR(2). When this context is
  32      -resumed using \fBswapcontext()\fR or \fBsetcontext\fR(2), execution continues
  33      -by calling the function \fIfunc\fR, passing it the arguments that follow
  34      -\fIargc\fR in the \fBmakecontext()\fR call. The value of \fIargc\fR must match
  35      -the number of pointer-sized integer arguments passed to \fIfunc\fR, otherwise
  36      -the behavior is undefined.
  37      -.sp
  38      -.LP
  39      -Before a call is made to \fBmakecontext()\fR, the context being modified should
       10 +.Dd "Jul 14, 2014"
       11 +.Dt MAKECONTEXT 3C
       12 +.Os
       13 +.Sh NAME
       14 +.Nm makecontext, swapcontext
       15 +.Nd manipulate user contexts
       16 +.Sh SYNOPSIS
       17 +.In ucontext.h
       18 +.Ft void
       19 +.Fn makecontext "ucontext_t *ucp" "void \*(lp*func\*(rp\*(lp\*(rp, int argc, ..."
       20 +.Ft int
       21 +.Fn swapcontext "ucontext_t *restrict oucp" "const ucontext_t *restrict ucp"
       22 +.Sh DESCRIPTION
       23 +The
       24 +.Fn makecontext
       25 +function modifies the context specified by
       26 +.Fa ucp ,
       27 +which has been initialized using
       28 +.Xr getcontext 2 .
       29 +When this context is
       30 +resumed using
       31 +.Fn swapcontext
       32 +or
       33 +.Xr setcontext 2 ,
       34 +execution continues by calling the function
       35 +.Fa func ,
       36 +passing it the arguments that follow
       37 +.Fa argc
       38 +in the
       39 +.Fn makecontext
       40 +call. The value of
       41 +.Fa argc
       42 +must match the number of pointer-sized integer arguments passed to
       43 +.Fn func ,
       44 +otherwise the behavior is undefined.
       45 +.Lp
       46 +Before a call is made to
       47 +.Fn makecontext ,
       48 +the context being modified should
  40   49  have a stack allocated for it. The stack is assigned to the context by
  41      -initializing the \fBuc_stack\fR member.
  42      -.sp
  43      -.LP
  44      -The \fBuc_link\fR member is used to determine the context that will be resumed
  45      -when the context being modified by \fBmakecontext()\fR returns.  The
  46      -\fBuc_link\fR member should be initialized prior to the call to
  47      -\fBmakecontext()\fR. If the \fBuc_link\fR member is initialized to \fINULL\fR,
  48      -the thread executing \fIfunc\fR will exit when \fIfunc\fR returns. See
  49      -\fBpthread_exit\fR(3C).
  50      -.sp
  51      -.LP
  52      -The \fBswapcontext()\fR function saves the current context in the context
  53      -structure pointed to by \fIoucp\fR and sets the context to the context
  54      -structure pointed to by \fIucp\fR.
  55      -.sp
  56      -.LP
  57      -If the \fIucp\fR or \fIoucp\fR argument points to an invalid address, the
  58      -behavior is undefined and \fBerrno\fR may be set to \fBEFAULT\fR.
  59      -.SH RETURN VALUES
  60      -.sp
  61      -.LP
  62      -On successful completion, \fBswapcontext()\fR returns \fB0\fR. Otherwise,
  63      -\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
  64      -.SH ERRORS
  65      -.sp
  66      -.LP
  67      -The \fBswapcontext()\fR function will fail if:
  68      -.sp
  69      -.ne 2
  70      -.na
  71      -\fB\fBENOMEM\fR\fR
  72      -.ad
  73      -.RS 10n
  74      -The \fIucp\fR argument does not have enough stack left to complete the
  75      -operation.
  76      -.RE
  77      -
  78      -.sp
  79      -.LP
  80      -The \fBswapcontext()\fR function may fail if:
  81      -.sp
  82      -.ne 2
  83      -.na
  84      -\fB\fBEFAULT\fR\fR
  85      -.ad
  86      -.RS 10n
  87      -The \fIucp\fR or \fIoucp\fR argument points to an invalid address.
  88      -.RE
  89      -
  90      -.SH EXAMPLES
  91      -.LP
  92      -\fBExample 1 \fRAlternate execution context on a stack whose memory was
  93      -allocated using \fBmmap()\fR.
  94      -.sp
  95      -.in +2
  96      -.nf
       50 +initializing the
       51 +.Fa uc_stack
       52 +member.
       53 +.Lp
       54 +The
       55 +.Fa uc_link
       56 +member is used to determine the context that will be resumed
       57 +when the context being modified by
       58 +.Fn makecontext
       59 +returns.  The
       60 +.Fa uc_link
       61 +member should be initialized prior to the call to
       62 +.Fn makecontext .
       63 +If the
       64 +.Fa uc_link
       65 +member is initialized to
       66 +.Dv NULL ,
       67 +the thread executing
       68 +.Fa func
       69 +will exit when
       70 +.Fa func
       71 +returns. See
       72 +.Xr pthread_exit 3C .
       73 +.Lp
       74 +The
       75 +.Fn swapcontext
       76 +function saves the current context in the context
       77 +structure pointed to by
       78 +.Fa oucp
       79 +and sets the context to the context
       80 +structure pointed to by
       81 +.Fa ucp .
       82 +.Lp
       83 +If the
       84 +.Fa ucp
       85 +or
       86 +.Fa oucp
       87 +argument points to an invalid address, the
       88 +behavior is undefined and
       89 +.Va errno
       90 +may be set to
       91 +.Er EFAULT .
       92 +.Sh RETURN VALUES
       93 +.Rv -std swapcontext
       94 +.Sh EXAMPLES
       95 +.Ss Example 1
       96 +The following example illustrates execution context on a stack whose memory was
       97 +allocated using
       98 +.Xr  mmap 2 :
       99 +.Bd -literal -offset indent
  97  100  #include <stdio.h>
  98  101  #include <ucontext.h>
  99  102  #include <sys/mman.h>
 100  103  
 101  104  void
 102  105  assign(long a, int *b)
 103  106  {
 104  107          *b = (int)a;
 105  108  }
 106  109  
↓ open down ↓ 14 lines elided ↑ open up ↑
 121  124  
 122  125          uc.uc_link = &back;
 123  126  
 124  127          makecontext(&uc, assign, 2, 100L, &value);
 125  128          swapcontext(&back, &uc);
 126  129  
 127  130          printf("done %d\en", value);
 128  131  
 129  132          return (0);
 130  133  }
 131      -.fi
 132      -.in -2
 133      -
 134      -.SH USAGE
 135      -.sp
 136      -.LP
      134 +.Ed
      135 +.Sh ERRORS
      136 +The
      137 +.Fn swapcontext
      138 +function will fail if:
      139 +.Bl -tag -width Er
      140 +.It Er ENOMEM
      141 +The
      142 +.Fa ucp
      143 +argument does not have enough stack left to complete the operation.
      144 +.El
      145 +.Lp
      146 +The
      147 +.Fn swapcontext
      148 +function may fail if:
      149 +.Bl -tag -width Er
      150 +.It Er EFAULT
      151 +The
      152 +.Fa ucp
      153 +or
      154 +.Fa oucp
      155 +argument points to an invalid address.
      156 +.El
      157 +.Sh USAGE
 137  158  These functions are useful for implementing user-level context switching
 138  159  between multiple threads of control within a process (co-processing). More
 139  160  effective multiple threads of control can be obtained by using native support
 140      -for multithreading. See \fBthreads\fR(5).
 141      -.SH ATTRIBUTES
 142      -.sp
 143      -.LP
 144      -See \fBattributes\fR(5) for descriptions of the following attributes:
 145      -.sp
 146      -
 147      -.sp
 148      -.TS
 149      -box;
 150      -c | c
 151      -l | l .
 152      -ATTRIBUTE TYPE  ATTRIBUTE VALUE
 153      -_
 154      -Interface Stability     Standard
 155      -_
 156      -MT-Level        MT-Safe
 157      -.TE
 158      -
 159      -.SH SEE ALSO
 160      -.sp
 161      -.LP
 162      -\fBmmap\fR(2), \fBgetcontext\fR(2), \fBsigaction\fR(2), \fBsigprocmask\fR(2),
 163      -\fBpthread_exit\fR(3C), \fBucontext.h\fR(3HEAD), \fBattributes\fR(5),
 164      -\fBstandards\fR(5), \fBthreads\fR(5)
 165      -.SH NOTES
 166      -.sp
 167      -.LP
 168      -The semantics of the \fBuc_stack\fR member of the \fBucontext_t\fR structure
 169      -have changed as they apply to inputs to \fBmakecontext()\fR. Prior to Solaris
 170      -10, the \fBss_sp\fR member of the \fBuc_stack\fR structure represented the high
      161 +for multithreading. See
      162 +.Xr pthreads 5 .
      163 +.Sh INTERFACE STABILITY
      164 +.Sy Obsolete Standard .
      165 +.Sh MT-LEVEL
      166 +.Sy MT-Safe .
      167 +.Sh SEE ALSO
      168 +.Xr mmap 2 ,
      169 +.Xr getcontext 2 ,
      170 +.Xr sigaction 2 ,
      171 +.Xr sigprocmask 2 ,
      172 +.Xr pthread_exit 3C ,
      173 +.Xr ucontext.h 3HEAD ,
      174 +.Xr standards 5 ,
      175 +.Xr pthreads 5
      176 +.Sh NOTES
      177 +The semantics of the
      178 +.Fa uc_stack
      179 +member of the
      180 +.Ft ucontext_t
      181 +structure have changed as they apply to inputs to
      182 +.Fn makecontex .
      183 +Prior to Solaris 10, the
      184 +.Fa ss_sp
      185 +member of the
      186 +.Fa uc_stack
      187 +structure represented the high
 171  188  memory address of the area reserved for the stack. The \fBss_sp\fR member now
 172  189  represents the base (low memory address), in keeping with other uses of
 173      -\fBss_sp\fR.
 174      -.sp
 175      -.LP
 176      -This change in the meaning of \fBss_sp\fR is now the default behavior. The
 177      -\fB-D__MAKECONTEXT_V2_SOURCE\fR compilation flag used in Solaris 9 update
      190 +.Fa ss_sp .
      191 +.Lp
      192 +This change in the meaning of
      193 +.Fa ss_sp
      194 +is now the default behavior. The
      195 +.Dv -D__MAKECONTEXT_V2_SOURCE
      196 +compilation flag used in Solaris 9 update
 178  197  releases to access this behavior is obsolete.
 179      -.sp
 180      -.LP
      198 +.Lp
 181  199  Binary compatibility has been preserved with releases prior to Solaris 10.
 182      -Before recompiling, applications that use \fBmakecontext()\fR must be updated
 183      -to reflect this behavior change. The example below demonstates a typical change
 184      -that must be applied:
 185      -.sp
 186      -.in +2
 187      -.nf
 188      ---- example1_s9.c       Thu Oct  3 11:58:17 2002
 189      -+++ example1.c  Thu Jun 27 13:28:16 2002
 190      -@@ -27,12 +27,9 @@
 191      -        uc.uc_stack.ss_sp = mmap(0, sz,
 192      -            PROT_READ | PROT_WRITE | PROT_EXEC,
 193      -            MAP_PRIVATE | MAP_ANON, -1, 0);
 194      --       uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
 195      -        uc.uc_stack.ss_size = sz;
 196      -        uc.uc_stack.ss_flags = 0;
 197      -
 198      -        uc.uc_link = &back
 199      -
 200      -        makecontext(&uc, assign, 2, 100L, &value);
 201      -.fi
 202      -.in -2
 203      -
      200 +Before recompiling, applications that use
      201 +.Fn makecontext
      202 +must be updated
      203 +to reflect this behavior change.
      204 +.Lp
      205 +Portable applications should not use this function. Instead, applications
      206 +should use
      207 +.Xr pthreads 5
      208 +routines.
      209 +.Lp
      210 +Note that the definition of
      211 +.Fn makecontext
      212 +violates
      213 +.St -isoC .
      214 +There is no way to declare this function that does not violate that
      215 +standard.
      216 +.Sh STANDARDS
      217 +This function  was introduced in
      218 +.St -xpg4.2 ,
      219 +and subsequently removed from
      220 +.St -p1003.1-2008 .
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX