man3p/shmat.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "SHMAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" shmat
   4 .SH NAME
   5 shmat \- XSI shared memory attach operation
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <sys/shm.h>
   9 .br
  10 .sp
  11 void *shmat(int\fP \fIshmid\fP\fB, const void *\fP\fIshmaddr\fP\fB,
  12 int\fP \fIshmflg\fP\fB); \fP
  13 \fB
  14 .br
  15 \fP
  16 .SH DESCRIPTION
  17 .LP
  18 The \fIshmat\fP() function operates on XSI shared memory (see the
  19 Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.340,
  20 Shared Memory Object). It is unspecified whether this function
  21 interoperates with the realtime interprocess communication facilities
  22 defined in \fIRealtime\fP .
  23 .LP
  24 The \fIshmat\fP() function attaches the shared memory segment associated
  25 with the shared memory identifier specified by
  26 \fIshmid\fP to the address space of the calling process. The segment
  27 is attached at the address specified by one of the following
  28 criteria:
  29 .IP " *" 3
  30 If \fIshmaddr\fP is a null pointer, the segment is attached at the
  31 first available address as selected by the system.
  32 .LP
  33 .IP " *" 3
  34 If \fIshmaddr\fP is not a null pointer and (\fIshmflg\fP &SHM_RND)
  35 is non-zero, the segment is attached at the address
  36 given by (\fIshmaddr\fP -((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)).
  37 The character \fB'%'\fP is the C-language remainder
  38 operator.
  39 .LP
  40 .IP " *" 3
  41 If \fIshmaddr\fP is not a null pointer and (\fIshmflg\fP &SHM_RND)
  42 is 0, the segment is attached at the address given by
  43 \fIshmaddr\fP.
  44 .LP
  45 .IP " *" 3
  46 The segment is attached for reading if (\fIshmflg\fP &SHM_RDONLY)
  47 is non-zero and the calling process has read permission;
  48 otherwise, if it is 0 and the calling process has read and write permission,
  49 the segment is attached for reading and writing.
  50 .LP
  51 .SH RETURN VALUE
  52 .LP
  53 Upon successful completion, \fIshmat\fP() shall increment the value
  54 of \fIshm_nattch\fP in the data structure associated with
  55 the shared memory ID of the attached shared memory segment and return
  56 the segment's start address.
  57 .LP
  58 Otherwise, the shared memory segment shall not be attached, \fIshmat\fP()
  59 shall return -1, and \fIerrno\fP shall be set to
  60 indicate the error.
  61 .SH ERRORS
  62 .LP
  63 The \fIshmat\fP() function shall fail if:
  64 .TP 7
  65 .B EACCES
  66 Operation permission is denied to the calling process; see \fIXSI
  67 Interprocess
  68 Communication\fP .
  69 .TP 7
  70 .B EINVAL
  71 The value of \fIshmid\fP is not a valid shared memory identifier,
  72 the \fIshmaddr\fP is not a null pointer, and the value of
  73 (\fIshmaddr\fP -((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)) is an illegal
  74 address for attaching shared memory; or the
  75 \fIshmaddr\fP is not a null pointer, (\fIshmflg\fP &SHM_RND) is 0,
  76 and the value of \fIshmaddr\fP is an illegal address for
  77 attaching shared memory.
  78 .TP 7
  79 .B EMFILE
  80 The number of shared memory segments attached to the calling process
  81 would exceed the system-imposed limit.
  82 .TP 7
  83 .B ENOMEM
  84 The available data space is not large enough to accommodate the shared
  85 memory segment.
  86 .sp
  87 .LP
  88 \fIThe following sections are informative.\fP
  89 .SH EXAMPLES
  90 .LP
  91 None.
  92 .SH APPLICATION USAGE
  93 .LP
  94 The POSIX Realtime Extension defines alternative interfaces for interprocess
  95 communication. Application developers who need to
  96 use IPC should design their applications so that modules using the
  97 IPC routines described in \fIXSI Interprocess Communication\fP can
  98 be easily modified to use the alternative
  99 interfaces.
 100 .SH RATIONALE
 101 .LP
 102 None.
 103 .SH FUTURE DIRECTIONS
 104 .LP
 105 None.
 106 .SH SEE ALSO
 107 .LP
 108 \fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIexec\fP()
 109 ,
 110 \fIexit\fP() , \fIfork\fP() , \fIshmctl\fP() , \fIshmdt\fP() , \fIshmget\fP()
 111 , \fIshm_open\fP() ,
 112 \fIshm_unlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
 113 \fI<sys/shm.h>\fP
 114 .SH COPYRIGHT
 115 Portions of this text are reprinted and reproduced in electronic form
 116 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 117 -- Portable Operating System Interface (POSIX), The Open Group Base
 118 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 119 Electrical and Electronics Engineers, Inc and The Open Group. In the
 120 event of any discrepancy between this version and the original IEEE and
 121 The Open Group Standard, the original IEEE and The Open Group Standard
 122 is the referee document. The original Standard can be obtained online at
 123 http://www.opengroup.org/unix/online.html .