| 1 |
'\" t |
| 2 |
.\" Copyright 2006, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH sem_open 3 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
sem_open \- initialize and open a named semaphore |
| 10 |
.SH LIBRARY |
| 11 |
POSIX threads library |
| 12 |
.RI ( libpthread ,\~ \-lpthread ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.BR "#include <fcntl.h>" " /* For O_* constants */" |
| 16 |
.BR "#include <sys/stat.h>" " /* For mode constants */" |
| 17 |
.B #include <semaphore.h> |
| 18 |
.P |
| 19 |
.BI "sem_t *sem_open(const char *" name ", int " oflag ", ..." |
| 20 |
.BI " \f[R]/*\f[] mode_t " mode \ |
| 21 |
", unsigned int " value " \f[R]*/\f[] );" |
| 22 |
.fi |
| 23 |
.SH DESCRIPTION |
| 24 |
.BR sem_open () |
| 25 |
creates a new POSIX semaphore or opens an existing semaphore. |
| 26 |
The semaphore is identified by |
| 27 |
.IR name . |
| 28 |
For details of the construction of |
| 29 |
.IR name , |
| 30 |
see |
| 31 |
.BR sem_overview (7). |
| 32 |
.P |
| 33 |
The |
| 34 |
.I oflag |
| 35 |
argument specifies flags that control the operation of the call. |
| 36 |
(Definitions of the flags values can be obtained by including |
| 37 |
.IR <fcntl.h> .) |
| 38 |
If |
| 39 |
.B O_CREAT |
| 40 |
is specified in |
| 41 |
.IR oflag , |
| 42 |
then the semaphore is created if |
| 43 |
it does not already exist. |
| 44 |
The owner (user ID) of the semaphore is set to the effective |
| 45 |
user ID of the calling process. |
| 46 |
The group ownership (group ID) is set to the effective group ID |
| 47 |
of the calling process. |
| 48 |
.\" In reality the filesystem IDs are used on Linux. |
| 49 |
If both |
| 50 |
.B O_CREAT |
| 51 |
and |
| 52 |
.B O_EXCL |
| 53 |
are specified in |
| 54 |
.IR oflag , |
| 55 |
then an error is returned if a semaphore with the given |
| 56 |
.I name |
| 57 |
already exists. |
| 58 |
.P |
| 59 |
If |
| 60 |
.B O_CREAT |
| 61 |
is specified in |
| 62 |
.IR oflag , |
| 63 |
then two additional arguments must be supplied. |
| 64 |
The |
| 65 |
.I mode |
| 66 |
argument specifies the permissions to be placed on the new semaphore, |
| 67 |
as for |
| 68 |
.BR open (2). |
| 69 |
(Symbolic definitions for the permissions bits can be obtained by including |
| 70 |
.IR <sys/stat.h> .) |
| 71 |
The permissions settings are masked against the process umask. |
| 72 |
Both read and write permission should be granted to each class of |
| 73 |
user that will access the semaphore. |
| 74 |
The |
| 75 |
.I value |
| 76 |
argument specifies the initial value for the new semaphore. |
| 77 |
If |
| 78 |
.B O_CREAT |
| 79 |
is specified, and a semaphore with the given |
| 80 |
.I name |
| 81 |
already exists, then |
| 82 |
.I mode |
| 83 |
and |
| 84 |
.I value |
| 85 |
are ignored. |
| 86 |
.SH RETURN VALUE |
| 87 |
On success, |
| 88 |
.BR sem_open () |
| 89 |
returns the address of the new semaphore; |
| 90 |
this address is used when calling other semaphore-related functions. |
| 91 |
On error, |
| 92 |
.BR sem_open () |
| 93 |
returns |
| 94 |
.BR SEM_FAILED , |
| 95 |
with |
| 96 |
.I errno |
| 97 |
set to indicate the error. |
| 98 |
.SH ERRORS |
| 99 |
.TP |
| 100 |
.B EACCES |
| 101 |
The semaphore exists, but the caller does not have permission to |
| 102 |
open it. |
| 103 |
.TP |
| 104 |
.B EEXIST |
| 105 |
Both |
| 106 |
.B O_CREAT |
| 107 |
and |
| 108 |
.B O_EXCL |
| 109 |
were specified in |
| 110 |
.IR oflag , |
| 111 |
but a semaphore with this |
| 112 |
.I name |
| 113 |
already exists. |
| 114 |
.TP |
| 115 |
.B EINVAL |
| 116 |
.I value |
| 117 |
was greater than |
| 118 |
.BR SEM_VALUE_MAX . |
| 119 |
.TP |
| 120 |
.B EINVAL |
| 121 |
.I name |
| 122 |
consists of just "/", followed by no other characters. |
| 123 |
.TP |
| 124 |
.B EMFILE |
| 125 |
The per-process limit on the number of open file descriptors has been reached. |
| 126 |
.TP |
| 127 |
.B ENAMETOOLONG |
| 128 |
.I name |
| 129 |
was too long. |
| 130 |
.TP |
| 131 |
.B ENFILE |
| 132 |
The system-wide limit on the total number of open files has been reached. |
| 133 |
.TP |
| 134 |
.B ENOENT |
| 135 |
The |
| 136 |
.B O_CREAT |
| 137 |
flag was not specified in |
| 138 |
.I oflag |
| 139 |
and no semaphore with this |
| 140 |
.I name |
| 141 |
exists; |
| 142 |
or, |
| 143 |
.\" this error can occur if we have a name of the (nonportable) form |
| 144 |
.\" /dir/name, and the directory /dev/shm/dir does not exist. |
| 145 |
.B O_CREAT |
| 146 |
was specified, but |
| 147 |
.I name |
| 148 |
wasn't well formed. |
| 149 |
.TP |
| 150 |
.B ENOMEM |
| 151 |
Insufficient memory. |
| 152 |
.SH ATTRIBUTES |
| 153 |
For an explanation of the terms used in this section, see |
| 154 |
.BR attributes (7). |
| 155 |
.TS |
| 156 |
allbox; |
| 157 |
lbx lb lb |
| 158 |
l l l. |
| 159 |
Interface Attribute Value |
| 160 |
T{ |
| 161 |
.na |
| 162 |
.nh |
| 163 |
.BR sem_open () |
| 164 |
T} Thread safety MT-Safe |
| 165 |
.TE |
| 166 |
.SH STANDARDS |
| 167 |
POSIX.1-2008. |
| 168 |
.SH HISTORY |
| 169 |
POSIX.1-2001. |
| 170 |
.SH SEE ALSO |
| 171 |
.BR sem_close (3), |
| 172 |
.BR sem_getvalue (3), |
| 173 |
.BR sem_post (3), |
| 174 |
.BR sem_unlink (3), |
| 175 |
.BR sem_wait (3), |
| 176 |
.BR sem_overview (7) |