libmultifile(3)

NAME
libmultifile - Client Library for multifile(1)

SYNOPSIS
#include <multifile.h>
-I/usr/local/include -L/usr/local/lib -lmultifile -lcrypto -lssl

DESCRIPTION
libmultifile provides reentrant, blocking-IO code to communicate with multifile servers.

  USAGE
The library provides 6 functions.

    char fc_error[ 256 ];
    SSL_CTX *ctx;
    struct fc_ssl {
       SSL *ssl;
       int fd;
    };
    int fc_init( int );
    void fc_deinit();
    struct fc_ssl *fc_connect_to_server( char *, char *, int, int );
    void fc_close_connection( struct fc_ssl * );
    int fc_read_frame( struct fc_ssl *, unsigned char * );
    int fc_send_frame( struct fc_ssl *, unsigned char *, unsigned int );

Do not define any other global symbol beginning with the 3 characters 'fc_' because the library reserves that namespace.

  FC_INIT()
Use fc_init() to initialize OpenSSL before using any of the other functions. Note that this function sets SIGPIPE to be ignored.

    int fc_init();

On success, the function returns 0.

On error, the function returns -1 and writes an error message into fc_error.

  FC_DEINIT()
Use fc_deinit() to free the OpenSSL context when you are finished using the library.

    void fc_deinit();

  FC_CONNECT_TO_SERVER()
Use fc_connect_to_server() to establish a connection to a multifile server.

    struct cm_ssl *fc_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 fc_ssl.

On failure, the function returns NULL and writes an error message into fc_error.

  FC_CLOSE_CONNECTION()
Use fc_close_connection() to close a connection.

    void fc_close_connection( struct fc_ssl * );

The function shuts down the TLS connection, closes the underlying descriptor, and frees the struct fc_ssl pointed to by the argument.

  FC_READ_FRAME()
Use fc_read_frame() to read a 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 fc_read_frame( struct fc_ssl *conn, unsigned char *buffer );

The conn argument is the pointer returned by fc_connect_to_server().

The buffer argument is a character array of 1056 elements.

On success, the function reads an incoming frame's payload into buffer and returns the number of characters read.

On EOF, the function returns 0.

On error, the function returns -1 and writes an error message into fc_error.

  FC_SEND_FRAME()
Use fc_end_frame() to send a frame to a server.

    int fc_send_frame( struct fc_ssl *conn, unsigned char *buffer, unsigned int len );

The conn argument is the pointer returned by fc_connect_to_server();

The buffer argument is a character array containing frame payload data.

The len argument is the length of the data in buffer. The length must be between 1 and 1056 bytes in length.

On success, the function sends the frame to the server and returns 0.

If the peer has closed the connection, the function returns -2.

On error, the function returns -1 and writes an error message into fc_error.

AUTHORS
James Bailie <bailie9@icloud.com>
mammothcheese.ca