share/man/man3c/thr_min_stack.3c

   1 '\" te
   2 .\"  Copyright (c) 1997 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH THR_MIN_STACK 3C "Nov 26, 2017"
   7 .SH NAME
   8 thr_min_stack \- return the minimum-allowable size for a thread's stack
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ]
  13 #include <thread.h>
  14
  15 \fBsize_t\fR \fBthr_min_stack\fR(\fB\fR\fIvoid\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 When a thread is created with a user-supplied stack, the user must reserve
  21 enough space to run this thread. In a dynamically linked execution environment,
  22 it is very hard to know what the minimum stack requirements are for a thread.
  23 The function \fBthr_min_stack()\fR returns the amount of space needed to
  24 execute a null thread. This is a thread that was created to execute a null
  25 procedure. A thread that does something useful should have a stack size that is
  26 \fBthr_min_stack()\fR + \fI<some increment>\fR\&.
  27 .sp
  28 .LP
  29 Most users should not be creating threads with user-supplied stacks. This
  30 functionality was provided to support applications that wanted complete control
  31 over their execution environment.
  32 .sp
  33 .LP
  34 Typically, users should let the threads library manage stack allocation. The
  35 threads library provides default stacks which should meet the requirements of
  36 any created thread.
  37 .sp
  38 .LP
  39 \fBthr_min_stack()\fR will return the unsigned int \fBTHR_MIN_STACK,\fR which
  40 is the minimum-allowable size for a thread's stack.
  41 .sp
  42 .LP
  43 In this implementation the default size for a user-thread's stack is one
  44 mega-byte. If the second argument to \fBthr_create\fR(3C) is \fBNULL,\fR then
  45 the default stack size for the newly-created thread will be used. Otherwise,
  46 you may specify a stack-size that is at least \fBTHR_MIN_STACK,\fR yet less
  47 than the size of your machine's virtual memory.
  48 .sp
  49 .LP
  50 It is recommended that the default stack size be used.
  51 .sp
  52 .LP
  53 To determine the smallest-allowable size for a thread's stack, execute the
  54 following:
  55 .sp
  56 .in +2
  57 .nf
  58 /* cc thisfile.c */
  59 #include <thread.h>
  60 #include <stdio.h>
  61 main(\|)  {
  62         printf("thr_min_stack(\|) returns %u\en",thr_min_stack(\|));
  63 }
  64 .fi
  65 .in -2
  66
  67 .SH ATTRIBUTES
  68 .LP
  69 See \fBattributes\fR(5) for descriptions of the following attributes:
  70 .sp
  71
  72 .sp
  73 .TS
  74 box;
  75 c | c
  76 l | l .
  77 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  78 _
  79 MT-Level        MT-Safe
  80 .TE
  81
  82 .SH SEE ALSO
  83 .LP
  84 \fBattributes\fR(5), \fBstandards\fR(5)