Headers Index Help Within this page: Functions Constants Variables
This library reads and writes comma separated variable formatted text files. When the file is read, all fields are decoded into strings. A number of field output functions are provided to allow strings, integers and real numbers to be output. Alternatively, it can accept strings containing comma separated fields for decoding and it can assemble strings of comma separated fields for use elsewhere in the program.
The rules defining a validly formatted csv file are:
There are a number of possible quote modes. Changes to the quote mode only affect output and take effect immediately. The quote modes are:
The NEVER quote mode is intended to be combined with a nonstandard separator to allow the creating of files suitable for input to database loaders and to the creation of tab-separated files.
Many csv files may be open at once. Each file has a CSV control block that contains the resources and settings applicable to the file. The control block will exist if csvopen() was able to allocate and initialise memory for it. All other functions can be called if the control block pointer is NULL or points to a valid control block, so the pointer should be initialised to NULL when it is declared. Functions passed a NULL control block pointer will return an error code.
This package provides the ability to change both field and line delimiters. It also provides control over the amount of field quoting to be applied to the file. All changes to run conditions should be made by using the csvsetxxxx() functions. All settings are specific to a single file and are stored in the CSV control block. Internal fields within the control block are subject to change without notice. Because of this they should not be accessed directly and must not be modified by the calling program except via the functions provided for this purpose.
Functions that return an integer but have no explicit meaning described for the return value should be assumed to return zero for success and a negative value if an error has occurred.
In all cases a call to csvgeterr() after another function will return zero if no error ocurred and a negative value if an error has ocurred. This can be translated into a displayable string by calling csvgeterrtext(). The current error status is held in a hidden global variable that is common to all active csv files, so it is good practise to check the error status, with csvgeterr() if necessary, after every csv function call and to translate and report the error immediately.
The calling programs should include csv.h and must be linked using -lenviron.
environ - C programming support functions
This program is free software; you can redistribute it and/or
modify it under the terms of the Lesser GNU General Public License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the Lesser GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Copyright (C) 2005 Martin C Gregorie
Contact Martin Gregorie at martin@gregorie.org
#include <csv.h>
CSV *csvclose(CSV *cb);
Close a CSV file and delete the CSV control block, releasing the space it occupies. Returns null.
In: csv.c
Return to the top
#include <csv.h>
int csvgeterr(void);
Retrieve the current error code. Returns zero if there is no error. Errors are positive if they are standard system error codes and negative integers if they are specific to this library.
In: csv.c
Return to the top
#include <csv.h>
char *csvgeterrtext(void);
Return a pointer to a string containing a textual description of the current error. This always returns a string pointer, but the string is empty if there was no current error.
In: csv.c
Return to the top
#include <csv.h>
char *csvgetfield(CSV *f, int n);
Returns a pointer to the the contents of the nth field in the last line read by csvgetline(). Fields are numbered from 0. It returns NULL if called before csvgetline(), n<0 or is beyond the last field. Fields are separated by the current separator character. Fields may be surrounded by "..."; such quotes are removed. Within "...", "" is replaced by a single double quote mark and the separator character has no special meaning. In unquoted fields, quotes are regular characters. There can be an arbitrary number of fields of any length; NULL is returned if memory cannot be obtained to hold the current field or if the attempt to unpack the field fails. Fields must be treated as read-only storage; the caller must make a copy to preserve or change the field contents.
In: csv.c
Return to the top
#include <csv.h>
char *csvgetline(CSV *f);
This reads one line from the open file f. It assumes that all lines are terminated by carriage return, linefeed or EOF. It returns a pointer to the line with the terminator removed or NULL if EOF was encountered. The line may be of any arbitrary length. NULL will be returned if the memory limit is exceeded while the line is being read. The line must be treated as read-only storage. The caller must make a copy to preserve or change its content.
In: csv.c
Return to the top
#include <csv.h>
int csvgetn(CSV *f);
Returns the number of fields in the last line read by csvgetline(). It returns -1 if it is called before csvgetline() is called for the first time. Returns the number of fields in the last line read. Negative values indicate that an error has occurred.
In: csv.c
Return to the top
#include <csv.h>
CSV *csvopen(char *name, char *mode);
Open a file for csv use, returning a CSV control block pointer that is specific to the file that has just been opened. Name is the file name, mode the file opening mode, which must be "r" or "w".
If the file name is null, stdin or stdout is opened depending on whether the opening mode is "r" or "w".
If the file name is null and the mode is "s" no file will be opened because it is assumed that input and output will be to strings.
Returns a pointer to the CSV control block on success and null if an error ocurred.
In: csv.c
Return to the top
#include <csv.h>
int csvputint(CSV *f, int val);
Appends val to the current line as a signed numeric string. If it is not the first field on the line it is preceeded by a separator character. Quoting depends on the current quote mode:
Signals an error if the separator character is found in the numeric string if the quote mode is NORMAL, NEVER or MINIMAL. Returns zero if the field is successfully processed and non-zero if errors were encountered.
In: csv.c
Return to the top
#include <csv.h>
int csvputline(CSV *f);
Write the current output line to the file after appending the current newline character(s). The line buffer is cleared. Returns 0 if successful and a non-zero value otherwise.
In: csv.c
Return to the top
#include <csv.h>
int csvputreal(CSV *f, double val);
Identical with csvputint() except that a real number is output.
In: csv.c
Return to the top
#include <csv.h>
int csvputstr(CSV *f, char *val);
Appends val to the current line. If it is not the first field on the line it is preceeded by a separator character. Quoting depends on the current quote mode:
Returns zero if the field is successfully processed and non-zero if errors were encountered.
In: csv.c
Return to the top
#include <csv.h>
void csvsetdebug(int d);
Set CSV library debugging level. Debugging is global to all csv files and may be set at any time. Default is zero (no debugging), 1 traces all csv library calls, and 2 or greater traces internal function operations.
Debugging level 1 is intended as a debugging aid for the calling program. Higher debugging levels are used to debug the internals of this package.
In: csv.c
Return to the top
#include <csv.h>
int csvsetnl(CSV *f, int nlcode);
Set the type of line separator to be output. The value must be one of the following:
In: csv.c
Return to the top
#include <csv.h>
int csvsetquote(CSV *f, int quotemode);
Set the quote mode to one of the defined values. The quotation mode is one of the following:
In: csv.c
Return to the top
#include <csv.h>
int csvsetsep(CSV *f, int sepchar);
Change the field separator character. Returns zero if this is successful and non-zero if the requested separator character is invalid. Valid separators are any printable ASCII character except newline, carriage return or double quote. The change takes effect immediately.
In: csv.c
Return to the top
#include <csv.h>
int csvstrin(CSV *f, char *str);
Input a string containing a list of csv fields to be decoded. The string is terminated by a null and should not contain any newline characters. The string is stored internally and parsed into fields. Returns zero on success and non-zero if errors were encountered.
In: csv.c
Return to the top
#include <csv.h>
char *csvstrout(CSV *f);
Return a string containing a set of csv fields that has just been built. The string will be null terminated and will not contain a trailing newline. csvstrprep() should be called before a set of fields are added to the output string. Returns null if errors were encountered.
In: csv.c
Return to the top
#include <csv.h>
int csvstrprep(CSV *f);
Prepare a receiving area to receive a string to be filled with csv fields for later return by csvstrout(). The separator and quoting control values are reset to their default values. Returns zero if the field was prepared successfully and non-zero if errors were encountered.
In: csv.c
Return to the topline_delimiters | enum line_delimiters { CRLF = 1, CR = 2, LF = 3 }; |
quote_modes | enum quote_modes { NORMAL = 1, ALWAYS = 2, NEVER = 3, MINIMAL = 4 }; |
CSV | typedef struct { FILE *f; char *name; char *line; char *sline; char *oline; char **field; int sused; int maxline; int maxfield; int maxoline; int outptr; int nfield; int quotemode; char sepchar[2]; char nl[3]; } CSV; |