lib/libc/sys/_lwp_ctl.2

   1 .\"     $NetBSD: _lwp_ctl.2,v 1.3 2009/02/17 18:51:56 njoly Exp $
   2 .\"
   3 .\" Copyright (c)2007 YAMAMOTO Takashi,
   4 .\" All rights reserved.
   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 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" ------------------------------------------------------------
  28 .Dd May 5, 2008
  29 .Dt _LWP_CTL 2
  30 .Os
  31 .Sh NAME
  32 .Nm _lwp_ctl
  33 .Nd prepare per-LWP communication area between kernel and userland
  34 .\" ------------------------------------------------------------
  35 .Sh LIBRARY
  36 .Lb libc
  37 .\" ------------------------------------------------------------
  38 .Sh SYNOPSIS
  39 .In lwp.h
  40 .Ft int
  41 .Fn _lwp_ctl "int features" "struct lwpctl **address"
  42 .\" ------------------------------------------------------------
  43 .Sh DESCRIPTION
  44 .Fn _lwp_ctl
  45 prepares per-LWP communication area for the calling LWP,
  46 and maps it into the calling process' address space.
  47 It takes the following arguments.
  48 .Bl -tag -width features
  49 .It Fa features
  50 The bitwise-OR of the following flags.
  51 .Bl -tag -width LWPCTL_FEATURE_CURCPU
  52 .It Dv LWPCTL_FEATURE_CURCPU
  53 Request lc_curcpu.
  54 .It Dv LWPCTL_FEATURE_PCTR
  55 Request lc_pctr.
  56 .El
  57 .It Fa address
  58 The address to store a pointer to lwpctl structure for the calling LWP.
  59 .El
  60 .Pp
  61 The per-LWP communication area is described by an lwpctl structure.
  62 It has following members, depending on
  63 .Fa features .
  64 .Bl -tag -width int_lc_curcpu
  65 .It int lc_curcpu
  66 The integral identifier of the CPU on which the LWP is running,
  67 or
  68 .Dv LWPCTL_CPU_NONE
  69 when the LWP is not running on any CPU.
  70 It's updated by the kernel and should be considered as read-only for
  71 userland.
  72 It's available only if requested with the
  73 .Dv LWPCTL_FEATURE_CURCPU
  74 flag.
  75 .It int lc_pctr
  76 The integer which is incremented on every context switches to the LWP.
  77 It can be used to detect preemption of the LWP.
  78 (thus its name "preemption counter".)
  79 It's updated by the kernel and should be considered as read-only for
  80 userland.
  81 It's available only if requested with the
  82 .Dv LWPCTL_FEATURE_PCTR
  83 flag.
  84 .El
  85 .\" ------------------------------------------------------------
  86 .Sh RETURN VALUES
  87 .Fn _lwp_ctl
  88 returns 0 on success.
  89 Otherwise, \-1 is returned and
  90 .Va errno
  91 is set to indicate the error.
  92 .\" ------------------------------------------------------------
  93 .\".Sh ERRORS
  94 .\" ------------------------------------------------------------
  95 .Sh SEE ALSO
  96 .Xr errno 2