diff options
author | joerg <joerg@FreeBSD.org> | 1995-10-03 19:17:21 +0000 |
---|---|---|
committer | joerg <joerg@FreeBSD.org> | 1995-10-03 19:17:21 +0000 |
commit | 5556a72169afb1e4959d0bc74c7a4bfcf738a848 (patch) | |
tree | fdb5cc5cbe5bb4db279acfc3170902c28afee17d /lib/libc | |
parent | 3fc43db861e597f1130b985d780f0197ed473b13 (diff) | |
download | FreeBSD-src-5556a72169afb1e4959d0bc74c7a4bfcf738a848.zip FreeBSD-src-5556a72169afb1e4959d0bc74c7a4bfcf738a848.tar.gz |
Add man pages for the SYSV shm* and sem* functions.
This partially closes PR # docs/177.
This should probably also go into 2.1.
Submitted by: daveho@infocom.com (David Hovemeyer)
Diffstat (limited to 'lib/libc')
-rw-r--r-- | lib/libc/sys/Makefile.inc | 5 | ||||
-rw-r--r-- | lib/libc/sys/semctl.2 | 173 | ||||
-rw-r--r-- | lib/libc/sys/semget.2 | 137 | ||||
-rw-r--r-- | lib/libc/sys/semop.2 | 192 | ||||
-rw-r--r-- | lib/libc/sys/shmat.2 | 110 | ||||
-rw-r--r-- | lib/libc/sys/shmctl.2 | 136 | ||||
-rw-r--r-- | lib/libc/sys/shmget.2 | 138 |
7 files changed, 890 insertions, 1 deletions
diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 05cc6e8..dc65844 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -94,9 +94,11 @@ MAN2+= sys/accept.2 sys/access.2 sys/acct.2 sys/adjtime.2 sys/bind.2 \ sys/nfssvc.2 sys/open.2 sys/pathconf.2 sys/pipe.2 sys/profil.2 \ sys/quotactl.2 sys/read.2 sys/readlink.2 sys/reboot.2 sys/recv.2 \ sys/rename.2 sys/revoke.2 sys/rmdir.2 sys/rtprio.2 sys/select.2 \ + sys/semctl.2 sys/semget.2 sys/semop.2 \ sys/send.2 sys/setgroups.2 \ sys/setpgid.2 sys/setregid.2 sys/setreuid.2 \ - sys/setsid.2 sys/setuid.2 sys/shutdown.2 \ + sys/setsid.2 sys/setuid.2 sys/shmat.2 sys/shmctl.2 sys/shmget.2 \ + sys/shutdown.2 \ sys/sigaction.2 sys/sigpending.2 sys/sigprocmask.2 sys/sigreturn.2 \ sys/sigaltstack.2 sys/sigstack.2 sys/sigsuspend.2 sys/socket.2 \ sys/socketpair.2 sys/stat.2 sys/statfs.2 sys/swapon.2 sys/symlink.2 \ @@ -130,6 +132,7 @@ MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2 MLINKS+=send.2 sendmsg.2 send.2 sendto.2 MLINKS+=setpgid.2 setpgrp.2 MLINKS+=setuid.2 setegid.2 setuid.2 seteuid.2 setuid.2 setgid.2 +MLINKS+=shmat.2 shmdt.2 MLINKS+=stat.2 fstat.2 stat.2 lstat.2 MLINKS+=statfs.2 fstatfs.2 MLINKS+=syscall.2 __syscall.2 diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 new file mode 100644 index 0000000..fe60ce0 --- /dev/null +++ b/lib/libc/sys/semctl.2 @@ -0,0 +1,173 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" +.Dd September 12, 1995 +.Dt SEMCTL 2 +.Os FreeBSD +.Sh NAME +.Nm semctl +.Nd control operations on a semaphore set +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ipc.h> +.Fd #include <sys/sem.h> +.Ft int +.Fn "semctl" "int semid" "int semnum" "int cmd" "union semun arg" +.Sh DESCRIPTION +.Fn Semctl +performs the operation indicated by +.Fa cmd +on the semaphore set indicated by +.Fa semid . +For the commands that use the +.Fa arg +parameter, +.Fa "union semun" +is defined as follows: +.Bd -literal +.\" +.\" From <sys/sem.h>: +.\" +union semun { + int val; /* value for SETVAL */ + struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ + u_short *array; /* array for GETALL & SETALL */ +}; +.Ed +.Pp +Commands are performed as follows: +.\" +.\" This section based on Stevens, _Advanced Programming in the UNIX +.\" Environment_. +.\" +.Bl -tag -width IPC_RMIDXXX +.It Dv IPC_STAT +Fetch the semaphore set's +.Fa "struct semid_ds" , +storing it in the memory pointed to by +.Fa arg.buf . +.It Dv IPC_SET +Changes the +.Fa sem_perm.uid , +.Fa sem_perm.gid , +and +.Fa sem_perm.mode +members of the semaphore set's +.Fa "struct semid_ds" +to match those of the struct pointed to by +.Fa arg.buf . +The calling process's effective uid must +match either +.Fa sem_perm.uid +or +.Fa sem_perm.cuid , +or it must have superuser privileges. +.It IPC_RMID +Immediately removes the semaphore set from the system. The calling +process's effictive uid must equal the semaphore set's +.Fa sem_perm.uid +or +.Fa sem_perm.cuid , +or the process must have superuser priviliges. +.It Dv GETVAL +Return the value of semaphore number +.Fa semnum . +.It Dv SETVAL +Set the value of semaphore number +.Fa semnum +to +.Fa arg.val . +.It Dv GETPID +Return the pid of the last process to perform an operation on +semaphore number +.Fa semnum . +.It Dv GETNCNT +Return the number of processes waiting for semaphore number +.Fa semnum Ns 's +value to become greater than its current value. +.It Dv GETZCNT +Return the number of processes waiting for semaphore number +.Fa semnum Ns 's +value to become 0. +.It Dv GETALL +Fetch the value of all of the semaphores in the set into the +array pointed to by +.Fa arg.array . +.It Dv SETALL +Set the values of all of the semaphores in the set to the values +in the array pointed to by +.Fa arg.array . +.El +.Pp +The +.Fa "struct semid_ds" +is defined as follows: +.Bd -literal +.\" +.\" Taken straight from <sys/sem.h>. +.\" +struct semid_ds { + struct ipc_perm sem_perm; /* operation permission struct */ + struct sem *sem_base; /* pointer to first semaphore in set */ + u_short sem_nsems; /* number of sems in set */ + time_t sem_otime; /* last operation time */ + long sem_pad1; /* SVABI/386 says I need this here */ + time_t sem_ctime; /* last change time */ + /* Times measured in secs since */ + /* 00:00:00 GMT, Jan. 1, 1970 */ + long sem_pad2; /* SVABI/386 says I need this here */ + long sem_pad3[4]; /* SVABI/386 says I need this here */ +}; +.Ed +.Sh RETURN VALUES +On success, when +.Fa cmd +is one of GETVAL, GETNCNT, or GETZCNT, +.Fn semctl +returns the corresponding value; otherwise, 0 is returned. +On failure, -1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Semctl +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No semaphore set corresponds to +.Fa semid . +.It Bq Er EINVAL +.Fa semnum +is not in the range of valid semaphores for given semaphore set. +.It Bq Er EPERM +The calling process's effective uid does not match the uid of +the semaphore set's owner or creator. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +semaphore set. +.Sh SEE ALSO +.Xr semget 2 , +.Xr semop 2 diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 new file mode 100644 index 0000000..323aef4 --- /dev/null +++ b/lib/libc/sys/semget.2 @@ -0,0 +1,137 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" +.Dd September 12, 1995 +.Dt SEMGET 2 +.Os FreeBSD +.Sh NAME +.Nm semget +.Nd obtain a semaphore id +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ipc.h> +.Fd #include <sys/sem.h> +.Ft int +.Fn "semget" "key_t key" "int nsems" "int flag" +.Sh DESCRIPTION +Based on the values of +.Fa key +and +.Fa flag , +.Fn semget +returns the identifier of a newly created or previously existing +set of semaphores. +.\" +.\" This is copied verbatim from the shmget manpage. Perhaps +.\" it should go in a common manpage, such as .Xr ipc 2 +.\" +The key +is analogous to a filename: it provides a handle that names an +IPC object. There are three ways to specify a key: +.Bl -bullet +.It +IPC_PRIVATE may be specified, in which case a new IPC object +will be created. +.It +An integer constant may be specified. If no IPC object corresponding +to +.Fa key +is specified and the IPC_CREAT bit is set in +.Fa flag , +a new one will be created. +.It +.Fn ftok +may be used to generate a key from a pathname. See +.Xr ftok 3 . +.El +.\" +.\" Likewise for this section, except SHM_* becomes SEM_*. +.\" +.Pp +The mode of a newly created IPC object is determined by +.Em OR Ns 'ing +the following constants into the +.Fa flag +parameter: +.Bl -tag -width XSEM_WXX6XXX +.It Dv SEM_R +Read access for user. +.It Dv SEM_W +Write access for user. +.It Dv (SEM_R>>3) +Read access for group. +.It Dv (SEM_W>>3) +Write access for group. +.It Dv (SEM_R>>6) +Read access for other. +.It Dv (SEM_W>>6) +Write access for other. +.El +.Pp +If a new set of semaphores is being created, +.Fa nsems +is used to indicate the number of semaphores the set should contain. +Otherwise, +.Fa nsems +may be specified as 0. +.Sh RETURN VALUES +.Fn Semget +returns the id of a semaphore set if successful; otherwise, -1 +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Semget +will fail if: +.Bl -tag -width Er +.\" ipcperm could fail (we're opening to read and write, as it were) +.It Bq Er EACCES +Access permission failure. +.\" +.\" sysv_sem.c is quite explicit about these, so I'm pretty sure +.\" this is accurate +.\" +.It Bq Er EEXIST +IPC_CREAT and IPC_EXCL were specified, and a semaphore set +corresponding to +.Fa key +already exists. +.It Bq Er EINVAL +The number of semaphores requested exceeds the system imposed maximum +per set. +.It Bq Er ENOSPC +Insufficiently many semaphores are available. +.It Bq Er ENOSPC +The kernel could not allocate a +.Fa "struct semid_ds" . +.It Bq Er ENOENT +No semaphore set was found corresponding to +.Fa key , +and IPC_CREAT was not specified. +.Sh SEE ALSO +.Xr semctl 2 , +.Xr semop 2 diff --git a/lib/libc/sys/semop.2 b/lib/libc/sys/semop.2 new file mode 100644 index 0000000..74fa01b --- /dev/null +++ b/lib/libc/sys/semop.2 @@ -0,0 +1,192 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" +.Dd September 22, 1995 +.Dt SEMOP 2 +.Os FreeBSD +.Sh NAME +.Nm semop +.Nd atomic array of operations on a semaphore set +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ipc.h> +.Fd #include <sys/sem.h> +.Ft int +.Fn "semop" "int semid" "struct sembuf array[]" "unsigned nops" +.Sh DESCRIPTION +.Fn Semop +atomically performs the array of operations indicated by +.Fa array +on the semaphore set indicated by +.Fa semid . +The length of +.Fa array +is indicated by +.Fa nops . +Each operation is encoded in a +.Fa "struct sembuf" , +which is defined as follows: +.Bd -literal +.\" +.\" From <sys/sem.h> +.\" +struct sembuf { + u_short sem_num; /* semaphore # */ + short sem_op; /* semaphore operation */ + short sem_flg; /* operation flags */ +}; +.Ed +.Pp +For each element in +.Fa array , +.Fa sem_op +and +.Fa sem_flg +determine an operation to be performed on semaphore number +.Fa sem_num +in the set. The values SEM_UNDO and IPC_NOWAIT may be +.Em OR Ns 'ed +into the +.Fa sem_flg +member in order to modify the behavior of the given operation. +.Pp +The operation performed depends as follows on the value of +.Fa sem_op : +.\" +.\" This section is based on the description of semop() in +.\" Stevens, _Advanced Programming in the UNIX Environment_. +.\" +.Bl -bullet +.It +When +.Fa sem_op +is positive, the semaphore's value is incremented by +.Fa sem_op Ns 's +value. If SEM_UNDO is specified, the semaphore's adjust on exit +value is decremented by +.Fa sem_op Ns 's +value. A positive value for +.Fa sem_op +generally corresponds to a process releasing a resource +associated with the semaphore. +.It +The behavior when +.Fa sem_op +is negative depends on the current value of the semaphore: +.Bl -bullet +.It +If the current value of the semaphore is greater than or equal to +the absolute value of +.Fa sem_op , +then the value is decremented by the absolute value of +.Fa sem_op . +If SEM_UNDO is specified, the semaphore's adjust on exit +value is incremented by the absolute value of +.Fa sem_op . +.It +If the current value of the semaphore is less than +.Fa sem_op Ns 's +value, one of the following happens: +.\" XXX a *second* sublist? +.Bl -bullet +.It +If IPC_NOWAIT was specifed, then +.Fn semop +returns immediately with a return value of EAGAIN. +.It +If some other process has removed the semaphore with the IPC_RMID +option of +.Fn semctl , +then +.Fn semop +returns immediately with a return value of EINVAL. +.It +Otherwise, the calling process is put to sleep until the semaphore's +value is greater than or equal to the absolute value of +.Fa sem_op . +When this condition becomes true, the semaphore's value is decremented +by the absolute value of +.Fa sem_op , +and the semaphore's adjust on exit value is incremented by the +absolute value of +.Fa sem_op . +.El +.Pp +A negative value for +.Fa sem_op +generally means that a process is waiting for a resource to become +available. +.El +.Pp +.It +When +.Fa sem_op +is zero, the process waits for the semaphore's value to become zero. +If it is already zero, the call to +.Fn semop +can return immediately. Otherwise, the calling process is put to +sleep until the semaphore's value becomes zero. +.El +.Pp +For each semaphore a process has in use, the kernel maintains an +`adjust on exit' value, as alluded to earlier. When a process +exits, either voluntarily or involuntarily, the adjust on exit value +for each semaphore is added to the semaphore's value. This can +be used to insure that a resource is released if a process terminates +unexpectedly. +.Sh RETURN VALUES +On success, +.Fn semop +returns 0; otherwise, -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Semop +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No semaphore set corresponds to +.Fa semid . +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +semaphore set. +.It Bq Er EAGAIN +The semaphore's value was less than +.Fa sem_op , +and IPC_NOWAIT was specified. +.It Bq Er E2BIG +Too many operations were specified. +.It Bq Er EFBIG +.\" +.\" I'd have thought this would be EINVAL, but the source says +.\" EFBIG. +.\" +.Fa sem_num +was not in the range of valid semaphores for the set. +.Sh SEE ALSO +.Xr semget 2 , +.Xr semctl 2 diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 new file mode 100644 index 0000000..587eebc --- /dev/null +++ b/lib/libc/sys/shmat.2 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" +.Dd August 2, 1995 +.Dt SHMAT 2 +.Os FreeBSD +.Sh NAME +.Nm shmat , +.Nm shmdt +.Nd attach or detach shared memory +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ipc.h> +.Fd #include <sys/shm.h> +.Ft void * +.Fn "shmat" "int shmid" "void *addr" "int flag" +.Ft int +.Fn "shmdt" "void *addr" +.Sh DESCRIPTION +.Fn Shmat +attaches the shared memory segment identifed by +.Fa shmid +to the calling process's address space. The address where the segment +is attached is determined as follows: +.\" +.\" These are cribbed almost exactly from Stevens, _Advanced Programming in +.\" the UNIX Environment_. +.\" +.Bl -bullet +.It +If +.Fa addr +is 0, the segment is attached at an address selected by the +kernel. +.It +If +.Fa addr +is nonzero and SHM_RND is not specifed in +.Fa flag , +the segment is attached the specified address. +.It +If +.Fa addr +is specified and SHM_RND is specified, +.Fa addr +is rounded down to the nearest multiple of SHMLBA. +.El +.Pp +.Fn Shmdt +detaches the shared memory segment at the address specified by +.Fa addr +from the calling process's address space. +.Sh RETURN VALUES +Upon success, +.Fn shmat +returns the address where the segment is attached; otherwise, -1 +is returned and +.Va errno +is set to indicate the error. +.Pp +Upon success, +.Fn shmdt +returns 0; otherwise, -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Shmat +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No shared memory segment was found corresponding to +.Fa shmid . +.It Bq Er EINVAL +.Fa addr +was not an acceptable address. +.El +.Pp +.Fn Shmdt +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa addr +does not point to a shared memory segment. +.Sh "SEE ALSO" +.Xr shmget 2 , +.Xr shmctl 2 diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 new file mode 100644 index 0000000..b1c5a4b --- /dev/null +++ b/lib/libc/sys/shmctl.2 @@ -0,0 +1,136 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" +.Dd July 17, 1995 +.Dt SHMCTL 2 +.Os FreeBSD +.Sh NAME +.Nm shmctl +.Nd shared memory control +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ipc.h> +.Fd #include <sys/shm.h> +.Ft int +.Fn "shmctl" "int shmid" "int cmd" "struct shmid_ds *buf" +.Sh DESCRIPTION +Performs the action specified by +.Fa cmd +on the shared memory segment identified by +.Fa shmid : +.Bl -tag -width SHM_UNLOCKX +.It Dv IPC_STAT +Fetch the segment's +.Fa "struct shmid_ds" , +storing it in the memory pointed to by +.Fa buf . +.\" +.\" XXX need to make sure that this is correct for FreeBSD +.\" +.It Dv IPC_SET +Changes the +.Fa shm_perm.uid , +.Fa shm_perm.gid , +and +.Fa shm_perm.mode +members of the segment's +.Fa "struct shmid_ds" +to match those of the struct pointed to by +.Fa buf . +The calling process's effective uid must +match either +.Fa shm_perm.uid +or +.Fa shm_perm.cuid , +or it must have superuser privileges. +.It Dv IPC_RMID +Removes the segment from the system. The removal will not take +effect until all processes having attached the segment have exited; +however, once the IPC_RMID operation has taken place, no further +processes will be allowed to attach the segment. For the operation +to succeed, the calling process's effective uid must match +.Fa shm_perm.uid +or +.Fa shm_perm.cuid , +or the process must have superuser privilges. +.\" .It Dv SHM_LOCK +.\" Locks the segment in memory. The calling process must have +.\" superuser privileges. Not implemented in FreeBSD. +.\" .It Dv SHM_UNLOCK +.\" Unlocks the segment from memory. The calling process must +.\" have superuser priviliges. Not implemented in FreeBSD. +.El +.Pp +The +.Fa "shmid_ds" +struct is defined as follows: +.\" +.\" I fiddled with the spaces a bit to make it fit well when viewed +.\" with nroff, but otherwise it's straight from sys/shm.h +.\" +.Bd -literal +struct shmid_ds { + struct ipc_perm shm_perm; /* operation permission structure */ + int shm_segsz; /* size of segment in bytes */ + pid_t shm_lpid; /* process ID of last shared memory op */ + pid_t shm_cpid; /* process ID of creator */ + short shm_nattch; /* number of current attaches */ + time_t shm_atime; /* time of last shmat() */ + time_t shm_dtime; /* time of last shmdt() */ + time_t shm_ctime; /* time of last change by shmctl() */ + void *shm_internal; /* sysv stupidity */ +}; +.Ed +.Sh RETURN VALUES +Upon successful completion, +.Fn shmctl +returns 0. Otherwise, it returns -1 and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Shmctl +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid operation, or +no shared memory segment was found corresponding to +.Fa shmid . +.\" +.\" XXX I think the following is right: ipcperm() only returns EPERM +.\" when an attempt is made to modify (IPC_M) by a non-creator +.\" non-owner +.It Bq Er EPERM +The calling process's effective uid does not match the uid of +the shared memory segment's owner or creator. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +shared memory segment. +.Sh "SEE ALSO" +.Xr shmget 2 , +.Xr shmat 2 , +.Xr shmdt 2 , +.Xr ftok 3 diff --git a/lib/libc/sys/shmget.2 b/lib/libc/sys/shmget.2 new file mode 100644 index 0000000..3df3272 --- /dev/null +++ b/lib/libc/sys/shmget.2 @@ -0,0 +1,138 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" +.Dd July 3, 1995 +.Dt SHMGET 2 +.Os FreeBSD +.Sh NAME +.Nm shmget +.Nd obtain a shared memory identifier +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ipc.h> +.Fd #include <sys/shm.h> +.Ft int +.Fn "shmget" "key_t key" "int size" "int flag" +.Sh DESCRIPTION +Based on the values of +.Fa key +and +.Fa flag , +.Fn shmget +returns the identifier of a newly created or previously existing shared +memory segment. +.\" +.\" The following bit about keys and modes also applies to semaphores +.\" and message queues. +.\" +The key +is analogous to a filename: it provides a handle that names an +IPC object. There are three ways to specify a key: +.Bl -bullet +.It +IPC_PRIVATE may be specified, in which case a new IPC object +will be created. +.It +An integer constant may be specified. If no IPC object corresponding +to +.Fa key +is specified and the IPC_CREAT bit is set in +.Fa flag , +a new one will be created. +.It +.Fn ftok +may be used to generate a key from a pathname. See +.Xr ftok 3 . +.El +.Pp +The mode of a newly created IPC object is determined by +.Em OR Ns 'ing +the following constants into the +.Fa flag +parameter: +.Bl -tag -width XSHM_WXX6XXX +.It Dv SHM_R +Read access for user. +.It Dv SHM_W +Write access for user. +.It Dv (SHM_R>>3) +Read access for group. +.It Dv (SHM_W>>3) +Write access for group. +.It Dv (SHM_R>>6) +Read access for other. +.It Dv (SHM_W>>6) +Write access for other. +.El +.\" +.\" XXX - we should also mention how uid, euid, and gid affect ownership +.\" and use +.\" +.\" end section about keys and modes +.\" +.Pp +When creating a new shared memory segment, +.Fa size +indicates the desired size of the new segment in bytes. The size +of the segment may be rounded up to a multiple convenient to the +kernel (i.e., the page size). +.Sh RETURN VALUES +Upon successful completion, +.Fn shmget +returns the positive integer identifier of a shared memory segment. +Otherwise, -1 is returned and +.Va errno +set to indicate the error. +.Sh ERRORS +.Fn Shmget +will fail if: +.Bl -tag -width Er +.\" +.\" XXX What about ipcperm failing? +.\" +.It Bq Er EINVAL +Size specified is greater than the size of the previously existing segment. +Size specified is less than the system imposed minumum, or greater than +the system imposed maximum. +.It Bq Er ENOENT +No shared memory segment was found matching +.Fa key , +and IPC_CREAT was not specified. +.It Bq Er ENOSPC +The kernel was unable to allocate enough memory to +satisfy the request. +.It Bq Er EEXIST +IPC_CREAT and IPC_EXCL were specified, and a shared memory segment +corresponding to +.Fa key +already exists. +.Pp +.Sh "SEE ALSO" +.Xr shmctl 2 , +.Xr shmat 2 , +.Xr shmdt 2 , +.Xr ftok 3 |