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)  bound-
       ary.

       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 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 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 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)
       {
	    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:

       +-----------------------------+-----------------------------+
       |      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.10							    8 Mar 2000								msgsnap(2)