sstrings2(5) - Linux man page

Sinopsys

The Safe Strings Libraray is a simple collection of C functions that handle with strings in a safe way. All function were written with ANSI C (C99) functions are were tested before this current release was made, but this doesn't mean that all function are bug free. So, if you find erros and bugs, please report them at yanezp@informatik.uni-freiburg.de

The functions of this library look at the necessary space for the operations and try to reserve that space (with malloc or realloc). The functions only begin working with their tasks when the memory allocation is successful. The code is released under the term of the GPL-2.

This function should be used only with C. C++ has std::string and std::string should be used there, so don't use this funtion with C++.

Programming with Sstrings

It is very easy to use the Safe Strings library. Please read this manual page if you haven't worked with this library yet.

Writing code and including source files

The have to include the sstring2.h header file. string.h is included by sstring2.h

The library allocates the memory space using an alternative malloc/realloc implementation so you have to free the memory. This version implements an experimental (and rudimentary) garbage collector (disabled by default). If you use it then you don't need to free the memory allocated by the sstrings functions (memory allocated with sstrings functions only). See also ss_string_enable_gc(3).

#include <stdio.h>
#include <sstrings2.h>
int main(void)
{
    ss_string *str;
    str = ss_string_new("Hello");
    if(!str)
    {
        ss_string_perror("ss_string_new");
        return 1;
    }
    if(!ss_string_append_c_string(str, " World!"))
    {
        ss_string_perror("ss_sstring_append");
        ss_string_free(str, 1);
        return 1;
    }
    printf("%s\n", str->str);
    ss_string_free(str, 1);
    return 0;
}

Linking source code with sstrings Use -lsstrings2 to link this library. Example:

$ gcc test.c -otest -lsstrings2

Online documentation

You find

the online documentation at

http://klingsor.informatik.uni-freiburg.de/projects/sstring/doc

THE ss_string OBJECT

The new versions of sstring work with an own string object. This object is used to save information about the string, its length and how may bytes are allocated for it.

typedef struct {
        char *str; /* pointer to allocated string */
        size_t len; /* length of the string */
        size_t bytes; /* how many bytes are allocated */

} ss_string;

Before you start using ss_string objects you have to create them (using ss_string_new(3)). You have to use ss_string_free(3) to free the allocated memory of the object and the allocated memory of the string.

Error Constants

When the functions cannot be executed properly (because of an error) then the variable ss_errno is set to one of the following values:

List of error constants
Name              || value || Description
=========================================
SS_NOERR             0        describes the state of no error
SS_NOMEM             1        Not enough memory
SS_NULL              2        Input is a null pointer
SS_EINVAL            3        Invalid argument