From 1f46aed53dfeb292a0918a810a079b43ddeb4e85 Mon Sep 17 00:00:00 2001 From: trasz Date: Mon, 13 Jul 2009 12:53:43 +0000 Subject: Move msg{snd,recv,get,ctl} manual pages from section 3 to 2. Approved by: re (kib) --- ObsoleteFiles.inc | 5 ++ lib/libc/gen/Makefile.inc | 2 +- lib/libc/gen/ftok.3 | 6 +- lib/libc/gen/msgctl.3 | 210 ------------------------------------------- lib/libc/gen/msgget.3 | 141 ----------------------------- lib/libc/gen/msgrcv.3 | 222 ---------------------------------------------- lib/libc/gen/msgsnd.3 | 184 -------------------------------------- lib/libc/sys/Makefile.inc | 1 + lib/libc/sys/msgctl.2 | 210 +++++++++++++++++++++++++++++++++++++++++++ lib/libc/sys/msgget.2 | 141 +++++++++++++++++++++++++++++ lib/libc/sys/msgrcv.2 | 222 ++++++++++++++++++++++++++++++++++++++++++++++ lib/libc/sys/msgsnd.2 | 184 ++++++++++++++++++++++++++++++++++++++ 12 files changed, 767 insertions(+), 761 deletions(-) delete mode 100644 lib/libc/gen/msgctl.3 delete mode 100644 lib/libc/gen/msgget.3 delete mode 100644 lib/libc/gen/msgrcv.3 delete mode 100644 lib/libc/gen/msgsnd.3 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 diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc index 4b46c07..b988324 100644 --- a/ObsoleteFiles.inc +++ b/ObsoleteFiles.inc @@ -14,6 +14,11 @@ # The file is partitioned: OLD_FILES first, then OLD_LIBS and OLD_DIRS last. # +# 20090709: msgctl.3 msgget.3 msgrcv.3 msgsnd.3 manual pages moved +OLD_FILES+=usr/share/man/man3/msgctl.3.gz +OLD_FILES+=usr/share/man/man3/msgget.3.gz +OLD_FILES+=usr/share/man/man3/msgrcv.3.gz +OLD_FILES+=usr/share/man/man3/msgsnd.3.gz # 20090630: old kernel RPC implementation removal OLD_FILES+=usr/include/nfs/rpcv2.h # 20090624: update usbdi(9) diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc index a4badb9..8837038 100644 --- a/lib/libc/gen/Makefile.inc +++ b/lib/libc/gen/Makefile.inc @@ -55,7 +55,7 @@ MAN+= alarm.3 arc4random.3 \ getpagesize.3 getpass.3 getpeereid.3 getprogname.3 getpwent.3 \ getttyent.3 getusershell.3 getvfsbyname.3 \ glob.3 initgroups.3 isgreater.3 ldexp.3 lockf.3 makecontext.3 \ - modf.3 msgctl.3 msgget.3 msgrcv.3 msgsnd.3 \ + modf.3 \ nice.3 nlist.3 pause.3 popen.3 \ posix_spawn.3 posix_spawn_file_actions_addopen.3 \ posix_spawn_file_actions_init.3 posix_spawnattr_getflags.3 \ diff --git a/lib/libc/gen/ftok.3 b/lib/libc/gen/ftok.3 index a1c7dde..78bfe45 100644 --- a/lib/libc/gen/ftok.3 +++ b/lib/libc/gen/ftok.3 @@ -24,7 +24,7 @@ .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ -.Dd June 24, 1994 +.Dd July 9, 2009 .Os .Dt FTOK 3 .Sh NAME @@ -41,7 +41,7 @@ The .Fn ftok function attempts to create a unique key suitable for use with the -.Xr msgget 3 , +.Xr msgget 2 , .Xr semget 2 and .Xr shmget 2 @@ -66,7 +66,7 @@ does not exist or if it cannot be accessed by the calling process. .Sh SEE ALSO .Xr semget 2 , .Xr shmget 2 , -.Xr msgget 3 +.Xr msgget 2 .Sh HISTORY The .Fn ftok diff --git a/lib/libc/gen/msgctl.3 b/lib/libc/gen/msgctl.3 deleted file mode 100644 index 7d4ec0d..0000000 --- a/lib/libc/gen/msgctl.3 +++ /dev/null @@ -1,210 +0,0 @@ -.\" $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. -.\" -.\" $FreeBSD$ -.\"/ -.Dd April 3, 2008 -.Dt MSGCTL 3 -.Os -.Sh NAME -.Nm msgctl -.Nd message control operations -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/ipc.h -.In sys/msg.h -.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 . -.Pp -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 -.In sys/msg.h -and contains (amongst others) the following members: -.Bd -literal -struct msqid_ds { - struct ipc_perm msg_perm; /* msg queue permission bits */ - struct msg *msg_first; /* first message in the queue */ - struct msg *msg_last; /* last message in the queue */ - msglen_t msg_cbytes; /* number of bytes in use on the queue */ - msgqnum_t msg_qnum; /* number of msgs in the queue */ - msglen_t 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 -.Pp -The -.Vt ipc_perm -structure used inside the -.Vt msqid_ds -structure is defined in -.In sys/ipc.h -and looks like this: -.Bd -literal -struct ipc_perm { - uid_t cuid; /* creator user id */ - gid_t cgid; /* creator group id */ - uid_t uid; /* user id */ - gid_t gid; /* group id */ - mode_t mode; /* r/w permission */ - unsigned short seq; /* sequence # (to generate unique ipcid) */ - key_t key; /* user specified msg/sem/shm key */ -}; -.Ed -.Pp -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 -.In 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 -.Pp -The permission to read from or write to a message queue (see -.Xr msgsnd 3 -and -.Xr msgrcv 3 ) -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 -.Rv -std msgctl -.Sh ERRORS -The -.Fn msgctl -function -will fail if: -.Bl -tag -width Er -.It Bq Er EPERM -The -.Fa cmd -argument -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. -.Pp -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 EACCES -The command is IPC_STAT -and the caller has no read permission for this message queue. -.It Bq Er EINVAL -The -.Fa msqid -argument -is not a valid message queue identifier. -.Pp -.Va cmd -is not a valid command. -.It Bq Er EFAULT -The -.Fa buf -argument -specifies an invalid address. -.El -.Sh SEE ALSO -.Xr msgget 3 , -.Xr msgrcv 3 , -.Xr msgsnd 3 -.Sh HISTORY -Message queues appeared in the first release of -.At V . diff --git a/lib/libc/gen/msgget.3 b/lib/libc/gen/msgget.3 deleted file mode 100644 index e257c60..0000000 --- a/lib/libc/gen/msgget.3 +++ /dev/null @@ -1,141 +0,0 @@ -.\" $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. -.\" $FreeBSD$ -.\" -.\"/ -.Dd August 17, 1995 -.Dt MSGGET 3 -.Os -.Sh NAME -.Nm msgget -.Nd get message queue -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/ipc.h -.In sys/msg.h -.Ft int -.Fn msgget "key_t key" "int msgflg" -.Sh DESCRIPTION -The -.Fn msgget -function -returns the message queue identifier associated with -.Fa key . -A message queue identifier is a unique integer greater than zero. -.Pp -A message queue is created if either -.Fa key -is equal to -.Dv IPC_PRIVATE , -or -.Fa key -does not have a message queue identifier associated with it, and the -.Dv IPC_CREAT -bit is set in -.Fa msgflg . -.Pp -If a new message queue is created, the data structure associated with it (the -.Va msqid_ds -structure, see -.Xr msgctl 3 ) -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 -.Pf ( Dv 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 EACCES -A message queue is already associated with -.Fa key -and the caller has no permission to access it. -.It Bq Er EEXIST -Both -.Dv IPC_CREAT -and -.Dv 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 -.Dv IPC_CREAT -was not set in -.Fa msgflg -and no message queue associated with -.Fa key -was found. -.El -.Sh SEE ALSO -.Xr msgctl 3 , -.Xr msgrcv 3 , -.Xr msgsnd 3 -.Sh HISTORY -Message queues appeared in the first release of -.At V . diff --git a/lib/libc/gen/msgrcv.3 b/lib/libc/gen/msgrcv.3 deleted file mode 100644 index e554dcd..0000000 --- a/lib/libc/gen/msgrcv.3 +++ /dev/null @@ -1,222 +0,0 @@ -.\" $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. -.\" $FreeBSD$ -.\" -.\"/ -.Dd June 15, 2005 -.Dt MSGRCV 3 -.Os -.Sh NAME -.Nm msgrcv -.Nd receive a message from a message queue -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/ipc.h -.In sys/msg.h -.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 -.Pp -.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 -.Pf ( Dv MSGMAX ) . -.Pp -The value of -.Fa msgtyp -has one of the following meanings: -.Bl -bullet -.It -The -.Fa msgtyp -argument -is greater than 0. -The first message of type -.Fa msgtyp -will be received. -.It -The -.Fa msgtyp -argument -is equal to 0. -The first message on the queue will be received. -.It -The -.Fa msgtyp -argument -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 -.Pp -The -.Fa msgsz -argument -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 -.Dv MSG_NOERROR -flag is set in -.Fa msgflg , -otherwise an error will be returned. -.Pp -If no matching message is present on the message queue specified by -.Fa msqid , -the behavior of -.Fn msgrcv -depends on whether the -.Dv IPC_NOWAIT -flag is set in -.Fa msgflg -or not. -If -.Dv IPC_NOWAIT -is set, -.Fn msgrcv -will immediately return a value of -1, and set -.Va errno -to -.Er ENOMSG . -If -.Dv 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 -.Er EINVAL . -.It -A signal is received and caught. --1 is returned, and -.Va errno -set to -.Er EINTR . -.El -.Pp -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. -.El -.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 -The -.Fn msgrcv -function -will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The -.Fa msqid -argument -is not a valid message queue identifier. -.Pp -The message queue was removed while -.Fn msgrcv -was waiting for a message of the requested type to become available on it. -.Pp -The -.Fa msgsz -argument -is less than 0. -.It Bq Er E2BIG -A matching message was received, but its size was greater than -.Fa msgsz -and the -.Dv MSG_NOERROR -flag was not set in -.Fa msgflg . -.It Bq Er EACCES -The calling process does not have read access to the message queue. -.It Bq Er EFAULT -The -.Fa msgp -argument -points to an invalid address. -.It Bq Er EINTR -The system call was interrupted by the delivery of a signal. -.It Bq Er ENOMSG -There is no message of the requested type available on the message queue, -and -.Dv IPC_NOWAIT -is set in -.Fa msgflg . -.El -.Sh SEE ALSO -.Xr msgctl 3 , -.Xr msgget 3 , -.Xr msgsnd 3 -.Sh HISTORY -Message queues appeared in the first release of -.At V . diff --git a/lib/libc/gen/msgsnd.3 b/lib/libc/gen/msgsnd.3 deleted file mode 100644 index fc802b3..0000000 --- a/lib/libc/gen/msgsnd.3 +++ /dev/null @@ -1,184 +0,0 @@ -.\" $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. -.\" -.\" $FreeBSD$ -.\" -.Dd October 12, 2006 -.Dt MSGSND 3 -.Os -.Sh NAME -.Nm msgsnd -.Nd send a message to a message queue -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/ipc.h -.In sys/msg.h -.Ft int -.Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg" -.Sh DESCRIPTION -The -.Fn msgsnd -function sends a message to the message queue specified in -.Fa msqid . -The -.Fa msgp -argument -points to a structure containing the message. -This structure should -consist of the following members: -.Bd -literal - long mtype; /* message type */ - char mtext[1]; /* body of message */ -.Ed -.Pp -.Va mtype -is an integer greater than 0 that can be used for selecting messages (see -.Xr msgrcv 3 ) , -.Va mtext -is an array of -.Fa msgsz -bytes. -The argument -.Fa msgsz -can range from 0 to a system-imposed maximum, -.Dv MSGMAX . -.Pp -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 -.Pf ( Va msg_qbytes , -see -.Xr msgctl 3 ) , -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 -.Dv IPC_NOWAIT -mask set in it, the call will return immediately. -If -.Fa msgflg -does not have -.Dv 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 message queue is removed, in which case -1 will be returned, and -.Va errno -is set to -.Er EINVAL . -.It -The caller catches a signal. -The call returns with -.Va errno -set to -.Er EINTR . -.El -.Pp -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 -.Rv -std msgsnd -.Sh ERRORS -The -.Fn msgsnd -function -will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The -.Fa msqid -argument -is not a valid message queue identifier -.Pp -The message queue was removed while -.Fn msgsnd -was waiting for a resource to become available in order to deliver the -message. -.Pp -The -.Fa msgsz -argument -is greater than -.Va msg_qbytes . -.Pp -The -.Fa mtype -argument -is not greater than 0. -.It Bq Er EACCES -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 -.Dv IPC_NOWAIT -was set in -.Fa msgflg . -.It Bq Er EFAULT -The -.Fa msgp -argument -points to an invalid address. -.It Bq Er EINTR -The system call was interrupted by the delivery of a signal. -.El -.Sh HISTORY -Message queues appeared in the first release of AT&T Unix System V. -.Sh BUGS -.Nx -and -.Fx -do not define the -.Er EIDRM -error value, which should be used -in the case of a removed message queue. diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index da4f3c5..1e6059d 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -81,6 +81,7 @@ MAN+= abort2.2 accept.2 access.2 acct.2 adjtime.2 \ mlockall.2 mmap.2 modfind.2 modnext.2 modstat.2 mount.2 mprotect.2 \ mq_close.2 mq_getattr.2 mq_notify.2 mq_open.2 mq_receive.2 mq_send.2 \ mq_setattr.2 \ + msgctl.2 msgget.2 msgrcv.2 msgsnd.2 \ msync.2 munmap.2 nanosleep.2 nfssvc.2 ntp_adjtime.2 open.2 \ pathconf.2 pipe.2 poll.2 posix_openpt.2 profil.2 ptrace.2 quotactl.2 \ read.2 readlink.2 reboot.2 recv.2 rename.2 revoke.2 rfork.2 rmdir.2 \ diff --git a/lib/libc/sys/msgctl.2 b/lib/libc/sys/msgctl.2 new file mode 100644 index 0000000..34c5263 --- /dev/null +++ b/lib/libc/sys/msgctl.2 @@ -0,0 +1,210 @@ +.\" $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. +.\" +.\" $FreeBSD$ +.\"/ +.Dd July 9, 2009 +.Dt MSGCTL 2 +.Os +.Sh NAME +.Nm msgctl +.Nd message control operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.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 . +.Pp +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 +.In sys/msg.h +and contains (amongst others) the following members: +.Bd -literal +struct msqid_ds { + struct ipc_perm msg_perm; /* msg queue permission bits */ + struct msg *msg_first; /* first message in the queue */ + struct msg *msg_last; /* last message in the queue */ + msglen_t msg_cbytes; /* number of bytes in use on the queue */ + msgqnum_t msg_qnum; /* number of msgs in the queue */ + msglen_t 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 +.Pp +The +.Vt ipc_perm +structure used inside the +.Vt msqid_ds +structure is defined in +.In sys/ipc.h +and looks like this: +.Bd -literal +struct ipc_perm { + uid_t cuid; /* creator user id */ + gid_t cgid; /* creator group id */ + uid_t uid; /* user id */ + gid_t gid; /* group id */ + mode_t mode; /* r/w permission */ + unsigned short seq; /* sequence # (to generate unique ipcid) */ + key_t key; /* user specified msg/sem/shm key */ +}; +.Ed +.Pp +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 +.In 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 +.Pp +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 +.Rv -std msgctl +.Sh ERRORS +The +.Fn msgctl +function +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The +.Fa cmd +argument +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. +.Pp +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 EACCES +The command is IPC_STAT +and the caller has no read permission for this message queue. +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +.Va cmd +is not a valid command. +.It Bq Er EFAULT +The +.Fa buf +argument +specifies an invalid address. +.El +.Sh SEE ALSO +.Xr msgget 2 , +.Xr msgrcv 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libc/sys/msgget.2 b/lib/libc/sys/msgget.2 new file mode 100644 index 0000000..27e1766 --- /dev/null +++ b/lib/libc/sys/msgget.2 @@ -0,0 +1,141 @@ +.\" $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. +.\" $FreeBSD$ +.\" +.\"/ +.Dd July 9, 2009 +.Dt MSGGET 2 +.Os +.Sh NAME +.Nm msgget +.Nd get message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgget "key_t key" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgget +function +returns the message queue identifier associated with +.Fa key . +A message queue identifier is a unique integer greater than zero. +.Pp +A message queue is created if either +.Fa key +is equal to +.Dv IPC_PRIVATE , +or +.Fa key +does not have a message queue identifier associated with it, and the +.Dv IPC_CREAT +bit is set in +.Fa msgflg . +.Pp +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 +.Pf ( Dv 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 EACCES +A message queue is already associated with +.Fa key +and the caller has no permission to access it. +.It Bq Er EEXIST +Both +.Dv IPC_CREAT +and +.Dv 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 +.Dv 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 V . diff --git a/lib/libc/sys/msgrcv.2 b/lib/libc/sys/msgrcv.2 new file mode 100644 index 0000000..917a953 --- /dev/null +++ b/lib/libc/sys/msgrcv.2 @@ -0,0 +1,222 @@ +.\" $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. +.\" $FreeBSD$ +.\" +.\"/ +.Dd July 9, 2009 +.Dt MSGRCV 2 +.Os +.Sh NAME +.Nm msgrcv +.Nd receive a message from a message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.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 +.Pp +.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 +.Pf ( Dv MSGMAX ) . +.Pp +The value of +.Fa msgtyp +has one of the following meanings: +.Bl -bullet +.It +The +.Fa msgtyp +argument +is greater than 0. +The first message of type +.Fa msgtyp +will be received. +.It +The +.Fa msgtyp +argument +is equal to 0. +The first message on the queue will be received. +.It +The +.Fa msgtyp +argument +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 +.Pp +The +.Fa msgsz +argument +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 +.Dv MSG_NOERROR +flag is set in +.Fa msgflg , +otherwise an error will be returned. +.Pp +If no matching message is present on the message queue specified by +.Fa msqid , +the behavior of +.Fn msgrcv +depends on whether the +.Dv IPC_NOWAIT +flag is set in +.Fa msgflg +or not. +If +.Dv IPC_NOWAIT +is set, +.Fn msgrcv +will immediately return a value of -1, and set +.Va errno +to +.Er ENOMSG . +If +.Dv 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 +.Er EINVAL . +.It +A signal is received and caught. +-1 is returned, and +.Va errno +set to +.Er EINTR . +.El +.Pp +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. +.El +.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 +The +.Fn msgrcv +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +The message queue was removed while +.Fn msgrcv +was waiting for a message of the requested type to become available on it. +.Pp +The +.Fa msgsz +argument +is less than 0. +.It Bq Er E2BIG +A matching message was received, but its size was greater than +.Fa msgsz +and the +.Dv MSG_NOERROR +flag was not set in +.Fa msgflg . +.It Bq Er EACCES +The calling process does not have read access to the message queue. +.It Bq Er EFAULT +The +.Fa msgp +argument +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.It Bq Er ENOMSG +There is no message of the requested type available on the message queue, +and +.Dv IPC_NOWAIT +is set in +.Fa msgflg . +.El +.Sh SEE ALSO +.Xr msgctl 2 , +.Xr msgget 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libc/sys/msgsnd.2 b/lib/libc/sys/msgsnd.2 new file mode 100644 index 0000000..d6333bb --- /dev/null +++ b/lib/libc/sys/msgsnd.2 @@ -0,0 +1,184 @@ +.\" $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. +.\" +.\" $FreeBSD$ +.\" +.Dd July 9, 2009 +.Dt MSGSND 2 +.Os +.Sh NAME +.Nm msgsnd +.Nd send a message to a message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgsnd +function sends a message to the message queue specified in +.Fa msqid . +The +.Fa msgp +argument +points to a structure containing the message. +This structure should +consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed +.Pp +.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 +.Fa msgsz +bytes. +The argument +.Fa msgsz +can range from 0 to a system-imposed maximum, +.Dv MSGMAX . +.Pp +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 +.Pf ( 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 +.Dv IPC_NOWAIT +mask set in it, the call will return immediately. +If +.Fa msgflg +does not have +.Dv 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 message queue is removed, in which case -1 will be returned, and +.Va errno +is set to +.Er EINVAL . +.It +The caller catches a signal. +The call returns with +.Va errno +set to +.Er EINTR . +.El +.Pp +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 +.Rv -std msgsnd +.Sh ERRORS +The +.Fn msgsnd +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier +.Pp +The message queue was removed while +.Fn msgsnd +was waiting for a resource to become available in order to deliver the +message. +.Pp +The +.Fa msgsz +argument +is greater than +.Va msg_qbytes . +.Pp +The +.Fa mtype +argument +is not greater than 0. +.It Bq Er EACCES +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 +.Dv IPC_NOWAIT +was set in +.Fa msgflg . +.It Bq Er EFAULT +The +.Fa msgp +argument +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.El +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. +.Sh BUGS +.Nx +and +.Fx +do not define the +.Er EIDRM +error value, which should be used +in the case of a removed message queue. -- cgit v1.1