lib/libc/sys/shmget.2

   1 .\"     $NetBSD: shmget.2,v 1.22 2008/10/27 16:49:10 wiz 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 .\"
  32 .Dd October 27, 2008
  33 .Dt SHMGET 2
  34 .Os
  35 .Sh NAME
  36 .Nm shmget
  37 .Nd get shared memory segment
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/shm.h
  42 .Ft int
  43 .Fn shmget "key_t key" "size_t size" "int shmflg"
  44 .Sh DESCRIPTION
  45 .Fn shmget
  46 returns the shared memory identifier associated with the key
  47 .Fa key .
  48 .Pp
  49 A shared memory segment is created if either
  50 .Fa key
  51 is equal to
  52 .Dv IPC_PRIVATE ,
  53 or
  54 .Fa key
  55 does not have a shared memory segment identifier associated with it, and the
  56 .Dv IPC_CREAT
  57 bit is set in
  58 .Fa shmflg .
  59 If both the
  60 .Dv IPC_CREAT
  61 bit and the
  62 .Dv IPC_EXCL
  63 bit are set in
  64 .Fa shmflg ,
  65 and
  66 .Fa key
  67 has a shared memory segment identifier associated with it already,
  68 the operation will fail.
  69 .Pp
  70 If a new shared memory segment is created, the data structure
  71 associated with it (the
  72 .Va shmid_ds
  73 structure, see
  74 .Xr shmctl 2 )
  75 is initialized as follows:
  76 .Bl -bullet
  77 .It
  78 .Va shm_perm.cuid
  79 and
  80 .Va shm_perm.uid
  81 are set to the effective uid of the calling process.
  82 .It
  83 .Va shm_perm.gid
  84 and
  85 .Va shm_perm.cgid
  86 are set to the effective gid of the calling process.
  87 .It
  88 .Va shm_perm.mode
  89 is set to the lower 9 bits of
  90 .Fa shmflg .
  91 .It
  92 .Va shm_lpid ,
  93 .Va shm_nattch ,
  94 .Va shm_atime ,
  95 and
  96 .Va shm_dtime
  97 are set to 0.
  98 .It
  99 .Va shm_ctime
 100 is set to the current time.
 101 .It
 102 .Va shm_segsz
 103 is set to the value of
 104 .Fa size .
 105 .El
 106 .Sh RETURN VALUES
 107 Upon successful completion a positive shared memory segment identifier
 108 is returned.
 109 Otherwise, \-1 is returned and the global variable
 110 .Va errno
 111 is set to indicate the error.
 112 .Sh ERRORS
 113 .Bl -tag -width Er
 114 .It Bq Er EACCES
 115 A shared memory segment is already associated with
 116 .Fa key
 117 and the caller has no permission to access it.
 118 .It Bq Er EEXIST
 119 Both
 120 .Dv IPC_CREAT
 121 and
 122 .Dv IPC_EXCL
 123 are set in
 124 .Fa shmflg ,
 125 and a shared memory segment is already associated with
 126 .Fa key .
 127 .It Bq Er EINVAL
 128 No shared memory segment is to be created, and a shared memory segment
 129 exists for
 130 .Fa key ,
 131 but the size of the segment associated with it is less
 132 than
 133 .Fa size ,
 134 which is non-zero.
 135 .Pp
 136 A shared memory segment
 137 .Em is
 138 to be created, and
 139 .Fa size
 140 is less than the system imposed minimum, or greater than the system
 141 imposed maximum (refer to the
 142 .Li kern.ipc
 143 values in
 144 .Xr sysctl 7 ) .
 145 .It Bq Er ENOENT
 146 .Dv IPC_CREAT
 147 is not set in
 148 .Fa shmflg
 149 and no shared memory segment associated with
 150 .Fa key
 151 was found.
 152 .It Bq Er ENOMEM
 153 There is not enough memory left to create a shared memory segment of the
 154 requested size.
 155 .It Bq Er ENOSPC
 156 A new shared memory identifier could not be created because the system limit
 157 for the number of shared memory identifiers has been reached.
 158 .El
 159 .Sh SEE ALSO
 160 .Xr ipcrm 1 ,
 161 .Xr ipcs 1 ,
 162 .Xr mmap 2 ,
 163 .Xr shmat 2 ,
 164 .Xr shmctl 2 ,
 165 .Xr ftok 3 ,
 166 .Xr sysctl 7
 167 .Sh STANDARDS
 168 The
 169 .Nm
 170 system call conforms to
 171 .St -xsh5 .
 172 .Sh HISTORY
 173 Shared memory segments appeared in the first release of
 174 .At V .