lib/libc/sys/lwp_create.2

   1 .\" Copyright (c) 2007 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Simon 'corecode' Schubert <corecode@fs.ei.tum.de>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $DragonFly: src/lib/libc/sys/lwp_create.2,v 1.1 2007/03/12 21:06:18 corecode Exp $
  34 .\"
  35 .Dd March 12, 2007
  36 .Dt LWP_CREATE 2
  37 .Os
  38 .Sh NAME
  39 .Nm lwp_create
  40 .Nd spawn a new lwp
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft int
  46 .Fn lwp_create "struct lwp_params *params"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn lwp_create
  50 function is used to spawn a new lwp in the current process.
  51 In some way, this is like
  52 .Xr fork 2 ,
  53 however
  54 .Fn lwp_create
  55 does not return twice as parent and child.
  56 Instead, the new lwp will start running a function which
  57 is provided with the parameters
  58 .Fa params ,
  59 as outlined below.
  60 .Bd -literal
  61 struct lwp_params {
  62         void (*func)(void *);   /* Function to start execution */
  63         void *arg;              /* Parameter to this function */
  64         void *stack;            /* Stack address to use */
  65         lwpid_t *tid1;          /* Address to copy out new tid */
  66         lwpid_t *tid2;          /* Same */
  67 };
  68 .Ed
  69 .Pp
  70 The
  71 .Fa params
  72 passed to
  73 .Fn lwp_create
  74 are as follows.
  75 Set
  76 .Fa func
  77 to specify the function to be executed in the new lwp.
  78 It is the duty of
  79 .Fa func
  80 to terminate
  81 execution of the lwp correctly, either by calling
  82 .Xr extexit 2
  83 or
  84 .Xr exit 3 .
  85 If the
  86 .Fa func
  87 simply returns, behavior is unspecified.
  88 The only function argument passed to
  89 .Fa func
  90 is
  91 .Fa arg .
  92 .Pp
  93 The new lwp starts out with its stack frame set to
  94 .Fa stack .
  95 This parameter, like
  96 .Fa func
  97 is mandatory.  If any of these is invalid, behavior is
  98 unspecified.
  99 .Pp
 100 The fields
 101 .Fa tid1
 102 and
 103 .Fa tid2
 104 point to variables where the tid of the new lwp should be stored.
 105 There are two parameters so that storage for both parent
 106 and child can be specified separately.  Set any of these fields to
 107 NULL in case you don't need the tid to be copied out.
 108 .Sh RETURN VALUES
 109 Upon successful completion, the value 0 is returned;
 110 otherwise the value -1 is returned and
 111 .Va errno
 112 will be set to
 113 .Er EINVAL .
 114 .Sh SEE ALSO
 115 .Xr extexit 2 ,
 116 .Xr rfork 2 ,
 117 .Xr exit 3
 118 .Sh HISTORY
 119 The
 120 .Fn lwp_create
 121 function first appeared in
 122 .Dx 1.9 .