mqueues: Add librt (realtime library).
authorStathis Kamperis <beket@dragonflybsd.org>
Wed, 7 Oct 2009 19:40:42 +0000 (19:40 +0000)
committerStathis Kamperis <beket@dragonflybsd.org>
Sun, 11 Oct 2009 20:14:57 +0000 (23:14 +0300)
12 files changed:
include/Makefile
include/mqueue.h [new file with mode: 0644]
lib/librt/Makefile [new file with mode: 0644]
lib/librt/mq.c [new file with mode: 0644]
lib/librt/mq_close.2 [new file with mode: 0644]
lib/librt/mq_getattr.2 [new file with mode: 0644]
lib/librt/mq_notify.2 [new file with mode: 0644]
lib/librt/mq_open.2 [new file with mode: 0644]
lib/librt/mq_receive.2 [new file with mode: 0644]
lib/librt/mq_send.2 [new file with mode: 0644]
lib/librt/mq_setattr.2 [new file with mode: 0644]
lib/librt/mq_unlink.2 [new file with mode: 0644]

index 2f41d0a..cecd397 100644 (file)
@@ -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 (file)
index 0000000..bf2f32b
--- /dev/null
@@ -0,0 +1,58 @@
+/*     $NetBSD: mqueue.h,v 1.4 2009/01/11 03:04:12 christos Exp $      */
+
+/*
+ * Copyright (c) 2007, Mindaugas Rasiukevicius <rmind at NetBSD org>
+ * 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 <fcntl.h>
+#include <signal.h>
+#include <time.h>
+
+#include <sys/cdefs.h>
+#include <sys/types.h>
+
+#include <sys/mqueue.h>
+
+__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 (file)
index 0000000..4d1e296
--- /dev/null
@@ -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 <bsd.lib.mk>
diff --git a/lib/librt/mq.c b/lib/librt/mq.c
new file mode 100644 (file)
index 0000000..54313a2
--- /dev/null
@@ -0,0 +1,138 @@
+/*-
+ * Copyright (c) 2006 David Xu <davidxu@freebsd.org>
+ * 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 <sys/cdefs.h>
+#include <sys/types.h>
+#include <sys/syscall.h>
+#include <sys/sysproto.h>
+#include <sys/mqueue.h>
+
+#include <errno.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <signal.h>
+
+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 (file)
index 0000000..0c06897
--- /dev/null
@@ -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 (file)
index 0000000..1178eff
--- /dev/null
@@ -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 (file)
index 0000000..a80f310
--- /dev/null
@@ -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 (file)
index 0000000..81a7aa9
--- /dev/null
@@ -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 (file)
index 0000000..eaf514d
--- /dev/null
@@ -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 (file)
index 0000000..75fe0ea
--- /dev/null
@@ -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 (file)
index 0000000..e461dd7
--- /dev/null
@@ -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 (file)
index 0000000..0f29224
--- /dev/null
@@ -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 .