<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>libini_config: The INI configuration interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libini_config
 <span id="projectnumber">0.5.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">The INI configuration interface </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The goal of the this interface is to allow applications to read configuration from an INI file.</p>
<p>So why yet another library to read data from an INI file? As we started the SSSD project we looked around for a open source library that would meet the following requirements:</p><ul>
<li>Is written in C (not C++)</li>
<li>Is lightweight.</li>
<li>Has an live community.</li>
<li>Supported on multiple platforms .</li>
<li>Can evolve as we build SSSD solution.</li>
<li>Can deal with different types of values including arrays.</li>
<li>Can deal with sections that are related to each other and can form a hierarchy of sections.</li>
<li>Has a compatible license we can use.</li>
</ul>
<p>We have seen several solutions but none was able to fully address our requirements. As a result we started developing our own INI parsing library.</p>
<p>Currently INI parser allows reading and merging INI files and getting a resulting configuration in one object.</p>
<p>One of the main advantages of this interface is that the library is created with the idea of reading the configuration data, not managing it. Thus currently you will not find any function that alters the configuration data read from the files. There is a set of proposed enhancements to be able to manipulate the configuration data and save it back but there has been no real driver for it. This API is focused on letting applications read data from a file (or files) and interpret it, not to generate configuration files. There are all sorts of different tools that already do that.</p>
<p>The INI configuration interface uses COLLECTION (see libcollection interface) to store data internally.</p>
<p>Concepts:</p><ul>
<li>INI file consists of the key value pairs.</li>
<li>Keys and values are separated by the equal sign. Spaces around equal sign are trimmed. Everything before the equal sign is the key, everything after is the value.</li>
<li>Comments are the lines that start with ";" or "#" in the first position of the line.</li>
<li>Library now supports multi-line values. Values that span across multiple lines should start with a single space on every new line.</li>
<li>After being read both keys and values are stored in the internal objects.</li>
<li>Application configuration can consist from multiple files. For example, there can be a generic file in /etc containing configuration for all applications of a particular class running on a box and then there might be a special file with parameters specific for each application in the /etc/whatever.d directory. Interface does not allow reading multiple files in one call. Instead files need to be read separately and then merged together. A helper function to do so might be added later.</li>
<li>If there is no section in the file or there are key value pairs declared before the first section, those pairs will be placed into the default section with the name "default".</li>
<li>All values are treated as strings. Spaces are trimmed at the beginning and the end of the value. The value ends at the end of the line. If values is too long, an error will be returned.</li>
<li>Parsing of a value happens when a caller tries to interpret the value. The caller can use different functions to do this. The value can be treated as numeric, logical, string, binary, array of strings or array of numbers. In case of arrays parsing functions accept separators that will be used to slice the value into the array of elements.</li>
<li>If there is any error parsing section and key values it can be intercepted by the caller. There are different modes that the library supports regarding error handling. See details in the description of individual functions.</li>
<li>The library allows ini files with fragmented sections. This means that a section can be scattered across the file. Flags control what to do in such situation.</li>
<li><p class="startli">The library allows storing and retrieving multiple key value pairs with the same key in one section.</p>
<p class="startli"><em>There is a deprecated interface that can be found in ini_config.h. This interface is supported only for backwards compatibility and should not be used.</em> </p>
</li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-release
>
by-pkgid
>
f1fdcdb82c21d8820a1f9ab48439717f
>
files
>
44
