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