lib/libc/sys/shmat.2

   1 .\"     $NetBSD: shmat.2,v 1.18 2010/03/22 19:30:55 joerg 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 June 17, 2002
  33 .Dt SHMAT 2
  34 .Os
  35 .Sh NAME
  36 .Nm shmat ,
  37 .Nm shmdt
  38 .Nd map/unmap shared memory
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/shm.h
  43 .Ft void *
  44 .Fn shmat "int shmid" "const void *shmaddr" "int shmflg"
  45 .Ft int
  46 .Fn shmdt "const void *shmaddr"
  47 .Sh DESCRIPTION
  48 .Fn shmat
  49 maps the shared memory segment associated with the shared memory identifier
  50 .Fa shmid
  51 into the address space of the calling process.
  52 The address at which the segment is mapped is determined by the
  53 .Fa shmaddr
  54 parameter.
  55 If it is equal to 0, the system will pick an address itself.
  56 Otherwise, an attempt is made to map the shared memory segment at the
  57 address
  58 .Fa shmaddr
  59 specifies.
  60 If
  61 .Dv SHM_RND
  62 is set in
  63 .Fa shmflg ,
  64 the system will round the address down to a multiple of
  65 .Dv SHMLBA
  66 bytes
  67 .Pf ( Dv SHMLBA
  68 is defined in
  69 .In sys/shm.h ) .
  70 .Pp
  71 A shared memory segment can be mapped read-only by specifying the
  72 .Dv SHM_RDONLY
  73 flag in
  74 .Fa shmflg .
  75 .Pp
  76 .Fn shmdt
  77 unmaps the shared memory segment that is currently mapped at
  78 .Fa shmaddr
  79 from the calling process' address space.
  80 .Fa shmaddr
  81 must be a value returned by a prior
  82 .Fn shmat
  83 call.
  84 A shared memory segment will remain in existence until it is
  85 removed by a call to
  86 .Xr shmctl 2
  87 with the
  88 .Dv IPC_RMID
  89 command.
  90 .Sh RETURN VALUES
  91 .Fn shmat
  92 returns the address at which the shared memory segment has been mapped into
  93 the calling process' address space when successful,
  94 .Fn shmdt
  95 returns 0 on successful completion.
  96 Otherwise, a value of \-1 is returned, and the global variable
  97 .Va errno
  98 is set to indicate the error.
  99 .Sh ERRORS
 100 .Fn shmat
 101 will fail if:
 102 .Bl -tag -width Er
 103 .It Bq Er EACCES
 104 The calling process has no permission to access this shared memory segment.
 105 .It Bq Er ENOMEM
 106 There is not enough available data space for the calling process to
 107 map the shared memory segment.
 108 .It Bq Er EINVAL
 109 .Fa shmid
 110 is not a valid shared memory identifier.
 111 .Pp
 112 .Fa shmaddr
 113 specifies an illegal address.
 114 .It Bq Er EMFILE
 115 The number of shared memory segments has reached the system-wide limit.
 116 .El
 117 .Pp
 118 .Fn shmdt
 119 will fail if:
 120 .Bl -tag -width Er
 121 .It Bq Er EINVAL
 122 .Fa shmaddr
 123 is not the start address of a mapped shared memory segment.
 124 .El
 125 .Sh SEE ALSO
 126 .Xr ipcrm 1 ,
 127 .Xr ipcs 1 ,
 128 .Xr mmap 2 ,
 129 .Xr shmctl 2 ,
 130 .Xr shmget 2
 131 .Sh STANDARDS
 132 The
 133 .Nm shmat
 134 and
 135 .Nm shmdt
 136 system calls conform to
 137 .St -xsh5 .
 138 .Sh HISTORY
 139 Shared memory segments appeared in the first release of
 140 .At V .