.\" $NetBSD: sem_open.3,v 1.3 2005/01/29 14:19:43 wiz Exp $ .\" .\" Copyright (C) 2000 Jason Evans . .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" From: FreeBSD: src/lib/libc/gen/sem_open.3,v 1.12 2004/07/02 16:45:56 ru .\" .Dd January 21, 2005 .Dt SEM_OPEN 3 .Os .Sh NAME .Nm sem_open , .Nm sem_close , .Nm sem_unlink .Nd named semaphore operations .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In semaphore.h .Ft "sem_t *" .Fn sem_open "const char *name" "int oflag" ... .Ft int .Fn sem_close "sem_t *sem" .Ft int .Fn sem_unlink "const char *name" .Sh DESCRIPTION The .Fn sem_open function creates or opens the named semaphore specified by .Fa name . The returned semaphore may be used in subsequent calls to .Xr sem_getvalue 3 , .Xr sem_wait 3 , .Xr sem_trywait 3 , .Xr sem_post 3 , and .Fn sem_close . .Pp The following bits may be set in the .Fa oflag argument: .Bl -tag -width ".Dv O_CREAT" .It Dv O_CREAT Create the semaphore if it does not already exist. .Pp The third argument to the call to .Fn sem_open must be of type .Vt mode_t and specifies the mode for the semaphore. Only the .Dv S_IWUSR , S_IWGRP , and .Dv S_IWOTH bits are examined; it is not possible to grant only .Dq read permission on a semaphore. The mode is modified according to the process's file creation mask; see .Xr umask 2 . .Pp The fourth argument must be an .Vt "unsigned int" and specifies the initial value for the semaphore, and must be no greater than .Dv SEM_VALUE_MAX . .It Dv O_EXCL Create the semaphore if it does not exist. If the semaphore already exists, .Fn sem_open will fail. This flag is ignored unless .Dv O_CREAT is also specified. .El .Pp The .Fn sem_close function closes a named semaphore that was opened by a call to .Fn sem_open . .Pp The .Fn sem_unlink function removes the semaphore named .Fa name . Resources allocated to the semaphore are only deallocated when all processes that have the semaphore open close it. .Sh RETURN VALUES If successful, the .Fn sem_open function returns the address of the opened semaphore. If the same .Fa name argument is given to multiple calls to .Fn sem_open by the same process without an intervening call to .Fn sem_close , the same address is returned each time. If the semaphore cannot be opened, .Fn sem_open returns .Dv SEM_FAILED and the global variable .Va errno is set to indicate the error. .Pp .Rv -std sem_close sem_unlink .Sh ERRORS The .Fn sem_open function will fail if: .Bl -tag -width Er .It Bq Er EACCES The semaphore exists and the permissions specified by .Fa oflag at the time it was created deny access to this process. .It Bq Er EACCES The semaphore does not exist, but permission to create it is denied. .It Bq Er EEXIST .Dv O_CREAT and .Dv O_EXCL are set but the semaphore already exists. .It Bq Er EINTR The call was interrupted by a signal. .It Bq Er EINVAL The .Fn sem_open operation is not supported for the given .Fa name . .It Bq Er EINVAL The .Fa value argument is greater than .Dv SEM_VALUE_MAX . .\"FreeBSD never returns EMFILE .\".It Bq Er EMFILE .\"Too many semaphores are in use by this process. .It Bq Er ENAMETOOLONG The .Fa name argument is too long. .It Bq Er ENFILE The system limit on semaphores has been reached. .It Bq Er ENOENT .Dv O_CREAT is not set and the named semaphore does not exist. .It Bq Er ENOSPC There is not enough space to create the semaphore. .El .Pp The .Fn sem_close function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa sem argument is not a valid semaphore. .El .Pp The .Fn sem_unlink function will fail if: .Bl -tag -width Er .It Bq Er EACCES Permission is denied to unlink the semaphore. .It Bq Er ENAMETOOLONG The specified .Fa name is too long. .It Bq Er ENOENT The named semaphore does not exist. .El .Sh SEE ALSO .Xr close 2 , .Xr open 2 , .Xr umask 2 , .Xr unlink 2 , .Xr sem_getvalue 3 , .Xr sem_post 3 , .Xr sem_trywait 3 , .Xr sem_wait 3 , .Xr sem 4 .Sh STANDARDS The .Fn sem_open , .Fn sem_close , and .Fn sem_unlink functions conform to .St -p1003.1-96 . .Sh HISTORY Support for named semaphores first appeared in .Nx 2.0 . .Sh BUGS This implementation places strict requirements on the value of .Fa name : it must begin with a slash .Pq Ql / , contain no other slash characters, and be less than 14 characters in length not including the terminating null character.