doc/man/econf_readFile.3 - master - githubmirror/libeconf

doc/man/econf_readFile.3
148 строк4 KB
Stefan Schubert
improved Documentation (#246)
15 дек 2025, 19:41
15 дек 2025, 19:41c6b5d16
'\" t
.\"     Title: ECONF_READFILE
.\"    Author: libeconf developers
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2023-12-15
.\"    Manual: libeconf Manual
.\"    Source: libeconf
.\"  Language: English
.\"
.TH "ECONF_READFILE" "3" "2023\-12\-15" "libeconf" "libeconf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
 
.SH "NAME"
econf_readFile \- parse a configuration file

.SH "SYNOPSIS"
      
.sp
.ft B
.nf
#include <libeconf\&.h>
.fi
.ft
.sp

.BI "econf_err econf_readFile(econf_file\ **" "result" ", const\ char\ *" "file_name" ", const\ char\ *" "delim" ", const\ char\ *" "comment" ");"

.SH "DESCRIPTION"
    
.PP
\fBeconf_readFile\fR reads and parses the configuration file specified by \fIfile_name\fR\&. The function allocates a new
\fBeconf_file\fR object, populates it with the parsed data, and stores a pointer to it in \fIresult\fR\&.

.PP
The \fIdelim\fR argument specifies the character (or characters) used to separate keys from values (e\&.g\&., "=" or ":")\&. The
\fIcomment\fR argument specifies the character that introduces a comment (e\&.g\&., "#" or ";")\&. Lines starting with this character are ignored during parsing\&.

.PP
The caller is responsible for freeing the allocated memory by calling \fBeconf_free\fR on \fIresult\fR when it is no longer needed\&.

.SH "RETURN VALUE"

.PP
On success, \fBeconf_readFile\fR returns \fBECONF_SUCCESS\fR\&.

.PP
On failure, a non\-zero error code of type \fBeconf_err\fR is returned\&.

.SH "ERRORS"

.PP
\fBECONF_NOFILE\fR
.RS 4
          The specified \fIfile_name\fR does not exist\&.
.RE

.PP
\fBECONF_NOMEM\fR
.RS 4
          Insufficient memory to allocate the \fIresult\fR structure\&.
.RE

.PP
\fBECONF_MISSING_BRACKET\fR
.br
\fBECONF_TEXT_AFTER_SECTION\fR
.br
\fBECONF_EMPTY_SECTION_NAME\fR
.br
\fBECONF_MISSING_DELIMITER\fR
.RS 4
          The file contains syntax errors and could not be parsed successfully\&.
.RE

.PP
\fBECONF_ARGUMENT_IS_NULL_VALUE\fR
.RS 4
          One of the required arguments (such as \fIresult\fR or \fIfile_name\fR) is NULL\&.
.RE

.SH "EXAMPLE"

.PP
The following example demonstrates how to read a simple configuration file:
    
.sp
.if n \{\
.RS 4
.\}
.nf
      #include <libeconf\&.h>
      #include <stdio\&.h>

      int main(void) {
          econf_file *conf = NULL;
          econf_err err;

          /* Read file with "=" as delimiter and "#" as comment */
          err = econf_readFile(&conf, "/etc/example\&.conf", "=", "#");

          if (err != ECONF_SUCCESS) {
              fprintf(stderr, "Failed to read file: %s\en", econf_errString(err));
              return 1;
          }

          /* \&.\&.\&. Process configuration \&.\&.\&. */

          econf_free(conf);
          return 0;
      }
    
.fi
.if n \{\
.RE
.\}
.sp

.SH APPLICATION USAGE

Default behaviour if entries have the same name in one file: The first hit will be returned\&. Further entries will be ignored\&. This can be changed by setting the environment variable JOIN_SAME_ENTRIES (see econf_set_opt)\&. In that case entries with the same name will be joined to one single entry\&. Keys have to be unique per section\&. Otherwise the behaviour is undefined\&.

.SH "SEE ALSO"
.PP
\fBlibeconf\fR(3),
\fBeconf_free\fR(3),
\fBeconf_writeFile\fR(3),
\fBeconf_errString\fR(3)\&
\fBeconf_set_opt\fR(3)\&.

.RE