barcode 0.94

A library for drawing bar codes

October 1999

by Alessandro Rubini (rubini@{gnu.org,prosa.it})


Overview

The barcode package is mainly a C library for creating bar-code output files. It also includes a command line front-end and (in a foreseeable future) a graphic frontend.

The package is designed as a library because we think the main use for barcode-generation tools is inside more featured applications. The library addresses bar code printing as two distinct problems: creation of bar information and actual conversion to an output format. To this aim we use an intermediate representation for bar codes, which is currently documented in the `ps.c' source file (not in this document).

Note that the library and the accompanying material is released according to the GPL license, not the LGPL one. A copy of the GPL is included in the distribution tarball.

The Underlying Data Structure

Every barcode-related function acts on a data structure defined in the `barcode.h' header, which must be included by any C source file that uses the library. The header is installed by make install.

The definition of the data structure is included here for reference:

struct Barcode_Item {
    int flags;         /* type of encoding and other flags */
    char *ascii;       /* malloced */
    char *partial;     /* malloced too */
    char *textinfo;    /* information about text positioning */
    char *encoding;    /* code name, filled by encoding engine */
    int width, height; /* output units */
    int xoff, yoff;    /* output units */
    int margin;        /* output units */
    double scalef;     /* requested scaling for barcode */
    int error;         /* an errno-like value, in case of failure */
};

The exact meaning of each field and the various flags implemented are described in the following sections.

Even though you won't usually need to act on the contents of this structure, some of the functions in the library receive arguments that are directly related to one or more of these fields.

The Fields

int flags;
The flags are, as you may suspect, meant to specify the exact behaviour of the library. They are often passed as an argument to barcode functions and are discussed in the next section.
char *ascii;
char *partial;
char *textinfo;
char *encoding;
These fields are internally managed by the library, and you are not expected to touch them if you use the provided API. All of them are allocated with malloc.
int width;
int height;
They specify the width and height of the active barcode region (i.e., excluding the white margin), in the units used to create output data (for postscript they are points, 1/72th of an inch, 0.0352 mm). The fields can be either assigned to in the structure or via Barcode_Position(), at your choice. If either value or both are left to their default value of zero, the output engine will assign default values according to the specified scaling factor. If the specified width is bigger than needed (according to the scaling factor), the output barcode will be centered in its requested region. If either the width of the height are too small for the specified scale factor, the output bar code will expand symmetrically around the requested region.
int xoff;
int yoff;
The fields specify offset from the coordinate origin of the output engine (for postscript, position 0,0 is the lower left corner of the page). The fields can be either assigned to in the structure or via Barcode_Position(), at your choice. The offset specifies where the white margin begins, not where the first bar will be printed. To print real ink to the specified position you should set margin to 0.
int margin;
The white margin that will be left around the printed area of the bar code. The same margin is applied to all sides of the printed area. The default value for the margin is defined in `barcode.h' as BARCODE_DEFAULT_MARGIN (10).
double scalef;
The enlarge or shrink value for the bar code over its default dimension. The width and scalef fields interact deeply in the creation of the output, and a complete description of the issues appears later in this section.
int error;
The field is used when a barcode function fails to host an errno-like integer value.

Use of the width and scalef fields.

A width unit is the width of the thinnest bar and/or space in the chosen code; it defaults to 1 point if the output is postscript or encapsulated postscript.

Either or both the code width and the scale factor can be left unspecified (i.e., zero). The library deals with defaults in the following way:

Both unspecified
If both the width and the scale factor are unspecified, the scale factor will default to 1.0 and the width is calculated according to the actual width of the bar code being printed.
Width unspecified
If the width is not specified, it is calculated according to the values of scalef.
Scale factor unspecified
If the scale factor is not specified, it will be chosen so that the generated bar code exactly fits the specified width.
Both specified
The code will be printed inside the specified region according to the specified scale factor. It will be aligned to the left. If, however, the chosen width is too small for the specific bar code and scaling factor, then the code will extend symmetrically to the left and to the right of the chosen region.

The Flags

The following flags are supported by version 0.94 of the library:

BARCODE_ENCODING_MASK
The mask is used to extract the encoding-type identifier from the flags field.
BARCODE_EAN
BARCODE_UPC
BARCODE_ISBN
BARCODE_128B
BARCODE_128C
BARCODE_39
BARCODE_I25
The currently supported encoding types: EAN (13 digits, 8 digits, 13 + 2 addon and 13 + 5 addon), UPC (UPC-A, UPC-E, UPC-A with 2 or 5 digit addon), ISBN (with or without the 5-digit addon), CODE128-B (the whole set of printable ASCII characters), CODE128-C (two digits encoded by each barcode symbol), CODE39 (alphanumeric) and "interleaved 2 of 5" (numeric). See section Supported Encodings
BARCODE_ANY
This special encoding type (represented by a value of zero, so it will be the default) tells the encoding procedure to look for the first encoding type that can deal with a textual string. Therefore, a 11-digit code will be printed as UPC (as well as 6-digit, 11+2 and 11+5), a 12-digit (or 7-digit, or 12+2 or 12+5) as EAN13, an ISBN code (with or without hyphens, with or without add-5) will be encoded in its EAN13 representation, an even number of digits is encoded using CODE128C and a generic string is encoded using CODE128B. Since code-39 offers a much larger representation for the same text string, code128-b is preferred over code39 for alphanumeric strings.
BARCODE_NO_ASCII
Instructs the engine not to print the ascii string on output. By default the bar code is accompanied with an ascii version of the text it encodes.
BARCODE_NO_CHECKSUM
Instructs the engine not to add the checksum character to the output. Not all the encoding types can drop the checksum; those where the checksum is mandatory (like EAN and UPC) just ignore the flag.
BARCODE_OUTPUT_MASK
The mask is used to extract the output-type identifier from the flags field.
BARCODE_OUT_PS
BARCODE_OUT_EPS
The currently supported encoding types: full-page postscript and encapsulated postscript.
BARCODE_OUT_NOHEADERS
The flag instructs the printing engine not to print the header and footer part of the file. This makes sense for the postscript engine but might not make sense for other engines; such other engines will silently ignore the flag.

Functions Exported by the Library

The functions included in the barcode library are declared in the header file barcode.h. They perform the following tasks:

struct Barcode_Item *Barcode_Create(char *text);
The function creates a new barcode object to deal with a specified text string. It returns NULL in case of failure and a pointer to a barcode data structure in case of success.
int Barcode_Delete(struct Barcode_Item *bc);
Destroy a barcode object. Always returns 0 (success)
int Barcode_Encode(struct Barcode_Item *bc, int flags);
Encode the text included in the bc object. Valid flags are the encoding type (other flags are ignored) and BARCODE_NO_CHECKSUM (other flags are silently ignored); if the flag argument is zero, bc->flags will apply. The function returns 0 on success and -1 in case of error. After successful termination the data structure will host the description of the bar code and its textual representation, after a failure the error field will include the reason of the failure.
int Barcode_Print(struct Barcode_Item *bc, FILE *f, int flags);
Print the bar code described by bc to the specified file. Valid flags are the output type, BARCODE_NO_ASCII and BARCODE_OUT_NOHEADERS, other flags are ignored. If any of these flags is zero, it will be inherited from bc->flags which therefore takes precedence. The function returns 0 on success and -1 in case of error (with bc->error set accordingly). In case of success, the bar code is printed to the specified file, which won't be closed after use.
int Barcode_Position(struct Barcode_Item *bc, int wid, int hei, int xoff, int yoff, double scalef);
The function is a shortcut to assign values to the data structure.
int Barcode_Encode_and_Print(char *text, FILE *f, int wid, int hei, int xoff, int yoff, double scalef, int flags);
The function deals with the whole life of the barcode object by calling the other functions; it uses all the specified flags.
int Barcode_Version(char *versionname);
Returns the current version as an integer number of the form major * 10000 + minor * 100 + release. Therefore, version 1.03.5 will be returned as 10305 and version 0.53 as 5300. If the argument is non-null, it will be used to return the version number as a string. Note that the same information is available from two preprocessor macros: BARCODE_VERSION (the string) and BARCODE_VERSION_INT (the integer number).

The barcode frontend program

The barcode program is a front-end to access some features of the library from the command line. It is able to read user supplied strings from the command line or a data file (standard input by default) and encode all of them.

The Command Line

barcode accepts the following options:

--help or -h
Print a usage summary and exit.
-i filename
Identify a file where strings to be encoded are read from. If missing (and if -b is not used) it defaults to standard input. Each data line of the input file will be used to create one barcode output.
-o filename
Output file. It defaults to standard output.
-b string
Specify a single "barcode" string to be encoded. The option can be used multiple times in order to encode multiple strings (this will result in multi-page postscript output or a table of barcodes if -t is specified). The strings must match the encoding chosen; if it doesn't match the program will print a warning to stderr and generate "blank" output (although not zero-lenght). Please note that a string including spaces or other special characters must be properly quoted.
-e encoding
encoding is the name of the chosen encoding format being used. It defaults to the value of the environment variable BARCODE_ENCODING or to auto detection if the environment is also unset.
-g geometry
The geometry argument is of the form "<width> x <height> [+ <xmargin> + <ymargin>]" (with no intervening spaces). The margin values, if missing, default to 0). The specified values must be integer numbers and they represent print points (I plan to add support for different units, like inches and millimeters, but this is currently not supported). The argument is used to place the printout code on the page. Note that an additional white margin of 10 points is added to the printout. If the option is unspecified, BARCODE_GEOMETRY is looked up in the environment, if missing a default size and no margin (but the default 10 points) are used.
-t table-geometry
Used to print several barcodes to a single page, this option is meant to be used to print stickers. The argument is of the form "<columns> x <lines> [+ <leftmargin> + <bottommargin> [- <rightmargin> [- <topmargin>]]]" (with no intervening spaces); if missing, the top and right margin will default to be the same as the bottom and left margin. The margins are specified in print points or in the chosen unit (see -u below). If the option is not specified, BARCODE_TABLE is looked up in the environment, otherwise no table is printed and each barcode will get its own page.
-m margin(s)
Specifies an internal margin for each sticker in the table. The argument is of the form "<xmargin>,<ymargin>" and the margin is applied symmetrically to the sticker. If unspecified, the environment variable BARCODE_MARGIN is used or a default internal margin of 10 points is used.
-n
"Numeric" output: don't print the ASCII form of the code, only the bars.
-c
No checksum character (for encodings that allow it, like code 39, other codes, like UPC or EAN, ignore this option).
-E
Encapsulated postscript (default is normal postscript. When the output is generated a EPS only one text string is encoded.
-p pagesize
Specify a non-default page size. The page size can be specified in millimeters, inches or plain numbers (for example: "210x297mm", "8.5x11in", "595x842"). A page specification as numbers will be interpreted according to the current unit specification (see -u below). If libpaper is available, you can also specify the page size with its name, like "A3" or "letter" (libpaper is a standard component of Debian GNU/Linux, but may be missing elsewhere). The default page size is your system-wide default if libpaper is there, A4 otherwise.
-u unit
Choose the unit used in size specifications. Accepted values are "mm", "cm", "in" and "pt". By default, the program will check BARCODE_UNIT in the environment, and assume points otherwise (this behaviour is compatible with 0.92 and previous versions. If -u appears more than once, each instance will modified the behaviour for the arguments at its right, as the command line is processes left to right. The program internally works with points, and any size is approximated to the nearest multiple of one point. The -u option affect -g (geometry), -t (table) and -p (page size).

Supported Encodings

The program encodes text strings passed either on the command line (with -b) or retrieved from standard input. The text representation is interpreted according to the following rules. When auto-detection of the encoding is enabled (i.e, no explicit encoding type is specified), the encoding types are scanned to find one that can digest the text string.

UPC
The UPC frontend accepts only strings made up of digits (and, if a supplemental encoding is used, a blank to separate it). It accepts strings of 11 digits (UPC-A) or 6 digits (UPC-E). The 12th digit of UPC-A is the checksum and is added by the library, if you pass a 12-digit string it will be rejected as invalid. For UPC-A, a trailing string of 2 digits or 5 digits is accepted as well. Therefore, valid strings look like one of the following: "01234567890" (UPC-A), "012345" (UPC-E), "01234567890 12" (UPC-A, add-2) and "01234567890 12345" (UPC-A add-5).
EAN
The EAN frontend is similar to UPC; it accepts strings of digits, 12 or 7 characters long, the checksum digit is added by the library and a string of 13 or 8 characters is rejected. The add-2 and add-5 extension are accepted for the EAN13 encoding. Valid strings look like one of the following: "123456789012" (EAN-13), "1234567" (EAN-8), "123456789012 12" (EAN-13 with add-2) and "123456789012 12345" (EAN-13 with add-5).
ISBN
ISBN numbers are encoded as EAN-13 symbols, with an optional add-5 trailer. The ISBN frontend of the library accepts real ISBN numbers and deals with any hyphen and, if present, the ISBN checksum character before encoding data. Valid representations for ISBN strings are for example: "1-56592-292-1", "3-89721-122-X" and "3-89721-122-X 06900".
code 128-B
This encoding can represent all of the printing ASCII characters, from the space (32) to DEL (127). The checksum digit is mandatory in this encoding.
code 128-C
The "C" variation of Code-128 uses Code-128 symbols to represent two digits at a time (Code-128 is made up of 104 symbols whose interpretation is controlled by the start symbol being used). Code 128-C is thus the most compact way to represent any even number of digits. The encoder refuses to deal with an odd number of digits because the caller is expected to provide proper padding to an even number of digits. (Since Code-128 includes control symbols to switch charset, it is theoretically possible to represent the odd digit as a Code 128-A or 128-B symbol, but this tool doesn't currently implement this option).
code 39
The code-39 standard can encode uppercase letters, digits, the blank space, plus, minus, dot, star, dollar, slash, percent. Any string that is only composed of such characters is accepted by the code-39 encoder. To avoid loosing information, the encoder refuses to encode mixed-case strings (a lowercase string is nonetheless accepted as a shortcut, but is encoded as uppercase).
interleaved 2 of 5
This encoding can only represent an even number of digits (odd digits are represented by bars, and even digits by the interleaving spaces). The name stresses the fact that two of the five items (bars or spaces) allocated to each symbol are wide, while the rest are narrow. The checksum digit is optional (can be disabled via BARCODE_NO_CHECKSUM). Since the number of digits, including the checksum, must be even, a leading zero is inserted in the string being encoded if needed (this is specifically stated in the specs I have access to).

Bugs and Pending Issues.

The current management of borders/margins is far from optimal. The "default" margin applied by the library interferes with the external representation, but I feel it is mandatory to avoid creating barcode output with no surrounding white space (the problem is especially relevant for EPS output).

Code128-A should be supported.


This document was generated on 24 October 1999 using the texi2html translator version 1.51.