From b4f690c1be69b42a55df1174f6e4bf67bbfee298 Mon Sep 17 00:00:00 2001 From: Theo de Raadt Date: Thu, 14 Dec 1995 02:22:02 +0000 Subject: properly add them... --- lib/libc/sys/msgctl.2 | 201 +++++++++++++++++++++++++++++++++++++++++++++++ lib/libc/sys/msgget.2 | 126 +++++++++++++++++++++++++++++ lib/libc/sys/msgrcv.2 | 181 ++++++++++++++++++++++++++++++++++++++++++ lib/libc/sys/msgsnd.2 | 145 ++++++++++++++++++++++++++++++++++ lib/libc/sys/semctl.2 | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++ lib/libc/sys/semget.2 | 130 ++++++++++++++++++++++++++++++ lib/libc/sys/semop.2 | 152 +++++++++++++++++++++++++++++++++++ lib/libc/sys/shmat.2 | 117 +++++++++++++++++++++++++++ lib/libc/sys/shmctl.2 | 187 ++++++++++++++++++++++++++++++++++++++++++++ lib/libc/sys/shmget.2 | 124 +++++++++++++++++++++++++++++ 10 files changed, 1576 insertions(+) create mode 100644 lib/libc/sys/msgctl.2 create mode 100644 lib/libc/sys/msgget.2 create mode 100644 lib/libc/sys/msgrcv.2 create mode 100644 lib/libc/sys/msgsnd.2 create mode 100644 lib/libc/sys/semctl.2 create mode 100644 lib/libc/sys/semget.2 create mode 100644 lib/libc/sys/semop.2 create mode 100644 lib/libc/sys/shmat.2 create mode 100644 lib/libc/sys/shmctl.2 create mode 100644 lib/libc/sys/shmget.2 (limited to 'lib') diff --git a/lib/libc/sys/msgctl.2 b/lib/libc/sys/msgctl.2 new file mode 100644 index 00000000000..b7b84ee5520 --- /dev/null +++ b/lib/libc/sys/msgctl.2 @@ -0,0 +1,201 @@ +.\" $NetBSD: msgctl.2,v 1.1 1995/10/16 23:49:15 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt MSGCTL 2 +.Os NetBSD +.Sh NAME +.Nm msgctl +.Nd message control operations +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf" +.Sh DESCRIPTION +The +.Fn msgctl +system call performs some control operations on the message queue specified +by +.Fa msqid . + +Each message queue has a data structure associated with it, parts of which +may be altered by +.Fn msgctl +and parts of which determine the actions of +.Fn msgctl . +The data structure is defined in +.Aq Pa sys/msg.h +and contains (amongst others) the following members: +.Bd -literal +struct msqid_ds { + struct ipc_perm msg_perm; /* msg queue permission bits */ + u_long msg_cbytes; /* # of bytes in use on the queue */ + u_long msg_qnum; /* # of msgs in the queue */ + u_long msg_qbytes; /* max # of bytes on the queue */ + pid_t msg_lspid; /* pid of last msgsnd() */ + pid_t msg_lrpid; /* pid of last msgrcv() */ + time_t msg_stime; /* time of last msgsnd() */ + time_t msg_rtime; /* time of last msgrcv() */ + time_t msg_ctime; /* time of last msgctl() */ +}; +.Ed + +The +.Bf -literal +ipc_perm +.Ef +structure used inside the +.Bf -literal +shmid_ds +.Ef +structure is defined in +.Aq Pa sys/ipc.h +and looks like this: +.Bd -literal +struct ipc_perm { + ushort cuid; /* creator user id */ + ushort cgid; /* creator group id */ + ushort uid; /* user id */ + ushort gid; /* group id */ + ushort mode; /* permission (9 bits, see chmod(2)) */ + ushort seq; /* sequence # (to generate unique id) */ + key_t key; /* user specified msg/sem/shm key */ +}; +.Ed + +The operation to be performed by +.Fn msgctl +is specified in +.Fa cmd +and is one of: +.Bl -tag -width IPC_RMIDX +.It Dv IPC_STAT +Gather information about the message queue and place it in the +structure pointed to by +.Fa buf . +.It Dv IPC_SET +Set the value of the +.Va msg_perm.uid , +.Va msg_perm.gid , +.Va msg_perm.mode +and +.Va msg_qbytes +fields in the structure associated with +.Fa msqid . +The values are taken from the corresponding fields in the structure +pointed to by +.Fa buf . +This operation can only be executed by the super-user, or a process that +has an effective user id equal to either +.Va msg_perm.cuid +or +.Va msg_perm.uid +in the data structure associated with the message queue. +The value of +.Va msg_qbytes +can only be increased by the super-user. Values for +.Va msg_qbytes +that exceed the system limit (MSGMNB from +.Aq Pa sys/msg.h ) +are silently truncated to that limit. + +.It Dv IPC_RMID +Remove the message queue specified by +.Fa msqid +and destroy the data associated with it. Only the super-user or a process +with an effective uid equal to the +.Va msg_perm.cuid +or +.Va msg_perm.uid +values in the data structure associated with the queue can do this. +.El + +The permission to read from or write to a message queue (see +.Xr msgsnd 2 +and +.Xr msgrcv 2 ) +is determined by the +.Va msg_perm.mode +field in the same way as is +done with files (see +.Xr chmod 2 ), +but the effective uid can match either the +.Va msg_perm.cuid +field or the +.Va msg_perm.uid +field, and the +effective gid can match either +.Va msg_perm.cgid +or +.Va msg_perm.gid . +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. Otherwise, -1 is +returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn msgctl +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Fa cmd +is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does +the effective uid match either the +.Va msg_perm.uid +or +.Va msg_perm.cuid +fields of the data structure associated with the message queue. + +An attempt is made to increase the value of +.Va msg_qbytes +through IPC_SET +but the caller is not the super-user. +.It Bq Er EACCESS +The command is IPC_STAT +and the caller has no read permission for this message queue. +.It Bq Er EINVAL +.Fa msqid +is not a valid message queue identifier. + +.Va cmd +is not a valid command. +.It Bq Er EFAULT +.Fa buf +specifies an invalid address. +.El +.Sh SEE ALSO +.Xr msgsnd 2 , +.Xr msgrcv 2 , +.Xr msgget 2 +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. diff --git a/lib/libc/sys/msgget.2 b/lib/libc/sys/msgget.2 new file mode 100644 index 00000000000..6952927dc5c --- /dev/null +++ b/lib/libc/sys/msgget.2 @@ -0,0 +1,126 @@ +.\" $NetBSD: msgget.2,v 1.1 1995/10/16 23:49:19 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt MSGGET 2 +.Os NetBSD +.Sh NAME +.Nm msgget +.Nd get message queue +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn msgget "key_t key" "int msgflg" +.Sh DESCRIPTION +.Fn msgget +returns the message queue identifier associated with +.Fa key . +A message queue identifier is a unique integer greater than zero. + +A message queue is created if either +.Fa key +is equal to IPC_PRIVATE, or +.Fa key +does not have a message queue identifier associated with it, and the IPC_CREAT +bit is set in +.Fa msgflg. + +If a new message queue is created, the data structure associated with it (the +.Va msqid_ds +structure, see +.Xr msgctl 2 ) +is initialized as follows: +.Bl -bullet +.It +.Va msg_perm.cuid +and +.Va msg_perm.uid +are set to the effective uid of the calling process. +.It +.Va msg_perm.gid +and +.Va msg_perm.cgid +are set to the effective gid of the calling process. +.It +.Va msg_perm.mode +is set to the lower 9 bits of +.Fa msgflg . +.It +.Va msg_cbytes , +.Va msg_qnum , +.Va msg_lspid , +.Va msg_lrpid , +.Va msg_rtime , +and +.Va msg_stime +are set to 0 +.It +.Va msg_qbytes +is set to the system wide maximum value for the number of bytes in a queue +(MSGMNB). +.It +.Va msg_ctime +is set to the current time. +.El +.Sh RETURN VALUES +Upon successful completion a positive message queue identifier is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACESS +A message queue is already associated with +.Fa key +and the caller has no permission to access it. +.It Bq Er EEXIST +Both IPC_CREAT and IPC_EXCL are set in +.Fa msgflg , +and a message queue is already associated with +.Fa key . +.It Bq Er ENOSPC +A new message queue could not be created because the system limit for +the number of message queues has been reached. +.It Bq Er ENOENT +IPC_CREAT was not set in +.Fa msgflg +and no message queue associated with +.Fa key +was found. +.El +.Sh SEE ALSO +.Xr msgctl 2 , +.Xr msgrcv 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. diff --git a/lib/libc/sys/msgrcv.2 b/lib/libc/sys/msgrcv.2 new file mode 100644 index 00000000000..ca7814bfaeb --- /dev/null +++ b/lib/libc/sys/msgrcv.2 @@ -0,0 +1,181 @@ +.\" $NetBSD: msgrcv.2,v 1.1 1995/10/16 23:49:20 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt MSGRCV 2 +.Os NetBSD +.Sh NAME +.Nm msgrcv +.Nd receive a message from a message queue +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgrcv +function receives a message from the message queue specified in +.Fa msqid , +and places it into the structure pointed to by +.Fa msgp . +This structure should consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed + +.Va mtype +is an integer greater than 0 that can be used for selecting messages, +.Va mtext +is an array of bytes, with a size up to that of the system limit (MSGMAX). + +The value of +.Fa msgtyp +has one of the following meanings: +.Bl -bullet +.It +.Fa msgtyp +is greater than 0. The first message of type +.Fa msgtyp +will be received. +.It +.Fa msgtyp +is equal to 0. The first message on the queue will be received. +.It +.Fa msgtyp +is less than 0. The first message of the lowest message type that is +less than or equal to the absolute value of +.Fa msgtyp +will be received. +.El + +.Fa msgsz +specifies the maximum length of the requested message. If the received +message has a length greater than +.Fa msgsz +it will be silently truncated if the MSG_NOERROR flag is set in +.Fa msgflg , +otherwise an error will be returned. + +If no matching message is present on the message queue specified by +.Fa msqid , +the behaviour of +.Fn msgrcv +depends on whether the IPC_NOWAIT flag is set in +.Fa msgflg +or not. If IPC_NOWAIT is set, +.Fn msgrcv +will immediately return a value of -1, and set +.Va errno +to EAGAIN. If IPC_NOWAIT is not set, the calling process will be blocked +until: +.Bl -bullet +.It +A message of the requested type becomes available on the message queue. +.It +The message queue is removed, in which case -1 will be returned, and +.Va errno +set to EINVAL. +.It +A signal is received and caught. -1 is returned, and +.Va errno +set to EINTR. +.El + +If a message is successfully received, the data structure associated with +.Fa msqid +is updated as follows: +.Bl -bullet +.It +.Va msg_cbytes +is decremented by the size of the message. +.It +.Va msg_lrpid +is set to the pid of the caller. +.It +.Va msg_lrtime +is set to the current time. +.It +.Va msg_qnum +is decremented by 1. +.Sh RETURN VALUES +Upon successful completion, +.Fn msgrcv +returns the number of bytes received into the +.Va mtext +field of the structure pointed to by +.Fa msgp . +Otherwise, -1 is returned, and +.Va errno +set to indicate the error. +.Sh ERRORS +.Fn msgrcv +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa msqid +is not a valid message queue identifier + +The message queue was removed while +.Fn msgrcv +was waiting for a message of the requested type to become available on it. + +.Fa msgsz +is less than 0. +.It Bq Er E2BIG +A matching message was received, but its size was greater than +.Fa msgsz +and the MSG_NOERROR flag was not set in +.Fa msgflg . +.It Bq Er EACCESS +The calling process does not have read access to the message queue. +.It Bq Er EFAULT +.Fa msgp +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.It Bq Er EAGAIN +There is no message of the requested type available on the message queue, +and IPC_NOWAIT is set in +.Fa msgflg . +.Sh SEE ALSO +.Xr msgsnd 2 , +.Xr msgctl 2 , +.Xr msgget 2 +.Sh BUGS +NetBSD does not define the EIDRM error value, which should be used in +the case of a removed message queue, nor the ENOMSG value, which +should be used when no suitable message is available and IPC_NOWAIT +is set. +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. diff --git a/lib/libc/sys/msgsnd.2 b/lib/libc/sys/msgsnd.2 new file mode 100644 index 00000000000..54a0a069519 --- /dev/null +++ b/lib/libc/sys/msgsnd.2 @@ -0,0 +1,145 @@ +.\" $NetBSD: msgsnd.2,v 1.1 1995/10/16 23:49:24 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt MSGSND 2 +.Os NetBSD +.Sh NAME +.Nm msgsnd +.Nd send a message to a message queue +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn msgsnd "int msqid" "void *msgp" "size_t msgsz" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgsnd +function sends a message from the message queue specified in +.Fa msqid . +.Fa msgp +points to a structuer containing the message. This structure should +consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed + +.Va mtype +is an integer greater than 0 that can be used for selecting messages (see +.Xr msgrcv 2 ) , +.Va mtext +is an array of bytes, with a size up to that of the system limit (MSGMAX). + +If the number of bytes already on the message queue plus +.Fa msgsz +is bigger than the maximum number of bytes on the message queue ( +.Va msg_qbytes , +see +.Xr msgctl 2 ) , +or the number of messages on all queues system-wide is already equal to +the system limit, +.Fa msgflg +determines the action of +.Fn msgsnd . +If +.Fa msgflg +has IPC_NOWAIT mask set in it, the call will return immediately. If +.Fa msgflg +does not have IPC_NOWAIT set in it, the call will block until: +.Bl -bullet +.It +The condition which caused the call to block does no longer exist. +The message will be sent. +.It +The messag queue is removed, in which case -1 will be returned, and +.Va errno +is set to EINVAL. +.It +The caller catches a signal. The call returns with +.Va errno +set to EINTR. +.El + +After a successful call, the data structure associated with the message +queue is updated in the following way: +.Bl -bullet +.It +.Va msg_cbytes +is incremented by the size of the message. +.It +.Va msg_qnum +is incremented by 1. +.It +.Va msg_lspid +is set to the pid of the calling process. +.It +.Va msg_stime +is set to the current time. +.El +.Sh RETURN VALUES +Upon successful completion, 0 is returned. Otherwise, -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn msgsnd +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa msqid +is not a valid message queue identifier + +The message queue was removed while +.Fn msgsnd +was waiting for a resource to become available in order to deliver the +message. + +.Fa msgsz +is less than 0, or greater than +.Va msg_qbytes . +.It Bq Er EACCESS +The calling process does not have write access to the message queue. +.It Bq Er EAGAIN +There was no space for this message either on the queue, or in the whole +system, and IPC_NOWAIT was set in +.Fa msgflg . +.It Bq Er EFAULT +.Fa msgp +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.El +.Sh BUGS +NetBSD does not define the EIDRM error value, which should be used +in the case of a removed message queue. +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 new file mode 100644 index 00000000000..d3ff3888a4d --- /dev/null +++ b/lib/libc/sys/semctl.2 @@ -0,0 +1,213 @@ +.\" $NetBSD: semctl.2,v 1.1 1995/10/16 23:49:26 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt SEMCTL 2 +.Os NetBSD +.Sh NAME +.Nm semctl +.Nd semaphore control operations +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn semctl "int semid" "int semnum" "int cmd" "union semun arg" +.Sh DESCRIPTION +The +.Fn semctl +system call provides a number of control operations on the semaphore specified +by +.Fa semnum +and +.Fa semid . +The operation to be performed is specified in +.Fa cmd +(see below). +.Fa arg +is a union of the following fields: +.Bd -literal + int val; /* value for SETVAL */ + struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ + u_short *array; /* array for GETALL & SETALL */ +.Ed + +The +.Bf -literal +semid_ds +.Ef +structure used in the IPC_SET and IPC_STAT commands is defined +as follows in +.Aq Pa sys/sem.h : +.Bd -literal +struct semid_ds { + struct ipc_perm sem_perm; /* operation permissions */ + struct sem *sem_base; /* semaphore set */ + u_short sem_nsems; /* number of sems in set */ + time_t sem_otime; /* last operation time */ + time_t sem_ctime; /* last change time */ +}; +.Ed + +The +.Bf -literal +ipc_perm +.Ef +structure used inside the +.Bf -literal +semid_ds +.Ef +structure is defined in +.Aq Pa sys/ipc.h +and looks like this: +.Bd -literal +struct ipc_perm { + ushort cuid; /* creator user id */ + ushort cgid; /* creator group id */ + ushort uid; /* user id */ + ushort gid; /* group id */ + ushort mode; /* r/w permission (see chmod(2)) */ + ushort seq; /* sequence # (to generate unique msg/sem/shm id) */ + key_t key; /* user specified msg/sem/shm key */ +}; +.Ed + +.Fn semctl +provides the following operations: +.Bl -tag -width IPC_RMIDX +.It Dv GETVAL +Return the value of the semaphore. +.It Dv SETVAL +Set the value of the semaphore to +.Va arg.val . +.It Dv GETPID +Return the pid of the last process that did an operation on this semaphore. +.It Dv GETNCNT +Return the number of processes waiting to acquire the semaphore. +.It Dv GETZCNT +Return the number of processes waiting for the value of the semaphore to +reach 0. +.It Dv GETALL +Return the values for all the semaphores associated with +.Fa semid . +.It Dv SETALL +Set the values for all the semaphores that are associated with the semaphore +identifier +.Fa semid +to the corresponding values in +.Va arg.array . +.It Dv IPC_STAT +Gather statistics about a semaphore and place the information in the +.Bf -literal +semid_ds +.Ef +structure pointed to by +.Fa arg.buf +(see above). +.It Dv IPC_SET +Set the value of the +.Va sem_perm.uid , +.Va sem_perm.gid +and +.Va sem_perm.mode +fields in the structure associated with the semaphore. +The values are taken from the corresponding fields in the structure +pointed to by +.Fa arg.buf . +This operation can only be executed by the super-user, or a process that +has an effective user id equal to either +.Va sem_perm.cuid +or +.Va sem_perm.uid +in the data structure associated with the message queue. +.It Dv IPC_RMID +Remove the semaphores associated with +.Fa semid +from the system and destroy the data structures associated with it. Only the +super-user or a process with an effective uid equal to the +.Va sem_perm.cuid +or +.Va sem_perm.uid +values in the data structure associated with the semaphore can do this. +.El + +The permission to read or change a message queue (see +.Xr semop 2 ) +is determined by the +.Va sem_perm.mode +field in the same way as is +done with files (see +.Xr chmod 2 ), +but the effective uid can match either the +.Va sem_perm.cuid +field or the +.Va sem_perm.uid +field, and the +effective gid can match either +.Va sem_perm.cgid +or +.Va sem_perm.gid . +.Sh RETURN VALUES +For the GETVAL, GETPID, GETNCNT and GETZCNT operations, +.Fn semctl +returns one of the values described above if successful. All other operations +will make +.Fn semctl +return 0 if no errors occur. Otherwise -1 is returned and +.Va errno +set to reflect the error. +.Sh ERRORS +.Fn semctl +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Fa cmd +is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does +the effective uid match either the +.Va sem_perm.uid +or +.Va sem_perm.cuid +fields of the data structure associated with the message queue. +.It Bq Er EACCESS +The caller has no operation permission for this semaphore. +.It Bq Er EINVAL +.Fa semid +is not a valid message semaphore identifier. + +.Va cmd +is not a valid command. +.It Bq Er EFAULT +.Fa arg.buf +specifies an invalid address. +.El +.Sh SEE ALSO +.Xr semop 2 +.Xr semget 2 diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 new file mode 100644 index 00000000000..c05bfd88c73 --- /dev/null +++ b/lib/libc/sys/semget.2 @@ -0,0 +1,130 @@ +.\" $NetBSD: semget.2,v 1.1 1995/10/16 23:49:27 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt SEMGET 2 +.Os NetBSD +.Sh NAME +.Nm semget +.Nd get semaphore set +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn semget "key_t key" "int nsems" "int semflg" +.Sh DESCRIPTION +The +.Fn semget +system call returns the semaphore identifier associated with +.Fa key . + +A new set containing +.Fa nsems +semaphores is created if either +.Fa key +is equal to IPC_PRIVATE, or +.Fa key +does not have a semaphore set associated with it, and the IPC_CREAT bit is +set in +.Fa msgflg. + +If a new set of semaphores is created, the data structure associated with it +(the +.Va semid_ds +structure, see +.Xr semctl 2 ) +is intialized as follows: +.Bl -bullet +.It +.Va sem_perm.cuid +and +.Va sem_perm.uid +are set to the effective uid of the calling process. +.It +.Va sem_perm.gid +and +.Va sem_perm.cgid +are set to the effective gid of the calling process. +.It +.Va sem_perm.mode +is set to the lower 9 bits of +.Fa msgflg . +.It +.Va sem_nsems +is set to the value of +.Fa nsems +.It +.Va sem_ctime +is set to the current time +.It +.Va sem_otime +is set to 0 +.El +.Sh RETURN VALUES +.Fn semget +returns a non-negative semaphore identifier if successful. Otherwise, -1 +is returned and +.Va errno +is set to reflect the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCESS +The caller has no permission to access a semaphore set already associated with +.Fa key. +.It Bq Er EEXIST +Both IPC_CREAT and IPC_EXCL are set in +.Fa msgflg , +and a semaphore set is already associated with +.Fa key . +.It Bq Er EINVAL +.Va nsems +is less than 0 or greater than the system limit for the number in a semaphore +set. + +A semaphore set associated with +.Fa key +exists, but has fewer semaphores than the number specified in +.Fa nsems . +.It Bq Er ENOSPC +A new set of semaphores could not be created because the system limit +for the number of semaphores or the number of semaphore sets has been +reached. +.It Bq Er ENOENT +IPC_CREAT was not set in +.Fa msgflg +and no semaphore set associated with +.Fa key +was found. +.El +.Sh SEE ALSO +.Xr semop 2 +.Xr semctl 2 diff --git a/lib/libc/sys/semop.2 b/lib/libc/sys/semop.2 new file mode 100644 index 00000000000..28eeb7daf68 --- /dev/null +++ b/lib/libc/sys/semop.2 @@ -0,0 +1,152 @@ +.\" $NetBSD: semop.2,v 1.1 1995/10/16 23:49:28 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt SEMOP 2 +.Os NetBSD +.Sh NAME +.Nm semop +.Nd semaphore operations +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn semop "int semid" "struct sembuf *sops" "int nsops" +.Sh DESCRIPTION +.Fn semop +provides a number of atomic operations on a set of semaphores. The semaphore +set is specified by +.Fa semid . +.Fa sops +is an array of semaphore operations, +.Fa nsops +is the number of operations in this array. The +.Va sembuf +structures in the array contain the following members: +.Bd -literal + u_short sem_num; /* semaphore # */ + short sem_op; /* semaphore operation */ + short sem_flg; /* operation flags */ +.Ed + +Each operation (specified in +.Va sem_op ) +is applied to semaphore number +.Va sem_num +in the set of semaphores specified by +.Fa semid . +The value of +.Va sem_op +determines the action taken in the following way: +.Bl -bullet +.It +.Va sem_op +is less than 0. The current process is blocked until the value of the +semaphore is greater than or equal to the absolute value of +.Va sem_op . +The absolute value of +.Va sem_op +is then subtracted from the value of the semaphore, and the calling +process continues. Negative values of +.Va sem_op +are thus used to enter critical regions. +.It +.Va sem_op +is greater than 0. Its value is added to the value of the specified +semaphore. This is used to leave critical regions. +.It +.Va sem_op +is equal to 0. The calling process is blocked until the value of the +specified semaphore reaches 0. +.El + +The behaviour of each operation is influenced by the flags set in +.Va sem_flg +in the following way: +.Bl -tag -width IPC_NOWAITX +.It IPC_NOWAIT +In the case where the calling process would normally block, waiting +for a semaphore to reach a certain value, IPC_NOWAIT makes the +call return immediately, returning a value of -1 and setting +.Va errno +to EAGAIN. +.It SEM_UNDO +Keep track of the changes that this call makes to the value of a semaphore, +so that they can be undone when the calling process terminates. This is +useful to prevent other processes waiting on a semaphore to block forever, +should the process that has the semaphore locked terminate in a critical +section. +.El +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. Otherwise, -1 is +returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn semop +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +There is no semaphore associated with +.Fa semid . + +The semaphore set was removed while the process was waiting for one of +its semaphores to reach a certain value. + +.It Bq Er EACCESS +The calling process has no permission to access the specified semaphore set. +.It Bq Er E2BIG +The value of +.Fa nsops +is too big. The maximum is specified in MAX_SOPS in +.It Bq Er EFBIG +.Va sem_num +in one of the sem_buf structures is less than 0, or greater than the actual +number of semaphores in the set specified by +.Fa semid . +.It Bq Er ENOSPC +SEM_UNDO was requested, and there is not enough space left in the kernel to +store the unfo information. +.It Bq Er EAGAIN +The requested operation can not immediately be performed, and IPC_NOWAIT +was set in +.Va sem_flg . +.It Bq Er EFAULT +.Fa sops +points to an illegal address. +.Sh SEE ALSO +.Xr semctl 2 , +.Xr semget 2 +.Sh BUGS +In case of a removed semaphore identifier, +.Va errno +should be set to EIDRM, but NetBSD does not define this error. diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 new file mode 100644 index 00000000000..1f845596faa --- /dev/null +++ b/lib/libc/sys/shmat.2 @@ -0,0 +1,117 @@ +.\" $NetBSD: shmat.2,v 1.1 1995/10/16 23:49:29 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt SHMAT 2 +.Os NetBSD +.Sh NAME +.Nm shmat , +.Nm shmdt +.Nd map/unmap shared memory +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft void * +.Fn shmat "int shmid" "void *shmaddr" "int shmflg" +.Ft int +.Fn shmdt "void *shmaddr" +.Sh DESCRIPTION +.Fn shmat +maps the shared memory segment associated with the shared memory identifier +.Fa shmid +into the address space of the calling process. The address at which the +segment is mapped is determined by the +.Fa shmaddr +parameter. If it is equal to 0, the system will pick an address itself. +Otherwise, an attempt is made to map the shared memory segment at the +address +.Fa shmaddr +specifies. If SHM_RND is set in +.Fa shmflg , +the system will round the address down to a multiple of SHMLBA bytes +(SHMLBA is defined in +.Aq Pa sys/shm.h +). + +A shared memory segment can be mapped read-only by specifying the +SHM_RDONLY flag in +.Fa shmflg . + +.Fn shmdt +unmaps the shared memory segment that is currently mapped at +.Fa shmaddr +from the calling process' address space. +.Fa shmaddr +must be a value returned by a prior +.Fn shmat +call. A shared memory segment will remain existant until it is removed by +a call to +.Xr shmctl 2 +with the IPC_RMID command. +.Sh RETURN VALUES +.Fn shmat +returns the address at which the shared memory segment has been mapped into +the calling process' address space when successful, +.Fn shmdt +returns 0 on successful completion. Otherwise, a value of -1 is returned, +and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn shmat +will fail if: +.Bl -tag -width Er +.It Bq Er EACCESS +The calling process has no permission to access this shared memory segment. +.It Bq Er ENOMEM +There is not enough available data space for the calling process to +map the shared memory segment. +.It Bq Er EINVAL +.Fa shmid +is not a valid shared memory identifier. + +.Fa shmaddr +specifies an illegal address. +.It Bq Er EMFILE +The number of shared memory segments has reached the system-wide limit. +.El + +.Fn shmdt +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa shmaddr +is not the start address of a mapped shared memory segment. +.Sh SEE ALSO +.Xr shmctl 2 , +.Xr shmget 2 , +.Xr mmap 2 diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 new file mode 100644 index 00000000000..fbb33ab0e31 --- /dev/null +++ b/lib/libc/sys/shmctl.2 @@ -0,0 +1,187 @@ +.\" $NetBSD: shmctl.2,v 1.1 1995/10/16 23:49:30 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt SHMCTL 2 +.Os NetBSD +.Sh NAME +.Nm shmctl +.Nd shared memory control operations +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf" +.Sh DESCRIPTION +The +.Fn shmctl +system call performs some control operations on the shared memory area +specified by +.Fa shmid . + +Each shared memory segment has a data structure associated with it, +parts of which may be altered by +.Fn shmctl +and parts of which determine the actions of +.Fn shmctl . + +This structure is defined as follows in +.Aq Pa sys/shm.h : +.Bd -literal +struct shmid_ds { + struct ipc_perm shm_perm; /* operation permissions */ + int shm_segsz; /* size of segment in bytes */ + pid_t shm_lpid; /* pid of last shm op */ + pid_t shm_cpid; /* pid of creator */ + short shm_nattch; /* # of current attaches */ + time_t shm_atime; /* last shmat() time*/ + time_t shm_dtime; /* last shmdt() time */ + time_t shm_ctime; /* last change by shmctl() */ + void *shm_internal; /* sysv stupidity */ +}; +.Ed +The +.Bf -literal +ipc_perm +.Ef +structure used inside the +.Bf -literal +shmid_ds +.Ef +structure is defined in +.Aq Pa sys/ipc.h +and looks like this: +.Bd -literal +struct ipc_perm { + ushort cuid; /* creator user id */ + ushort cgid; /* creator group id */ + ushort uid; /* user id */ + ushort gid; /* group id */ + ushort mode; /* r/w permission (see chmod(2)) */ + ushort seq; /* sequence # (to generate unique msg/sem/shm id) */ + key_t key; /* user specified msg/sem/shm key */ +}; +.Ed + +The operation to be performed by +.Fn shmctl +is specified in +.Fa cmd +and is one of: +.Bl -tag -width IPC_RMIDX +.It Dv IPC_STAT +Gather information about the shared memory segment and place it in the +structure pointed to by +.Fa buf . +.It Dv IPC_SET +Set the value of the +.Va shm_perm.uid , +.Va shm_perm.gid +and +.Va shm_perm.mode +fields in the structure associated with +.Fa shmid . +The values are taken from the corresponding fields in the structure +pointed to by +.Fa buf . +This operation can only be executed by the super-user, or a process that +has an effective user id equal to either +.Va shm_perm.cuid +or +.Va shm_perm.uid +in the data structure associated with the shared memory segment. + +.It Dv IPC_RMID +Remove the shared memory segment specified by +.Fa shmid +and destroy the data associated with it. Only the super-user or a process +with an effective uid equal to the +.Va shm_perm.cuid +or +.Va shm_perm.uid +values in the data structure associated with the queue can do this. +.El + +The read and write permissions on a shared memory identifier +are determined by the +.Va shm_perm.mode +field in the same way as is +done with files (see +.Xr chmod 2 ), +but the effective uid can match either the +.Va shm_perm.cuid +field or the +.Va shm_perm.uid +field, and the +effective gid can match either +.Va shm_perm.cgid +or +.Va shm_perm.gid . +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. Otherwise, -1 is +returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn shmctl +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Fa cmd +is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does +the effective uid match either the +.Va shm_perm.uid +or +.Va shm_perm.cuid +fields of the data structure associated with the shared memory segment. + +An attempt is made to increase the value of +.Va shm_qbytes +through IPC_SET +but the caller is not the super-user. +.It Bq Er EACCESS +The command is IPC_STAT +and the caller has no read permission for this shared memory segment. +.It Bq Er EINVAL +.Fa shmid +is not a valid shared memory segment identifier. + +.Va cmd +is not a valid command. +.It Bq Er EFAULT +.Fa buf +specifies an invalid address. +.El +.Sh SEE ALSO +.Xr shmat 2 , +.Xr shmdt 2 , +.Xr shmget 2 diff --git a/lib/libc/sys/shmget.2 b/lib/libc/sys/shmget.2 new file mode 100644 index 00000000000..76fd0588823 --- /dev/null +++ b/lib/libc/sys/shmget.2 @@ -0,0 +1,124 @@ +.\" $NetBSD: shmget.2,v 1.1 1995/10/16 23:49:32 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. +.\"/ +.Dd August 17, 1995 +.Dt SHMGET 2 +.Os NetBSD +.Sh NAME +.Nm shmget +.Nd get shared memory area identifier +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn shmget "key_t key" "int size" "int shmflg" +.Sh DESCRIPTION +.Fn shmget +returns the shared memory identifier associated with the key +.Fa key . + +A shared memory segment is created if either +.Fa key +is equal to IPC_PRIVATE, or +.Fa key +does not have a shared memory segment identifier associated with it, and the IPC_CREAT +bit is set in +.Fa shmflg. + +If a new shared memory segment is created, the data structure associated with it (the +.Va shmid_ds +structure, see +.Xr shmctl 2 ) +is initialized as follows: +.Bl -bullet +.It +.Va shm_perm.cuid +and +.Va shm_perm.uid +are set to the effective uid of the calling process. +.It +.Va shm_perm.gid +and +.Va shm_perm.cgid +are set to the effective gid of the calling process. +.It +.Va shm_perm.mode +is set to the lower 9 bits of +.Fa shmflg . +.It +.Va shm_lpid , +.Va shm_nattch , +.Va shm_atime , +and +.Va shm_dtime +are set to 0 +.It +.Va shm_ctime +is set to the current time. +.It +.Va shm_segsz +is set to the value of +.Fa size . +.El +.Sh RETURN VALUES +Upon successful completion a positive shared memory segment identifier is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACESS +A shared memory segment is already associated with +.Fa key +and the caller has no permission to access it. +.It Bq Er EEXIST +Both IPC_CREAT and IPC_EXCL are set in +.Fa shmflg , +and a shared memory segment is already associated with +.Fa key . +.It Bq Er ENOSPC +A new shared memory indentifier could not be created because the system limit +for the number of shared memory identifiers has been reached. +.It Bq Er ENOENT +IPC_CREAT was not set in +.Fa shmflg +and no shared memory segment associated with +.Fa key +was found. +.It Bq Er ENOMEM +There is not enough memory left to created a shared memory segment of the +requested size. +.El +.Sh SEE ALSO +.Xr shmctl 2 , +.Xr shmat 2 , +.Xr shmdt 2 -- cgit v1.2.3