sl@0: /** @file  ../include/sys/msg.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @fn  msgget(key_t key, int msgflg)
sl@0: @param key
sl@0: @param msgflg
sl@0: @return   Upon successful completion a positive message queue identifier is returned.
sl@0: Otherwise, -1 is returned and the global variable errno is set to indicate the error.
sl@0: 
sl@0:   The msgget function
sl@0: returns the message queue identifier associated with key. A message queue identifier is a unique integer greater than zero.
sl@0: 
sl@0:  A message queue is created if either key is equal to IPC_PRIVATE, or key does not have a message queue identifier associated with it and 
sl@0:   the IPC_CREAT bit is set in msgflg.
sl@0: 
sl@0:  If a new message queue is created, the data structure associated with it (the msqid_ds structure, see msgctl is initialized as follows: msg_perm.cuid and msg_perm.uid are set to the effective uid of the calling process.
sl@0: In the current implementation, uid is set to root. msg_perm.gid and msg_perm.cgid are set to the effective gid of the calling process.
sl@0: In the current implementation, gid is set to root. msg_perm.mode is set to the lower 9 bits of msgflg. msg_cbytes, msg_qnum, msg_lspid, msg_lrpid, msg_rtime, and msg_stime are set to 0. msg_qbytes is set to the system wide maximum value for the number of bytes in a queue (Dv MSGMNB). msg_ctime is set to the current time.
sl@0: 
sl@0: Examples:
sl@0: 
sl@0:  Example code to create a message queue using msgget
sl@0:  
sl@0: @code
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id, len;
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    /*
sl@0:     * Create a message queue with a given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, IPC_CREAT | IPC_EXCL | 0666)) == -1) {
sl@0:        printf("Message Q create failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:     }
sl@0:     msg_buf.mtype = 1; /* message identifier */
sl@0:     strcpy(msg_buf.mtext, "some_data_to_send"); /* data */
sl@0:     len = strlen(msg_buf.mtext)+1;
sl@0:     /*
sl@0:      * Put the message in the queue
sl@0:      */
sl@0:     if (msgsnd(msq_id, (struct msgbuf *)&msg;_buf, len, 0) == -1) {
sl@0:         printf("Message Q send failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Example code to return an existing message queue with msgget
sl@0: @code
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id;
sl@0:    int msg_len = 128;
sl@0:    int msg_type = 0; /* Any type of message */
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    /*
sl@0:     * Get the message queue id for the given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, 0)) == -1) {
sl@0:        printf("Message Q  get id failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:     }
sl@0:     /*
sl@0:      * Get the message from the queue
sl@0:      */
sl@0:     if (msgrcv(msq_id, (struct msgbuf *)&msg;_buf, msg_len, msg_type, 0) == -1) {
sl@0:         printf("Message Q recv failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     /*
sl@0:      * Remove the message queue
sl@0:      */
sl@0:      if (msgctl(msq_id, IPC_RMID, NULL) == -1) {
sl@0:        printf("Message Q  delete failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:      }
sl@0:      return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @see msgctl()
sl@0: @see msgrcv()
sl@0: @see msgsnd()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg)
sl@0: @param msqid
sl@0: @param msgp
sl@0: @param msgsz
sl@0: @param msgflg
sl@0: 
sl@0: @return   The msgsnd function returns the value 0 if successful; otherwise the
sl@0: value -1 is returned and errno is set to indicate the error.
sl@0: 
sl@0: The msgsnd function sends a message to the message queue specified in msqid. The msgp argument points to a structure containing the message. This structure should consist of the following members: 
sl@0: @code
sl@0: long mtype;    /* message type */
sl@0: char mtext[1]; /* body of message */
sl@0: @endcode
sl@0: 
sl@0: mtype is an integer greater than 0 that can be used for selecting messages (see msgrcv mtext is an array of bytes, with a size up to that of the system limit (Dv MSGMAX). 
sl@0: 
sl@0: If the number of bytes already on the message queue plus msgsz is bigger than the maximum number of bytes on the message queue (Va msg_qbytes, see msgctl or the number of messages on all queues system-wide is already equal to the system limit, msgflg determines the action of msgsnd. If msgflg has IPC_NOWAIT mask set in it, the call will return immediately. If msgflg does not have IPC_NOWAIT set in it, the call will block until: 
sl@0: 
sl@0: The condition which caused the call to block does no longer exist. The message will be sent. 
sl@0: The message queue is removed, in which case -1 will be returned, and errno is set to EINVAL. 
sl@0: After a successful call, the data structure associated with the message queue is updated in the following way: 
sl@0: 
sl@0: msg_cbytes is incremented by the size of the message. 
sl@0: msg_qnum is incremented by 1. 
sl@0: msg_lspid is set to the pid of the calling process. 
sl@0: msg_stime is set to the current time.   
sl@0:   
sl@0:   
sl@0: Examples:
sl@0: @code
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id, len;
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    /*
sl@0:     * Create a message queue with the given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, IPC_CREAT | IPC_EXCL | 0666)) == -1) {
sl@0:        printf("Message Q create failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:     }
sl@0:     msg_buf.mtype = 1; /* message identifier */
sl@0:     strcpy(msg_buf.mtext, "some_data_to_send"); /* data */
sl@0:     len = strlen(msg_buf.mtext)+1;
sl@0:     /*
sl@0:      * Put the message in the queue
sl@0:      */
sl@0:     if (msgsnd(msq_id, (struct msgbuf *)&msg;_buf, len, 0) == -1) {
sl@0:         printf("Message Q send failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, int msgflg)
sl@0: @param msqid
sl@0: @param msgp
sl@0: @param msgsz
sl@0: @param msgtyp
sl@0: @param msgflg
sl@0: @return   Upon successful completion, msgrcv returns the number of bytes received into the mtext field of the structure pointed to by msgp. Otherwise, -1 is returned, and errno set to indicate the error.
sl@0: 
sl@0:   The msgrcv function receives a message from the message queue specified 
sl@0: in msqid and places it into the structure pointed to by msgp. This structure should consist of the following members: 
sl@0: @code
sl@0: long mtype;    /* message type */
sl@0: char mtext[1]; /* body of message */
sl@0: @endcode
sl@0: 
sl@0:  mtype is an integer greater than 0 that can be used for selecting messages, mtext is an array of bytes with a size up to that of the system limit (Dv MSGMAX).
sl@0: 
sl@0:  The value of msgtyp has one of the following meanings: The msgtyp argument
sl@0: is greater than 0.
sl@0: The first message of type msgtyp will be received. The msgtyp argument
sl@0: is equal to 0.
sl@0: The first message on the queue (of any message type) will be received. The msgtyp argument
sl@0: is less than 0.
sl@0: The first message of the lowest message type that is
sl@0: less than or equal to the absolute value of msgtyp will be received.
sl@0: 
sl@0:  The msgsz argument
sl@0: specifies the maximum length of the requested message.
sl@0: If the received
sl@0: message has a length greater than msgsz it will be silently truncated if the MSG_NOERROR flag is set in msgflg, otherwise an error will be returned.
sl@0: 
sl@0:  If no matching message is present on the message queue specified by msqid, the behavior of msgrcv depends on whether the IPC_NOWAIT flag is set in msgflg or not. If IPC_NOWAIT is set, msgrcv will immediately return a value of -1 and set errno to ENOMSG. If IPC_NOWAIT is not set, the calling process will be blocked until: A message of the requested type becomes available on the message queue. The message queue is removed, in which case -1 will be returned and errno set to EINVAL.
sl@0: 
sl@0:  If a message is successfully received, the data structure associated with msqid is updated as follows: msg_cbytes is decremented by the size of the message. msg_lrpid is set to the pid of the caller. msg_lrtime is set to the current time. msg_qnum is decremented by 1.
sl@0: 
sl@0: Examples:
sl@0: 
sl@0:  Receive a message from the queue
sl@0:  
sl@0: @code
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id;
sl@0:    int msg_len = 128;
sl@0:    int msg_type = 0; /* Any type of message */
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    int ret_val = -1;
sl@0:    /*
sl@0:     * Get the message queue id for the given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, IPC_CREAT)) == -1) {
sl@0:        printf("Message Q  get id failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:     }
sl@0:     /*
sl@0:      * Get the message from the queue
sl@0:      */
sl@0:     if ((ret_val = msgrcv(msq_id, (struct msgbuf *)&msg;_buf, msg_len, msg_type, 0)) == -1) {
sl@0:         printf("Message Q recv failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     /*
sl@0:      * Remove the message queue
sl@0:      */
sl@0:      if (msgctl(msq_id, IPC_RMID, NULL) == -1) {
sl@0:        printf("Message Q  delete failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:      }
sl@0:      return ret_val;
sl@0: }
sl@0: 
sl@0: 
sl@0:  Send a message to the queue
sl@0: 
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id, len;
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    /*
sl@0:     * Create a message queue with the given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, IPC_CREAT | IPC_EXCL | 0666)) == -1) {
sl@0:        printf("Message Q create failed with errno %d0, errno);
sl@0:        return -1;
sl@0:     }
sl@0:     msg_buf.mtype = 1; /* message identifier */
sl@0:     strcpy(msg_buf.mtext, "some_data_to_send"); /* data */
sl@0:     len = strlen(msg_buf.mtext)+1;
sl@0:     /*
sl@0:      * Put the message in the queue
sl@0:      */
sl@0:     if (msgsnd(msq_id, (struct msgbuf *)&msg;_buf, len, 0) == -1) {
sl@0:         printf("Message Q send failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @see msgctl()
sl@0: @see msgget()
sl@0: @see msgsnd()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  msgctl(int msqid, int cmd, struct msqid_ds *buf)
sl@0: @param msqid
sl@0: @param cmd
sl@0: @param buf
sl@0: @return   The msgctl function returns the value 0 if successful; otherwise the
sl@0: value -1 is returned and errno is set to indicate the error.
sl@0: 
sl@0: The msgctl system call performs some control operations on the message queue specified by msqid. 
sl@0: Each message queue has a data structure associated with it, parts of which may be altered by msgctl and parts of which determine the actions of msgctl. The data structure is defined in \<sys/msg.h\> and contains (amongst others) the following members: 
sl@0: 
sl@0: @code
sl@0: struct msqid_ds {
sl@0:         struct  ipc_perm msg_perm;      /* msg queue permission bits */
sl@0:         struct  msg *msg_first; /* first message in the queue */
sl@0:         struct  msg *msg_last;  /* last message in the queue */
sl@0:         u_long  msg_cbytes;     /* number of bytes in use on the queue */
sl@0:         u_long  msg_qnum;       /* number of msgs in the queue */
sl@0:         u_long  msg_qbytes;     /* max # of bytes on the queue */
sl@0:         pid_t   msg_lspid;      /* pid of last msgsnd() */
sl@0:         pid_t   msg_lrpid;      /* pid of last msgrcv() */
sl@0:         time_t  msg_stime;      /* time of last msgsnd() */
sl@0:         long    msg_pad1;
sl@0:         time_t  msg_rtime;      /* time of last msgrcv() */
sl@0:         long    msg_pad2;
sl@0:         time_t  msg_ctime;      /* time of last msgctl() */
sl@0:         long    msg_pad3;
sl@0:         long    msg_pad4[4];
sl@0: };
sl@0: @endcode
sl@0: 
sl@0: The ipc_perm structure used inside the shmid_ds structure is defined in \<sys/ipc.h\> and looks like this: 
sl@0: @code
sl@0: struct ipc_perm {
sl@0:         ushort  cuid;   /* creator user id */
sl@0:         ushort  cgid;   /* creator group id */
sl@0:         ushort  uid;    /* user id */
sl@0:         ushort  gid;    /* group id */
sl@0:         ushort  mode;   /* r/w permission */
sl@0:         ushort  seq;    /* sequence # (to generate unique msg/sem/shm id) */
sl@0:         key_t   key;    /* user specified msg/sem/shm key */
sl@0: };
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: 
sl@0: The operation to be performed by msgctl is specified in cmd and is one of: IPC_STAT  Gather information about the message queue and place it in the structure pointed to by buf.  
sl@0: IPC_SET  Set the value of the msg_perm.uid, msg_perm.gid, msg_perm.mode and msg_qbytes fields in the structure associated with msqid. The values are taken from the corresponding fields in the structure pointed to by buf. Values for msg_qbytes that exceed the system limit (MSGMNB from \<sys/msg.h\>) are silently truncated to that limit.  
sl@0: IPC_RMID  Remove the message queue specified by msqid and destroy the data associated with it.  
sl@0: 
sl@0: 
sl@0: 
sl@0: The permission to read from or write to a message queue (see msgsnd and msgrcv is determined by the msg_perm.mode field in the same way as is done with files (see chmod) 
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id, len;
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    /*
sl@0:     * Create a message queue with a given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, IPC_CREAT | IPC_EXCL | 0666)) == -1) {
sl@0:        printf("Message Q create failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:     }
sl@0:     msg_buf.mtype = 1; /* message identifier */
sl@0:     strcpy(msg_buf.mtext, "some_data_to_send"); /* data */
sl@0:     len = strlen(msg_buf.mtext)+1;
sl@0:     /*
sl@0:      * Put the message in the queue
sl@0:      */
sl@0:     if (msgsnd(msq_id, (struct msgbuf *)&msg;_buf, len, 0) == -1) {
sl@0:         printf("Message Q send failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include <sys/types.h>
sl@0: #include <sys/ipc.h>
sl@0: #include <sys/msg.h>
sl@0: #include <stdio.h>
sl@0: #include <string.h>
sl@0: #include <errno.h>
sl@0: 
sl@0: #define MESSAGE_Q_KEY 1000
sl@0: 
sl@0: int main(void)
sl@0: {
sl@0:    int msq_id;
sl@0:    int msg_len = 128;
sl@0:    int msg_type = 0; /* Any type of message */
sl@0:    struct {
sl@0:        long mtype;
sl@0:        char mtext[128];
sl@0:    } msg_buf;
sl@0:    /*
sl@0:     * Get the message queue id for the given key
sl@0:     */
sl@0:     if ((msq_id = msgget(MESSAGE_Q_KEY, 0)) == -1) {
sl@0:        printf("Message Q  get id failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:     }
sl@0:     /*
sl@0:      * Get the message from the queue
sl@0:      */
sl@0:     if (msgrcv(msq_id, (struct msgbuf *)&msg;_buf, msg_len, msg_type, 0) == -1) {
sl@0:         printf("Message Q recv failed with errno %d
sl@0: ", errno);
sl@0:     }
sl@0:     /*
sl@0:      * Remove the message queue
sl@0:      */
sl@0:      if (msgctl(msq_id, IPC_RMID, NULL) == -1) {
sl@0:        printf("Message Q  delete failed with errno %d
sl@0: ", errno);
sl@0:        return -1;
sl@0:      }
sl@0:      return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Note :The below data members of the structure  msqid_ds are internal components.
sl@0: @code
sl@0: 	struct  msg *msg_first
sl@0: 	struct  msg *msg_last; 
sl@0: 	long    msg_pad1;
sl@0: 	long    msg_pad2;
sl@0: 	long    msg_pad3;
sl@0: 	long    msg_pad4[4];
sl@0: @endcode
sl@0: and are not filled if msgctl is called with the flag IPC_STAT.
sl@0: 
sl@0: @see msgget()
sl@0: @see msgrcv()
sl@0: @see msgsnd()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @struct msqid_ds
sl@0: 
sl@0: The msqid_ds structure defines a message queue associated with a message queue ID. There is one queue per message queue ID. 
sl@0: Collectively, the queues are stored as an array, with message queue IDs serving as an index into the array.
sl@0: Contains the following members,
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_perm
sl@0: msg queue permission bits
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_first
sl@0: first message in the queue
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_last
sl@0: last message in the queue
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_cbytes
sl@0: number of bytes in use on the queue
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_qnum
sl@0: number of msgs in the queue 
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_qbytes
sl@0: max n of bytes on the queue
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_lspid
sl@0: pid of last msgsnd() 
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_lrpid
sl@0: pid of last msgrcv()
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_stime
sl@0: time of last msgsnd()
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_pad1
sl@0: time of last msgsnd()
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_rtime
sl@0: time of last msgrcv()
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_pad2
sl@0: time of last msgrcv()
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_ctime
sl@0: time of last msgctl()
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_pad3
sl@0: time of last msgctl()
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @var msqid_ds::msg_pad4
sl@0: time of last msgctl()
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: /** @def MSG_NOERROR
sl@0: 
sl@0: The MSG_NOERROR identifier value, the msqid_ds struct and the msg struct are as defined by the SV API Intel 386 Processor Supplement.
sl@0: don't complain about too long msgs.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: