Manual Pages for UNIX Operating System command usage for man msgsnap

System Calls                                           msgsnap(2)



NAME
     msgsnap - message queue snapshot operation

SYNOPSIS
     #include 

     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.




SunOS 5.11           Last change: 8 Mar 2000                    1






System Calls                                           msgsnap(2)



     The  msgtyp  argument  specifies  the  types   of   messages
     requested as follows:

         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
     completion, no changes are made to the data structures asso-
     ciated 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 pro-
               cess.  See Intro(2).


     EINVAL    The msqid argument is not a  valid  message  queue
               identifier  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)



SunOS 5.11           Last change: 8 Mar 2000                    2






System Calls                                           msgsnap(2)



       {
            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  attri-
     butes:












SunOS 5.11           Last change: 8 Mar 2000                    3






System Calls                                           msgsnap(2)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|


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













































SunOS 5.11           Last change: 8 Mar 2000                    4