thr_create

Creates a new thread.

Library:LibC
Classification:UNIX International
Service:Threads

Syntax

  #include <thread.h>
   
  int thr_create (
     void       *stack_base,
     size_t      stack_size,
     void       *(*start_routine)(void *),
     void       *arg,
     long        flags,
     thread_t   *new_thr);

Parameters

stack_base

(IN) Points to the allocated stack for the thread. If NULL, the minimum size stack is allocated. If non-NULL, the value must be equal to or greater than the minimum stack size (see thr_minstack). If a user-allocated stack is used, the stack needs to be aligned on a 32-bit boundary.

stack_size

(IN) Specifies the size of the thread stack.

start_routine

(IN) Points to the function on which the thread should start executing.

arg

(IN) Points to an argument passed to the start_routine.

flags

(IN) Specifies the thread attributes. You can set it to zero or a bitwise OR of the following. If zero, the thread is created as a joinable thread.

Flag

Value

Description

THR_BOUND

0x00000080

Create a thread (application or daemon) that automatically frees system resources when the thread exits. When this flag is not set, some system resources are not freed until the application exits.

THR_DETACHED

0x00000010

Create the new thread in a detached state. A detached thread cannot be waited for. A thread created without this flag is defined to be a joinable thread. A joinable thread is also referred to as a waitable thread or a non-detached thread. Only joinable threads can be waited for (or “joined”) using the thr_join interface.

THR_NEW_LWP

0xFFFFFFFE

Binds the thread to the current CPU.

THR_SUSPENDED

0x00000020

Create the new thread in a suspended state. The thread does not start execution until thr_continue is called.

THR_DAEMON

0x00000040

Create a new thread as a daemon thread. Daemon threads are not considered when determining when the last application thread has exited. Daemon threads are always detached; the THR_DETACHED flag must also be set when creating a daemon thread.
new_thr

(OUT) Points to the thread ID of the newly created thread.

Return Values

If successful, returns 0. Otherwise, returns one of the following error codes:

Decimal

Constant

Description

9

EINVAL

A parameter is invalid, possibly the flags or stack_size parameter.

24

EAGAIN

The system lacks the necessary resources to create a new thread or the process has reached its limit for threads.

79

ENOTSUP

The stack_base parameter is not supported on NetWare and must be set to 0.

Remarks

The thread is created executing start_routine with arg as its sole argument. If the start_routine returns, the effect is as if thr_exit was called, using the return value of start_routine as the exit status. The thread in which main was originally invoked differs from this process. When it returns from main, the effect is as if exit was called, using the return value of main as the exit status.

The signal state of the new thread is initialized as follows:

  • The signal mask is inherited from the creating thread.

  • The set of signals pending for the new thread is empty.

If thr_create fails, no new thread is created, and the contents of the new_thr parameter are undefined.

See Also