/** @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

*/