--- name: "SP_connect" 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_connect" --- # SP\_connect(3) Connect an application to a daemon ## NAME SP\_connect - Connect an application to a daemon ## SYNOPSIS **#include \**\ **int SP\_connect( const char \****spread\_name***, const char \****private\_name***, int** *priority***, int** *group\_membership***, mailbox \****mbox***, char \****private\_group***);** ## DESCRIPTION **SP\_connect** is the initial call an application must make to establish a connection with a Spread daemon. All other spread calls must refer to a valid *mbox* returned by this function. The *spread\_name* is the name of the Spread daemon to connect to. It should be a string in one of the following forms: - **4803** This will connect to the Spread daemon on the local machine running on port 4803. This form cannot be used to connect to a Windows95/NT machine. - **4803@localhost** This will also connect to the Spread daemon on the local machine running on port 4803. This form can be used on Windows95/NT machines. - **4803@host.domain.edu** or **4803@128.220.221.99** This will connect to the machine identified by either domain name or IP address at the specified port. The *private\_name* is the name this connection would like to be known as. It must be unique on the machine running the spread daemon. The name can be of at most MAX\_PRIVATE\_NAME characters, with the same character restrictions as a group name (mainly it cannot contain the '#' character). If the application does not care what name it uses, it can pass in a NULL pointer into this field and the daemon will assign the connection a unique, random name. The *priority* is a 0/1 flag for whether this connection will be a "Priority" connection or not. Currently this has no effect. The *group\_membership* is a boolean integer. If 1 then the application will receive group membership messages for this connection, if 0 then the application will **not** receive **any** membership change messages. The *mbox* should be a pointer to a mailbox variable. After the **SP\_connect** call returns this variable will hold the mbox for the connection. The *private\_group* should be a pointer to a string big enough to hold at least MAX\_GROUP\_NAME characters. After the Connect call returns it will contain the private group name of this connection. This group name can be used to send unicast messages to this connection and no one can join this special group. ## RETURN VALUES Returns **ACCEPT\_SESSION** on success or one of the following errors ( \< 0 ): - **ILLEGAL\_SPREAD** The *spread\_name* given to connect to was illegal for some reason. Usually because it was a unix socket on Windows95/NT, an improper format for a host or an illegal port number - **COULD\_NOT\_CONNECT** Lower level socket calls failed to allow a connection to the specified spread daemon right now. - **CONNECTION\_CLOSED** During communication to establish the connection errors occured and the setup could not be completed. - **REJECT\_VERSION** The daemon or library has a version mismatch. - **REJECT\_NO\_NAME** This is a protocol error which should not occur if the connection request is sent correctly to the daemon. It means that the length of the user name was not sent (if no user name is provided a length of 0 must be sent). - **REJECT\_ILLEGAL\_NAME** Name provided violated some requirement (length or used an illegal character) - **REJECT\_NOT\_UNIQUE** Name provided is not unique on this daemon. Recommended response is to try again with a different name. ## BUGS None. ## AUTHOR Yair Amir \\ Jonathan Stanton \\ Commedia Project \ ## SEE ALSO [**libsp**(3)](/libsp/3.md)