bsd/man/man2/shmat.2

   1 .\"   $OpenBSD: shmat.2,v 1.2 1996/10/08 01:20:15 michaels Exp $
   2 .\"     $NetBSD: shmat.2,v 1.1 1995/10/16 23:49:29 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1995 Frank van der Linden
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"      This product includes software developed for the NetBSD Project
  18 .\"      by Frank van der Linden
  19 .\" 4. The name of the author may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"/
  33 .Dd August 17, 1995
  34 .Dt SHMAT 2
  35 .Os
  36 .Sh NAME
  37 .Nm shmat ,
  38 .Nm shmdt
  39 .Nd map/unmap shared memory
  40 .Sh SYNOPSIS
  41 .Fd #include <sys/shm.h>
  42 .Ft void *
  43 .Fo shmat
  44 .Fa "int shmid"
  45 .Fa "const void *shmaddr"
  46 .Fa "int shmflg"
  47 .Fc
  48 .Ft int
  49 .Fo shmdt
  50 .Fa "const void *shmaddr"
  51 .Fc
  52 .Sh DESCRIPTION
  53 .Fn shmat
  54 maps the shared memory segment associated with the shared memory identifier
  55 .Fa shmid
  56 into the address space of the calling process. The address at which the
  57 segment is mapped is determined by the
  58 .Fa shmaddr
  59 parameter. If it is equal to 0, the system will pick an address itself.
  60 Otherwise, an attempt is made to map the shared memory segment at the
  61 address
  62 .Fa shmaddr
  63 specifies. If SHM_RND is set in
  64 .Fa shmflg ,
  65 the system will round the address down to a multiple of SHMLBA bytes
  66 (SHMLBA is defined in
  67 .Aq Pa sys/shm.h
  68 ).
  69 A shared memory segment can be mapped read-only by specifying the
  70 SHM_RDONLY flag in
  71 .Fa shmflg .
  72 .Fn shmdt
  73 unmaps the shared memory segment that is currently mapped at
  74 .Fa shmaddr
  75 from the calling process' address space.
  76 .Fa shmaddr
  77 must be a value returned by a prior
  78 .Fn shmat
  79 call. A shared memory segment will remain existant until it is removed by
  80 a call to
  81 .Xr shmctl 2
  82 with the IPC_RMID command.
  83 .Sh RETURN VALUES
  84 .Fn shmat
  85 returns the address at which the shared memory segment has been mapped into
  86 the calling process' address space when successful,
  87 .Fn shmdt
  88 returns 0 on successful completion. Otherwise, a value of -1 is returned,
  89 and the global variable
  90 .Va errno
  91 is set to indicate the error.
  92 .Sh ERRORS
  93 The
  94 .Fn shmat
  95 system call will fail if:
  96 .Bl -tag -width Er
  97 .\" ===========
  98 .It Bq Er EACCES
  99 The calling process has no permission to access this shared memory segment.
 100 .\" ===========
 101 .It Bq Er EINVAL
 102 .Fa shmid
 103 is not a valid shared memory identifier.
 104 .Fa shmaddr
 105 specifies an illegal address.
 106 .\" ===========
 107 .It Bq Er EMFILE
 108 The number of shared memory segments has reached the system-wide limit.
 109 .\" ===========
 110 .It Bq Er ENOMEM
 111 There is not enough available data space for the calling process to
 112 map the shared memory segment.
 113 .Pp
 114 .El
 115 The
 116 .Fn shmdt
 117 system call will fail if:
 118 .Bl -tag -width Er
 119 .It Bq Er EINVAL
 120 .Fa shmaddr
 121 is not the start address of a mapped shared memory segment.
 122 .El
 123 .Sh LEGACY SYNOPSIS
 124 .Fd #include <sys/types.h>
 125 .Fd #include <sys/ipc.h>
 126 .Fd #include <sys/shm.h>
 127 .Pp
 128 The include files
 129 .In sys/types.h
 130 and
 131 .In sys/ipc.h
 132 are necessary for both functions.
 133 .Sh SEE ALSO
 134 .Xr mmap 2 ,
 135 .Xr shmctl 2 ,
 136 .Xr shmget 2 ,
 137 .Xr compat 5