lib/libc/gen/msgget.3

   1 .\"     $NetBSD: msgget.2,v 1.1 1995/10/16 23:49:19 jtc Exp $
   2 .\"
   3 .\" Copyright (c) 1995 Frank van der Linden
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed for the NetBSD Project
  17 .\"      by Frank van der Linden
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\" $FreeBSD$
  32 .\"
  33 .\"/
  34 .Dd August 17, 1995
  35 .Dt MSGGET 3
  36 .Os FreeBSD
  37 .Sh NAME
  38 .Nm msgget
  39 .Nd get message queue
  40 .Sh SYNOPSIS
  41 .Fd #include <sys/types.h>
  42 .Fd #include <sys/ipc.h>
  43 .Fd #include <sys/msg.h>
  44 .Ft int
  45 .Fn msgget "key_t key" "int msgflg"
  46 .Sh DESCRIPTION
  47 .Fn msgget
  48 returns the message queue identifier associated with
  49 .Fa key .
  50 A message queue identifier is a unique integer greater than zero.
  51 .Pp
  52 A message queue is created if either
  53 .Fa key
  54 is equal to
  55 .Dv IPC_PRIVATE ,
  56 or
  57 .Fa key
  58 does not have a message queue identifier associated with it, and the
  59 .Dv IPC_CREAT
  60 bit is set in
  61 .Fa msgflg.
  62 .Pp
  63 If a new message queue is created, the data structure associated with it (the
  64 .Va msqid_ds
  65 structure, see
  66 .Xr msgctl 3 )
  67 is initialized as follows:
  68 .Bl -bullet
  69 .It
  70 .Va msg_perm.cuid
  71 and
  72 .Va msg_perm.uid
  73 are set to the effective uid of the calling process.
  74 .It
  75 .Va msg_perm.gid
  76 and
  77 .Va msg_perm.cgid
  78 are set to the effective gid of the calling process.
  79 .It
  80 .Va msg_perm.mode
  81 is set to the lower 9 bits of
  82 .Fa msgflg .
  83 .It
  84 .Va msg_cbytes ,
  85 .Va msg_qnum ,
  86 .Va msg_lspid ,
  87 .Va msg_lrpid ,
  88 .Va msg_rtime ,
  89 and
  90 .Va msg_stime
  91 are set to 0.
  92 .It
  93 .Va msg_qbytes
  94 is set to the system wide maximum value for the number of bytes in a queue
  95 .Pf ( Dv MSGMNB ) .
  96 .It
  97 .Va msg_ctime
  98 is set to the current time.
  99 .El
 100 .Sh RETURN VALUES
 101 Upon successful completion a positive message queue identifier is returned.
 102 Otherwise, -1 is returned and the global variable
 103 .Va errno
 104 is set to indicate the error.
 105 .Sh ERRORS
 106 .Bl -tag -width Er
 107 .It Bq Er EACCES
 108 A message queue is already associated with
 109 .Fa key
 110 and the caller has no permission to access it.
 111 .It Bq Er EEXIST
 112 Both
 113 .Dv IPC_CREAT
 114 and
 115 .Dv IPC_EXCL
 116 are set in
 117 .Fa msgflg ,
 118 and a message queue is already associated with
 119 .Fa key .
 120 .It Bq Er ENOSPC
 121 A new message queue could not be created because the system limit for
 122 the number of message queues has been reached.
 123 .It Bq Er ENOENT
 124 .Dv IPC_CREAT
 125 was not set in
 126 .Fa msgflg
 127 and no message queue associated with
 128 .Fa key
 129 was found.
 130 .El
 131 .Sh SEE ALSO
 132 .Xr msgctl 3 ,
 133 .Xr msgrcv 3 ,
 134 .Xr msgsnd 3
 135 .Sh HISTORY
 136 Message queues appeared in the first release of
 137 .At V .