274 lines
6.8 KiB
Groff
274 lines
6.8 KiB
Groff
.\" $NetBSD: mq_open.3,v 1.6 2012/03/15 19:04:47 njoly Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.\"
|
|
.Dd June 7, 2010
|
|
.Dt MQ_OPEN 3
|
|
.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 ".Dv O_RDONLY"
|
|
.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 ".Dv O_NONBLOCK"
|
|
.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 IMPLEMENTATION 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 3 ,
|
|
.Xr mq_close 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
|
|
.Lk http://www.opengroup.org/unix/online.html .
|