summaryrefslogtreecommitdiffstats
path: root/man3/sem_open.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/sem_open.3')
-rw-r--r--man3/sem_open.3176
1 files changed, 176 insertions, 0 deletions
diff --git a/man3/sem_open.3 b/man3/sem_open.3
new file mode 100644
index 0000000..0845be9
--- /dev/null
+++ b/man3/sem_open.3
@@ -0,0 +1,176 @@
+'\" t
+.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH sem_open 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+sem_open \- initialize and open a named semaphore
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.BR "#include <fcntl.h>" " /* For O_* constants */"
+.BR "#include <sys/stat.h>" " /* For mode constants */"
+.B #include <semaphore.h>
+.PP
+.BI "sem_t *sem_open(const char *" name ", int " oflag );
+.BI "sem_t *sem_open(const char *" name ", int " oflag ,
+.BI " mode_t " mode ", unsigned int " value );
+.fi
+.SH DESCRIPTION
+.BR sem_open ()
+creates a new POSIX semaphore or opens an existing semaphore.
+The semaphore is identified by
+.IR name .
+For details of the construction of
+.IR name ,
+see
+.BR sem_overview (7).
+.PP
+The
+.I oflag
+argument specifies flags that control the operation of the call.
+(Definitions of the flags values can be obtained by including
+.IR <fcntl.h> .)
+If
+.B O_CREAT
+is specified in
+.IR oflag ,
+then the semaphore is created if
+it does not already exist.
+The owner (user ID) of the semaphore is set to the effective
+user ID of the calling process.
+The group ownership (group ID) is set to the effective group ID
+of the calling process.
+.\" In reality the filesystem IDs are used on Linux.
+If both
+.B O_CREAT
+and
+.B O_EXCL
+are specified in
+.IR oflag ,
+then an error is returned if a semaphore with the given
+.I name
+already exists.
+.PP
+If
+.B O_CREAT
+is specified in
+.IR oflag ,
+then two additional arguments must be supplied.
+The
+.I mode
+argument specifies the permissions to be placed on the new semaphore,
+as for
+.BR open (2).
+(Symbolic definitions for the permissions bits can be obtained by including
+.IR <sys/stat.h> .)
+The permissions settings are masked against the process umask.
+Both read and write permission should be granted to each class of
+user that will access the semaphore.
+The
+.I value
+argument specifies the initial value for the new semaphore.
+If
+.B O_CREAT
+is specified, and a semaphore with the given
+.I name
+already exists, then
+.I mode
+and
+.I value
+are ignored.
+.SH RETURN VALUE
+On success,
+.BR sem_open ()
+returns the address of the new semaphore;
+this address is used when calling other semaphore-related functions.
+On error,
+.BR sem_open ()
+returns
+.BR SEM_FAILED ,
+with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The semaphore exists, but the caller does not have permission to
+open it.
+.TP
+.B EEXIST
+Both
+.B O_CREAT
+and
+.B O_EXCL
+were specified in
+.IR oflag ,
+but a semaphore with this
+.I name
+already exists.
+.TP
+.B EINVAL
+.I value
+was greater than
+.BR SEM_VALUE_MAX .
+.TP
+.B EINVAL
+.I name
+consists of just "/", followed by no other characters.
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B ENAMETOOLONG
+.I name
+was too long.
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.B ENOENT
+The
+.B O_CREAT
+flag was not specified in
+.I oflag
+and no semaphore with this
+.I name
+exists;
+or,
+.\" this error can occur if we have a name of the (nonportable) form
+.\" /dir/name, and the directory /dev/shm/dir does not exist.
+.B O_CREAT
+was specified, but
+.I name
+wasn't well formed.
+.TP
+.B ENOMEM
+Insufficient memory.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR sem_open ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH SEE ALSO
+.BR sem_close (3),
+.BR sem_getvalue (3),
+.BR sem_post (3),
+.BR sem_unlink (3),
+.BR sem_wait (3),
+.BR sem_overview (7)