man/man3/sem_open.3

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