2.
A basic conversion consists of from and to phases. Search of codec name is
case insensitive.
. ISO-8859-1 : UTF-8
from
to
Figure 1: Basic two phases conversion
Between from and to phases, we can have an inter phase.
. UTF-8 : UPPER : UTF-8
from
inter
to
Figure 2: Conversion with inter-mapping phase
There can be more than one inter phases.
. UTF-8 : UPPER : FULL : UTF-8
from
inter
inter
to
Figure 3: Conversion with multiple inter-mapping phases
An inter phase can be used standalonely, mostly in programmatic way.
. HALF
inter
Figure 4: Standalone inter-mapping phase
Conversions can be cascaded with pipe symbol. In most cases it is equivalent
to shell pipe unless the use of codecs manipulating ﬂag (described in section
2.2).
. UTF-8 : BIG5 | BIG5 : UTF-8
from
to
from
to
Figure 5: Cascaded conversions
ASCII-compatible codecs are designed to exclude ASCII part and named as
FOO, with alias FOO ⇒ FOO,ASCII or ASCII, FOO.
2

3.
1.2
Codecs & Fallback
A phase consists of one or more codecs, separated by comma. The latter
codecs will be utilized if and only if the former codecs fail to consume the
incoming data, once a codec ﬁnish its task, the ﬁrst codec will be up again for
upcoming data.
. UTF-8 : ASCII , 3F
from
to
Figure 6: Fallback codec
1.3
Codec argument
Some codecs take arguments, after the hash symbol.
. UTF-8 : ASCII , ANY#3F
Figure 7: Passing argument to codec
Some codecs take arguments in key-value form. Argument name and value
consist of numbers, alphabets, hyphen and underscore, binary data are represented in hexadecimal form.
. UTF-8 : ASCII , ESCAPE#PREFIX=2575
Figure 8: Passing argument to codec in key-value form
Multiple arguments can be passed by being concatenated with ampersand.
. UTF-8 : ASCII , ESCAPE#PREFIX=262378&SUFFIX=3B
Figure 9: Passing multiple arguments to codec
List of data can be passed in dot-separated form.
. ANY#013F.0121 : ASCII
Figure 10: Data list
3

8.
3.3.1
BSDCONV HOLD
This is default output mode after bsdconv init(). Usually used with BSDCONV AUTOMALLOC or BSDCONV PREMALLOCED to get squeezed output.
3.3.2
BSDCONV AUTOMALLOC
Output buﬀer will be allocated dynamically, the actual buﬀer size will be
ins->output.len + output content length, it is useful when you need to have
terminating null byte.
3.3.3
BSDCONV PREMALLOCED
If ins->output.data is NULL, the total length of content to be output will
be put to ins->output.len, but output will still be hold in memory. Otherwise,
bsdconv() will ﬁll as much unfragmented data as possible within the buﬀer size
limit speciﬁed at ins->output.len.
3.3.4
BSDCONV FILE
Output will be fwrite() to the given FILE * at ins->output.data.
3.3.5
BSDCONV FD
Output will be write() to the given (int) ﬁle descriptor at ins->output.data.
Casting to intptr t (deﬁned in <stdint.h>) is needed to eliminate compiler
warning.
3.3.6
BSDCONV NULL
Output will be discard. This is usually used with evaluating conversion (see
section 3.4).
3.4
Counters
Counters are listed in ins->counter in linked-list with following structure.
struct b s d con v_co unt er _ ent ry {
char * key ;
bs dconv_count er_t val ;
struct b sdco nv_ c o u n te r _e n t r y * next ;
};
IERR and OERR are mandatory error counters.
8