1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/sys/shm.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,341 @@
1.4 +/** @file ../include/sys/shm.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +/** @fn shmget(key_t key, int size, int shmflg)
1.9 +@param key
1.10 +@param size
1.11 +@param shmflg
1.12 +@return Upon successful completion, shmget returns the positive integer identifier of a shared memory segment.
1.13 +Otherwise, -1 is returned and errno set to indicate the error.
1.14 +
1.15 +@code
1.16 + SHM_R Read access for user.
1.17 + SHM_W Write access for user.
1.18 + ( SHM_R>>3 )
1.19 + Read access for group.
1.20 + ( SHM_W>>3 )
1.21 + Write access for group.
1.22 + ( SHM_R>>6 )
1.23 + Read access for other.
1.24 + ( SHM_W>>6 )
1.25 + Write access for other.
1.26 +
1.27 +@endcode
1.28 + Based on the values of key and shmflg, shmget returns the identifier of a newly created or previously existing shared
1.29 +memory segment. The key
1.30 +is analogous to a filename: it provides a handle that names an
1.31 +IPC object.
1.32 +There are three ways to specify a key: IPC_PRIVATE may be specified, in which case a new IPC object
1.33 +will be created. An integer constant may be specified.
1.34 +If no IPC object corresponding
1.35 +to key is specified and the IPC_CREAT bit is set in shmflg, a new one will be created. The ftok may be used to generate a key from a pathname.
1.36 +
1.37 +@code
1.38 +
1.39 + The mode of a newly created IPC object is determined by OR 'ing the following constants into the shmflg argument: SHM_R Read access for user. SHM_W Write access for user. ( SHM_R>>3 ) Read access for group. ( SHM_W>>3 ) Write access for group. ( SHM_R>>6 ) Read access for other. ( SHM_W>>6 ) Write access for other.
1.40 +
1.41 +@endcode
1.42 +
1.43 + When creating a new shared memory segment, size indicates the desired size of the new segment in bytes.
1.44 +The size
1.45 +of the segment may be rounded up to a multiple convenient to the
1.46 +kernel (i.e., the page size).
1.47 +
1.48 +Examples:
1.49 +@code
1.50 +#include <sys/ipc.h>
1.51 +#include <sys/shm.h>
1.52 +#include <stdio.h>
1.53 +#include <string.h>
1.54 +#include <errno.h>
1.55 +
1.56 +#define SHM_SEG_SIZE 1024
1.57 +
1.58 +int main(void)
1.59 +{
1.60 + int shm_id;
1.61 + int perm;
1.62 + /*
1.63 + * Create a shared memory segment
1.64 + */
1.65 + perm = SHM_R | SHM_W;
1.66 + if ((shm_id = shmget(IPC_PRIVATE, SHM_SEG_SIZE,
1.67 + IPC_CREAT | IPC_EXCL | perm))
1.68 + == -1) {
1.69 + printf("Shared memory create failed with errno %d", errno);
1.70 + return -1;
1.71 + }
1.72 + return 0;
1.73 +}
1.74 +
1.75 +@endcode
1.76 +
1.77 +
1.78 +@publishedAll
1.79 +@externallyDefinedApi
1.80 +*/
1.81 +
1.82 +/** @fn shmat(int shmid, const void *shmaddr, int shmflg)
1.83 +@param shmid
1.84 +@param shmaddr
1.85 +@param shmflg
1.86 +Note: This description also covers the following functions -
1.87 + shmdt()
1.88 +
1.89 +@return Upon success, shmat returns the address where the segment is attached; otherwise, -1
1.90 +is returned and errno is set to indicate the error. The shmdt function returns the value 0 if successful; otherwise the
1.91 +value -1 is returned and errno is set to indicate the error.
1.92 +
1.93 + The shmat system call
1.94 +attaches the shared memory segment identified by shmid to the calling process's address space.
1.95 +The address where the segment
1.96 +is attached is determined as follows: If shmaddr is 0, the segment is attached at an address selected by the
1.97 +kernel. If shmaddr is nonzero and SHM_RND is not specified in shmflg, the segment is attached the specified address. (a nonzero addr is not supported) If addr is specified and SHM_RND is specified, addr is rounded down to the nearest multiple of SHMLBA.(a nonzero addr is not supported)
1.98 +
1.99 + The shmdt system call
1.100 +detaches the shared memory segment at the address specified by shmaddr from the calling process's address space.
1.101 +
1.102 +Examples:
1.103 +@code
1.104 +#include <sys/ipc.h>
1.105 +#include <sys/shm.h>
1.106 +#include <stdio.h>
1.107 +#include <string.h>
1.108 +#include <errno.h>
1.109 +
1.110 +#define SHM_SEG_SIZE 1024
1.111 +
1.112 +int main(void)
1.113 +{
1.114 + int shm_id;
1.115 + char *shm_addr;
1.116 + /*
1.117 + * Create a shared memory segment
1.118 + */
1.119 + if ((shm_id = shmget(IPC_PRIVATE, SHM_SEG_SIZE,
1.120 + IPC_CREAT | IPC_EXCL | 0666))
1.121 + == -1) {
1.122 + printf("Shared memory create failed with errno %d", errno);
1.123 + return -1;
1.124 + }
1.125 + /*
1.126 + * Attach the shared memory segment to the
1.127 + * process address space
1.128 + */
1.129 + if((shm_addr = (char *)shmat(shm_id, NULL, 0)) == (void *)-1) {
1.130 + printf("Shared memory attach failed with errno %d", errno);
1.131 + return -1;
1.132 + }
1.133 + /*
1.134 + * Copy data to shared memory segment
1.135 + */
1.136 + strcpy(shm_addr, "some_random_data");
1.137 + /*
1.138 + * Detach the shared memory segment
1.139 + */
1.140 + if(shmdt(shm_addr) == -1) {
1.141 + printf("Shared memory detach failed with errno %d", errno);
1.142 + }
1.143 + /*
1.144 + * Remove the shared memory segment
1.145 + */
1.146 + if(shmctl(shm_id, IPC_RMID, NULL) == -1) {
1.147 + printf("Shared memory destroy failed with errno %d", errno);
1.148 + }
1.149 + return 0;
1.150 +}
1.151 +
1.152 +@endcode
1.153 +
1.154 +
1.155 +@publishedAll
1.156 +@externallyDefinedApi
1.157 +*/
1.158 +
1.159 +/** @fn shmdt(const void *shmaddr)
1.160 +@param shmaddr
1.161 +Refer to shmat() for the documentation
1.162 +
1.163 +
1.164 +
1.165 +
1.166 +@publishedAll
1.167 +@externallyDefinedApi
1.168 +*/
1.169 +
1.170 +
1.171 +/** @fn shmctl(int shmid, int cmd, struct shmid_ds *buf)
1.172 +@param shmid
1.173 +@param cmd
1.174 +@param buf
1.175 +@return The shmctl function returns the value 0 if successful; otherwise the
1.176 +value -1 is returned and errno is set to indicate the error.
1.177 +
1.178 +@code
1.179 + IPC_STAT Fetch the segment's struct shmid_ds ,
1.180 + storing it in the memory pointed to by buf.
1.181 + IPC_SET Changes the shm_perm.uid, shm_perm.gid, and shm_perm.mode members of the segment's struct shmid_ds to match those of the struct pointed to by buf.
1.182 + IPC_RMID Removes the segment from the system.
1.183 + The removal will not take
1.184 + effect until all processes having attached the segment have exited;
1.185 + however, once the IPC_RMID operation has taken place, no further
1.186 + processes will be allowed to attach the segment.
1.187 +
1.188 +@endcode
1.189 +
1.190 +Performs the action specified by cmd on the shared memory segment identified by shmid:
1.191 +
1.192 + IPC_STAT Fetch the segment's struct shmid_ds ,
1.193 +storing it in the memory pointed to by buf.
1.194 +IPC_SET Changes the shm_perm.uid, shm_perm.gid, and shm_perm.mode members of the segment's struct shmid_ds to match those of the struct pointed to by buf.
1.195 +IPC_RMID Removes the segment from the system.
1.196 +
1.197 +The removal will not take
1.198 +effect until all processes having attached the segment have exited;
1.199 +however, once the IPC_RMID operation has taken place, no further
1.200 +processes will be allowed to attach the segment.
1.201 +
1.202 + The shmid_ds
1.203 +structure is defined as follows:
1.204 +@code
1.205 +struct shmid_ds {
1.206 + struct ipc_perm shm_perm; /* operation permission structure */
1.207 + int shm_segsz; /* size of segment in bytes */
1.208 + pid_t shm_lpid; /* process ID of last shared memory op */
1.209 + pid_t shm_cpid; /* process ID of creator */
1.210 + short shm_nattch; /* number of current attaches */
1.211 + time_t shm_atime; /* time of last shmat() */
1.212 + time_t shm_dtime; /* time of last shmdt() */
1.213 + time_t shm_ctime; /* time of last change by shmctl() */
1.214 + void *shm_internal; /* sysv stupidity */
1.215 +};
1.216 +@endcode
1.217 +
1.218 +Examples:
1.219 +@code
1.220 +#include <sys/ipc.h>
1.221 +#include <sys/shm.h>
1.222 +#include <stdio.h>
1.223 +#include <string.h>
1.224 +#include <errno.h>
1.225 +
1.226 +#define SHM_SEG_SIZE 1024
1.227 +
1.228 +int main(void)
1.229 +{
1.230 + int shm_id;
1.231 + char *shm_addr;
1.232 + /*
1.233 + * Create a shared memory segment
1.234 + */
1.235 + if ((shm_id = shmget(IPC_PRIVATE, SHM_SEG_SIZE,
1.236 + IPC_CREAT | IPC_EXCL | 0666))
1.237 + == -1) {
1.238 + printf("Shared memory create failed with errno %d", errno);
1.239 + return -1;
1.240 + }
1.241 + /*
1.242 + * Attach the shared memory segment to the
1.243 + * process address space
1.244 + */
1.245 + if((shm_addr = (char *)shmat(shm_id, NULL, 0)) == (void *)-1) {
1.246 + printf("Shared memory attach failed with errno %d", errno);
1.247 + return -1;
1.248 + }
1.249 + /*
1.250 + * Copy data to shared memory segment
1.251 + */
1.252 + strcpy(shm_addr, "some_random_data");
1.253 + /*
1.254 + * Detach the shared memory segment
1.255 + */
1.256 + if(shmdt(shm_addr) == -1) {
1.257 + printf("Shared memory detach failed with errno %d", errno);
1.258 + }
1.259 + /*
1.260 + * Remove the shared memory segment
1.261 + */
1.262 + if(shmctl(shm_id, IPC_RMID, NULL) == -1) {
1.263 + printf("Shared memory destroy failed with errno %d", errno);
1.264 + }
1.265 + return 0;
1.266 +}
1.267 +
1.268 +@endcode
1.269 +
1.270 +
1.271 +@publishedAll
1.272 +@externallyDefinedApi
1.273 +*/
1.274 +
1.275 +
1.276 +/** @struct shmid_ds
1.277 +
1.278 +Defines a shared memory region
1.279 +
1.280 +@publishedAll
1.281 +@externallyDefinedApi
1.282 +*/
1.283 +
1.284 +/** @var shmid_ds::shm_perm
1.285 +inode's device
1.286 +*/
1.287 +
1.288 +/** @var shmid_ds::shm_segsz
1.289 +size of segment in bytes
1.290 +*/
1.291 +
1.292 +/** @var shmid_ds::shm_lpid
1.293 +process ID of last shared memory op
1.294 +*/
1.295 +
1.296 +/** @var shmid_ds::shm_cpid
1.297 +process ID of creator
1.298 +*/
1.299 +
1.300 +/** @var shmid_ds::shm_nattch
1.301 +number of current attaches
1.302 +*/
1.303 +
1.304 +/** @var shmid_ds::shm_atime
1.305 +time of last shmat()
1.306 +*/
1.307 +
1.308 +/** @var shmid_ds::shm_dtime
1.309 +time of last shmdt()
1.310 +*/
1.311 +
1.312 +/** @var shmid_ds::shm_ctime
1.313 +time of last change by shmctl()
1.314 +*/
1.315 +
1.316 +/** @var shmid_ds::shm_internal
1.317 +sysv stupidity
1.318 +*/
1.319 +
1.320 +/** @def SHM_RDONLY
1.321 +
1.322 +Attach read-only (else read-write)
1.323 +
1.324 +@publishedAll
1.325 +@externallyDefinedApi
1.326 +*/
1.327 +
1.328 +/** @def SHM_RND
1.329 +
1.330 +Round attach address to SHMLBA
1.331 +
1.332 +@publishedAll
1.333 +@externallyDefinedApi
1.334 +*/
1.335 +
1.336 +/** @def SHMLBA
1.337 +
1.338 +Segment low boundary address multiple
1.339 +
1.340 +@publishedAll
1.341 +@externallyDefinedApi
1.342 +*/
1.343 +
1.344 +