Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for msgsnap (opensolaris section 2)

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 buf-
       fer 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 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.11				    8 Mar 2000				       msgsnap(2)


All times are GMT -4. The time now is 11:43 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password