From ad1ea71c7ac965a6d9e13ea88a3583e7c817a0ce Mon Sep 17 00:00:00 2001 From: tjr Date: Wed, 15 Jan 2003 03:07:40 +0000 Subject: Document the named semaphore functions. This could still use a bit of polishing. --- lib/libc_r/man/sem_open.3 | 183 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 165 insertions(+), 18 deletions(-) (limited to 'lib/libc_r') diff --git a/lib/libc_r/man/sem_open.3 b/lib/libc_r/man/sem_open.3 index 07c9543..00a3ad2 100644 --- a/lib/libc_r/man/sem_open.3 +++ b/lib/libc_r/man/sem_open.3 @@ -26,7 +26,7 @@ .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ -.Dd February 15, 2000 +.Dd January 15, 2003 .Dt SEM_OPEN 3 .Os .Sh NAME @@ -46,36 +46,183 @@ .Fn sem_unlink "const char *name" .Sh DESCRIPTION The -.Fn sem_open , -.Fn sem_close , +.Fn sem_open +function creates or opens the named semaphore specified by +.Fa name . +The returned semaphore may be used in subsequent calls to +.Fn sem_getvalue , +.Fn sem_wait , +.Fn sem_trywait , +.Fn sem_post and -.Fn sem_unlink -functions are not supported by this implementation. -.Sh RETURN VALUES +.Fn sem_close . +.Pp +The following bits may be 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 -returns SEM_FAILED and sets -.Va errno -to indicate an error. -.Fn sem_close +must be of type +.Vt mode_t +and specifies the mode for the semaphore. +Only the +.Dv S_IWUSR , +.Dv 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 -return -1 and set +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 -to indicate an error. +is set to indicate the error. +.Pp +.Rv -std sem_close +.Pp +.Rv -std sem_unlink .Sh ERRORS -.Fn sem_open , -.Fn sem_close , +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 the 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 set but 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 -will fail: +function will fail if: .Bl -tag -width Er -.It Bq Er ENOSYS -Function not supported by this implementation. +.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_wait 3 , +.Xr sem_trywait 3 , +.Xr sem_post 3 , +.Xr sem 4 .Sh STANDARDS +The .Fn sem_open , .Fn sem_close , and .Fn sem_unlink -conform to +functions conform to .St -p1003.1-96 . +.Sh HISTORY +Support for named semaphores first appeared in +.Fx 5.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. -- cgit v1.1