From 2184c93c956bfd2b7bd76c1fc362d5b23164e23a Mon Sep 17 00:00:00 2001 From: Stathis Kamperis Date: Wed, 7 Oct 2009 19:40:42 +0000 Subject: [PATCH] mqueues: Add librt (realtime library). --- include/Makefile | 4 +- include/mqueue.h | 58 +++++++++++ lib/librt/Makefile | 10 ++ lib/librt/mq.c | 138 ++++++++++++++++++++++++ lib/librt/mq_close.2 | 69 ++++++++++++ lib/librt/mq_getattr.2 | 91 ++++++++++++++++ lib/librt/mq_notify.2 | 95 +++++++++++++++++ lib/librt/mq_open.2 | 277 +++++++++++++++++++++++++++++++++++++++++++++++++ lib/librt/mq_receive.2 | 176 +++++++++++++++++++++++++++++++ lib/librt/mq_send.2 | 207 ++++++++++++++++++++++++++++++++++++ lib/librt/mq_setattr.2 | 108 +++++++++++++++++++ lib/librt/mq_unlink.2 | 97 +++++++++++++++++ 12 files changed, 1328 insertions(+), 2 deletions(-) create mode 100644 include/mqueue.h create mode 100644 lib/librt/Makefile create mode 100644 lib/librt/mq.c create mode 100644 lib/librt/mq_close.2 create mode 100644 lib/librt/mq_getattr.2 create mode 100644 lib/librt/mq_notify.2 create mode 100644 lib/librt/mq_open.2 create mode 100644 lib/librt/mq_receive.2 create mode 100644 lib/librt/mq_send.2 create mode 100644 lib/librt/mq_setattr.2 create mode 100644 lib/librt/mq_unlink.2 diff --git a/include/Makefile b/include/Makefile index 2f41d0a458..cecd397d46 100644 --- a/include/Makefile +++ b/include/Makefile @@ -15,7 +15,7 @@ INCS= a.out.h ar.h assert.h bitstring.h complex.h cpio.h ctype.h db.h \ fts.h ftw.h getopt.h glob.h grp.h histedit.h \ iconv.h ieeefp.h ifaddrs.h iso646.h inttypes.h \ langinfo.h libgen.h limits.h link.h locale.h malloc.h math.h memory.h \ - mpool.h monetary.h ndbm.h netconfig.h \ + mpool.h mqueue.h monetary.h ndbm.h netconfig.h \ netdb.h nl_types.h nlist.h nss.h nsswitch.h objformat.h \ paths.h printf.h pthread.h pthread_np.h pwd.h \ ranlib.h readpassphrase.h regex.h regexp.h \ @@ -37,7 +37,7 @@ MHDRS= float.h floatingpoint.h varargs.h # Only for default SHARED=copies case SHDRS= soundcard.h joystick.h -LHDRS= aio.h errno.h fcntl.h linker_set.h mqueue.h poll.h sched.h \ +LHDRS= aio.h errno.h fcntl.h linker_set.h poll.h sched.h \ semaphore.h syslog.h termios.h ucontext.h # directories which also contain header files that need to be copied. diff --git a/include/mqueue.h b/include/mqueue.h new file mode 100644 index 0000000000..bf2f32be49 --- /dev/null +++ b/include/mqueue.h @@ -0,0 +1,58 @@ +/* $NetBSD: mqueue.h,v 1.4 2009/01/11 03:04:12 christos Exp $ */ + +/* + * Copyright (c) 2007, Mindaugas Rasiukevicius + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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. + */ + +#ifndef _MQUEUE_H_ +#define _MQUEUE_H_ + +#include +#include +#include + +#include +#include + +#include + +__BEGIN_DECLS +int mq_close(mqd_t); +int mq_getattr(mqd_t, struct mq_attr *); +int mq_notify(mqd_t, const struct sigevent *); +mqd_t mq_open(const char *, int, ...); +ssize_t mq_receive(mqd_t, char *, size_t, unsigned *); +int mq_send(mqd_t, const char *, size_t, unsigned); +int mq_setattr(mqd_t, const struct mq_attr * __restrict, + struct mq_attr * __restrict); +ssize_t mq_timedreceive(mqd_t, char * __restrict, size_t, + unsigned * __restrict, const struct timespec * __restrict); +int mq_timedsend(mqd_t, const char *, size_t, unsigned, + const struct timespec *); +int mq_unlink(const char *); +__END_DECLS + +#endif /* _MQUEUE_H_ */ + diff --git a/lib/librt/Makefile b/lib/librt/Makefile new file mode 100644 index 0000000000..4d1e296666 --- /dev/null +++ b/lib/librt/Makefile @@ -0,0 +1,10 @@ +LIB=rt +SHLIB_MAJOR=0 +CFLAGS+=-Winline -Wall -g + +SRCS+= mq.c + +MAN+= mq_close.2 mq_getattr.2 mq_notify.2 mq_open.2 mq_receive.2 \ + mq_send.2 mq_setattr.2 mq_unlink.2 \ + +.include diff --git a/lib/librt/mq.c b/lib/librt/mq.c new file mode 100644 index 0000000000..54313a2b06 --- /dev/null +++ b/lib/librt/mq.c @@ -0,0 +1,138 @@ +/*- + * Copyright (c) 2006 David Xu + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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$ + */ + +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +extern int __sys_mq_open(const char *, int, mode_t, + const struct mq_attr *); +extern int __sys_mq_close(int fd); +extern int __sys_mq_getattr(mqd_t mqd, struct mq_attr *attr); +extern int __sys_mq_notify(int, const struct sigevent *); +extern ssize_t __sys_mq_receive(mqd_t mqd, char *buf, size_t len, + unsigned *prio); +extern ssize_t __sys_mq_send(mqd_t mqd, char *buf, size_t len, unsigned prio); +extern int __sys_mq_setattr(int, const struct mq_attr *__restrict, + struct mq_attr *__restrict); +extern ssize_t __sys_mq_timedreceive(int, char *__restrict, size_t, + unsigned *__restrict, const struct timespec *__restrict); +extern int __sys_mq_timedsend(int, const char *, size_t, unsigned, + const struct timespec *); +extern int __sys_mq_unlink(const char *); + +__weak_reference(__mq_open, mq_open); +__weak_reference(__mq_open, _mq_open); +__weak_reference(__mq_close, mq_close); +__weak_reference(__mq_close, _mq_close); +__weak_reference(__mq_notify, mq_notify); +__weak_reference(__mq_notify, _mq_notify); +__weak_reference(__mq_getattr, mq_getattr); +__weak_reference(__mq_getattr, _mq_getattr); +__weak_reference(__mq_setattr, mq_setattr); +__weak_reference(__mq_setattr, _mq_setattr); +__weak_reference(__mq_timedreceive, mq_timedreceive); +__weak_reference(__mq_timedreceive, _mq_timedreceive); +__weak_reference(__mq_timedsend, mq_timedsend); +__weak_reference(__mq_timedsend, _mq_timedsend); +__weak_reference(__mq_unlink, mq_unlink); +__weak_reference(__mq_unlink, _mq_unlink); +__weak_reference(__mq_send, mq_send); +__weak_reference(__mq_send, _mq_send); +__weak_reference(__mq_receive, mq_receive); +__weak_reference(__mq_receive, _mq_receive); + +mqd_t +__mq_open(const char *name, int oflag, mode_t mode, + const struct mq_attr *attr) +{ + return (__sys_mq_open(name, oflag, mode, attr)); +} + +int +__mq_close(mqd_t mqd) +{ + return (__sys_mq_close(mqd)); +} + +int +__mq_notify(mqd_t mqd, const struct sigevent *evp) +{ + return (__sys_mq_notify(mqd, evp)); +} + +int +__mq_getattr(mqd_t mqd, struct mq_attr *attr) +{ + return (__sys_mq_getattr(mqd, attr)); +} + +int +__mq_setattr(mqd_t mqd, const struct mq_attr *newattr, struct mq_attr *oldattr) +{ + return (__sys_mq_setattr(mqd, newattr, oldattr)); +} + +ssize_t +__mq_timedreceive(mqd_t mqd, char *buf, size_t len, + unsigned *prio, const struct timespec *timeout) +{ + return (__sys_mq_timedreceive(mqd, buf, len, prio, timeout)); +} + +ssize_t +__mq_receive(mqd_t mqd, char *buf, size_t len, unsigned *prio) +{ + return (__sys_mq_receive(mqd, buf, len, prio)); +} + +ssize_t +__mq_timedsend(mqd_t mqd, char *buf, size_t len, + unsigned prio, const struct timespec *timeout) +{ + return (__sys_mq_timedsend(mqd, buf, len, prio, timeout)); +} + +ssize_t +__mq_send(mqd_t mqd, char *buf, size_t len, unsigned prio) +{ + return (__sys_mq_send(mqd, buf, len, prio)); +} + +int +__mq_unlink(const char *path) +{ + return (__sys_mq_unlink(path)); +} diff --git a/lib/librt/mq_close.2 b/lib/librt/mq_close.2 new file mode 100644 index 0000000000..0c0689732f --- /dev/null +++ b/lib/librt/mq_close.2 @@ -0,0 +1,69 @@ +.\" $NetBSD: mq_close.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_CLOSE 2 +.Os +.Sh NAME +.Nm mq_close +.Nd close a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_close "mqd_t mqdes" +.Sh DESCRIPTION +The +.Fn mq_close +function will remove the association between the message queue descriptor, +.Fa mqdes , +and its message queue. +.Pp +If the process has successfully attached a notification request to +the message queue via this +.Fa mqdes , +this attachment will be removed, and the message queue is available +for another process to attach for notification. +.Sh RETURN VALUES +.Rv -std mq_close +.Sh ERRORS +The +.Fn mq_close +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_getattr 3 , +.Xr mq_notify 3 , +.Xr mq_open 3 , +.Xr mq_receive 3 , +.Xr mq_send 3 , +.Xr mq_setattr 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_close +function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_getattr.2 b/lib/librt/mq_getattr.2 new file mode 100644 index 0000000000..1178effabf --- /dev/null +++ b/lib/librt/mq_getattr.2 @@ -0,0 +1,91 @@ +.\" $NetBSD: mq_getattr.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_GETATTR 2 +.Os +.Sh NAME +.Nm mq_getattr +.Nd get message queue attributes (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_getattr "mqd_t mqdes" "struct mq_attr *mqstat" +.Sh DESCRIPTION +The +.Fn mq_getattr +function will obtain status information and attributes of the +message queue and the open message queue description associated +with the message queue descriptor. +.Pp +The +.Fa mqdes +argument specifies a message queue descriptor. +.Pp +The results are returned in the +.Vt mq_attr +structure referenced by the +.Va mqstat +argument. +.Pp +Upon return, the following members have the values associated with +the open message queue description as set when the message queue was +opened and as modified by subsequent +.Xr mq_setattr 3 +calls: +.Va mq_flags . +.Pp +The following attributes of the message queue will be returned as set +at message queue creation: +.Va mq_maxmsg , +.Va mq_msgsize . +.Pp +Upon return, the following members within the +.Vt mq_attr +structure referenced by the +.Fa mqstat +argument will be set to the current state of the message queue: +.Bl -tag -width mq_curmsgs +.It Va mq_curmsgs +The number of messages currently on the queue. +.El +.Sh RETURN VALUES +.Rv -std mq_getattr +.Sh ERRORS +The +.Fn mq_getattr +function may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The mqdes argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_notify 3 , +.Xr mq_open 3 , +.Xr mq_receive 3 , +.Xr mq_send 3 , +.Xr mq_setattr 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_notify.2 b/lib/librt/mq_notify.2 new file mode 100644 index 0000000000..a80f310feb --- /dev/null +++ b/lib/librt/mq_notify.2 @@ -0,0 +1,95 @@ +.\" $NetBSD: mq_notify.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_NOTIFY 2 +.Os +.Sh NAME +.Nm mq_notify +.Nd notify process that a message is available (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" +.Sh DESCRIPTION +If the argument +.Fa notification +is not +.Dv NULL , +this function will register the calling process to be notified of +message arrival at an empty message queue associated with the +specified message queue descriptor, +.Fa mqdes . +The notification specified by the +.Fa notification +argument will be sent to the process when the message queue +transitions from empty to non-empty. +At any time, only one process may be registered for notification +by a message queue. +If the calling process or any other process has already registered +for notification of message arrival at the specified message queue, +subsequent attempts to register for that message queue fails. +.Pp +If +.Fa notification +is +.Dv NULL +and the process is currently registered for notification by the +specified message queue, the existing registration will be removed. +.Pp +When the notification is sent to the registered process, +its registration will be removed. +The message queue will then be available for registration. +.Pp +If a process has registered for notification of message arrival +at a message queue and some thread is blocked in +.Fn mq_receive +waiting to receive a message when a message arrives at the queue, +the arriving message will satisfy the appropriate +.Fn mq_receive . +The resulting behavior is as if the message queue remains empty, +and no notification will be sent. +.Sh RETURN VALUES +.Rv -std mq_notify +.Sh ERRORS +The +.Fn mq_notify +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.It Bq Er EBUSY +A process is already registered for notification by the message queue. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_getattr 3 , +.Xr mq_open 3 , +.Xr mq_receive 3 , +.Xr mq_send 3 , +.Xr mq_setattr 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_open.2 b/lib/librt/mq_open.2 new file mode 100644 index 0000000000..81a7aa9a2c --- /dev/null +++ b/lib/librt/mq_open.2 @@ -0,0 +1,277 @@ +.\" $NetBSD: mq_open.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_OPEN 2 +.Os +.Sh NAME +.Nm mq_open +.Nd open a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft mqd_t +.Fn mq_open "const char *name" "int oflag" +.Ft mqd_t +.Fn mq_open "const char *name" "int oflag" "mode_t mode" "struct mq_attr *attr" +.Sh DESCRIPTION +The +.Fn mq_open +function establishes the connection between a process and a message queue +with a message queue descriptor. +It creates an open message queue description that refers to the message +queue, and a message queue descriptor that refers to that open message +queue description. +The message queue descriptor is used by other functions to refer to that +message queue. +The +.Fa name +argument points to a string naming a message queue, +which should conform to the construction rules for a pathname. +The +.Fa name +should begin with a slash character. +The processes calling +.Fn mq_open +with the same value of +.Fa name +will refer to the same message queue object, +as long as that name has not been removed. +If the +.Fa name +argument is not +the name of an existing message queue and creation is not requested, +.Fn mq_open +fails and returns an error. +.Pp +The +.Fa oflag +argument requests the desired receive and/or send access to the message queue. +The requested access permission to receive messages or send messages are +granted if the calling process would be granted read or write access, +respectively, to an equivalently protected file. +.Pp +The value of +.Fa oflag +is the bitwise-inclusive OR of values from the following list. +Applications must specify exactly one of the first three values +(access modes) below in the value of +.Fa oflag : +.Bl -tag -width It +.It Dv O_RDONLY +Open the message queue for receiving messages. +The process can use the returned message queue descriptor with +.Xr mq_receive 3 , +but not +.Xr mq_send 3 . +.It Dv O_WRONLY +Open the queue for sending messages. +The process can use the returned message queue descriptor with +.Xr mq_send 3 +but not +.Xr mq_receive 3 . +.It Dv O_RDWR +Open the queue for both receiving and sending messages. +The process can use any of the functions allowed for +.Dv O_RDONLY +and +.Dv O_WRONLY . +.El +.Pp +In all cases, a message queue may be open multiple times in the same +or different processes for sending/receiving messages. +.Pp +Any combination of the remaining flags may be specified in the value of +.Fa oflag : +.Bl -tag -width It +.It Dv O_CREAT +Create a message queue. +It requires two additional arguments: +.Fa mode +and +.Fa attr . +If the pathname +.Fa name +has already been used to create a message queue that still exists, +then this flag will have no effect, except as noted under +.Dv O_EXCL . +Otherwise, a message queue will be created without any messages in it. +The user ID of the message queue will be set to the effective user ID +of the process, and the group ID of the message queue will be set to +the effective group ID of the process. +The permission bits of the message queue will be set to the value of the +.Fa mode +argument, except those set in the file mode creation mask of +the process. +When bits in +.Fa mode +other than the file permission bits are specified, the effect +is unspecified. +If +.Fa attr +is +.Dv NULL , +the message queue will be created with implementation-defined default +message queue attributes. +If +.Fa attr +is +.No non- Ns Dv NULL +and the calling process has the appropriate privilege on +.Fa name , +the message queue +.Va mq_maxmsg +and +.Va mq_msgsize +attributes will be set to the values of the corresponding members in the +.Vt mq_attr +structure referred to by +.Fa attr . +If +.Fa attr +is +.No non- Ns Dv NULL , +but the calling process does not have the +appropriate privilege on +.Fa name , +the +.Fn mq_open +function will fail and return an error without creating the message queue. +.It Dv O_EXCL +If +.Dv O_EXCL +and +.Dv O_CREAT +are set, +.Fn mq_open +fails if the message queue +.Fa name +exists. +The check for the existence of the message queue and the creation of the +message queue if it does not exist will be atomic with respect to other +threads executing +.Fn mq_open +naming the same +.Fa name +with +.Dv O_EXCL +and +.Dv O_CREAT +set. +If +.Dv O_EXCL +is set and +.Dv O_CREAT +is not set, the result is undefined. +.It Dv O_NONBLOCK +Determines whether an +.Xr mq_send 3 +or +.Xr mq_receive 3 +waits for resources or messages that are not currently available, +or fails with errno set to +.Er EAGAIN . +.El +.Pp +The +.Fn mq_open +function does not add or remove messages from the queue. +.Sh NOTES +The +.Xr select 2 +and +.Xr poll 2 +system calls to the message queue descriptor are supported by +.Nx , +however, it is not portable. +.Sh RETURN VALUES +Upon successful completion, +.Fn mq_open +returns a message queue descriptor. +Otherwise, the function returns +.Pq Dv mqd_t +\-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_open +function fails if: +.Bl -tag -width Er +.It Bq Er EACCES +The message queue exists and the permissions specified by +.Fa oflag +are denied, or the message queue does not exist and permission +to create the message queue is denied. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are set and the named message queue already exists. +.It Bq Er EINTR +The +.Fn mq_open +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fn mq_open +function is not supported for the given name, or +.Dv O_CREAT +was specified in +.Fa oflag , +the value of +.Fa attr +is not +.Dv NULL , +and either +.Va mq_maxmsg +or +.Va mq_msgsize +was less than or equal to zero. +.It Bq Er EMFILE +Too many message queue descriptors or file descriptors are currently +in use by this process. +.It Bq Er ENAMETOOLONG +The length of the +.Fa name +argument exceeds +.Brq Dv PATH_MAX +or a pathname component is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENFILE +Too many message queues are currently open in the system. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named message queue does not exist. +.It Bq Er ENOSPC +There is insufficient space for the creation of the new message queue. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_getattr 3 , +.Xr mq_notify 3 , +.Xr mq_receive 3 , +.Xr mq_send 3 , +.Xr mq_setattr 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_receive.2 b/lib/librt/mq_receive.2 new file mode 100644 index 0000000000..eaf514d182 --- /dev/null +++ b/lib/librt/mq_receive.2 @@ -0,0 +1,176 @@ +.\" $NetBSD: mq_receive.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_RECEIVE 2 +.Os +.Sh NAME +.Nm mq_receive, mq_timedreceive +.Nd receive a message from a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft ssize_t +.Fo mq_receive +.Fa "mqd_t mqdes" +.Fa "char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *msg_prio" +.Fc +.In mqueue.h +.In time.h +.Ft ssize_t +.Fo mq_timedreceive +.Fa "mqd_t mqdes" +.Fa "char *restrict msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *restrict msg_prio" +.Fa "const struct timespec *restrict abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_receive +function receives the oldest of the highest priority message(s) +from the message queue specified by +.Fa mqdes . +If the size of the buffer in bytes, specified by the +.Fa msg_len +argument, is less than the +.Va mq_msgsize +attribute of the message queue, the function fails and returns an error. +Otherwise, the selected message will be removed from the queue and copied +to the buffer pointed to by the +.Fa msg_ptr +argument. +.Pp +If the argument +.Fa msg_prio +is not +.Dv NULL , +the priority of the selected message will be stored in the location +referenced by +.Fa msg_prio . +.Pp +If the specified message queue is empty and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_receive +blocks until a message is enqueued on the message queue or until +.Fn mq_receive +is interrupted by a signal. +If more than one thread is waiting to receive a message when a +message arrives at an empty queue, then the thread of highest +priority that has been waiting the longest will be selected to +receive the message. +If the specified message queue is empty and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +no message will be removed from the queue, and +.Fn mq_receive +returns an error. +.Pp +The timeout expires when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The resolution of the timeout is based on the CLOCK_REALTIME clock. +The +.Fa timespec +argument is defined in the +.Aq time.h +header. +.Pp +Under no circumstance will the operation fail with a timeout if a +message can be removed from the message queue immediately. +The validity of the +.Fa abs_timeout +parameter will not be checked if a message can be removed from the +message queue immediately. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_receive +and +.Fn mq_timedreceive +functions return a value of zero. +Otherwise, no message will be removed from the queue, +the functions return a value of +\-1, and set the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_receive +and +.Fn mq_timedreceive +functions fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +.Dv O_NONBLOCK +was set in the message description associated with +.Fa mqdes , +and the specified message queue is empty. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for reading. +.It Bq Er EINTR +The +.Fn mq_receive +or +.Fn mq_timedreceive +operation was interrupted by a signal. +.It Bq Er EINVAL +The process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.It Bq Er EMSGSIZE +The specified message buffer size, +.Fa msg_len , +is less than the message size attribute of the message queue. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, +but no message arrived on the queue before the specified timeout expired. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_getattr 3 , +.Xr mq_notify 3 , +.Xr mq_open 3 , +.Xr mq_send 3 , +.Xr mq_setattr 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +These functions are expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_receive +and +.Fn mq_timedreceive +functions first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_send.2 b/lib/librt/mq_send.2 new file mode 100644 index 0000000000..75fe0eaa0e --- /dev/null +++ b/lib/librt/mq_send.2 @@ -0,0 +1,207 @@ +.\" $NetBSD: mq_send.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_SEND 2 +.Os +.Sh NAME +.Nm mq_send , mq_timedsend +.Nd send a message to a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_send +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fc +.In mqueue.h +.In time.h +.Ft int +.Fo mq_timedsend +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fa "const struct timespec *abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_send +function will add the message pointed to by the argument +.Fa msg_ptr +to the message queue specified by +.Fa mqdes . +The +.Fa msg_len +argument specifies the length of the message, in bytes, pointed to by +.Fa msg_ptr . +The value of +.Fa msg_len +will be less than or equal to the +.Fa mq_msgsize +attribute of the message queue, or +.Fn mq_send +will fail. +.Pp +If the specified message queue is not full, +.Fn mq_send +behaves as if the message is inserted into the message queue at the +position indicated by the +.Fa msg_prio +argument. +A message with a larger numeric value of +.Fa msg_prio +will be inserted before messages with lower values of +.Fa msg_prio . +A message will be inserted after other messages in the queue, +if any, with equal +.Fa msg_prio . +The value of +.Fa msg_prio +will be less than +.Brq Dv MQ_PRIO_MAX . +.Pp +If the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_send +blocks until space becomes available to enqueue the message, or until +.Fn mq_send +is interrupted by a signal. +If more than one thread is waiting to send when space becomes available +in the message queue, then the thread of the highest priority that has +been waiting the longest will be unblocked to send its message. +If the specified message queue is full and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +the message will not be queued and +.Fn mq_send +will return an error. +.Pp +The +.Fn mq_timedsend +function will add a message to the message queue specified by +.Fa mqdes +in the manner defined for the +.Fn mq_send +function. +However, if the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +the wait for sufficient room in the queue will be terminated +when the specified timeout expires. +If +.Dv O_NONBLOCK +is set in the message queue description, this function will be equivalent to +.Fn mq_send . +.Pp +The timeout will expire when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The resolution of the timeout is based on the CLOCK_REALTIME clock. +The +.Fa timespec +argument is defined in the +.Aq time.h +header. +.Pp +Under no circumstance will the operation fail with a timeout if there is +sufficient room in the queue to add the message immediately. +The validity of the +.Fa abs_timeout +parameter need not be checked when there is sufficient room in the queue. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_send +and +.Fn mq_timedsend +functions return a value of zero. +Otherwise, no message will be enqueued, +the functions will return \-1, and the global variable +.Va errno +will be set to indicate the error. +.Sh ERRORS +The +.Fn mq_send +and +.Fn mq_timedsend +functions fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The +.Dv O_NONBLOCK +flag is set in the message queue description associated with +.Fa mqdes , +and the specified message queue is full. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for writing. +.It Bq Er EINTR +A signal interrupted the call to +.Fn mq_send +or +.Fn mq_timedsend . +.It Bq Er EINVAL +The value of +.Fa msg_prio +was outside the valid range, or +the process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.It Bq Er EMSGSIZE +The specified message length, +.Fa msg_len , +exceeds the message size attribute of the message queue. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, +but the timeout expired before the message could be added to the queue. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_getattr 3 , +.Xr mq_notify 3 , +.Xr mq_open 3 , +.Xr mq_receive 3 , +.Xr mq_setattr 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +These functions are expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_send +and +.Fn mq_timedsend +functions first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_setattr.2 b/lib/librt/mq_setattr.2 new file mode 100644 index 0000000000..e461dd7a3e --- /dev/null +++ b/lib/librt/mq_setattr.2 @@ -0,0 +1,108 @@ +.\" $NetBSD: mq_setattr.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_SETATTR 2 +.Os +.Sh NAME +.Nm mq_setattr +.Nd set message queue attributes (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_setattr +.Fa "mqd_t mqdes" +.Fa "const struct mq_attr *restrict mqstat" +.Fa "struct mq_attr *restrict omqstat" +.Fc +.Sh DESCRIPTION +The +.Fn mq_setattr +function sets attributes associated with the open message queue +description referenced by the message queue descriptor specified by +.Fa mqdes . +.Pp +The message queue attributes corresponding to the following members +defined in the +.Vt mq_attr +structure will be set to the specified values upon successful completion of +.Fn mq_setattr : +.Bl -tag -width mq_flags +.It Va mq_flags +The value of this member is the bitwise-logical OR of zero or more of +.Dv O_NONBLOCK +and any implementation-defined flags. +.El +.Pp +The values of the +.Va mq_maxmsg , +.Va mq_msgsize , +and +.Va mq_curmsgs +members of the +.Vt mq_attr +structure will be ignored by +.Fn mq_setattr . +.Pp +If +.Fa omqstat +is +.No non- Ns Dv NULL , +the +.Fn mq_setattr +function will store, in the location referenced by +.Fa omqstat +the previous message queue attributes and the current queue status. +These values are the same as would be returned by a call to +.Xr mq_getattr 3 +at that point. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_setattr +function returns zero and the attributes of the message queue will +have been changed as specified. +Otherwise, the message queue attributes are unchanged, +and the function returns a value of +\-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_setattr +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_getattr 3 , +.Xr mq_notify 3 , +.Xr mq_open 3 , +.Xr mq_receive 3 , +.Xr mq_send 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/lib/librt/mq_unlink.2 b/lib/librt/mq_unlink.2 new file mode 100644 index 0000000000..0f29224c6e --- /dev/null +++ b/lib/librt/mq_unlink.2 @@ -0,0 +1,97 @@ +.\" $NetBSD: mq_unlink.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd August 19, 2009 +.Dt MQ_UNLINK 2 +.Os +.Sh NAME +.Nm mq_unlink +.Nd remove a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn mq_unlink +function removes the message queue named by the pathname +.Fa name . +After a successful call to +.Fn mq_unlink +with +.Fa name , +a call to +.Xr mq_open 3 +with +.Fa name +fails if the flag +.Dv O_CREAT +is not set in +.Fa flags . +If one or more processes have the message queue open when +.Fn mq_unlink +is called, destruction of the message queue will be postponed until +all references to the message queue have been closed. +.Pp +Calls to +.Xr mq_open 3 +to recreate the message queue may fail until the message queue is +actually removed. +However, the +.Fn mq_unlink +call need not block until all references have been closed; +it may return immediately. +.Sh RETURN VALUES +Upon successful completion, the function returns a value of zero. +Otherwise, the named message queue will be unchanged by this function call, +and the function returns a value of \-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_unlink +function fails if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission is denied to unlink the named message queue. +.It Bq Er ENAMETOOLONG +The length of the name argument exceeds +.Brq Dv PATH_MAX +or a pathname +component is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENOENT +The named message queue does not exist. +.El +.Sh SEE ALSO +.Xr mq_close 3 , +.Xr mq_getattr 3 , +.Xr mq_notify 3 , +.Xr mq_open 3 , +.Xr mq_receive 3 , +.Xr mq_send 3 , +.Xr mq_setattr 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_unlink +function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . -- 2.11.4.GIT