File Utilities

Relevant source files

The following files were used as context for generating this wiki page:

• json_util.c
• json_util.h
• json_print.c
• json_tokener.c
• printbuf.c
• json_object.h

The File Utilities module in libfastjson provides a high-level API for synchronizing JSON object structures with the filesystem. It facilitates the serialization of in-memory fjson_object instances to disk and the deserialization of JSON files back into structured C objects. These utilities serve as a bridge between the core object model and persistent storage or external data streams.

At its core, the module leverages the json_tokener for parsing input streams and the json_print logic for generating output strings. By abstracting file descriptor management and buffer handling, it allows developers to perform complex I/O operations with minimal boilerplate code.
Sources: json_util.c:45-103, json_util.h:28-35

Input Operations: Reading JSON Files

Reading operations transform physical files or open file descriptors into fjson_object pointers. The implementation uses an internal buffer of 4096 bytes (FJSON_FILE_BUF_SIZE) to read data incrementally.

File and Descriptor Parsing Logic

The module provides two primary entry points for input: fjson_object_from_file and fjson_object_from_fd. The former acts as a wrapper that handles file opening and closing, while the latter performs the actual data extraction using a printbuf to accumulate the file contents before passing them to the tokener.

The flow above illustrates how file contents are buffered into memory before being processed by the JSON parser.
Sources: json_util.c:45-81, json_util.h:27, printbuf.c:66-79

Key Input Functions

Function	Description	Source
fjson_object_from_file	Opens a file as O_RDONLY and parses its content into a JSON object.	json_util.c:71-81
fjson_object_from_fd	Reads from an existing file descriptor until EOF and parses the result.	json_util.c:45-69

Output Operations: Writing JSON Files

Output utilities handle the conversion of JSON objects into formatted strings and their subsequent storage in the filesystem.

Serialization and File Persistence

The library supports both standard and extended writing functions. The extended version, fjson_object_to_file_ext, allows the caller to specify formatting flags such as FJSON_TO_STRING_PRETTY or FJSON_TO_STRING_SPACED. The writing process ensures data integrity by using O_TRUNC and O_CREAT with default permissions of 0644.

The sequence diagram details the transition from an in-memory object to a serialized file on disk.
Sources: json_util.c:85-117, json_object.h:60-84

File Output API

Function	Description	Source
fjson_object_to_file	Convenience wrapper for fjson_object_to_file_ext using FJSON_TO_STRING_PLAIN.	json_util.c:121-124
fjson_object_to_file_ext	Writes a JSON object to a file with specific formatting flags.	json_util.c:85-119
fjson_object_write	Directly writes a JSON object to a FILE* stream.	json_print.c:509-512

Primitive Data Parsing

Beyond file I/O, the utility module contains robust parsers for converting strings into C primitive types, specifically addressing cross-platform inconsistencies in system calls like sscanf.

Robust Integer Parsing

The fjson_parse_int64 function includes a specialized workaround for broken sscanf implementations that fail to handle 64-bit integer boundaries or ERANGE errors correctly. It performs a self-test via sscanf_is_broken_test and validates parsed results by re-serializing them to ensure string-to-int-to-string consistency.
Sources: json_util.c:132-217

Numerical Utility Functions

• fjson_parse_int64(buf, retval): Parses a string into a 64-bit integer, handling leading spaces and overflow validation.
• fjson_parse_double(buf, retval): Converts a string to a double-precision floating-point number.
• fjson_type_to_name(type): Maps an enum fjson_type to a human-readable string (e.g., "null", "boolean", "object").
  Sources: json_util.c:126-130, json_util.c:219-241

Summary

The File Utilities in libfastjson provide essential mechanisms for JSON persistence and robust type conversion. By utilizing internal print buffers and safe parsing logic, the module ensures that JSON data can be moved efficiently between memory and disk while maintaining compatibility across different system architectures and sscanf behaviors.
Sources: json_util.c:1-241, json_util.h:1-50