JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
man pages section 2: System Calls     Oracle Solaris 11 Information Library
search filter icon
search icon

Document Information

Preface

Introduction

System Calls

access(2)

acct(2)

acl(2)

adjtime(2)

alarm(2)

brk(2)

chdir(2)

chmod(2)

chown(2)

chroot(2)

close(2)

creat(2)

dup(2)

exec(2)

execl(2)

execle(2)

execlp(2)

execv(2)

execve(2)

execvex(2)

execvp(2)

_Exit(2)

_exit(2)

exit(2)

faccessat(2)

facl(2)

fchdir(2)

fchmod(2)

fchmodat(2)

fchown(2)

fchownat(2)

fchroot(2)

fcntl(2)

fexecve(2)

fgetlabel(2)

fork1(2)

fork(2)

forkall(2)

forkallx(2)

forkx(2)

fpathconf(2)

fstat(2)

fstatat(2)

fstatvfs(2)

futimens(2)

futimesat(2)

getacct(2)

getcontext(2)

getdents(2)

getegid(2)

geteuid(2)

getgid(2)

getgroups(2)

getisax(2)

getitimer(2)

getlabel(2)

getmsg(2)

getpflags(2)

getpgid(2)

getpgrp(2)

getpid(2)

getpmsg(2)

getppid(2)

getppriv(2)

getprojid(2)

getrctl(2)

getrlimit(2)

getsid(2)

gettaskid(2)

getuid(2)

getustack(2)

ioctl(2)

issetugid(2)

kill(2)

lchown(2)

link(2)

linkat(2)

llseek(2)

lseek(2)

lstat(2)

_lwp_cond_broadcast(2)

_lwp_cond_reltimedwait(2)

_lwp_cond_signal(2)

_lwp_cond_timedwait(2)

_lwp_cond_wait(2)

_lwp_continue(2)

_lwp_info(2)

_lwp_kill(2)

_lwp_mutex_lock(2)

_lwp_mutex_trylock(2)

_lwp_mutex_unlock(2)

_lwp_self(2)

_lwp_sema_init(2)

_lwp_sema_post(2)

_lwp_sema_trywait(2)

_lwp_sema_wait(2)

_lwp_suspend(2)

memcntl(2)

meminfo(2)

mincore(2)

mkdir(2)

mkdirat(2)

mknod(2)

mknodat(2)

mmap(2)

mmapobj(2)

mount(2)

mprotect(2)

msgctl(2)

msgget(2)

msgids(2)

msgrcv(2)

msgsnap(2)

msgsnd(2)

munmap(2)

nice(2)

ntp_adjtime(2)

ntp_gettime(2)

open(2)

openat(2)

pathconf(2)

pause(2)

pcsample(2)

pipe(2)

poll(2)

p_online(2)

ppoll(2)

pread(2)

priocntl(2)

priocntlset(2)

processor_bind(2)

processor_info(2)

profil(2)

pset_assign(2)

pset_bind(2)

pset_create(2)

pset_destroy(2)

pset_getattr(2)

pset_info(2)

pset_list(2)

pset_setattr(2)

putacct(2)

putmsg(2)

putpmsg(2)

pwrite(2)

read(2)

readlink(2)

readlinkat(2)

readv(2)

rename(2)

renameat(2)

resolvepath(2)

rmdir(2)

sbrk(2)

semctl(2)

semget(2)

semids(2)

semop(2)

semtimedop(2)

setcontext(2)

setegid(2)

seteuid(2)

setgid(2)

setgroups(2)

setitimer(2)

setpflags(2)

setpgid(2)

setpgrp(2)

setppriv(2)

setrctl(2)

setregid(2)

setreuid(2)

setrlimit(2)

setsid(2)

settaskid(2)

setuid(2)

setustack(2)

shmadv(2)

shmat(2)

shmctl(2)

shmdt(2)

shmget(2)

shmids(2)

shmop(2)

sigaction(2)

sigaltstack(2)

sigpending(2)

sigprocmask(2)

sigsend(2)

sigsendset(2)

sigsuspend(2)

sigwait(2)

__sparc_utrap_install(2)

stat(2)

statvfs(2)

stime(2)

swapctl(2)

symlink(2)

symlinkat(2)

sync(2)

sysfs(2)

sysinfo(2)

time(2)

times(2)

uadmin(2)

ulimit(2)

umask(2)

umount(2)

umount2(2)

uname(2)

unlink(2)

unlinkat(2)

ustat(2)

utime(2)

utimensat(2)

utimes(2)

uucopy(2)

vfork(2)

vforkx(2)

vhangup(2)

waitid(2)

wracct(2)

write(2)

writev(2)

yield(2)

fork

, fork1

, forkall

, forkx

, forkallx

- create a new process

Synopsis

#include <sys/types.h>
#include <unistd.h>

pid_t fork(void);
pid_t fork1(void);
pid_t forkall(void);
#include <sys/fork.h>

pid_t forkx(int flags);
pid_t forkallx(int flags);

Description

The fork(), fork1(), forkall(), forkx(), and forkallx() functions create a new process. The address space of the new process (child process) is an exact copy of the address space of the calling process (parent process). The child process inherits the following attributes from the parent process:

Scheduling priority and any per-process scheduling parameters that are specific to a given scheduling class might or might not be inherited according to the policy of that particular class (see priocntl(2)). The child process might or might not be in the same process contract as the parent (see process(4)). The child process differs from the parent process in the following ways:

Record locks set by the parent process are not inherited by the child process (see fcntl(2)).

Although any open door descriptors in the parent are shared by the child, only the parent will receive a door invocation from clients even if the door descriptor is open in the child. If a descriptor is closed in the parent, attempts to operate on the door descriptor will fail even if it is still open in the child.

Threads

A call to forkall() or forkallx() replicates in the child process all of the threads (see thr_create(3C) and pthread_create(3C)) in the parent process. A call to fork1() or forkx() replicates only the calling thread in the child process.

A call to fork() is identical to a call to fork1(); only the calling thread is replicated in the child process. This is the POSIX-specified behavior for fork().

In releases of Solaris prior to Solaris 10, the behavior of fork() depended on whether or not the application was linked with the POSIX threads library. When linked with -lthread (Solaris Threads) but not linked with -lpthread (POSIX Threads), fork() was the same as forkall(). When linked with -lpthread, whether or not also linked with -lthread, fork() was the same as fork1().

Prior to Solaris 10, either -lthread or -lpthread was required for multithreaded applications. This is no longer the case. The standard C library provides all threading support for both sets of application programming interfaces. Applications that require replicate-all fork semantics must call forkall() or forkallx().

Fork Extensions

The forkx() and forkallx() functions accept a flags argument consisting of a bitwise inclusive-OR of zero or more of the following flags, which are defined in the header <sys/fork.h>:

FORK_NOSIGCHLD

Do not post a SIGCHLD signal to the parent process when the child process terminates, regardless of the disposition of the SIGCHLD signal in the parent. SIGCHLD signals are still possible for job control stop and continue actions if the parent has requested them.

FORK_WAITPID

Do not allow wait-for-multiple-pids by the parent, as in wait(), waitid(P_ALL), or waitid(P_PGID), to reap the child and do not allow the child to be reaped automatically due the disposition of the SIGCHLD signal being set to be ignored in the parent. Only a specific wait for the child, as in waitid(P_PID, pid), is allowed and it is required, else when the child exits it will remain a zombie until the parent exits.

If the flags argument is 0 forkx() is identical to fork() and forkallx() is identical to forkall().

fork() Safety

If a multithreaded application calls fork(), fork1(), or forkx(), and the child does more than simply call one of the exec(2) functions, there is a possibility of deadlock occurring in the child. The application should use pthread_atfork(3C) to ensure safety with respect to this deadlock. Should there be any outstanding mutexes throughout the process, the application should call pthread_atfork() to wait for and acquire those mutexes prior to calling fork(), fork1(), or forkx(). See “MT-Level of Libraries” on the attributes(5) manual page.

The pthread_atfork() mechanism is used to protect the locks that libc(3LIB) uses to implement interfaces such as malloc(3C). All interfaces provided by libc are safe to use in a child process following a fork(), except when fork() is executed within a signal handler.

The POSIX standard (see standards(5)) requires fork to be Async-Signal-Safe (see attributes(5)). This cannot be made to happen with fork handlers in place, because they acquire locks. To be in nominal compliance, no fork handlers are called when fork() is executed within a signal context. This leaves the child process in a questionable state with respect to its locks, but at least the calling thread will not deadlock itself attempting to acquire a lock that it already owns. In this situation, the application should strictly adhere to the advice given in the POSIX specification: “To avoid errors, the child process may only execute Async-Signal-Safe operations until such time as one of the exec(2) functions is called.”

Return Values

Upon successful completion, fork(), fork1(), forkall(), forkx(), and forkallx() return 0 to the child process and return the process ID of the child process to the parent process. Otherwise, (pid_t)-1 is returned to the parent process, no child process is created, and errno is set to indicate the error.

Errors

The fork(), fork1(), forkall(), forkx(), and forkallx() functions will fail if:

EAGAIN

A resource control or limit on the total number of processes, tasks or LWPs under execution by a single user, task, project, or zone has been exceeded, or the total amount of system memory available is temporarily insufficient to duplicate this process.

ENOMEM

There is not enough swap space.

EPERM

The {PRIV_PROC_FORK} privilege is not asserted in the effective set of the calling process.

The forkx() and forkallx() functions will fail if:

EINVAL

The flags argument is invalid.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Async-Signal-Safe.
Standard
See below.

For fork(), see standards(5).

See Also

alarm(2), exec(2), exit(2), fcntl(2), getitimer(2), getrlimit(2), memcntl(2), mmap(2), nice(2), priocntl(2), semop(2), shmop(2), times(2), umask(2), waitid(2), door_create(3C), exit(3C), plock(3C), pthread_atfork(3C), pthread_create(3C), signal(3C), system(3C), thr_create(3C) timer_create(3C), wait(3C), contract(4), process(4), attributes(5), privileges(5), standards(5)

Notes

An application should call _exit() rather than exit(3C) if it cannot execve(), since exit() will flush and close standard I/O channels and thereby corrupt the parent process's standard I/O data structures. Using exit(3C) will flush buffered data twice. See exit(2).

The thread in the child that calls fork(), fork1(), or fork1x() must not depend on any resources held by threads that no longer exist in the child. In particular, locks held by these threads will not be released.

In a multithreaded process, forkall() in one thread can cause blocking system calls to be interrupted and return with an EINTR error.