Functions

ms3_library_init()

void ms3_library_init(void)

Initializes the library for use. Should be called before any threads are spawned.

ms3_library_deinit()

void ms3_library_deinit(void)

Cleans up the library, typically for the end of the application’s execution.

ms3_library_init_malloc()

uint8_t ms3_library_init_malloc(ms3_malloc_callback m, ms3_free_callback f, ms3_realloc_callback r, ms3_strdup_callback s, ms3_calloc_callback c)

Initialize the library for use with custom allocator replacement functions. These functions are also fed into libcurl. The function prototypes should be as follows:

void *ms3_malloc_callback(size_t size)

To replace malloc().

void ms3_free_callback(void *ptr)

To replace free().

void *ms3_realloc_callback(void *ptr, size_t size)

To replace realloc().

char *ms3_strdup_callback(const char *str)

To replace strdup().

void *ms3_calloc_callback(size_t nmemb, size_t size)

To replace calloc().

Should be called before any threads are spawned. All parameters are required or the function will fail.

Remember: With great power comes great responsibility.

Parameters:

  • m – The malloc callback

  • f – The free callback

  • r – The realloc callback

  • s – The strdup callback

  • c – The calloc callback

Returns:

0 on success, MS3_ERR_PARAMETER if a parameter is NULL

ms3_init()

ms3_st *ms3_init(const char *s3key, const char *s3secret, const char *region, const char *base_domain)

Initializes a ms3_st object. This object should only be used in the thread that created it because it reuses connections. But it is safe to have other ms3_st objects running at the same time in other threads.

Note

You MUST call ms3_library_init() before spawning threads when using this access method.

Parameters:

  • s3key – The AWS access key

  • s3secret – The AWS secret key

  • region – The AWS region to use (such as us-east-1)

  • base_domain – A domain name to use if AWS S3 is not the desired server (set to NULL for S3)

Returns:

A newly allocated marias3 object

ms3_deinit()

void ms3_deinit(ms3_st *ms3)

Cleans up and frees a ms3_st object.

Parameters:

  • ms3 – The marias3 object

ms3_server_error()

const char *ms3_server_error(ms3_st *ms3)

Returns the last error message from the S3 server or underlying Curl library.

Parameters:

  • ms3 – The marias3 object

Returns:

The error message string or NULL if there is no message.

ms3_error()

const char *ms3_error(uint8_t errcode)

Returns an error message for a given error code

Parameters:

  • errcode – The error code to translate

Returns:

The error message

ms3_debug()

void ms3_debug(int debug_state)

Enables and disables debugging output on stderr.

Parameters:

  • debug_state – Set to 1 to enable debugging, zero to disable.

Note::

This enables/disables globally for the library

ms3_list()

uint8_t ms3_list(ms3_st *ms3, const char *bucket, const char *prefix, ms3_list_st **list)

Retrieves a list of files from a given S3 bucket and fills it into a ms3_list_st.

The list generated is the eqivilent of a recursive directory listing but only has files in it, no entries for directories.

The list will automatically be freed on the next list/list_dir call or ms3_deinit()

Parameters:

  • ms3 – The marias3 object

  • bucket – The bucket name to use

  • prefix – An optional path/file prefix to use (NULL for all files)

  • list – A pointer to a pointer that will contain the returned list

Returns:

0 on success, a positive integer on failure

Example

char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
ms3_list_st *list= NULL, *list_it= NULL;
uint8_t res;

ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);

res= ms3_list(ms3, s3bucket, NULL, &list);
if (res)
{
    printf("Error occurred: %d\n", res);
    return;
}
list_it= list;
while(list_it)
{
  printf("File: %s, size: %ld, tstamp: %ld\n", list_it->key, list_it->length, list_it->created);
  list_it= list_it->next;
}
ms3_deinit(ms3);

ms3_list_dir()

uint8_t ms3_list_dir(ms3_st *ms3, const char *bucket, const char *prefix, ms3_list_st **list)

Retrieves a list of files from a given S3 bucket and fills it into a ms3_list_st.

The list generated will automatically add the delimiter / and therefore filter up to the first / after the prefix. Unlike ms3_list() it includes directory entries. This is the eqivilent of doing a regular directory listing in a current directory (as designated by prefix).

The list will automatically be freed on the next list/list_dir call or ms3_deinit()

Parameters:

  • ms3 – The marias3 object

  • bucket – The bucket name to use

  • prefix – An optional path/file prefix to use (NULL for all files)

  • list – A pointer to a pointer that will contain the returned list

Returns:

0 on success, a positive integer on failure

ms3_list_free()

void ms3_list_free(ms3_list_st *list)

Deprecated since version 3.1.1: Now a NULL operation which be removed in 4.0

A NULL operation, previously free’d ms3_list(), but this is now done internally on ms3_deinit() or when a new list is requested.

Parameters:

  • list – The list to free

ms3_put()

uint8_t ms3_put(ms3_st *ms3, const char *bucket, const char *key, const uint8_t *data, size_t length)

Puts a binary data from a given pointer into S3 at a given key/filename. If an existing key/file exists with the same name this will be overwritten.

Parameters:

  • ms3 – The marias3 object

  • bucket – The bucket name to use

  • key – The key/filename to create/overwrite

  • data – A pointer to the data to write

  • length – The length of the data to write

Returns:

0 on success, a positive integer on failure

Example

char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
const char *test_string= "Another one bites the dust";

ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);

res= ms3_put(ms3, s3bucket, "test/ms3.txt", (const uint8_t*)test_string, strlen(test_string));
if (res)
{
    printf("Error occurred: %d\n", res);
    return;
}
ms3_deinit(ms3);

ms3_copy()

uint8_t ms3_copy(ms3_st *ms3, const char *source_bucket, const char *source_key, const char *dest_bucket, const char *dest_key)

S3 internally copies an object from a source bucket and key to a destination bucket and key.

Parameters:

  • ms3 – The marias3 object

  • source_bucket – The bucket where the source object is

  • source_key – The key/filename of the source object

  • dest_bucket – The destination bucket (can be the same as source)

  • dest_key – The destination key/filename

Returns:

0 on success, a positive integer on failure

ms3_move()

uint8_t ms3_move(ms3_st *ms3, const char *source_bucket, const char *source_key, const char *dest_bucket, const char *dest_key)

Moves an object from source to destination. Internally the library performs a copy and if successful performs a delete on the source object.

Parameters:

  • ms3 – The marias3 object

  • source_bucket – The bucket where the source object is

  • source_key – The key/filename of the source object

  • dest_bucket – The destination bucket (can be the same as source)

  • dest_key – The destination key/filename

Returns:

0 on success, a positive integer on failure

ms3_get()

uint8_t ms3_get(ms3_st *ms3, const char *bucket, const char *key, uint8_t **data, size_t *length)

Retrieves a given object from S3.

Note

The application is expected to free the resulting data pointer after use

Parameters:

  • ms3 – The marias3 object

  • bucket – The bucket name to use

  • key – The key/filename to retrieve

  • data – A pointer to a pointer the data to be retrieved into

  • length – A pointer to the data length

Returns:

0 on success, a positive integer on failure

Example

char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
uint8_t *data= NULL;
size_t length;

ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);

res= ms3_get(ms3, s3bucket, "test/ms3.txt", &data, &length);
if (res)
{
    printf("Error occurred: %d\n", res);
    return;
}
printf("File contents: %s\n", data);
printf("File length: %ld\n", length);
ms3_free(data);
ms3_deinit(ms3);

ms3_free()

void ms3_free(uint8_t *data)

Used to free the data allocated by ms3_get().

Parameters:

  • data – The data to free

ms3_set_option()

uint8_t ms3_set_option(ms3_st *ms3, ms3_set_option_t option, void *value)

Sets a given connection option. See ms3_set_option_t for a list of options.

Parameters:

  • ms3 – The marias3 object

  • option – The option to set

  • value – A pointer to the value for the option (if required, NULL if not)

Returns:

0 on success, a positive integer on failure

ms3_delete()

uint8_t ms3_delete(ms3_st *ms3, const char *bucket, const char *key)

Deletes an object from an S3 bucket

Parameters:

  • ms3 – The marias3 object

  • bucket – The bucket name to use

  • key – The key/filename to delete

Returns:

0 on success, a positive integer on failure

Example

char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;

ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);

res = ms3_delete(ms3, s3bucket, "test/ms3.txt");
if (res)
{
    printf("Error occurred: %d\n", res);
    return;
}
ms3_deinit(ms3);

ms3_status()

uint8_t ms3_status(ms3_st *ms3, const char *bucket, const char *key, ms3_status_st *status)

Retreives the status of a given filename/key into a ms3_status_st object. Will return an error if not found.

Parameters:

  • ms3 – The marias3 object

  • bucket – The bucket name to use

  • key – The key/filename to status check

  • status – A status object to fill

Returns:

0 on success, a positive integer on failure

Example

char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
ms3_status_st status;

ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);

res= ms3_status(ms3, s3bucket, "test/ms3.txt", &status);
if (res)
{
    printf("Error occurred: %d\n", res);
    return;
}
printf("File length: %ld\n", status.length);
printf("File timestamp: %ld\n", status.created);
ms3_deinit(ms3);

ms3_set_content_type()

void ms3_set_content_type(ms3_st *ms3, const char *content_type)

Sets the Content-Type: header for subsequent PUT requests. Note that this is not copied, so it should remain in scope for each ms3_put() call. Setting this to NULL will clear the Content-Type header to the default.

Parameters:

  • ms3 – The marias3 object

  • content_type – The mime type to set

ms3_get_content_type()

const char *ms3_get_content_type(ms3_st *ms3)

Gets the Content-Type: header for the previous GET request response from the S3 server. The memory for this is part of the ms3_st object and should not be freed by the application. The contents will be reset on each GET request.

Parameters:

  • ms3 – The marias3 object

  • content_type – The mime type for the previous request