libmultifile(3)        FreeBSD Library Functions Manual        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[ 128 ];

     SSL_CTX *ctx;

     struct fc_ssl {
        SSL *ssl;
        int fd;
     };

     int fc_init_tls( int );
     void fc_deinit_tls();

     struct fc_ssl *fc_connect_to_server( char *, char * );
     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_TLS()
     Use fc_init_tls() to initialize OpenSSL before using any of the other
     functions.

     int fc_init_tls();

     On success, the function returns 0.

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

   FC_DEINIT_TLS()
     Use fc_deinit_tls() to free the OpenSSL context when you are finished
     using the library.

     void fc_deinit_tls();

   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 *host, char *port, int ocsp );

     The host 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 ocsp argument indicates whether or not to request the certificate
     status with the TLS handshake.  Set ocsp to 1 to request the certificate
     status.  Set ocsp to 0 otherwise.  If the certificate status is
     requested, and the server does not perform OCSP stapling, or if the
     status is not valid, the handshake fails.

     On success, the function returns a pointer to a struct ms_ssl.

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

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

     void fc_close_tls_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 65535 elements.

     On success, the function reads an incoming frame 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 data.

     The len argument is the length of the data in buffer.  The length must be
     > 0 and <= 65535.

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

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

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

                               Mon Jul 08, 2019