man3/sem_open.3

   1 '\" t
   2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH SEM_OPEN 3 2012-05-13 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 sem_open \- initialize and open a named semaphore
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#include <fcntl.h>" "           /* For O_* constants */"
  32 .BR "#include <sys/stat.h>" "        /* For mode constants */"
  33 .B #include <semaphore.h>
  34 .sp
  35 .BI "sem_t *sem_open(const char *" name ", int " oflag );
  36 .BI "sem_t *sem_open(const char *" name ", int " oflag ", "
  37 .BI "                mode_t " mode ", unsigned int " value );
  38 .fi
  39 .sp
  40 Link with \fI\-pthread\fP.
  41 .SH DESCRIPTION
  42 .BR sem_open ()
  43 creates a new POSIX semaphore or opens an existing semaphore.
  44 The semaphore is identified by
  45 .IR name .
  46 For details of the construction of
  47 .IR name ,
  48 see
  49 .BR sem_overview (7).
  50
  51 The
  52 .I oflag
  53 argument specifies flags that control the operation of the call.
  54 (Definitions of the flags values can be obtained by including
  55 .IR <fcntl.h> .)
  56 If
  57 .B O_CREAT
  58 is specified in
  59 .IR oflag ,
  60 then the semaphore is created if
  61 it does not already exist.
  62 The owner (user ID) of the semaphore is set to the effective
  63 user ID of the calling process.
  64 The group ownership (group ID) is set to the effective group ID
  65 of the calling process.
  66 .\" In reality the filesystem IDs are used on Linux.
  67 If both
  68 .B O_CREAT
  69 and
  70 .B O_EXCL
  71 are specified in
  72 .IR oflag ,
  73 then an error is returned if a semaphore with the given
  74 .I name
  75 already exists.
  76 .PP
  77 If
  78 .B O_CREAT
  79 is specified in
  80 .IR oflag ,
  81 then two additional arguments must be supplied.
  82 The
  83 .I mode
  84 argument specifies the permissions to be placed on the new semaphore,
  85 as for
  86 .BR open (2).
  87 (Symbolic definitions for the permissions bits can be obtained by including
  88 .IR <sys/stat.h> .)
  89 The permissions settings are masked against the process umask.
  90 Both read and write permission should be granted to each class of
  91 user that will access the semaphore.
  92 The
  93 .I value
  94 argument specifies the initial value for the new semaphore.
  95 If
  96 .B O_CREAT
  97 is specified, and a semaphore with the given
  98 .I name
  99 already exists, then
 100 .I mode
 101 and
 102 .I value
 103 are ignored.
 104 .SH RETURN VALUE
 105 On success,
 106 .BR sem_open ()
 107 returns the address of the new semaphore;
 108 this address is used when calling other semaphore-related functions.
 109 On error,
 110 .BR sem_open ()
 111 returns
 112 .BR SEM_FAILED ,
 113 with
 114 .I errno
 115 set to indicate the error.
 116 .SH ERRORS
 117 .TP
 118 .B EACCES
 119 The semaphore exists, but the caller does not have permission to
 120 open it.
 121 .TP
 122 .B EEXIST
 123 Both
 124 .B O_CREAT
 125 and
 126 .B O_EXCL
 127 were specified in
 128 .IR oflag ,
 129 but a semaphore with this
 130 .I name
 131 already exists.
 132 .TP
 133 .B EINVAL
 134 .I value
 135 was greater than
 136 .BR SEM_VALUE_MAX .
 137 .TP
 138 .B EINVAL
 139 .I name
 140 consists of just "/", followed by no other characters.
 141 .TP
 142 .B EMFILE
 143 The process already has the maximum number of files and open.
 144 .TP
 145 .B ENAMETOOLONG
 146 .I name
 147 was too long.
 148 .TP
 149 .B ENFILE
 150 The system limit on the total number of open files has been reached.
 151 .TP
 152 .B ENOENT
 153 The
 154 .B O_CREAT
 155 flag was not specified in
 156 .IR oflag
 157 and no semaphore with this
 158 .I name
 159 exists;
 160 or,
 161 .\" this error can occur if we have a name of the (nonportable) form
 162 .\" /dir/name, and the directory /dev/shm/dir does not exist.
 163 .B O_CREAT
 164 was specified, but
 165 .I name
 166 wasn't well formed.
 167 .TP
 168 .B ENOMEM
 169 Insufficient memory.
 170 .SH CONFORMING TO
 171 POSIX.1-2001.
 172 .SH SEE ALSO
 173 .BR sem_close (3),
 174 .BR sem_getvalue (3),
 175 .BR sem_post (3),
 176 .BR sem_unlink (3),
 177 .BR sem_wait (3),
 178 .BR sem_overview (7)