/** @file ../include/sys/shm.h
@internalComponent
*/
/** @fn shmget(key_t key, int size, int shmflg)
@param key
@param size
@param shmflg
@return Upon successful completion, shmget returns the positive integer identifier of a shared memory segment.
Otherwise, -1 is returned and errno set to indicate the error.
@code
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.
@endcode
Based on the values of key and shmflg, shmget returns the identifier of a newly created or previously existing shared
memory segment. The key
is analogous to a filename: it provides a handle that names an
IPC object.
There are three ways to specify a key: IPC_PRIVATE may be specified, in which case a new IPC object
will be created. An integer constant may be specified.
If no IPC object corresponding
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.
@code
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.
@endcode
When creating a new shared memory segment, size indicates the desired size of the new segment in bytes.
The size
of the segment may be rounded up to a multiple convenient to the
kernel (i.e., the page size).
Examples:
@code
#include <sys/ipc.h>
#include <sys/shm.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#define SHM_SEG_SIZE 1024
int main(void)
{
int shm_id;
int perm;
/*
* Create a shared memory segment
*/
perm = SHM_R | SHM_W;
if ((shm_id = shmget(IPC_PRIVATE, SHM_SEG_SIZE,
IPC_CREAT | IPC_EXCL | perm))
== -1) {
printf("Shared memory create failed with errno %d", errno);
return -1;
}
return 0;
}
@endcode
@publishedAll
@externallyDefinedApi
*/
/** @fn shmat(int shmid, const void *shmaddr, int shmflg)
@param shmid
@param shmaddr
@param shmflg
Note: This description also covers the following functions -
shmdt()
@return Upon success, shmat returns the address where the segment is attached; otherwise, -1
is returned and errno is set to indicate the error. The shmdt function returns the value 0 if successful; otherwise the
value -1 is returned and errno is set to indicate the error.
The shmat system call
attaches the shared memory segment identified by shmid to the calling process's address space.
The address where the segment
is attached is determined as follows: If shmaddr is 0, the segment is attached at an address selected by the
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)
The shmdt system call
detaches the shared memory segment at the address specified by shmaddr from the calling process's address space.
Examples:
@code
#include <sys/ipc.h>
#include <sys/shm.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#define SHM_SEG_SIZE 1024
int main(void)
{
int shm_id;
char *shm_addr;
/*
* Create a shared memory segment
*/
if ((shm_id = shmget(IPC_PRIVATE, SHM_SEG_SIZE,
IPC_CREAT | IPC_EXCL | 0666))
== -1) {
printf("Shared memory create failed with errno %d", errno);
return -1;
}
/*
* Attach the shared memory segment to the
* process address space
*/
if((shm_addr = (char *)shmat(shm_id, NULL, 0)) == (void *)-1) {
printf("Shared memory attach failed with errno %d", errno);
return -1;
}
/*
* Copy data to shared memory segment
*/
strcpy(shm_addr, "some_random_data");
/*
* Detach the shared memory segment
*/
if(shmdt(shm_addr) == -1) {
printf("Shared memory detach failed with errno %d", errno);
}
/*
* Remove the shared memory segment
*/
if(shmctl(shm_id, IPC_RMID, NULL) == -1) {
printf("Shared memory destroy failed with errno %d", errno);
}
return 0;
}
@endcode
@publishedAll
@externallyDefinedApi
*/
/** @fn shmdt(const void *shmaddr)
@param shmaddr
Refer to shmat() for the documentation
@publishedAll
@externallyDefinedApi
*/
/** @fn shmctl(int shmid, int cmd, struct shmid_ds *buf)
@param shmid
@param cmd
@param buf
@return The shmctl function returns the value 0 if successful; otherwise the
value -1 is returned and errno is set to indicate the error.
@code
IPC_STAT Fetch the segment's struct shmid_ds ,
storing it in the memory pointed to by buf.
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.
IPC_RMID Removes the segment from the system.
The removal will not take
effect until all processes having attached the segment have exited;
however, once the IPC_RMID operation has taken place, no further
processes will be allowed to attach the segment.
@endcode
Performs the action specified by cmd on the shared memory segment identified by shmid:
IPC_STAT Fetch the segment's struct shmid_ds ,
storing it in the memory pointed to by buf.
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.
IPC_RMID Removes the segment from the system.
The removal will not take
effect until all processes having attached the segment have exited;
however, once the IPC_RMID operation has taken place, no further
processes will be allowed to attach the segment.
The shmid_ds
structure is defined as follows:
@code
struct shmid_ds {
struct ipc_perm shm_perm; /* operation permission structure */
int shm_segsz; /* size of segment in bytes */
pid_t shm_lpid; /* process ID of last shared memory op */
pid_t shm_cpid; /* process ID of creator */
short shm_nattch; /* number of current attaches */
time_t shm_atime; /* time of last shmat() */
time_t shm_dtime; /* time of last shmdt() */
time_t shm_ctime; /* time of last change by shmctl() */
void *shm_internal; /* sysv stupidity */
};
@endcode
Examples:
@code
#include <sys/ipc.h>
#include <sys/shm.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#define SHM_SEG_SIZE 1024
int main(void)
{
int shm_id;
char *shm_addr;
/*
* Create a shared memory segment
*/
if ((shm_id = shmget(IPC_PRIVATE, SHM_SEG_SIZE,
IPC_CREAT | IPC_EXCL | 0666))
== -1) {
printf("Shared memory create failed with errno %d", errno);
return -1;
}
/*
* Attach the shared memory segment to the
* process address space
*/
if((shm_addr = (char *)shmat(shm_id, NULL, 0)) == (void *)-1) {
printf("Shared memory attach failed with errno %d", errno);
return -1;
}
/*
* Copy data to shared memory segment
*/
strcpy(shm_addr, "some_random_data");
/*
* Detach the shared memory segment
*/
if(shmdt(shm_addr) == -1) {
printf("Shared memory detach failed with errno %d", errno);
}
/*
* Remove the shared memory segment
*/
if(shmctl(shm_id, IPC_RMID, NULL) == -1) {
printf("Shared memory destroy failed with errno %d", errno);
}
return 0;
}
@endcode
@publishedAll
@externallyDefinedApi
*/
/** @struct shmid_ds
Defines a shared memory region
@publishedAll
@externallyDefinedApi
*/
/** @var shmid_ds::shm_perm
inode's device
*/
/** @var shmid_ds::shm_segsz
size of segment in bytes
*/
/** @var shmid_ds::shm_lpid
process ID of last shared memory op
*/
/** @var shmid_ds::shm_cpid
process ID of creator
*/
/** @var shmid_ds::shm_nattch
number of current attaches
*/
/** @var shmid_ds::shm_atime
time of last shmat()
*/
/** @var shmid_ds::shm_dtime
time of last shmdt()
*/
/** @var shmid_ds::shm_ctime
time of last change by shmctl()
*/
/** @var shmid_ds::shm_internal
sysv stupidity
*/
/** @def SHM_RDONLY
Attach read-only (else read-write)
@publishedAll
@externallyDefinedApi
*/
/** @def SHM_RND
Round attach address to SHMLBA
@publishedAll
@externallyDefinedApi
*/
/** @def SHMLBA
Segment low boundary address multiple
@publishedAll
@externallyDefinedApi
*/