---
name: "SP_scat_multicast"
section: "3"
platform: "linux"
package: "libspread1-dev"
version: "3.17.4-2+b1"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/SP_multicast"
---

# SP\_scat\_multicast(3)

Multicast message to groups

Part of [SP\_multicast(3)](/SP_multicast/3.md).

## NAME

SP\_multicast, SP\_scat\_multicast, SP\_multigroup\_multicast, SP\_multigroup\_scat\_multicast - Multicast message to groups

## SYNOPSIS

**#include \<sp.h\>**

**int SP\_multicast( mailbox** *mbox***, service** *service\_type***, const char \****group***, int16** *mess\_type***, int** *mess\_len***, const char \****mess***);**\
 **int SP\_scat\_multicast( mailbox** *mbox***, service** *service\_type***, const char \****group***, int16** *mess\_type***, const scatter** *scat\_mess***);**

**int SP\_multigroup\_multicast( mailbox** *mbox***, service** *service\_type***, int** *num\_groups***, const char** *groups***\[\]\[MAX\_GROUP\_NAME\], int16** *mess\_type***, int** *mess\_len***, const char \****mess***);**\
 **int SP\_multigroup\_scat\_multicast( mailbox** *mbox***, service** *service\_type***, int** *num\_groups***, const char** *groups***\[\]\[MAX\_GROUP\_NAME\], int16** *mess\_type***, const scatter** *scat\_mess***);**

## DESCRIPTION

**SP\_multicast** and its variants all can multicast send a message to one or more groups.  The  message is sent on a particular connection and is marked as having come from the connection who sent it. The *service\_type* is a type field that should be set to the service this message requires. The valid flags for messages are:

**UNRELIABLE\_MESS**\
 **RELIABLE\_MESS**\
 **FIFO\_MESS**\
 **CAUSAL\_MESS**\
 **AGREED\_MESS**\
 **SAFE\_MESS**

This type  can be bit ORed with other flags like SELF\_DISCARD  if desired.  Currently SELF\_DISCARD is the only additional flag.

If the  **SP\_multicast** or  **SP\_scat\_multicast** versions are being used then only one group can be sent to. So the *group* string should include the name of the group to send to. If a multigroup varient is being used then the groups are specified by the *num\_groups* integer and the array of group names called *groups* representing all the groups the message should be sent to.   Each group has a string name of no more then MAX\_GROUP\_NAME chars. The array should have at least as many group names as the 'num\_groups'  parameter indicates. The Spread system will only send the message once but will deliver it to all connections which  have joined at least one of the groups listed.

The *mess\_type* This is a SHORT int (16 bits) which can be used by the  application arbitrarily.  The intent is that it could be used  to NAME different kinds of data messages so they can be differentiated without looking into the body of the message. This value  **will** be endian corrected before receiving.

If the non-scatter varients are being used then a single buffer is passed to the multicast call specifying the full message to be sent. The  *mess\_len* field gives the length in bytes of the message. While the *mess* field is a pointer to the buffer containing the message. For a scatter call both of these are replaced with one pointer, *scat\_mess,* to a scatter structure, which is just like an iovec.  This allows  messages made up of several parts to be sent without an extra copy on systems which support scatter-gather.

## RETURN VALUES

Returns the number of bytes sent on success or one of the following errors ( \< 0 ):

- **ILLEGAL\_SESSION**

  The  *mbox* given to multicast on was illegal.

- **ILLEGAL\_MESSAGE**

  The message had an illegal structure, like a scatter not filled out correctly.

- **CONNECTION\_CLOSED**

  During communication to send the message errors occured and the send could not be completed.

## BUGS

None.

## AUTHOR

Yair Amir \<yairamir@cnds.jhu.edu\>\
 Jonathan Stanton \<jonathan@cnds.jhu.edu\>\
 Commedia Project \<commedia@cnds.jhu.edu\>

## SEE ALSO

[**libsp**(3)](/libsp/3.md)