unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

msgsnap(2)                       System Calls                       msgsnap(2)



NAME
       msgsnap - message queue snapshot operation

SYNOPSIS
       #include <sys/msg.h>

       msgsnap(int msqid, void *buf, size_t bufsz, long msgtyp);

DESCRIPTION
       The  msgsnap()  function  reads all of the messages of type msgtyp from
       the queue associated with the message  queue  identifier  specified  by
       msqid and places them in the user-defined buffer pointed to by buf.

       The  buf  argument  points to a user-defined buffer that on return will
       contain first a buffer header structure:

       struct msgsnap_head {
            size_t  msgsnap_size;   /* bytes used/required in the buffer */
            size_t  msgsnap_nmsg;   /* number of messages in the buffer */
       };


       followed by msgsnap_nmsg messages, each of which starts with a  message
       header:

       struct msgsnap_mhead {
            size_t  msgsnap_mlen;   /* number of bytes in the message */
            long    msgsnap_mtype;  /* message type */
       };


       and followed by msgsnap_mlen bytes containing the message contents.

       Each  subsequent  message header is located at the first byte following
       the previous message contents, rounded up to a sizeof(size_t) boundary.

       The bufsz argument specifies the size  of buf in bytes.   If  bufsz  is
       less  than sizeof(msgsnap_head), msgsnap() fails with EINVAL.  If bufsz
       is insufficient to contain all of  the  requested  messages,  msgsnap()
       succeeds  but  returns with msgsnap_nmsg set to 0 and with msgsnap_size
       set to the required size of the buffer in bytes.

       The msgtyp argument specifies the types of messages requested  as  fol-
       lows:

         o  If msgtyp is 0, all of the messages on the queue are read.

         o  If msgtyp is greater than 0, all messages of type msgtyp are read.

         o  If  msgtyp  is  less  than  0, all messages with type less than or
            equal to the absolute value of msgtyp are read.


       The msgsnap() function is a non-destructive  operation.   Upon  comple-
       tion, no changes are made to the data structures associated with msqid.

RETURN VALUES
       Upon  successful  completion,  msgsnap()  returns  0.  Otherwise, -1 is
       returned and errno is set to indicate the error.

ERRORS
       The msgsnap() function will fail if:

       EACCES          Operation permission is denied to the calling  process.
                       See intro(2).



       EINVAL          The msqid argument is not a valid message queue identi-
                       fier or the value of bufsz is less  than  sizeof(struct
                       msgsnap_head).



       EFAULT          The buf argument points to an illegal address.



USAGE
       The  msgsnap()  function  returns  a  snapshot of messages on a message
       queue at one point in time.  The queue contents can change  immediately
       following return from msgsnap().

EXAMPLES
       Example 1: msgsnap() example

       This  is  sample C code indicating how to use the msgsnap function (see
       msgids(2)).

       void
       process_msgid(int msqid)
       {
            size_t bufsize;
            struct msgsnap_head *buf;
            struct msgsnap_mhead *mhead;
            int i;

            /* allocate a minimum-size buffer */
            buf = malloc(bufsize = sizeof(struct msgsnap_head));

            /* read all of the messages from the queue */
            for (;;) {
                 if (msgsnap(msqid, buf, bufsize, 0) != 0) {
                      perror("msgsnap");
                           free(buf);
                           return;
                 }
                 if (bufsize >= buf->msgsnap_size)  /* we got them all */
                      break;
                 /* we need a bigger buffer */
                 buf = realloc(buf, bufsize = buf->msgsnap_size);
            }

            /* process each message in the queue (there may be none) */
            mhead = (struct msgsnap_mhead *)(buf + 1);  /* first message */
            for (i = 0; i < buf->msgsnap_nmsg; i++) {
                 size_t mlen = mhead->msgsnap_mlen;

                 /* process the message contents */
                 process_message(mhead->msgsnap_mtype, (char *)(mhead+1), mlen);

                 /* advance to the next message header */
                 mhead = (struct msgsnap_mhead *)
                      ((char *)mhead + sizeof(struct msgsnap_mhead) +
                      ((mlen + sizeof(size_t) - 1) & ~(sizeof(size_t) - 1)));
            }

            free(buf);
       }


ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE MT-LevelAsync-Signal-Safe


SEE ALSO
       ipcrm(1),   ipcs(1),   intro(2),   msgctl(2),   msgget(2),   msgids(2),
       msgrcv(2), msgsnd(2), attributes(5)



SunOS 5.10                        8 Mar 2000                        msgsnap(2)