path: root/usr/src/man/man3c/pthread_create.3c

.\"
.\" 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
.\" http://www.opengroup.org/bookstore/.
.\"
.\" 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 SunOS 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" 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.
.\"
.\" 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.
.\"
.\" 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]
.\"
.\"
.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH PTHREAD_CREATE 3C "Mar 23, 2005"
.SH NAME
pthread_create \- create a thread
.SH SYNOPSIS
.LP
.nf
cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
#include <pthread.h>

\fBint\fR \fBpthread_create\fR(\fBpthread_t *restrict\fR \fIthread\fR,
     \fBconst pthread_attr_t *restrict\fR \fIattr\fR,
     \fBvoid *(*\fR\fIstart_routine\fR)(void*), \fBvoid *restrict\fR \fIarg\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpthread_create()\fR function is used to create a new thread, with
attributes specified by \fIattr\fR, within a process. If \fIattr\fR is
\fINULL,\fR the default attributes are used. (See \fBpthread_attr_init\fR(3C)).
If the attributes specified by \fIattr\fR are modified later, the thread's
attributes are not affected. Upon successful completion, \fBpthread_create()\fR
stores the  \fBID\fR of the created thread in the location referenced by
\fIthread\fR.
.sp
.LP
The thread is created executing \fIstart_routine\fR with \fIarg\fR as its sole
argument. If the \fIstart_routine\fR returns, the effect is as if there was an
implicit call to \fBpthread_exit()\fR using the return value of
\fIstart_routine\fR as the exit status. Note that the thread in which
\fBmain()\fR was originally invoked differs from this. When it returns from
\fBmain()\fR, the effect is as if there was an implicit call to \fBexit()\fR
using the return value of \fBmain()\fR as the exit status.
.sp
.LP
The signal state of the new thread is initialised as follows:
.RS +4
.TP
.ie t \(bu
.el o
The signal mask is inherited from the creating thread.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The set of signals pending for the new thread is empty.
.RE
.sp
.LP
Default thread creation:
.sp
.in +2
.nf
pthread_t tid;
void *start_func(void *), *arg;

pthread_create(&tid, NULL, start_func, arg);
.fi
.in -2

.sp
.LP
This would have the same effect as:
.sp
.in +2
.nf
\fBpthread_attr_t attr;

pthread_attr_init(&attr); /* initialize attr with default */
                          /* attributes */
pthread_create(&tid, &attr, start_func, arg);\fR
.fi
.in -2

.sp
.LP
User-defined thread creation: To create a thread that is scheduled on a
system-wide basis, use:
.sp
.in +2
.nf
pthread_attr_init(&attr); /* initialize attr with default */
                                       /* attributes */
pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM);
                                       /* system-wide contention */
pthread_create(&tid, &attr, start_func, arg);
.fi
.in -2

.sp
.LP
To customize the attributes for POSIX threads, see \fBpthread_attr_init\fR(3C).
.sp
.LP
A new thread created with \fBpthread_create()\fR uses the stack specified by
the \fIstackaddr\fR attribute, and the stack continues for the number of bytes
specified by the \fIstacksize\fR attribute. By default, the stack size is 1
megabyte for 32-bit processes and 2 megabyte for 64-bit processes (see
\fBpthread_attr_setstacksize\fR(3C)). If the default is used for both the
\fIstackaddr\fR and \fIstacksize\fR attributes, \fBpthread_create()\fR creates
a stack for the new thread with at least 1 megabyte for 32-bit processes and 2
megabyte for 64-bit processes. (For customizing stack sizes, see \fBNOTES\fR).
.sp
.LP
If \fBpthread_create()\fR fails, no new thread is created and the contents of
the location referenced by \fIthread\fR are undefined.
.SH RETURN VALUES
.sp
.LP
If successful, the \fBpthread_create()\fR function returns  \fB0\fR. Otherwise,
an error number is returned to indicate the error.
.SH ERRORS
.sp
.LP
The  \fBpthread_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
The system lacked the necessary resources to create another thread, or the
system-imposed limit on the total number of threads in a process
\fBPTHREAD_THREADS_MAX\fR would be exceeded.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The value specified by \fIattr\fR is invalid.
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 10n
The caller does not have appropriate permission to set the required scheduling
parameters or scheduling policy.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRExample of concurrency with multithreading
.sp
.LP
The following is an example of concurrency with multithreading. Since POSIX
threads and Solaris threads are fully compatible even within the same process,
this example uses \fBpthread_create()\fR if you execute \fBa.out 0\fR, or
\fBthr_create()\fR if you execute \fBa.out 1\fR.

.sp
.LP
Five threads are created that simultaneously perform a time-consuming function,
\fBsleep(\fR10\fB)\fR. If the execution of this process is timed, the results
will show that all five individual calls to sleep for ten-seconds completed in
about ten seconds, even on a uniprocessor. If a single-threaded process calls
\fBsleep(\fR10\fB)\fR five times, the execution time will be about 50-seconds.

.sp
.LP
The command-line to time this process is:

.sp
.ne 2
.na
\fBPOSIX threading\fR
.ad
.RS 21n
/usr/bin/time a.out 0
.RE

.sp
.ne 2
.na
\fBSolaris threading\fR
.ad
.RS 21n
/usr/bin/time a.out 1
.RE

.sp
.in +2
.nf
/* cc thisfile.c -lthread -lpthread */
#define _REENTRANT    /* basic 3-lines for threads */
#include <pthread.h>
#include <thread.h>

#define NUM_THREADS 5
#define SLEEP_TIME 10

void *sleeping(void *);   /* thread routine */
int i;
thread_t tid[NUM_THREADS];      /* array of thread IDs */

int
main(int argc, char *argv[])
{
    if (argc == 1)  {
        printf("use 0 as arg1 to use pthread_create(\|)\en");
        printf("or use 1 as arg1 to use thr_create(\|)\en");
        return (1);
    }

    switch (*argv[1])  {
    case '0':  /* POSIX */
        for ( i = 0; i < NUM_THREADS; i++)
            pthread_create(&tid[i], NULL, sleeping,
                (void *)SLEEP_TIME);
        for ( i = 0; i < NUM_THREADS; i++)
            pthread_join(tid[i], NULL);
        break;

    case '1':  /* Solaris */
        for ( i = 0; i < NUM_THREADS; i++)
            thr_create(NULL, 0, sleeping, (void *)SLEEP_TIME, 0,
                &tid[i]);
        while (thr_join(0, NULL, NULL) == 0)
            ;
        break;
    }  /* switch */
    printf("main(\|) reporting that all %d threads have
        terminated\en", i);
    return (0);
}  /* main */

void *
sleeping(void *arg)
{
    int sleep_time = (int)arg;
    printf("thread %d sleeping %d seconds ...\en", thr_self(\|),
        sleep_time);
    sleep(sleep_time);
    printf("\enthread %d awakening\en", thr_self(\|));
    return (NULL);
}
.fi
.in -2

.sp
.LP
If \fBmain()\fR had not waited for the completion of the other threads (using
\fBpthread_join\fR(3C) or \fBthr_join\fR(3C)), it would have continued to
process concurrently until it reached the end of its routine and the entire
process would have exited prematurely. See \fBexit\fR(2).

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBfork\fR(2), \fBpthread_attr_init\fR(3C), \fBpthread_cancel\fR(3C),
\fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), \fBsysconf\fR(3C),
\fBattributes\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
Multithreaded application threads execute independently of each other, so their
relative behavior is unpredictable. Therefore, it is possible for the thread
executing \fBmain()\fR to finish before all other user application threads. The
\fBpthread_join\fR(3C)function, on the other hand, must specify the terminating
thread (IDs) for which it will wait.
.sp
.LP
A user-specified stack size must be greater than the value
\fBPTHREAD_STACK_MIN\fR. A minimum stack size may not accommodate the stack
frame for the user thread function \fIstart_func\fR. If a stack size is
specified, it must accommodate \fIstart_func\fR requirements and the functions
that it may call in turn, in addition to the minimum requirement.
.sp
.LP
It is usually very difficult to determine the runtime stack requirements for a
thread. \fBPTHREAD_STACK_MIN\fR specifies how much stack storage is required to
execute a \fINULL\fR \fIstart_func\fR. The total runtime requirements for stack
storage are dependent on the storage required to do runtime linking, the amount
of storage required by library runtimes (as \fBprintf()\fR) that your thread
calls. Since these storage parameters are not known before the program runs, it
is best to use default stacks. If you know your runtime requirements or decide
to use stacks that are larger than the default, then it makes sense to specify
your own stacks.