---
name: "pthread_create"
section: "3"
platform: "macos"
package: "libpthread"
version: "539.100.4"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/pthread_create"
---

# pthread\_create(3)

create a new thread

## NAME

**pthread\_create** – create a new thread

## SYNOPSIS

**#include \<pthread.h\>**

*int*\

**pthread\_create**(*pthread\_t \*thread*, *const pthread\_attr\_t \*attr*, *void \*(\*start\_routine)(void \*)*, *void \*arg*);

## DESCRIPTION

The **pthread\_create**() function is used to create a new thread, with attributes specified by *attr*, within a process. If *attr* is NULL, the default attributes are used. If the attributes specified by *attr* are modified later, the thread's attributes are not affected. Upon successful completion **pthread\_create**() will store the ID of the created thread in the location specified by *thread*.

The thread is created executing *start\_routine* with *arg* as its sole argument. If the *start\_routine* returns, the effect is as if there was an implicit call to **pthread\_exit**() using the return value of *start\_routine* as the exit status. Note that the thread in which **main**() was originally invoked differs from this. When it returns from **main**(), the effect is as if there was an implicit call to **exit**() using the return value of **main**() as the exit status.

Upon thread exit the storage for the thread must be reclaimed by another thread via a call to **pthread\_join**(). Alternatively, **pthread\_detach**() may be called on the thread to indicate that the system may automatically reclaim the thread storage upon exit. The **pthread\_attr\_setdetachstate**() function may be used on the *attr* argument passed to **pthread\_create**() in order to achieve the same effect as a call to **pthread\_detach**() on the newly created thread.

The signal state of the new thread is initialized as:

- The signal mask is inherited from the creating thread.

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

## RETURN VALUES

If successful, the **pthread\_create**() function will return zero. Otherwise an error number will be returned to indicate the error.

## ERRORS

The **pthread\_create**() function will fail if:

- \[EAGAIN\]

  The system lacked the necessary resources to create another thread, or the system-imposed limit on the total number of threads in a process \[PTHREAD\_THREADS\_MAX\] would be exceeded.

- \[EPERM\]

  The caller does not have appropriate permission to set the required scheduling parameters or scheduling policy.

- \[EINVAL\]

  The value specified by *attr* is invalid.

## SEE ALSO

[fork(2)](/fork/2.md), [pthread\_attr(3)](/pthread_attr/3.md), [pthread\_cancel(3)](/pthread_cancel/3.md), [pthread\_cleanup\_pop(3)](/pthread_cleanup_pop/3.md), [pthread\_cleanup\_push(3)](/pthread_cleanup_push/3.md), [pthread\_exit(3)](/pthread_exit/3.md), [pthread\_join(3)](/pthread_join/3.md)

## STANDARDS

The **pthread\_create**() function conforms to ISO/IEC 9945-1:1996 (“POSIX.1”).