sem_open.3p (8116B)
- '\" et
- .TH SEM_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- sem_open
- \(em initialize and open a named semaphore
- .SH SYNOPSIS
- .LP
- .nf
- #include <semaphore.h>
- .P
- sem_t *sem_open(const char *\fIname\fP, int \fIoflag\fP, ...);
- .fi
- .SH DESCRIPTION
- The
- \fIsem_open\fR()
- function shall establish a connection between a named semaphore
- and a process. Following a call to
- \fIsem_open\fR()
- with semaphore name
- .IR name ,
- the process may reference the semaphore associated with
- .IR name
- using the address returned from the call. This semaphore may be used
- in subsequent calls to
- \fIsem_wait\fR(),
- \fIsem_timedwait\fR(),
- \fIsem_trywait\fR(),
- \fIsem_post\fR(),
- and
- \fIsem_close\fR().
- The semaphore remains usable by this process until the semaphore is
- closed by a successful call to
- \fIsem_close\fR(),
- \fI_exit\fR(),
- or one of the
- .IR exec
- functions.
- .P
- The
- .IR oflag
- argument controls whether the semaphore is created or merely accessed
- by the call to
- \fIsem_open\fR().
- The following flag bits may be set in
- .IR oflag :
- .IP O_CREAT 10
- This flag is used to create a semaphore if it does not already exist.
- If O_CREAT is set and the semaphore already exists, then O_CREAT has no
- effect, except as noted under O_EXCL. Otherwise,
- \fIsem_open\fR()
- creates a named semaphore. The O_CREAT flag requires a third and a
- fourth argument:
- .IR mode ,
- which is of type
- .BR mode_t ,
- and
- .IR value ,
- which is of type
- .BR unsigned .
- The semaphore is created with an initial value of
- .IR value .
- Valid initial values for semaphores are less than or equal to
- {SEM_VALUE_MAX}.
- .RS 10
- .P
- The user ID of the semaphore shall be set to the effective user ID of
- the process. The group ID of the semaphore shall be set to the effective
- group ID of the process; however, if the
- .IR name
- argument is visible in the file system, the group ID may be set to
- the group ID of the containing directory. The permission bits of the
- semaphore are set to the value of the
- .IR mode
- argument except those set in the file mode creation mask of the
- process. When bits in
- .IR mode
- other than the file permission bits are specified, the effect is
- unspecified.
- .P
- After the semaphore named
- .IR name
- has been created by
- \fIsem_open\fR()
- with the O_CREAT flag, other processes can connect to the semaphore by
- calling
- \fIsem_open\fR()
- with the same value of
- .IR name .
- .RE
- .IP O_EXCL 10
- If O_EXCL and O_CREAT are set,
- \fIsem_open\fR()
- fails if the semaphore
- .IR name
- exists. The check for the existence of the semaphore and the creation
- of the semaphore if it does not exist are atomic with respect to other
- processes executing
- \fIsem_open\fR()
- with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set,
- the effect is undefined.
- .RS 10
- .P
- If flags other than O_CREAT and O_EXCL are specified in the
- .IR oflag
- parameter, the effect is unspecified.
- .RE
- .P
- The
- .IR name
- argument points to a string naming a semaphore object. It is
- unspecified whether the name appears in the file system and is visible
- to functions that take pathnames as arguments. The
- .IR name
- argument conforms to the construction rules for a pathname, except
- that the interpretation of
- <slash>
- characters other than the leading
- <slash>
- character in
- .IR name
- is implementation-defined, and that the length limits for the
- .IR name
- argument are implementation-defined and need not be the same as
- the pathname limits
- {PATH_MAX}
- and
- {NAME_MAX}.
- If
- .IR name
- begins with the
- <slash>
- character, then processes calling
- \fIsem_open\fR()
- with the same value of
- .IR name
- shall refer to the same semaphore object, as long as that name has not
- been removed. If
- .IR name
- does not begin with the
- <slash>
- character, the effect is implementation-defined.
- .P
- If a process makes multiple successful calls to
- \fIsem_open\fR()
- with the same value for
- .IR name ,
- the same semaphore address shall be returned for each such successful
- call, provided that there have been no calls to
- \fIsem_unlink\fR()
- for this semaphore, and at least one previous successful
- \fIsem_open\fR()
- call for this semaphore has not been matched with a
- \fIsem_close\fR()
- call.
- .P
- References to copies of the semaphore produce undefined results.
- .SH "RETURN VALUE"
- Upon successful completion, the
- \fIsem_open\fR()
- function shall return the address of the semaphore. Otherwise, it
- shall return a value of SEM_FAILED and set
- .IR errno
- to indicate the error. The symbol SEM_FAILED is defined in the
- .IR <semaphore.h>
- header. No successful return from
- \fIsem_open\fR()
- shall return the value SEM_FAILED.
- .SH ERRORS
- If any of the following conditions occur, the
- \fIsem_open\fR()
- function shall return SEM_FAILED and set
- .IR errno
- to the corresponding value:
- .TP
- .BR EACCES
- The named semaphore exists and the permissions specified by
- .IR oflag
- are denied, or the named semaphore does not exist and permission to
- create the named semaphore is denied.
- .TP
- .BR EEXIST
- O_CREAT and O_EXCL are set and the named semaphore already exists.
- .TP
- .BR EINTR
- The
- \fIsem_open\fR()
- operation was interrupted by a signal.
- .TP
- .BR EINVAL
- The
- \fIsem_open\fR()
- operation is not supported for the given name, or O_CREAT was specified
- in
- .IR oflag
- and
- .IR value
- was greater than
- {SEM_VALUE_MAX}.
- .TP
- .BR EMFILE
- Too many semaphore descriptors or file descriptors are currently in use
- by this process.
- .TP
- .BR ENFILE
- Too many semaphores are currently open in the system.
- .TP
- .BR ENOENT
- O_CREAT is not set and the named semaphore does not exist.
- .TP
- .BR ENOMEM
- There is insufficient memory for the creation of the new named
- semaphore.
- .TP
- .BR ENOSPC
- There is insufficient space on a storage device for the creation of the
- new named semaphore.
- .P
- If any of the following conditions occur, the
- \fIsem_open\fR()
- function may return SEM_FAILED and set
- .IR errno
- to the corresponding value:
- .TP
- .BR ENAMETOOLONG
- .br
- The length of the
- .IR name
- argument exceeds
- {_POSIX_PATH_MAX}
- on systems that do not support the XSI option
- or exceeds
- {_XOPEN_PATH_MAX}
- on XSI systems,
- or has a pathname component that is longer than
- {_POSIX_NAME_MAX}
- on systems that do not support the XSI option
- or longer than
- {_XOPEN_NAME_MAX}
- on XSI systems.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- Early drafts required an error return value of \-1 with the type
- .BR "sem_t *"
- for the
- \fIsem_open\fR()
- function, which is not guaranteed to be portable across
- implementations. The revised text provides the symbolic error code
- SEM_FAILED to eliminate the type conflict.
- .SH "FUTURE DIRECTIONS"
- A future version might require the
- \fIsem_open\fR()
- and
- \fIsem_unlink\fR()
- functions to have semantics similar to normal file system operations.
- .SH "SEE ALSO"
- .ad l
- .IR "\fIsemctl\fR\^(\|)",
- .IR "\fIsemget\fR\^(\|)",
- .IR "\fIsemop\fR\^(\|)",
- .IR "\fIsem_close\fR\^(\|)",
- .IR "\fIsem_post\fR\^(\|)",
- .IR "\fIsem_timedwait\fR\^(\|)",
- .IR "\fIsem_trywait\fR\^(\|)",
- .IR "\fIsem_unlink\fR\^(\|)"
- .ad b
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<semaphore.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .