man3/sem_open.3

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