libmessageclient(3) FreeBSD Library Functions Manual libmessageclient(3) NAME libmessageclient – Client Library for libmessage(3) SYNOPSIS #include -I/usr/local/include -L/usr/local/lib -lmessageclient -lcrypto -lssl DESCRIPTION libmessageclient provides reentrant, blocking-IO code to communicate with LibMessage servers. USAGE The library provides 9 functions. char mc_error[ 256 ]; SSL_CTX *ctx; struct mc_ssl { SSL *ssl; int fd; }; int mc_init_tls( int ); void mc_deinit_tls(); int mc_set_max_message( unsigned int ); struct mc_ssl *mc_connect_to_server( char *, char *, int ); void mc_close_connection( struct mc_ssl * ); int mc_read_frame( struct mc_ssl *, unsigned char *, unsigned char ); int mc_read_message( struct mc_ssl *, unsigned char ** ); int mc_send_frame( struct mc_ssl *, unsigned char, unsigned int, unsigned char * ); int mc_send_message( struct mc_ssl *, unsigned int, unsigned char * ); Do not define any other global symbol beginning with the 3 characters ´mc_' because the library reserves that namespace. MC_INIT_TLS() Use mc_init_tls() to initialize OpenSSL before using any of the other functions. Note that this function sets SIGPIPE to be ignored. int mc_init_tls(); On success, the function returns 0. On error, the function returns -1 and writes an error message into mc_error. MC_DEINIT_TLS() Use mc_deinit_tls() to free the OpenSSL context when you are finished using the library. void mc_deinit_tls(); MC_CONNECT_TO_SERVER() Use mc_connect_to_server() to establish a connection to a LibMessage server. struct mc_ssl *mc_connect_to_server( char *hostname, char *port, int ignore ); The hostname argument is a string representing the hostname or IP address of the host on which the server is running. The port argument is a string representing the port on which the server is listening. The ignore argument indicates whether or not to ignore a mismatch between the hostname and the hostname on the server's certificate. This is useful for debugging over the loopback interface. On success, the function returns a pointer to a struct mc_ssl. On failure, the function returns NULL and writes an error message into mc_error. MC_CLOSE_CONNECTION() Use mc_close_tls_connection() to close a connection. void mc_close_tls_connection( struct mc_ssl * ); The function shuts down the TLS connection, closes the underlying descriptor, and frees the struct mc_ssl pointed to by the argument. MC_SET_MAX_MESSAGE Use mc_set_max_message() to set the maximum message size that both server and client use. The default maximum message size is 262128 bytes. unsigned int mc_set_max_message( unsigned int max ); The function returns 0 if max is not a multiple of the internal frame payload size, which is 32766. In this case, the maximum message size is unchanged. Otherwise, the function returns the new maximum message size. Both sides of a connection must use the same message size. If you change the default size, you must send a message to inform the server of your intent to change the size, and the server must agree to use the new size. How that is accomplished is up to you. MC_READ_FRAME() Use mc_read_frame() to read a single frame from a server. If you want to timeout the read, use setsockopt() to place a timeout on the underlying socket (the fd member of the struct ssl). int mc_read_frame( struct mc_ssl *conn, unsigned char *buffer, unsigned char *final ); The conn argument is the pointer returned by mc_connect_to_server(). The buffer argument is a character array of 32766 elements. The final argument is a pointer to an unsigned character. On success, the function reads an incoming frame's payload into buffer, writes the high-order bit of the frame into the high-order bit of final, and returns the number of characters read. The function returns 0 for an empty frame. On error, the function returns -1 and writes an error message into mc_error. On EOF, the function returns -2. MC_READ_MESSAGE() Use mc_read_message() to read a complete message from a server. If you want to timeout the read, use setsockopt() to place a timeout on the underlying socket (the fd member of the struct ssl). int mc_read_message( struct mc_ssl *conn, unsigned char **buffer ); The conn argument is the pointer returned by mc_connect_to_server(). The buffer argument is a pointer to a character pointer. On success, the function reads an incoming messages's payload into a dynamically-allocated buffer that you are responsible for freeing, places a pointer to that buffer in *buffer, and returns the number of characters read. The function returns 0 for an empty frame. *buffer is set to NULL. The function returns -1 on error and writes an error message into mc_error. *buffer is set to NULL. On EOF, the function returns -2. *buffer is set to NULL. MC_SEND_FRAME() Use mc_send_frame() to send a frame to a server. int mc_send_frame( struct mc_ssl *conn, unsigned int len, unsigned char *buffer ); The conn argument is the pointer returned by mc_connect_to_server(); The buffer argument is a character array containing frame data. The len argument is the length of the data in buffer. The length must be > 0 and <= 32766. On success, the function returns 0. If the peer has closed the connection, the function returns -2. On other errors, the function returns -1 and writes an error message into mc_error. MC_SEND_MESSAGE() Use mc_send_message() to send a complete message to a server. int mc_send_message( struct mc_ssl *conn, unsigned int len, unsigned char *buffer ); The conn argument is the pointer returned by mc_connect_to_server(); The buffer argument is a character array containing message data. The len argument is the length of the data in buffer. The length must be > 0 and <= 262128. On success, the function returns 0. If the peer has closed the connection, the function returns -2. On other errors, the function returns -1 and writes an error message into mc_error. AUTHORS James Bailie ⟨bailie9@icloud.com⟩ mammothcheese.ca Wed Mar 25, 2026 libmessageclient(3)