PXLIB(3)

📦 version 0.6.10, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 PXLIB(3) 💖

okay bestie, sit down, hydrate, because we're about to talk about pxlib — and no, it's not a skincare brand, it's the manual page for the library that reads and writes Paradox databases. 💅

✨ NAME ✨

pxlib — the library that lets you read and write Paradox databases. that's the whole vibe. 🦋

🌸 DESCRIPTION 🌸

So pxlib is a library for reading and writing Paradox databases, and ngl, it is far from being complete — but bestie, it is genuinely so helpful if you're on unix and you need to handle paradox databases, blob files, primary and secondary indexes. it's giving "small but mighty". 🔥

pxlib is a C-library with bindings for Python and PHP. The PHP one is part of PECL (http://pecl.php.net). This documentation only covers the functions of the C-library, but most of what's said here applies to the other language bindings too, iykyk. The PHP extension of pxlib is documented in PEAR, and the extension is called Paradox.

This library is the base for a gnumeric plugin that got officially added to gnumeric in version 1.4.0. pxlib is also used by hk_classes, which is itself the database access utilized by knoda (http://www.knoda.org). iconic lineage tbh. 👑

🚀 GETTING STARTED 🚀

Programs that want to use pxlib have to include the header file paradox.h and link against libpx. ✨

If the libgsf file access is what you're using, then you include paradox-gsf.h instead of paradox.h. But heads up bestie:

the gsf library cannot be used currently for writing, because pxlib requires read access on the database as well, and libgsf does not support that. 😭 In that case you'll have to create a temporary file first and copy it to the gsf stream afterwards.

Before reading or writing a database file, the library should be initialized with PX_boot(3). It sets the locale and selects the messages in your language as defined by the environment variable LC_ALL. 🌈 And when you're done, the library should be finalized by PX_shutdown(3). close the loop, periodt.

A Paradox database is represented by a pointer to pxdoc_t. That object can be created with PX_new(3) and destroyed with PX_delete(3). You can easily handle several documents at the same time — each one with its own pointer to pxdoc_t. multitasking main character energy fr fr. 💅

pxdoc_t is a pretty chunky structure holding all kinds of info about the paradox file. Most of the info you actually need lives in a substructure called px_head. And px_head is defined like this:

typedef struct px_head pxhead_t;
struct px_head {
  char *px_tablename;
  int px_recordsize;
  char px_filetype;
  int px_fileversion;
  int px_numrecords;
  int px_theonumrecords;
  int px_numfields;
  int px_maxtablesize;
  int px_headersize;
  int px_fileblocks;
  int px_firstblock;
  int px_lastblock;
  int px_indexfieldnumber;
  int px_indexroot;
  int px_numindexlevels;
  int px_writeprotected;
  int px_doscodepage;
  int px_primarykeyfields;
  char px_modifiedflags1;
  char px_modifiedflags2;
  char px_sortorder;
  int px_autoinc;
  int px_fileupdatetime;
  char px_refintegrity;
  struct px_field *px_fields;
};

This structure is defined in paradox.h and you can access it directly — though that is not encouraged at all, because the structure will disappear in the future. 💀 Most header values can already be read with PX_get_value(3) or PX_get_parameter(3), and set by PX_set_value(3) respectively PX_set_parameter(3). use those, bestie, future-you says thanks.

The following example does the basic preparation without creating nor opening a document on the disk:

...
#include <paradox.h>

main(int argc, char *argv[]) {
     pxdoc_t *pxdoc;

     PX_boot();
     pxdoc = PX_new();
     PX_delete(pxdoc);
     PX_shutdown();
}

To actually read a Paradox database from disk you'll have to call

int PX_open_file (pxdoc_t *pxdoc, const char *filename);

int PX_open_fp (pxdoc_t *pxdoc, FILE *fp);

PX_open_file(3) opens an existing file with the given file name, while PX_open_fp(3) uses an already open file. Both of them need a pointer to pxdoc_t. 🫶

Extending the previous example with one of those two functions to open a database is just another small step, like this:

...
#include <paradox.h>

main(int argc, char *argv[]) {
     pxdoc_t *pxdoc;

     PX_boot();
     pxdoc = PX_new();
     PX_open_file(pxdoc, "test.db");
     PX_close(pxdoc);
     PX_delete(pxdoc);
     PX_shutdown();
}

The database has to be closed with PX_close(3). And lowkey important: PX_close(3) will only close the file if it was opened by PX_open_file(3). PX_close(3) is crucial because it also flushes unwritten blocks to disk. don't skip it. 🚨

There are more sophisticated functions to create the handle for the Paradox database. They're used when error handling and memory management shall be controlled by the calling application. Check the manual pages PX_new2(3) and PX_new3(3) for a detailed description, or read the section about memory management and error handler below. 📚

If you'd rather create a brand new Paradox database, the above example must call

int PX_create_file (pxdoc_t *pxdoc, pxfield_t *fields, int numfields,
const char *filename, int type);

instead of PX_open_file(3). Creating a Paradox file requires three further parameters to specify the database layout and the file type, e.g. pxfFileTypNonIndexDB. This function can be used to create both databases and primary index files.

Secondary index files are not supported before version <= 0.6.0, due to several bugs in pxlib. 💀

Since the format of a secondary index file is identical to a database file, there's actually no need for special support of secondary indexes — it's left to the application to create them itself. And pxlib >= 0.6.0 can open databases for reading and writing, providing four new functions for this purpose. They're described in the section Modifying a database. ✨

Each field of the database is described by a structure:

typedef struct px_field pxfield_t;
struct px_field {
  char *px_fname;
  char px_ftype;
  int px_flen;
  int px_fdc;
};

The memory for the field array must be allocated by the calling application using pxlibs' memory management functions — but it will be freed by pxlib. For a list of available file types see the man page of PX_create_fp(3). 🎀

📖 READING RECORDS FROM A DATABASE 📖

Data in a Paradox database is organized in records containing fields. Which is much like other formats, e.g. dBase or a relational database system. Fields can be of 17 different data types as listed below. Field values are stored in sequential order in a record. A complete record is read by one of these functions:

int PX_get_record (pxdoc_t *pxdoc, int recno, char *data, int deleted);

int PX_get_record2 (pxdoc_t *pxdoc, int recno, char *data, int deleted,
pxdatablockinfo_t *pxdbinfo);

The second function returns additional data about the internal location of the record within the file, which is mostly valuable for debugging or creating a secondary index. 🔍 Both functions need a record number starting at 0 for the first record, and a memory area large enough for the record. The size of that area can be determined by the function PX_get_value(3) when recordsize is passed as the value name. The record will be read into that piece of memory straight from the database file without modifications.

Paradox files can be encrypted. pxlib will automatically decrypt a file while reading, without the need to supply a password. That's possible because of a very weak encryption algorithm and because the password is stored in the database file itself. 🙈 (yes really. it's giving "security" with air quotes.)

Once the record data has been read, it can be accessed with a number of different functions depending on the field type. The following list contains the field type and the function needed to retrieve the value. Nothing can prevent you from accessing the record data in a different way if you know what you're doing. 😌

`pxfAlpha`

int PX_get_data_alpha (pxdoc_t *pxdoc, char *data, int len, char **value);

The field value will be automatically converted from the encoding used in the database file to the encoding set by PX_set_parameter(3) with parameter name set to targetencoding. The string will be null terminated.

This function allocates memory for the field data which must be freed by the application. 💅 The chunk of memory can be different from len when encoding involves conversion from a 1-byte to a 2-byte character representation. That's also why the application can't precisely allocate the memory for the data — it must be left to pxlib. Read the section about Memory allocation for more details.

`pxfDate`

int PX_get_data_long (pxdoc_t *pxdoc, char *data, int len, long *value);

Fields of type date are actually 4 byte integer values counting days since jan-00-0000. To convert it into 3 single integers for year, month and day, you'll have to add 1721425 to the value and call the function

void PX_SdnToGregorian (long int *value, int *year, int *month, int *day);

in order to get a valid date. The value 1721425 is the number of days between the start of the julian calendar (4714 BC) and jan-00-0000. len must be set to 4. 📅

`pxfShort`

int PX_get_data_short (pxdoc_t *pxdoc, char *data, int len, short int *value);

This type is a short integer which is 2 bytes long. len must be set to 2.

`pxfLong`, `pxfAutoInc`

int PX_get_data_long (pxdoc_t *pxdoc, char *data, int len, long *value);

This type is an integer which is 4 bytes long. len must be set to 4.

`pxfNumber`, `pxfCurrency`

int PX_get_data_double (pxdoc_t *pxdoc, char *data, int len, double *value);

These types are floating point numbers. len must be set to 8.

`pxfLogical`

int PX_get_data_byte (pxdoc_t *pxdoc, char *data, int len, char *value);

The extracted value is either 0 (false) or <0 (true). len must be set to 1. ✅❌

`pxfBLOb`, `pxfMemoBLOb`, `pxFmtMemoBLOb`

int PX_get_data_blob (pxdoc_t *pxdoc, char *data, int len, int *modnr, int *blobsize, char **value);

Heads up: this function may not in any case succeed. 😭 You should call PX_set_blob_file(3) before, to make sure even blobs in a separate blob file can be retrieved. See the section about reading blobs for more information.

`pxfOLE`

This type is not supported, because there is too little known about it. Accessing fields of type pxfOLE like fields of type pxfBLOb may work. 🙈

`pxfGraphic`

int PX_get_data_graphic (pxdoc_t *pxdoc, char *data, int len, int *modnr, int *blobsize, char **value);

This function has not been tested very well. 🧚

to be continued bestie, there's more where that came from… 💜

pxfTime — grab it with PX_get_data_long(3), same as the field type pxfDate is documented. The number you get back is milli seconds since midnight. That's it, that's the whole vibe.
pxfTimestamp — this one's a PX_get_data_double(3) situation, and then you turn that timestamp into a string with:

char *PX_timestamp2string (pxdoc_t *pxdoc, double *value, const char *format);

PX_timestamp2string(3) takes a format string (all the deets on it live on that function's own manual page) and hands you back a string. Orrr you can just process the value yourself, no gatekeeping. What does the value actually mean? It's the number of seconds since jan-00-0000. Divide it by 86400 and convert it to an integer and boom, you've got the value that lives in fields of type pxfTime. Math girlies rise 🧮✨

pxfBCD

int PX_get_data_bcd (pxdoc_t *pxdoc, char *data, int len, char **value);

Heads up bestie, this function allocates memory for the field data, and you have to free it. It's not gonna do it for you. 💅

pxfBytes

int PX_get_data_bytes (pxdoc_t *pxdoc, char *data, int len, char **value);

Behaves just like PX_get_data_alpha(3)… except the character conversion doesn't happen at all. It will always copy exactly len bytes. Also allocates memory for the field data which must be freed by the application. Same rules, same responsibility 🫶

Okay so every single one of these functions takes the current Paradox database object as the first argument. Second argument? The start of the field data. For the first field that's literally the beginning of the whole record. The second field starts at an offset of length(first field), the third field starts at length(first field) plus length(second field), and so on forever and ever amen. The len is the size of the field. And the last parameter is a pointer to the data converted to an equivalent C type. Each function returns 0 on success or a value < 0 if something went wrong.

⚠️ Nobody is stopping you from accessing the data with the wrong function, or pointing at the wrong position in the record. No one. Not a single soul. So like… don't. Check the manual page of each function for the full detailed description before you go rogue.

Sequentially reading records and fields from a Paradox database looks like the next simplified example. It's giving big switch statement energy:

for(j=0; j<pxh->px_numrecords; j++) {
  int offset;
  if(PX_get_record(pxdoc, j, data)) {
    offset = 0;
    pxf = pxh->px_fields;
    for(i=0; i<pxh->px_numfields; i++) {
      switch(pxf->px_ftype) {
        case pxfAlpha: {
          char *value;
          if(0 < PX_get_data_alpha(pxdoc, &data[offset], pxf->px_flen, &value)) {
            // ...
            pxdoc->free(pxdoc, value);
          } else {
            // ...
          }
          break;
        }
        case pxfDate: {
          long value;
          int year, month, day;
          if(0 < PX_get_data_long(pxdoc, &data[offset], pxf->px_flen, &value)) {
            PX_SdnToGregorian(value+1721425, &year, &month, &day);
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfShort: {
          short int value;
          if(0 < PX_get_data_short(pxdoc, &data[offset], pxf->px_flen, &value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfAutoInc:
        case pxfLong: {
          long value;
          if(0 < PX_get_data_long(pxdoc, &data[offset], pxf->px_flen, &value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfTimestamp: {
          double value;
          if(0 < PX_get_data_double(pxdoc, &data[offset], pxf->px_flen, &value)) {
            char *str = PX_timestamp2string(pxdoc, value, "Y-m-d H:i:s");
            // ...
            pxdoc->free(pxdoc, str);
          } else {
            // ...
          }
          break;
        }
        case pxfTime: {
          long value;
          if(0 < PX_get_data_long(pxdoc, &data[offset], pxf->px_flen, &value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfCurrency:
        case pxfNumber: {
          double value;
          if(0 < PX_get_data_double(pxdoc, &data[offset], pxf->px_flen, &value)) {
            // ...
          } else {
            // ...
          }
          break;
        }
        case pxfLogical: {
          char value;
          if(0 < PX_get_data_byte(pxdoc, &data[offset], pxf->px_flen, &value)) {
            if(value)
              // ...
            else
              // ...
          } else {
            // ...
          }
          break;
        }
        case pxfBLOb:
        case pxfGraphic:
        case pxfOLE:
        case pxfMemoBLOb:
        case pxfFmtMemoBLOb: {
            char *blobdata;
            int mod_nr, size, ret;
            if(pxf->px_ftype == pxfGraphic)
              ret = PX_get_data_graphic(pxdoc, &data[offset], pxf->px_flen, &mod_nr, &size, &blobdata);
            else
              ret = PX_get_data_blob(pxdoc, &data[offset], pxf->px_flen, &mod_nr, &size, &blobdata);
            if(ret > 0) {
              if(blobdata) {
                // ...
                pxdoc->free(pxdoc, blobdata);
              } else {
                // ...
              }
            }
            break;
        }
        case pxfBCD: {
          char *value;
          int ret;
          if(0 < (ret = PX_get_data_bcd(pxdoc, &data[offset], pxf->px_fdc, &value))) {
            // ..
            pxdoc->free(pxdoc, value);
          } else if(ret == 0) {
            // ..
          } else {
            // ..
          }
          break;
        }
        case pxfBytes:
          // ..
          break;
        default:
          break;
      }
    }
    offset += pxf->px_flen;
    pxf++;
  } else {
    fprintf(stderr, _("Couldn't get record number %d\n"), j);
  }
}

✍️ WRITING RECORDS INTO A DATABASE ✍️

Write support slid into pxlib in version 0.1.9, but ngl it should still be considered experimental — though there have been reports from users who have successfully used it. So like, it works, but treat it with the respect of a new release 💀

Writing Paradox databases is honestly super similar to reading them. You just swap PX_open_file(3) for PX_create_file(3), and PX_get_record(3) for PX_put_record(3). That's the whole glow-up.

Modifying the above example so it creates a simple database with two columns gives you this:

...
#include <paradox.h>

main(int argc, char *argv[]) {
     pxdoc_t *pxdoc;
     pxfield_t pxf[2];
     int numfields = 2;

     PX_boot();
     pxdoc = PX_new();
     pxf[0].px_fname = PX_strdup(pxdoc, "column1");
     pxf[0].px_ftype = pxfShort;
     pxf[0].px_flen = 2;
     pxf[0].px_fdc = 0;
     pxf[1].px_fname = PX_strdup(pxdoc, "column2");
     pxf[1].px_ftype = pxfAlpha;
     pxf[1].px_flen = 20;
     pxf[1].px_fdc = 0;
     PX_create_file(pxdoc, pxf, numfields, "test.db", pxfFileTypNonIndexDB);
     PX_close(pxdoc);
     PX_delete(pxdoc);
     PX_shutdown();
}

🔧 MODIFYING A DATABASE 🔧

Starting from version 0.6.0, pxlib supports opening databases for reading and writing at the same time. Main character behavior honestly. If you're gonna do that, please make sure to open the file for the database in w+, r+, or a+ mode. And you'll also have to use a whole new set of functions, described below 👇

int PX_insert_record (pxdoc_t *pxdoc, pxval_t **data);

PX_insert_record(3) inserts a new record into a database. Fresh data, new entry, slay.

int PX_update_record (pxdoc_t *pxdoc, pxval_t **data, int recno);

PX_update_record(3) updates an existing record in database. Glow-up for one specific record.

int PX_delete_record (pxdoc_t *pxdoc, int recno);

int PX_retrieve_record (pxdoc_t *pxdoc, int recno);

🌐 ENCODING 🌐

Exchanging text is not a problem as long as both parties use the same encoding, or agree to use plain 7 bit ascii. Paradox lets you use any encoding with a known DOS code page, and it saves the corresponding code page number in the header of the database. You can request that number with PX_get_value(3) by passing codepage as the value name. 🎀

Reading fields of type pxfAlpha will return the unmodified value — unless the target encoding has been set by PX_set_parameter(3) to something different from the one stored in the database header. If the target encoding is set differently, PX_get_data_alpha(3) will automatically convert into the requested encoding. This is done either by the iconv or the recode library, depending on which one was found when pxlib was configured. And if both were available? iconv is preferred. Periodt.

🫧 READING BLOBS 🫧

Paradox knows five field types that all represent a type of blob data. Blobs can be stored in the database file, but they're usually stored in an extra file with the extension .MB. pxlib gives you two functions to read blob data:

int PX_get_data_blob (pxdoc_t *pxdoc, char *data, int len, int *modnr, int *blobsize, char **value);

and

int PX_get_data_graphic (pxdoc_t *pxdoc, char *data, int len, int *modnr, int *blobsize, char **value);

The second function must be used for fields of type pxfGraphic. The first function can be safely used for fields of type pxfBLOb, pxfMemoBLOb, and pxfFmtMemoBLOb. iykyk 💅

In order to read blob data from a .MB file, you first have to associate that file with the database file by calling:

int PX_set_blob_file (pxdoc_t *pxdoc, const char *filename);

✍️🫧 WRITING BLOBS 🫧✍️

Writing blobs is still the most experimental part of pxlib. There have already been success stories, but there are also some missing parts in the Paradox file format, which decreases confidence in those files. So like… she's trying her best but proceed with caution 🫶

🧠 MEMORY MANAGEMENT, ERROR HANDLING 🧠

okay so bestie, by default pxlib brings its own memory management and error handling to the party. it's got its whole own setup, fully self-sufficient. 💅 but here's the thing — lots of calling applications already have their own memory management and error handling, and they want everyone to use theirs, which is so valid. so pxlib can be told to use those functions instead, and you do that by calling PX_new3(3) instead of PX_new(3). that's literally it. swap the call, get the custom handlers. iconic. ✨

int PX_new3 (pxdoc_t *psdoc, (errorhandler *) (pxdoc_t *p, int type,
const char *msg, void *data), (allocproc *) (pxdoc_t *p, size_t size,
const char *caller), (reallocproc *) (pxdoc_t *p, void *mem, size_t
size, const char *caller), (freeproc *) (pxdoc_t *p, void *mem), void
*errorhandler_user_data);

now the errorhandler and that last parameter errorhandler_user_data? they let you pass arbitrary data as the last parameter into your very own errorhandler. 🎀 and this is highkey a real-world move — it's quite often used if errors are being output in a widget of a graphical toolkit. like, you just pass the pointer to that widget as errorhandler_user_data and pxlib will pass it forward to the error handler. chef's kiss, no cap. 🫶

🔐 ENCRYPTION 🔐

okay so this one's a vibe check with a warning label. Paradox supports a very weak encryption of the data blocks. yes, "very weak", that's the actual energy here, don't @ me. 🙈

the headers are not encrypted, just so we're clear. the encryption itself is accomplished by three static tables with 256 bytes each and a long integer generated from a password. that integer is called the checksum of the password.

and here's the plot twist: the checksum is stored in the header of the .db file, which makes it feasible to decrypt a file even without knowing the password. 😭 yeah. that's why we said weak.

pxlib reads encrypted files silently without asking for additional information. no prompts, no drama, it just reads. 💜

writing an encrypted file, though? that requires you to supply a password for calculating the checksum. the password can be set with PX_set_parameter(3). once it is set, encryption is automatically turned on. ⭐

bestie, listen: the password must be set before writing any records. the best place to do this is right after calling PX_create_file(3) or PX_create_fp(3). don't be late to this one, fr fr. 🌸

👀 SEE ALSO 👀

the detailed manual pages for each function of the library. go read them, they're giving main character energy. 📚✨

💖 AUTHOR 💖

this manual page was written by Uwe Steinmann <uwe@steinmann.cx>. thank you for your service, king. 👑

and that's the whole page, bestie! this was the PXLIB(3) manual page, dated March 27, 2006 — yeah it's vintage, it's giving retro, we respect the classics. 🦋 go forth and slay your Paradox files. 💅🌈

📦 where this page comes from

debian bookworm: pxlib-dev 0.6.8-1+b1
debian trixie: pxlib-dev 0.6.9-1+b1
ubuntu jammy: pxlib-dev 0.6.8-1
ubuntu noble: pxlib-dev 0.6.8-1
ubuntu questing: pxlib-dev 0.6.9-1
ubuntu resolute: pxlib-dev 0.6.9-1build1
ubuntu stonking: pxlib-dev 0.6.10-1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms