bstraux.h File Reference

C example that implements trivial additional functions. More...

#include <time.h>
#include "bstrlib.h"

Include dependency graph for bstraux.h:

Go to the source code of this file.

Macros
#define	bstrDeclare(b)   bstring(b) = NULL
#define	bstrFree(b)
#define	bAssign(a, b)   ((bassign)((a), (b)))
#define	bSubs(b, pos, len, a, c)   ((breplace)((b),(pos),(len),(a),(unsigned char)(c)))
#define	bStrchr(b, c)   ((bstrchr)((b), (c)))
#define	bStrchrFast(b, c)   ((bstrchr)((b), (c)))
#define	bCatCstr(b, s)   ((bcatcstr)((b), (s)))
#define	bCatBlk(b, s, len)   ((bcatblk)((b), (s), (len)))
#define	bCatStatic(b, s)   bCatBlk((b), ("" s ""), sizeof (s) - 1)
#define	bTrunc(b, n)   ((btrunc)((b), (n)))
#define	bReplaceAll(b, find, repl, pos)   ((bfindreplace)((b),(find),(repl),(pos)))
#define	bUppercase(b)   ((btoupper)(b))
#define	bLowercase(b)   ((btolower)(b))
#define	bCaselessCmp(a, b)   ((bstricmp)((a), (b)))
#define	bCaselessNCmp(a, b, n)   ((bstrnicmp)((a), (b), (n)))
#define	bBase64Decode(b)   (bBase64DecodeEx((b), NULL))
#define	bUuDecode(b)   (bUuDecodeEx((b), NULL))
#define	bAscTime(t)   (bStrfTime ("%c\n", (t)))
#define	bCTime(t)   ((t) ? bAscTime (localtime (t)) : NULL)
#define	bSecureDestroy(b)
#define	bSecureWriteProtect(t)

Typedefs
typedef int(*	bNwrite) (const void *buf, size_t elsize, size_t nelem, void *parm)

Functions
BSTR_PUBLIC struct bStream *	bsFromBstr (const bstring b)
	Create a bStream whose contents are a copy of the bstring passed in. More...
BSTR_PUBLIC bstring	bTail (bstring b, int n)
	Return with a string of the last n characters of b.
BSTR_PUBLIC bstring	bHead (bstring b, int n)
	Return with a string of the first n characters of b.
BSTR_PUBLIC int	bSetCstrChar (bstring a, int pos, char c)
	Sets the character at position pos to the character c in the bstring a. More...
BSTR_PUBLIC int	bSetChar (bstring b, int pos, char c)
	Sets the character at position pos to the character c in the bstring a. More...
BSTR_PUBLIC int	bFill (bstring a, char c, int len)
	Fill a given bstring with the character in parameter c, for a length n.
BSTR_PUBLIC int	bReplicate (bstring b, int n)
	Replicate the contents of b end to end n times and replace it in b.
BSTR_PUBLIC int	bReverse (bstring b)
	Reverse the contents of b in place.
BSTR_PUBLIC int	bInsertChrs (bstring b, int pos, int len, unsigned char c, unsigned char fill)
	Insert a repeated sequence of a given character into the string at position pos for a length len.
BSTR_PUBLIC bstring	bStrfTime (const char *fmt, const struct tm *timeptr)
	Takes a format string that is compatible with strftime and a struct tm pointer, formats the time according to the format string and outputs the bstring as a result. More...
BSTR_PUBLIC int	bJustifyLeft (bstring b, int space)
	Left justify a string.
BSTR_PUBLIC int	bJustifyRight (bstring b, int width, int space)
	Right justify a string to within a given width.
BSTR_PUBLIC int	bJustifyMargin (bstring b, int width, int space)
	Stretch a string to flush against left and right margins by evenly distributing additional white space between words. More...
BSTR_PUBLIC int	bJustifyCenter (bstring b, int width, int space)
	Center a string's non-white space characters to within a given width by inserting whitespaces at the beginning.
BSTR_PUBLIC char *	bStr2NetStr (const bstring b)
	Convert a bstring to a netstring. More...
BSTR_PUBLIC bstring	bNetStr2Bstr (const char *buf)
	Convert a netstring to a bstring. More...
BSTR_PUBLIC bstring	bBase64Encode (const bstring b)
	Generate a base64 encoding. More...
BSTR_PUBLIC bstring	bBase64DecodeEx (const bstring b, int *boolTruncError)
	Decode a base64 block of data. More...
BSTR_PUBLIC struct bStream *	bsUuDecode (struct bStream *sInp, int *badlines)
	Creates a bStream which performs the UUDecode of an an input stream. More...
BSTR_PUBLIC bstring	bUuDecodeEx (const bstring src, int *badlines)
	Performs a UUDecode of a block of data. More...
BSTR_PUBLIC bstring	bUuEncode (const bstring src)
	Performs a UUEncode of a block of data. More...
BSTR_PUBLIC bstring	bYEncode (const bstring src)
	Performs a YEncode of a block of data. More...
BSTR_PUBLIC bstring	bYDecode (const bstring src)
	Performs a YDecode of a block of data. More...
BSTR_PUBLIC struct bwriteStream *	bwsOpen (bNwrite writeFn, void *parm)
	Wrap a given open stream (described by a fwrite work-a-like function pointer and stream handle) into an open bwriteStream suitable for write streaming functions.
BSTR_PUBLIC int	bwsWriteBstr (struct bwriteStream *stream, const bstring b)
	Send a bstring to a bwriteStream. More...
BSTR_PUBLIC int	bwsWriteBlk (struct bwriteStream *stream, void *blk, int len)
	Send a block of data a bwriteStream. More...
BSTR_PUBLIC int	bwsWriteFlush (struct bwriteStream *stream)
	Force any pending data to be written to the core stream.
BSTR_PUBLIC int	bwsIsEOF (const struct bwriteStream *stream)
	Returns 0 if the stream is currently writable, 1 if the core stream has responded by not accepting the previous attempted write.
BSTR_PUBLIC int	bwsBuffLength (struct bwriteStream *stream, int sz)
	Set the length of the buffer used by the bwsStream. More...
BSTR_PUBLIC void *	bwsClose (struct bwriteStream *stream)
	Close the bwriteStream, and return the handle to the stream that was originally used to open the given stream. More...
BSTR_PUBLIC bstring	bSecureInput (int maxlen, int termchar, bNgetc vgetchar, void *vgcCtx)
	Read input from an abstracted input interface, for a length of at most maxlen characters. More...

Detailed Description

C example that implements trivial additional functions.

This file is not a necessary part of the core bstring library itself, but is just an auxilliary module which includes miscellaneous or trivial functions.

Macro Definition Documentation

bSecureDestroy

#define bSecureDestroy

(

b

)

Value:

do { \
    if ((b) && (b)->mlen > 0 && (b)->data) { \
        (void)memset((b)->data, 0, (size_t)(b)->mlen); \
        (void)bdestroy((b)); \
    } \
} while (0)

bSecureWriteProtect

#define bSecureWriteProtect

(

t

)

Value:

do { \
    if ((t).mlen >= 0) { \
        if ((t).mlen > (t).slen)) { \
            (void)memset((t).data + (t).slen, 0, \
                     (size_t)(t).mlen - (t).slen); \
        } \
        (t).mlen = -1; \
    } \
} while (0)

bstrFree

#define bstrFree

(

b

)

Value:

do { \
    if ((b) != NULL && (b)->slen >= 0 && (b)->mlen >= (b)->slen) { \
        bdestroy(b); \
        (b) = NULL; \
    } \
} while (0)

Function Documentation

bBase64DecodeEx()

BSTR_PUBLIC bstring bBase64DecodeEx	(	const bstring	b,
		int *	boolTruncError
	)

Decode a base64 block of data.

All MIME headers are assumed to have been removed.

See: RFC1341

Here is the call graph for this function:

bBase64Encode()

BSTR_PUBLIC bstring bBase64Encode

(

const bstring

b

)

Generate a base64 encoding.

See: RFC1341

Here is the call graph for this function:

bJustifyMargin()

BSTR_PUBLIC int bJustifyMargin	(	bstring	b,
		int	width,
		int	space
	)

Stretch a string to flush against left and right margins by evenly distributing additional white space between words.

If the line is too long to be margin justified, it is left justified.

Here is the call graph for this function:

bNetStr2Bstr()

BSTR_PUBLIC bstring bNetStr2Bstr

(

const char *

buf

)

Convert a netstring to a bstring.

See http://cr.yp.to/proto/netstrings.txt for a description of netstrings.

Note that the terminating "," must be present, however a following '\0' is not required.

Here is the call graph for this function:

bSecureInput()

BSTR_PUBLIC bstring bSecureInput	(	int	maxlen,
		int	termchar,
		bNgetc	vgetchar,
		void *	vgcCtx
	)

Read input from an abstracted input interface, for a length of at most maxlen characters.

If maxlen <= 0, then there is no length limit put on the input. The result is terminated early if vgetchar() return EOF or the user specified value termchar.

bSetChar()

BSTR_PUBLIC int bSetChar	(	bstring	b,
		int	pos,
		char	c
	)

Sets the character at position pos to the character c in the bstring a.

The string is not truncated if the character c is NUL ('\0'). pos must be in the position between 0 and b->slen inclusive, otherwise BSTR_ERR will be returned.

bSetCstrChar()

BSTR_PUBLIC int bSetCstrChar	(	bstring	a,
		int	pos,
		char	c
	)

Sets the character at position pos to the character c in the bstring a.

If the character c is NUL ('\0') then the string is truncated at this point. Note: this does not enable any other '\0' character in the bstring as terminator indicator for the string. pos must be in the position between 0 and b->slen inclusive, otherwise BSTR_ERR will be returned.

bsFromBstr()

BSTR_PUBLIC struct bStream* bsFromBstr

(

const bstring

b

)

Create a bStream whose contents are a copy of the bstring passed in.

This allows the use of all the bStream APIs with bstrings.

Here is the call graph for this function:

bStr2NetStr()

BSTR_PUBLIC char* bStr2NetStr

(

const bstring

b

)

Convert a bstring to a netstring.

See http://cr.yp.to/proto/netstrings.txt for a description of netstrings.

Note: 1) The value returned should be freed with a call to bcstrfree() at the point when it will no longer be referenced to avoid a memory leak. 2) If the returned value is non-NULL, then it also '\0' terminated in the character position one past the "," terminator.

Here is the call graph for this function:

bStrfTime()

BSTR_PUBLIC bstring bStrfTime	(	const char *	fmt,
		const struct tm *	timeptr
	)

Takes a format string that is compatible with strftime and a struct tm pointer, formats the time according to the format string and outputs the bstring as a result.

Note that if there is an early generation of a '\0' character, the bstring will be truncated to this end point.

bsUuDecode()

BSTR_PUBLIC struct bStream* bsUuDecode	(	struct bStream *	sInp,
		int *	badlines
	)

Creates a bStream which performs the UUDecode of an an input stream.

If there are errors in the decoding, they are counted up and returned in "badlines", if badlines is not NULL. It is assumed that the "begin" and "end" lines have already been stripped off. The potential security problem of writing the filename in the begin line is something that is beyond the scope of a portable library.

Here is the call graph for this function:

Here is the caller graph for this function:

bUuDecodeEx()

BSTR_PUBLIC bstring bUuDecodeEx	(	const bstring	src,
		int *	badlines
	)

Performs a UUDecode of a block of data.

If there are errors in the decoding, they are counted up and returned in "badlines", if badlines is not NULL. It is assumed that the "begin" and "end" lines have already been stripped off. The potential security problem of writing the filename in the begin line is something that is beyond the scope of a portable library.

Here is the call graph for this function:

bUuEncode()

BSTR_PUBLIC bstring bUuEncode

(

const bstring

src

)

Performs a UUEncode of a block of data.

The "begin" and "end" lines are not appended.

Here is the call graph for this function:

bwsBuffLength()

BSTR_PUBLIC int bwsBuffLength	(	struct bwriteStream *	stream,
		int	sz
	)

Set the length of the buffer used by the bwsStream.

If sz is zero, the length is not set. This function returns with the previous length.

bwsClose()

BSTR_PUBLIC void* bwsClose

(

struct bwriteStream *

stream

)

Close the bwriteStream, and return the handle to the stream that was originally used to open the given stream.

Note that even if the stream is at EOF it still needs to be closed with a call to bwsClose.

Here is the call graph for this function:

bwsWriteBlk()

BSTR_PUBLIC int bwsWriteBlk	(	struct bwriteStream *	stream,
		void *	blk,
		int	len
	)

Send a block of data a bwriteStream.

If the stream is at EOF BSTR_ERR is returned.

bwsWriteBstr()

BSTR_PUBLIC int bwsWriteBstr	(	struct bwriteStream *	stream,
		const bstring	b
	)

Send a bstring to a bwriteStream.

If the stream is at EOF BSTR_ERR is returned. Note that there is no deterministic way to determine the exact cut off point where the core stream stopped accepting data.

bYDecode()

BSTR_PUBLIC bstring bYDecode

(

const bstring

src

)

Performs a YDecode of a block of data.

See: http://www.yenc.org/whatis.htm, http://www.yenc.org/yenc-draft.1.3.txt

Here is the call graph for this function:

bYEncode()

BSTR_PUBLIC bstring bYEncode

(

const bstring

src

)

Performs a YEncode of a block of data.

No header or tail info is appended.

See: http://www.yenc.org/whatis.htm, http://www.yenc.org/yenc-draft.1.3.txt

Here is the call graph for this function: