| .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" 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. |
| .\" |
| .\" 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. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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> |
| .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com> |
| .\" Removed EIDRM from errors - that can't happen... |
| .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Added notes on capability requirements |
| .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Language and formatting clean-ups |
| .\" Added notes on /proc files |
| .\" |
| .TH MSGGET 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| msgget \- get a System V message queue identifier |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/types.h> |
| .B #include <sys/ipc.h> |
| .B #include <sys/msg.h> |
| .PP |
| .BI "int msgget(key_t " key ", int " msgflg ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR msgget () |
| system call returns the System\ V message queue identifier associated |
| with the value of the |
| .I key |
| argument. |
| It may be used either to obtain the identifier of a previously created |
| message queue (when |
| .I msgflg |
| is zero and |
| .I key |
| does not have the value |
| .BR IPC_PRIVATE ), |
| or to create a new set. |
| .PP |
| 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 |
| .I key |
| exists, and |
| .B IPC_CREAT |
| is specified in |
| .IR msgflg . |
| .PP |
| If |
| .I msgflg |
| specifies both |
| .B IPC_CREAT |
| and |
| .B IPC_EXCL |
| and a message queue already exists for |
| .IR key , |
| then |
| .BR msgget () |
| fails with |
| .I errno |
| set to |
| .BR EEXIST . |
| (This is analogous to the effect of the combination |
| .B O_CREAT | O_EXCL |
| for |
| .BR open (2).) |
| .PP |
| Upon creation, the least significant bits of the argument |
| .I msgflg |
| define the permissions of the message queue. |
| These permission bits have the same format and semantics |
| as the permissions specified for the |
| .I mode |
| argument of |
| .BR open (2). |
| (The execute permissions are not used.) |
| .PP |
| If a new message queue is created, |
| then its associated data structure |
| .I msqid_ds |
| (see |
| .BR msgctl (2)) |
| is initialized as follows: |
| .IP |
| .I msg_perm.cuid |
| and |
| .I msg_perm.uid |
| are set to the effective user ID of the calling process. |
| .IP |
| .I msg_perm.cgid |
| and |
| .I msg_perm.gid |
| are set to the effective group ID of the calling process. |
| .IP |
| The least significant 9 bits of |
| .I msg_perm.mode |
| are set to the least significant 9 bits of |
| .IR msgflg . |
| .IP |
| .IR msg_qnum , |
| .IR msg_lspid , |
| .IR msg_lrpid , |
| .IR msg_stime , |
| and |
| .I msg_rtime |
| are set to 0. |
| .IP |
| .I msg_ctime |
| is set to the current time. |
| .IP |
| .I msg_qbytes |
| is set to the system limit |
| .BR MSGMNB . |
| .PP |
| If the message queue already exists the permissions are |
| 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 |
| nonnegative integer), otherwise \-1 |
| with |
| .I errno |
| indicating the error. |
| .SH ERRORS |
| On failure, |
| .I errno |
| is set to one of the following values: |
| .TP |
| .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 |
| .B CAP_IPC_OWNER |
| capability in the user namespace that governs its IPC namespace. |
| .TP |
| .B EEXIST |
| .B IPC_CREAT |
| and |
| .BR IPC_EXCL |
| were specified in |
| .IR msgflg , |
| but a message queue already exists for |
| .IR key . |
| .TP |
| .B ENOENT |
| No message queue exists for |
| .I key |
| and |
| .I msgflg |
| did not specify |
| .BR IPC_CREAT . |
| .TP |
| .B ENOMEM |
| A message queue has to be created but the system does not have enough |
| memory for the new data structure. |
| .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. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SVr4. |
| .SH NOTES |
| The inclusion of |
| .I <sys/types.h> |
| and |
| .I <sys/ipc.h> |
| isn't required on Linux or by any version of POSIX. |
| However, |
| some old implementations required the inclusion of these header files, |
| and the SVID also documented their inclusion. |
| Applications intended to be portable to such old systems may need |
| to include these header files. |
| .\" Like Linux, the FreeBSD man pages still document |
| .\" the inclusion of these header files. |
| .PP |
| .B IPC_PRIVATE |
| isn't a flag field but a |
| .I key_t |
| type. |
| If this special value is used for |
| .IR key , |
| the system call ignores everything but the least significant 9 bits of |
| .I msgflg |
| and creates a new message queue (on success). |
| .PP |
| The following is a system limit on message queue resources affecting a |
| .BR msgget () |
| call: |
| .TP |
| .B MSGMNI |
| System-wide limit on the number of message queues. |
| Before Linux 3.19, |
| .\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 |
| the default value for this limit was calculated using a formula |
| based on available system memory. |
| Since Linux 3.19, the default value is 32,000. |
| On Linux, this limit can be read and modified via |
| .IR /proc/sys/kernel/msgmni . |
| .SS Linux notes |
| Until version 2.3.20, Linux would return |
| .B EIDRM |
| for a |
| .BR msgget () |
| on a message queue scheduled for deletion. |
| .SH BUGS |
| The name choice |
| .B IPC_PRIVATE |
| was perhaps unfortunate, |
| .B IPC_NEW |
| would more clearly show its function. |
| .SH SEE ALSO |
| .BR msgctl (2), |
| .BR msgrcv (2), |
| .BR msgsnd (2), |
| .BR ftok (3), |
| .BR capabilities (7), |
| .BR mq_overview (7), |
| .BR sysvipc (7) |