2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
2004-11-10 17:23:19 +00:00
|
|
|
.\" manual provflags the copyright notice and this permission notice are
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Added correction due to Nick Duffek <nsd@bbc.com>, aeb, 960426
|
|
|
|
.\" Modified Wed Nov 6 04:00:31 1996 by Eric S. Raymond <esr@thyrsus.com>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Removed EIDRM from errors - that can't happen...
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-10 17:23:19 +00:00
|
|
|
.\" Language and formatting clean-ups
|
|
|
|
.\" Added notes on /proc files
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2007-05-30 05:36:26 +00:00
|
|
|
.TH MSGGET 2 2004-05-27 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
msgget \- get a message queue identifier
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2008-06-18 08:57:49 +00:00
|
|
|
.B #include <sys/types.h>
|
|
|
|
.B #include <sys/ipc.h>
|
|
|
|
.B #include <sys/msg.h>
|
2008-07-08 14:36:09 +00:00
|
|
|
|
2008-07-06 14:54:26 +00:00
|
|
|
.BI "int msgget(key_t " key ", int " msgflg );
|
2008-07-08 14:36:09 +00:00
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2004-11-10 17:23:19 +00:00
|
|
|
The
|
|
|
|
.BR msgget ()
|
|
|
|
system call returns the message queue identifier associated
|
2004-11-03 13:51:07 +00:00
|
|
|
with the value of the
|
|
|
|
.I key
|
|
|
|
argument.
|
|
|
|
A new message queue is created if
|
|
|
|
.I key
|
|
|
|
has the value
|
|
|
|
.B IPC_PRIVATE
|
|
|
|
or
|
|
|
|
.I key
|
|
|
|
isn't
|
|
|
|
.BR IPC_PRIVATE ,
|
|
|
|
no message queue with the given key
|
2007-09-20 16:26:31 +00:00
|
|
|
.I key
|
2004-11-03 13:51:07 +00:00
|
|
|
exists, and
|
|
|
|
.B IPC_CREAT
|
2004-11-10 17:23:19 +00:00
|
|
|
is specified in
|
|
|
|
.IR msgflg .
|
|
|
|
.PP
|
|
|
|
If
|
2004-11-03 13:51:07 +00:00
|
|
|
.I msgflg
|
2004-11-10 17:23:19 +00:00
|
|
|
specifies both
|
2004-11-03 13:51:07 +00:00
|
|
|
.B IPC_CREAT
|
|
|
|
and
|
|
|
|
.B IPC_EXCL
|
|
|
|
and a message queue already exists for
|
2004-11-10 17:23:19 +00:00
|
|
|
.IR key ,
|
|
|
|
then
|
|
|
|
.BR msgget ()
|
2007-04-12 22:42:49 +00:00
|
|
|
fails with
|
2004-11-10 17:23:19 +00:00
|
|
|
.I errno
|
|
|
|
set to
|
|
|
|
.BR EEXIST .
|
2007-04-12 22:42:49 +00:00
|
|
|
(This is analogous to the effect of the combination
|
2004-11-10 17:23:19 +00:00
|
|
|
.B O_CREAT | O_EXCL
|
|
|
|
for
|
|
|
|
.BR open (2).)
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2004-11-10 17:23:19 +00:00
|
|
|
Upon creation, the least significant bits of the argument
|
2004-11-03 13:51:07 +00:00
|
|
|
.I msgflg
|
2004-11-10 17:23:19 +00:00
|
|
|
define the permissions of the message queue.
|
2004-11-03 13:51:07 +00:00
|
|
|
These permission bits have the same format and semantics
|
2007-04-12 22:42:49 +00:00
|
|
|
as the permissions specified for the
|
2004-11-10 17:23:19 +00:00
|
|
|
.I mode
|
|
|
|
argument of
|
|
|
|
.BR open (2).
|
|
|
|
(The execute permissions are not used.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
If a new message queue is created,
|
2004-11-10 17:23:19 +00:00
|
|
|
then its associated data structure
|
2005-09-15 12:06:26 +00:00
|
|
|
.I msqid_ds
|
2004-11-10 17:23:19 +00:00
|
|
|
(see
|
|
|
|
.BR msgctl (2))
|
2007-06-08 09:56:56 +00:00
|
|
|
is initialized as follows:
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_perm.cuid
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_perm.uid
|
2005-07-18 16:13:49 +00:00
|
|
|
are set to the effective user ID of the calling process.
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_perm.cgid
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_perm.gid
|
2005-07-18 16:13:49 +00:00
|
|
|
are set to the effective group ID of the calling process.
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
The least significant 9 bits of
|
|
|
|
.I msg_perm.mode
|
|
|
|
are set to the least significant 9 bits of
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR msgflg .
|
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.IR msg_qnum ,
|
|
|
|
.IR msg_lspid ,
|
|
|
|
.IR msg_lrpid ,
|
2007-09-20 16:26:31 +00:00
|
|
|
.I msg_stime
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_rtime
|
2004-11-03 13:51:07 +00:00
|
|
|
are set to 0.
|
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_ctime
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the current time.
|
|
|
|
.IP
|
2004-11-10 17:23:19 +00:00
|
|
|
.I msg_qbytes
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the system limit
|
|
|
|
.BR MSGMNB .
|
|
|
|
.PP
|
2004-11-10 17:23:19 +00:00
|
|
|
If the message queue already exists the permissions are
|
2004-11-03 13:51:07 +00:00
|
|
|
verified, and a check is made to see if it is marked for
|
|
|
|
destruction.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
If successful, the return value will be the message queue identifier (a
|
_syscall.2, accept.2, epoll_create.2, inotify_add_watch.2, ioctl.2, msgget.2, msgop.2, open.2, prctl.2, sched_setscheduler.2, semctl.2, semget.2, swapon.2, addseverity.3, cacosh.3, csqrt.3, dirfd.3, drand48.3, fputws.3, mq_send.3, posix_openpt.3, puts.3, sched_getcpu.3, shm_open.3, sqrt.3, sysconf.3, tgamma.3, ulimit.3, credentials.7, svipc.7: Global fix: s/non-negative/nonnegative/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:44:48 +00:00
|
|
|
nonnegative integer), otherwise \-1
|
2004-11-03 13:51:07 +00:00
|
|
|
with
|
2004-11-10 17:23:19 +00:00
|
|
|
.I errno
|
2004-11-03 13:51:07 +00:00
|
|
|
indicating the error.
|
|
|
|
.SH ERRORS
|
|
|
|
On failure,
|
2004-11-10 17:23:19 +00:00
|
|
|
.I errno
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to one of the following values:
|
2008-08-06 20:33:17 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EACCES
|
|
|
|
A message queue exists for
|
|
|
|
.IR key ,
|
|
|
|
but the calling process does not have permission to access the queue,
|
|
|
|
and does not have the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B CAP_IPC_OWNER
|
2004-11-03 13:51:07 +00:00
|
|
|
capability.
|
|
|
|
.TP
|
|
|
|
.B EEXIST
|
|
|
|
A message queue exists for
|
2005-11-02 13:55:25 +00:00
|
|
|
.I key
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
|
|
|
.I msgflg
|
2004-11-10 17:23:19 +00:00
|
|
|
specified both
|
2004-11-03 13:51:07 +00:00
|
|
|
.B IPC_CREAT
|
|
|
|
and
|
|
|
|
.BR IPC_EXCL .
|
|
|
|
.TP
|
|
|
|
.B ENOENT
|
|
|
|
No message queue exists for
|
|
|
|
.I key
|
|
|
|
and
|
|
|
|
.I msgflg
|
2004-11-10 17:23:19 +00:00
|
|
|
did not specify
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR IPC_CREAT .
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
2004-11-10 17:23:19 +00:00
|
|
|
A message queue has to be created but the system does not have enough
|
|
|
|
memory for the new data structure.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
|
|
|
A message queue has to be created but the system limit for the maximum
|
|
|
|
number of message queues
|
|
|
|
.RB ( MSGMNI )
|
|
|
|
would be exceeded.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
.B IPC_PRIVATE
|
|
|
|
isn't a flag field but a
|
2004-11-10 17:23:19 +00:00
|
|
|
.I key_t
|
2004-11-03 13:51:07 +00:00
|
|
|
type.
|
|
|
|
If this special value is used for
|
|
|
|
.IR key ,
|
2004-11-10 17:23:19 +00:00
|
|
|
the system call ignores everything but the least significant 9 bits of
|
2004-11-03 13:51:07 +00:00
|
|
|
.I msgflg
|
|
|
|
and creates a new message queue (on success).
|
|
|
|
.PP
|
|
|
|
The following is a system limit on message queue resources affecting a
|
2004-11-10 17:23:19 +00:00
|
|
|
.BR msgget ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call:
|
2008-08-06 20:33:17 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B MSGMNI
|
|
|
|
System wide maximum number of message queues: policy
|
2004-11-10 17:23:19 +00:00
|
|
|
dependent
|
|
|
|
(on Linux, this limit can be read and modified via
|
|
|
|
.IR /proc/sys/kernel/msgmni ).
|
2007-05-18 10:39:45 +00:00
|
|
|
.SS "Linux Notes"
|
2007-06-22 17:16:20 +00:00
|
|
|
Until version 2.3.20 Linux would return
|
2007-09-20 16:26:31 +00:00
|
|
|
.B EIDRM
|
2007-06-22 17:16:20 +00:00
|
|
|
for a
|
2007-05-18 10:39:45 +00:00
|
|
|
.BR msgget ()
|
|
|
|
on a message queue scheduled for deletion.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH BUGS
|
2007-06-22 17:16:20 +00:00
|
|
|
The name choice
|
2007-09-20 16:26:31 +00:00
|
|
|
.B IPC_PRIVATE
|
2007-12-16 13:13:29 +00:00
|
|
|
was perhaps unfortunate,
|
|
|
|
.B IPC_NEW
|
2004-11-03 13:51:07 +00:00
|
|
|
would more clearly show its function.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR msgctl (2),
|
|
|
|
.BR msgrcv (2),
|
|
|
|
.BR msgsnd (2),
|
|
|
|
.BR ftok (3),
|
2006-03-05 20:58:40 +00:00
|
|
|
.BR capabilities (7),
|
2006-04-21 03:53:43 +00:00
|
|
|
.BR mq_overview (7),
|
|
|
|
.BR svipc (7)
|