File: udunits2lib.html

package info (click to toggle)
udunits 2.2.26-5
links: PTS, VCS
area: main
in suites: buster
size: 3,332 kB
sloc: sh: 11,655; ansic: 11,070; xml: 2,619; yacc: 491; lex: 331; makefile: 233
file content (2426 lines) | stat: -rw-r--r-- 143,995 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright 2014 University Corporation for Atmospheric Research and contributors.
All rights reserved.

This software was developed by the Unidata Program Center of the
University Corporation for Atmospheric Research (UCAR)
<http://www.unidata.ucar.edu>.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

1) Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
   2) Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
   3) Neither the names of the development group, the copyright holders, nor the
      names of contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.
   4) This license shall terminate automatically and you may no longer exercise
      any of the rights granted to you by this license as of the date you
      commence an action, including a cross-claim or counterclaim, against
      the copyright holders or any contributor alleging that this software
      infringes a patent. This termination provision shall not apply for an
      action alleging patent infringement by combinations of this software with
      other software or hardware.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE. -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>The UDUNITS-2 C API Guide</title>

<meta name="description" content="The UDUNITS-2 C API Guide">
<meta name="keywords" content="The UDUNITS-2 C API Guide">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="#Top" rel="start" title="Top">
<link href="#Complete-Index" rel="index" title="Complete Index">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="dir.html#Top" rel="up" title="(dir)">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<h1 class="settitle" align="center">The UDUNITS-2 C API Guide</h1>


<a name="SEC_Contents"></a>
<h2 class="contents-heading">Table of Contents</h2>

<div class="contents">

<ul class="no-bullet">
  <li><a name="toc-Synopsis-1" href="#Synopsis">1 Synopsis</a></li>
  <li><a name="toc-What_0027s-a-Unit-Package-Good-For_003f" href="#Why">2 What&rsquo;s a Unit Package Good For?</a></li>
  <li><a name="toc-Unit_002dSystems-1" href="#Unit_002dSystems">3 Unit-Systems</a>
  <ul class="no-bullet">
    <li><a name="toc-Obtaining-a-Unit_002dSystem" href="#Obtaining">3.1 Obtaining a Unit-System</a></li>
    <li><a name="toc-Extracting-Units-from-a-Unit_002dSystem" href="#Extracting">3.2 Extracting Units from a Unit-System</a></li>
    <li><a name="toc-Adding-Units-to-a-Unit_002dSystem" href="#Adding">3.3 Adding Units to a Unit-System</a></li>
    <li><a name="toc-Adding-Unit_002dPrefixes-to-a-Unit_002dSystem" href="#Prefixes">3.4 Adding Unit-Prefixes to a Unit-System</a></li>
    <li><a name="toc-Miscelaneous-Operations-on-Unit_002dSystems" href="#Misc">3.5 Miscelaneous Operations on Unit-Systems</a></li>
  </ul></li>
  <li><a name="toc-Converting-Values-Between-Units" href="#Value-Conversion">4 Converting Values Between Units</a></li>
  <li><a name="toc-Parsing-a-String-into-a-Unit" href="#Parsing">5 Parsing a String into a Unit</a></li>
  <li><a name="toc-Unit-Syntax" href="#Syntax">6 Unit Syntax</a>
  <ul class="no-bullet">
    <li><a name="toc-Unit-Specification-Examples" href="#Examples">6.1 Unit Specification Examples</a></li>
    <li><a name="toc-Unit-Grammar" href="#Grammar">6.2 Unit Grammar</a></li>
  </ul></li>
  <li><a name="toc-Formatting-a-Unit-into-a-String" href="#Formatting">7 Formatting a Unit into a String</a></li>
  <li><a name="toc-Unit-Operations" href="#Operations">8 Unit Operations</a>
  <ul class="no-bullet">
    <li><a name="toc-Unary-Unit-Operations" href="#Unary">8.1 Unary Unit Operations</a></li>
    <li><a name="toc-Binary-Unit-Operations" href="#Binary">8.2 Binary Unit Operations</a></li>
  </ul></li>
  <li><a name="toc-Mapping-Between-Identifiers-and-Units" href="#Mapping">9 Mapping Between Identifiers and Units</a>
  <ul class="no-bullet">
    <li><a name="toc-Names-1" href="#Names">9.1 Names</a></li>
    <li><a name="toc-Symbols-1" href="#Symbols">9.2 Symbols</a></li>
  </ul></li>
  <li><a name="toc-The-Handling-of-Time" href="#Time">10 The Handling of Time</a></li>
  <li><a name="toc-Error-Handling" href="#Errors">11 Error Handling</a>
  <ul class="no-bullet">
    <li><a name="toc-Status-of-Last-Operation" href="#Status">11.1 Status of Last Operation</a></li>
    <li><a name="toc-Error_002dMessages" href="#Messages">11.2 Error-Messages</a></li>
  </ul></li>
  <li><a name="toc-The-Units-Database" href="#Database">12 The Units Database</a></li>
  <li><a name="toc-Data-Types" href="#Types">13 Data Types</a></li>
  <li><a name="toc-Index" href="#Complete-Index">Index</a></li>
</ul>
</div>


<a name="Top"></a>
<div class="header">
<p>
Next: <a href="#Synopsis" accesskey="n" rel="next">Synopsis</a>, Previous: <a href="dir.html#Top" accesskey="p" rel="previous">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="UDUNITS_002d2"></a>
<h1 class="top">UDUNITS-2</h1>
<p>This manual describes how to use the C API of the UDUNITS-2 library.
Among other things, the library allows C code to obtain a binary
representation of a unit of a physical quantity, to
operate on such units, and to convert numeric values between compatible
units.
</p>
<p>The library comes with an extensive database of units all referenced to the
SI system of units.
</p>
<p>Copyright 2014 University Corporation for Atmospheric Research and contributors.
All rights reserved.
</p>
<p>This software was developed by the Unidata Program Center of the
University Corporation for Atmospheric Research (UCAR)
&lt;http://www.unidata.ucar.edu&gt;.
</p>
<p>Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
</p>
<p>1) Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
   2) Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
   3) Neither the names of the development group, the copyright holders, nor the
      names of contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.
   4) This license shall terminate automatically and you may no longer exercise
      any of the rights granted to you by this license as of the date you
      commence an action, including a cross-claim or counterclaim, against
      the copyright holders or any contributor alleging that this software
      infringes a patent. This termination provision shall not apply for an
      action alleging patent infringement by combinations of this software with
      other software or hardware.
</p>
<p>THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.
</p>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Synopsis" accesskey="1">Synopsis</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Terse usage display
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Why" accesskey="2">Why</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">What&rsquo;s a unit package good for?
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Unit_002dSystems" accesskey="3">Unit-Systems</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Explanation of unit-systems and how to get one
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Parsing" accesskey="4">Parsing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Converting strings into units
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Syntax" accesskey="5">Syntax</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Syntax for string representation of units
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Formatting" accesskey="6">Formatting</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Converting units into strings
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Value-Conversion" accesskey="7">Value Conversion</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Converting values between units
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Prefixes" accesskey="8">Prefixes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Defining unit prefixes
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Mapping" accesskey="9">Mapping</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Mapping between units and identifiers
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Operations">Operations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Operations on units
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Time">Time</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Handling time
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Errors">Errors</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Error-handling
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Database">Database</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The units database
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Types">Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Data types
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Complete-Index">Complete Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Complete index
</td></tr>
</table>

<hr>
<a name="Synopsis"></a>
<div class="header">
<p>
Next: <a href="#Why" accesskey="n" rel="next">Why</a>, Previous: <a href="#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Synopsis-1"></a>
<h2 class="chapter">1 Synopsis</h2>
<a name="index-synopsis"></a>

<p>Coding:
</p><div class="example">
<pre class="example">#include &lt;udunits2.h&gt;
</pre><blockquote>
<table>
<tr><td><pre class="example">const char*</pre></td><td><pre class="example"><a href="#ut_005fget_005fpath_005fxml_0028_0029">ut_get_path_xml</a>(const char* <var>path</var>);</pre></td></tr>
<tr><td><pre class="example">ut_system*</pre></td><td><pre class="example"><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml</a>(const char* <var>path</var>);</pre></td></tr>
<tr><td><pre class="example">ut_system*</pre></td><td><pre class="example"><a href="#ut_005fnew_005fsystem_0028_0029">ut_new_system</a>(void);</pre></td></tr>
<tr><td><pre class="example">void</pre></td><td><pre class="example"><a href="#ut_005ffree_005fsystem_0028_0029">ut_free_system</a>(ut_system* <var>system</var>);</pre></td></tr>
<tr><td><pre class="example">ut_system*</pre></td><td><pre class="example"><a href="#ut_005fget_005fsystem_0028_0029">ut_get_system</a>(const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fget_005fdimensionless_005funit_005fone_0028_0029">ut_get_dimensionless_unit_one</a>(const ut_system* <var>system</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fget_005funit_005fby_005fname_0028_0029">ut_get_unit_by_name</a>(const ut_system* <var>system</var>, const char* <var>name</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fget_005funit_005fby_005fsymbol_0028_0029">ut_get_unit_by_symbol</a>(const ut_system* <var>system</var>, const char* <var>symbol</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fset_005fsecond_0028_0029">ut_set_second</a>(const ut_unit* <var>second</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fadd_005fname_005fprefix_0028_0029">ut_add_name_prefix</a>(ut_system* <var>system</var>, const char* <var>name</var>, double <var>value</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fadd_005fsymbol_005fprefix_0028_0029">ut_add_symbol_prefix</a>(ut_system* <var>system</var>, const char* <var>symbol</var>, double <var>value</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fnew_005fbase_005funit_0028_0029">ut_new_base_unit</a>(ut_system* <var>system</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fnew_005fdimensionless_005funit_0028_0029">ut_new_dimensionless_unit</a>(ut_system* <var>system</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fclone_0028_0029">ut_clone</a>(const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">void</pre></td><td><pre class="example"><a href="#ut_005ffree_0028_0029">ut_free</a>(ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">const char*</pre></td><td><pre class="example"><a href="#ut_005fget_005fname_0028_0029">ut_get_name</a>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fmap_005fname_005fto_005funit_0028_0029">ut_map_name_to_unit</a>(const char* <var>name</var>, const ut_encoding <var>encoding</var>, const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005funmap_005fname_005fto_005funit_0028_0029">ut_unmap_name_to_unit</a>(ut_system* <var>system</var>, const char* <var>name</var>, const ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fmap_005funit_005fto_005fname_0028_0029">ut_map_unit_to_name</a>(const ut_unit* <var>unit</var>, const char* <var>name</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005funmap_005funit_005fto_005fname_0028_0029">ut_unmap_unit_to_name</a>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">const char*</pre></td><td><pre class="example"><a href="#ut_005fget_005fsymbol_0028_0029">ut_get_symbol</a>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fmap_005fsymbol_005fto_005funit_0028_0029">ut_map_symbol_to_unit</a>(const char* <var>symbol</var>, const ut_encoding <var>encoding</var>, const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005funmap_005fsymbol_005fto_005funit_0028_0029">ut_unmap_symbol_to_unit</a>(ut_system* <var>system</var>, const char* <var>symbol</var>, const ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fmap_005funit_005fto_005fsymbol_0028_0029">ut_map_unit_to_symbol</a>(const ut_unit* <var>unit</var>, const char* <var>symbol</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005funmap_005funit_005fto_005fsymbol_0028_0029">ut_unmap_unit_to_symbol</a>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fis_005fdimensionless_0028_0029">ut_is_dimensionless</a>(const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fsame_005fsystem_0028_0029">ut_same_system</a>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fcompare_0028_0029">ut_compare</a>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fare_005fconvertible_0028_0029">ut_are_convertible</a>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>);</pre></td></tr>
<tr><td><pre class="example">cv_converter*</pre></td><td><pre class="example"><a href="#ut_005fget_005fconverter_0028_0029">ut_get_converter</a>(ut_unit* <var>from</var>, ut_unit* <var>to</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fscale_0028_0029">ut_scale</a>(double <var>factor</var>, const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005foffset_0028_0029">ut_offset</a>(const ut_unit* <var>unit</var>, double <var>offset</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005foffset_005fby_005ftime_0028_0029">ut_offset_by_time</a>(const ut_unit* <var>unit</var>, double <var>origin</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fmultiply_0028_0029">ut_multiply</a>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005finvert_0028_0029">ut_invert</a>(const ut_unit* <var>unit</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fdivide_0028_0029">ut_divide</a>(const ut_unit* <var>numer</var>, const ut_unit* <var>denom</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fraise_0028_0029">ut_raise</a>(const ut_unit* <var>unit</var>, int <var>power</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005froot_0028_0029">ut_root</a>(const ut_unit* <var>unit</var>, int <var>root</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005flog_0028_0029">ut_log</a>(double <var>base</var>, const ut_unit* <var>reference</var>);</pre></td></tr>
<tr><td><pre class="example">ut_unit*</pre></td><td><pre class="example"><a href="#ut_005fparse_0028_0029">ut_parse</a>(const ut_system* <var>system</var>, const char* <var>string</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">char*</pre></td><td><pre class="example"><a href="#ut_005ftrim_0028_0029">ut_trim</a>(char* <var>string</var>, ut_encoding <var>encoding</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fformat_0028_0029">ut_format</a>(const ut_unit* <var>unit</var>, char* <var>buf</var>, size_t <var>size</var>, unsigned <var>opts</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005faccept_005fvisitor_0028_0029">ut_accept_visitor</a>(const ut_unit* <var>unit</var>, const ut_visitor* <var>visitor</var>, void* <var>arg</var>);</pre></td></tr>
<tr><td><pre class="example">double</pre></td><td><pre class="example"><a href="#ut_005fencode_005fdate_0028_0029">ut_encode_date</a>(int <var>year</var>, int <var>month</var>, int <var>day</var>);</pre></td></tr>
<tr><td><pre class="example">double</pre></td><td><pre class="example"><a href="#ut_005fencode_005fclock_0028_0029">ut_encode_clock</a>(int <var>hours</var>, int <var>minutes</var>, double <var>seconds</var>);</pre></td></tr>
<tr><td><pre class="example">double</pre></td><td><pre class="example"><a href="#ut_005fencode_005ftime_0028_0029">ut_encode_time</a>(int <var>year</var>, int <var>month</var>, int <var>day</var>, int <var>hour</var>, int <var>minute</var>, double <var>second</var>);</pre></td></tr>
<tr><td><pre class="example">void</pre></td><td><pre class="example"><a href="#ut_005fdecode_005ftime_0028_0029">ut_decode_time</a>(double <var>value</var>, int* <var>year</var>, int* <var>month</var>, int* <var>day</var>, int* <var>hour</var>, int* <var>minute</var>, double* <var>second</var>, double* <var>resolution</var>);</pre></td></tr>
<tr><td><pre class="example">ut_status</pre></td><td><pre class="example"><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status</a>(void);</pre></td></tr>
<tr><td><pre class="example">void</pre></td><td><pre class="example"><a href="#ut_005fset_005fstatus_0028_0029">ut_set_status</a>(ut_status <var>status</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message</a>(const char* <var>fmt</var>, ...);</pre></td></tr>
<tr><td><pre class="example">ut_error_message_handler</pre></td><td><pre class="example"><a href="#ut_005fset_005ferror_005fmessage_005fhandler_0028_0029">ut_set_error_message_handler</a>(ut_error_message_handler <var>handler</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fwrite_005fto_005fstderr_0028_0029">ut_write_to_stderr</a>(const char* <var>fmt</var>, va_list <var>args</var>);</pre></td></tr>
<tr><td><pre class="example">int</pre></td><td><pre class="example"><a href="#ut_005fignore_0028_0029">ut_ignore</a>(const char* <var>fmt</var>, va_list <var>args</var>);</pre></td></tr>
<tr><td></td></tr>
<tr><td><pre class="example">float</pre></td><td><pre class="example"><a href="#cv_005fconvert_005ffloat_0028_0029">cv_convert_float</a>(const cv_converter* <var>converter</var>, float <var>value</var>);</pre></td></tr>
<tr><td><pre class="example">double</pre></td><td><pre class="example"><a href="#cv_005fconvert_005fdouble_0028_0029">cv_convert_double</a>(const cv_converter* <var>converter</var>, double <var>value</var>);</pre></td></tr>
<tr><td><pre class="example">float*</pre></td><td><pre class="example"><a href="#cv_005fconvert_005ffloats_0028_0029">cv_convert_floats</a>(const cv_converter* <var>converter</var>, const float* <var>in</var>, size_t <var>count</var>, float* <var>out</var>);</pre></td></tr>
<tr><td><pre class="example">double*</pre></td><td><pre class="example"><a href="#cv_005fconvert_005fdoubles_0028_0029">cv_convert_doubles</a>(const cv_converter* <var>converter</var>, const double* <var>const</var> in, <var>size_t</var> count, <var>double</var>* out);</pre></td></tr>
<tr><td><pre class="example">void</pre></td><td><pre class="example"><a href="#cv_005ffree_0028_0029">cv_free</a>(cv_converter* <var>conv</var>);</pre></td></tr>
</table>
</blockquote>
</div>

<p>Compiling:
</p><div class="example">
<pre class="example">c89 -I <em>includedir</em> ...
</pre></div>

<p>Where <em>includedir</em> is the installation-directory for C header
files (e.g., <code>/usr/local/include</code>).
</p>
<p>Linking:
</p><div class="example">
<pre class="example">c89 ... -L<em>libdir</em> -ludunits2 -lexpat ... -lm
</pre></div>

<p>Where <em>libdir</em> is the installation-directory for object code
libraries (e.g., <code>/usr/local/lib</code>).
</p>
<hr>
<a name="Why"></a>
<div class="header">
<p>
Next: <a href="#Unit_002dSystems" accesskey="n" rel="next">Unit-Systems</a>, Previous: <a href="#Synopsis" accesskey="p" rel="previous">Synopsis</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="What_0027s-a-Unit-Package-Good-For_003f"></a>
<h2 class="chapter">2 What&rsquo;s a Unit Package Good For?</h2>

<p>The existance of a software package is justified by what you can do with it.
The three main things you can do with the UDUNIT-2 package are
</p><ol>
<li> <a href="#Value-Conversion">Convert numeric values between compatible units</a>.
</li><li> Convert a string representation of a unit into a binary one &mdash; enabling
the programatic manipulation of units.
There are three ways to do this:
<ul>
<li> <a href="#Extracting">Get the unit</a> from a <a href="#unit_002dsystem">unit-system</a>.
This requires that
you know the unit&rsquo;s name or symbol and that the unit is in a unit-system.  
</li><li> <a href="#Parsing">Parse a string representation of the unit into its binary
representation</a>.
This requires that the string be parsable by <code><a href="#ut_005fparse_0028_0029">ut_parse()</a></code>.
</li><li> <a href="#Operations">Explicity construct the unit from subcomponent units
using unit operations</a>.
</li></ul>
</li><li> <a href="#Formatting">Convert a binary representation of a unit into a string</a> &mdash;
enabling the printing and storing of units in a human-readable form.
</li></ol>
<p>While the above might seem to be trivial activities, their 
general availability at the time might have helped prevent
the <a href="http://en.wikipedia.org/wiki/Mars_Climate_Orbiter">Mars Climate Orbiter</a> fiasco.
</p>
<a name="unit_002dsystem"></a><hr>
<a name="Unit_002dSystems"></a>
<div class="header">
<p>
Next: <a href="#Value-Conversion" accesskey="n" rel="next">Value Conversion</a>, Previous: <a href="#Why" accesskey="p" rel="previous">Why</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unit_002dSystems-1"></a>
<h2 class="chapter">3 Unit-Systems</h2>
<a name="index-unit_002dsystem"></a>
<a name="index-system-of-units"></a>

<p>A unit-system is a set of units that are all defined in terms of the same
set of
<a name="index-unit_002c-base"></a>
<a name="index-base-unit"></a>
base units.
In the SI system of units, for example, the base units are the
meter, kilogram, second, ampere, kelvin, mole, and candela.
(For definitions of these base units, see
<a href="http://physics.nist.gov/cuu/Units/current.html">http://physics.nist.gov/cuu/Units/current.html</a>.)
</p>
<p>In the UDUNITS-2 package, every accessible unit belongs to one and only one
unit-system.  It is not possible to convert numeric values between units
of different unit-systems.  Similarly, units belonging to different
unit-systems always compare unequal.
</p>
<p>There are several categories of operations on unit-systems:
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Obtaining" accesskey="1">Obtaining</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">How to obtain a unit-system.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Extracting" accesskey="2">Extracting</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Getting a unit from a unit-system.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Adding" accesskey="3">Adding</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Adding new units to a unit-system.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Prefixes" accesskey="4">Prefixes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Add new unit-prefixes to a unit-system.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Misc" accesskey="5">Misc</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Miscelaneous unit-system operations.
</td></tr>
</table>

<hr>
<a name="Obtaining"></a>
<div class="header">
<p>
Next: <a href="#Extracting" accesskey="n" rel="next">Extracting</a>, Up: <a href="#Unit_002dSystems" accesskey="u" rel="up">Unit-Systems</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Obtaining-a-Unit_002dSystem"></a>
<h3 class="section">3.1 Obtaining a Unit-System</h3>
<a name="index-database_002c-unit_002c-obtaining-predefined"></a>
<a name="index-unit-database_002c-obtaining-predefined"></a>
<a name="index-unit_002dsystem_002c-obtaining-predefined"></a>
<a name="index-units_002c-obtaining-predefined"></a>
<a name="index-ut_005fread_005fxml_0028_0029_002c-discussion-of"></a>
<p>Typically, you would obtain a unit-system of predefined units by reading
the default unit database using <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>
with a <code>NULL</code> pathname argument.
If this doesn&rsquo;t quite match your needs, then there are alternatives.
Together with the typical solution, the means for obtaining a useful
unit-system are (in order of increasing complexity):
</p>
<ul>
<li> Obtain the default unit-system using <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml</a>(NULL)</code>.
</li><li> Copy and customize the unit database and then
call <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code> with the pathname of the customized
database to obtain a customized unit-system.
</li><li> Same as either of the above but then adding new units to the unit-system using
<code><a href="#ut_005fnew_005fbase_005funit_0028_0029">ut_new_base_unit()</a></code> and
<code><a href="#ut_005fnew_005fdimensionless_005funit_0028_0029">ut_new_dimensionless_unit()</a></code>.
</li><li> Same as the above but also deriving new units using
<a href="#Operations">unit operations</a>
and then adding them to the unit-system using
<a href="#Mapping">unit mapping</a>.
</li><li> Same as the above but starting with an empty unit-system obtained from
<code><a href="#ut_005fnew_005fsystem_0028_0029">ut_new_system()</a></code>,
in which case you will definitely have to start with
<code><a href="#ut_005fnew_005fbase_005funit_0028_0029">ut_new_base_unit()</a></code> and
<code><a href="#ut_005fnew_005fdimensionless_005funit_0028_0029">ut_new_dimensionless_unit()</a></code>.
</li></ul>

<p>You should pass every unit-system pointer to <code><a href="#ut_005ffree_005fsystem_0028_0029">ut_free_system()</a></code>
when you no longer need the corresponding unit-system.
</p>
<a name="ut_005fget_005fpath_005fxml_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fpath_005fxml"></a>Function: <em><code>const char*</code></em> <strong>ut_get_path_xml</strong> <em><code>(const char* <var>path</var>, ut_status* status)</code></em></dt>
<dd><p>Returns the pathname of the XML-formatted unit-database corresponding to 
<var>path</var>. If <var>path</var> is non-<code>NULL</code>, then it is returned; otherwise,
if the environment variable <code>UDUNITS2_XML_PATH</code> is set, then its value is
returned; otherwise, the pathname of the default unit-database is returned.
The value of <code>*status</code> indicates which of these possibilities occurred:
</p>
<dl compact="compact">
<dt><code>UT_OPEN_ARG</code></dt>
<dd><p><var>path</var> is non-<code>NULL</code> and was returned.
</p></dd>
<dt><code>UT_OPEN_ENV</code></dt>
<dd><p><var>path</var> is <code>NULL</code>, the environment variable
<code>UDUNITS2_XML_PATH</code> is set, and its value was returned.
</p></dd>
<dt><code>UT_OPEN_DEFAULT</code></dt>
<dd><p><var>path</var> is <code>NULL</code>, the environment variable
<code>UDUNITS2_XML_PATH</code> is unset, and the pathname of the default unit-database
was returned.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fread_005fxml_0028_0029"></a><dl>
<dt><a name="index-ut_005fread_005fxml"></a>Function: <em><code>ut_system*</code></em> <strong>ut_read_xml</strong> <em><code>(const char* <var>path</var>)</code></em></dt>
<dd><p>Reads the XML-formatted unit-database specified by <var>path</var>
and returns the corresponding unit-sytem.
If <var>path</var> is <code>NULL</code>, then the pathname specified by the
environment variable <code>UDUNITS2_XML_PATH</code> is used if set; otherwise,
the compile-time pathname of the installed, default, unit database is
used.
You should pass the returned pointer to <code>ut_free_system()</code> when you
no longer need the unit-system.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_OPEN_ARG</code></dt>
<dd><p><var>path</var> is non-<code>NULL</code> but the file couldn&rsquo;t be opened.
See <code>errno</code> for the reason.
</p></dd>
<dt><code>UT_OPEN_ENV</code></dt>
<dd><p><var>path</var> is <code>NULL</code> and environment variable
<code>UDUNITS2_XML_PATH</code> is set but the file couldn&rsquo;t be opened.
See <code>errno</code> for the reason.
</p></dd>
<dt><code>UT_OPEN_DEFAULT</code></dt>
<dd><p><var>path</var> is <code>NULL</code>, environment variable
<code>UDUNITS2_XML_PATH</code> is unset, and the installed, default, unit
database couldn&rsquo;t be opened.
See <code>errno</code> for the reason.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error.  See <code>errno</code>.
</p></dd>
<dt><code>UT_PARSE</code></dt>
<dd><p>The database file couldn&rsquo;t be parsed.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fnew_005fsystem_0028_0029"></a><dl>
<dt><a name="index-ut_005fnew_005fsystem"></a>Function: <em><code>ut_system*</code></em> <strong>ut_new_system</strong> <em><code>(void)</code></em></dt>
<dd><p>Creates and returns a new unit-system.
On success, the unit-system will be empty
except for the dimensionless unit one.
You should pass the returned pointer to <code>ut_free_system()</code> when you
no longer need the unit-system.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return the following:
</p>
<dl compact="compact">
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error.  See <code>errno</code>.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Extracting"></a>
<div class="header">
<p>
Next: <a href="#Adding" accesskey="n" rel="next">Adding</a>, Previous: <a href="#Obtaining" accesskey="p" rel="previous">Obtaining</a>, Up: <a href="#Unit_002dSystems" accesskey="u" rel="up">Unit-Systems</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Extracting-Units-from-a-Unit_002dSystem"></a>
<h3 class="section">3.2 Extracting Units from a Unit-System</h3>

<p><strong>NOTE\:</strong> This section covers low-level access to the indidual units of a
<a href="#unit_002dsystem">unit-system</a>.
General parsing of arbitrary unit specifications is coverted in
the section <a href="#Parsing">Parsing</a>.
</p>
<p>A <a href="#unit_002dsystem">unit-system</a> contains mappings from identifiers to units (and
vice versa).
Consequently, once you have a unit-system, you can easily
obtain a unit for which you know the name or symbol using
the function <code><a href="#ut_005fget_005funit_005fby_005fname_0028_0029">ut_get_unit_by_name()</a></code> or
<code><a href="#ut_005fget_005funit_005fby_005fsymbol_0028_0029">ut_get_unit_by_symbol()</a></code>.
</p>
<a name="index-getting-a-unit-by-its-name"></a>
<a name="index-unit_002c-getting-by-name"></a>
<a name="ut_005fget_005funit_005fby_005fname_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005funit_005fby_005fname"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_get_unit_by_name</strong> <em><code>(const ut_system* <var>system</var>, const char* <var>name</var>)</code></em></dt>
<dd><p>Returns the unit to which <var>name</var> maps from the unit-system referenced by
<var>system</var> or <code>NULL</code> if no such unit exists.
Name comparisons are case-insensitive.
If this function returns <code>NULL</code>, then
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return 
one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p><var>name</var> doesn&rsquo;t map to a unit of <var>system</var>.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>name</var> is <code>NULL</code>.
</p></dd>
</dl>

<p>You should pass the returned unit to <code>ut_free()</code> when it is no longer
needed.
</p></dd></dl>

<a name="index-getting-a-unit-by-its-symbol"></a>
<a name="index-unit_002c-getting-by-symbol"></a>
<a name="ut_005fget_005funit_005fby_005fsymbol_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005funit_005fby_005fsymbol"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_get_unit_by_symbol</strong> <em><code>(const ut_system* <var>system</var>, const char* <var>symbol</var>)</code></em></dt>
<dd><p>Returns the unit to which <var>symbol</var> maps from the unit-system referenced by
<var>system</var> or <code>NULL</code> if no such unit exists.
Symbol comparisons are case-sensitive.
If this function returns <code>NULL</code>, then
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return 
one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p><var>symbol</var> doesn&rsquo;t map to a unit of <var>system</var>.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>symbol</var> is <code>NULL</code>.
</p></dd>
</dl>

<p>You should pass the returned unit to <code>ut_free()</code> when it is no longer
needed.
</p></dd></dl>

<a name="ut_005fget_005fdimensionless_005funit_005fone_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fdimensionless_005funit_005fone"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_get_dimensionless_unit_one</strong> <em><code>(const ut_system* <var>system</var>)</code></em></dt>
<dd><p>Returns the dimensionless unit one of the unit-system referenced by
<var>system</var>.
While not necessary, the returned pointer may be passed to <code>ut_free()</code>
when you no longer need the unit.
If <var>system</var> is <code>NULL</code>, then this function writes an error-message 
using <code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return <code>UT_BAD_ARG</code>.
</p></dd></dl>

<hr>
<a name="Adding"></a>
<div class="header">
<p>
Next: <a href="#Prefixes" accesskey="n" rel="next">Prefixes</a>, Previous: <a href="#Extracting" accesskey="p" rel="previous">Extracting</a>, Up: <a href="#Unit_002dSystems" accesskey="u" rel="up">Unit-Systems</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Adding-Units-to-a-Unit_002dSystem"></a>
<h3 class="section">3.3 Adding Units to a Unit-System</h3>
<a name="index-adding-units-to-a-unit_002dsystem"></a>
<a name="index-unit_002c-adding-to-a-unit_002dsystem"></a>
<a name="index-unit_002dsystem_002c-adding-a-unit-to"></a>

<p>If you use <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you should not normally need to
add any new units to a unit-system.
</p>
<p>Because you get units via their names or symbols, adding a unit to a
unit-system actually means mapping one or more identifiers (i.e., names
or symbols) to the unit.
Thereafter, you can use <code><a href="#ut_005fget_005funit_005fby_005fname_0028_0029">ut_get_unit_by_name()</a></code> and
<code><a href="#ut_005fget_005funit_005fby_005fsymbol_0028_0029">ut_get_unit_by_symbol()</a></code> to retrieve the unit.
The mapping of identifiers to units is covered <a href="#Mapping">here</a>.
</p>
<p>Having said that, it is possible to create a new base or dimensionless
unit within a unit-system using <code><a href="#ut_005fnew_005fbase_005funit_0028_0029">ut_new_base_unit()</a></code> or
<code><a href="#ut_005fnew_005fdimensionless_005funit_0028_0029">ut_new_dimensionless_unit()</a></code>&mdash;you&rsquo;ll just also have to map
identifiers to the newly-created unit in order to be able to retrieve
it later by identifier.
</p>
<a name="ut_005fnew_005fbase_005funit_0028_0029"></a><dl>
<dt><a name="index-ut_005fnew_005fbase_005funit"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_new_base_unit</strong> <em><code>(ut_system* <var>system</var>)</code></em></dt>
<dd><p>Creates and adds a new base-unit to the unit-system referenced by <var>system</var>.
This function returns the new base-unit.
You should pass the returned pointer to <code>ut_free()</code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
</dl>
<p>If you use <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you should not normally need to call this
function.
</p></dd></dl>

<a name="ut_005fnew_005fdimensionless_005funit_0028_0029"></a><dl>
<dt><a name="index-ut_005fnew_005fdimensionless_005funit"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_new_dimensionless_unit</strong> <em><code>(ut_system* <var>system</var>)</code></em></dt>
<dd><p>Creates and adds a new dimensionless-unit to the unit-system referenced by <var>system</var>.
This function returns the new dimensionless-unit.
You should pass the returned pointer to <code>ut_free()</code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
</dl>
<p>If you use <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you should not normally need to call this
function.
</p></dd></dl>

<hr>
<a name="Prefixes"></a>
<div class="header">
<p>
Next: <a href="#Misc" accesskey="n" rel="next">Misc</a>, Previous: <a href="#Adding" accesskey="p" rel="previous">Adding</a>, Up: <a href="#Unit_002dSystems" accesskey="u" rel="up">Unit-Systems</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Adding-Unit_002dPrefixes-to-a-Unit_002dSystem"></a>
<h3 class="section">3.4 Adding Unit-Prefixes to a Unit-System</h3>
<a name="index-prefixes_002c-adding-to-a-unit_002dsystem"></a>
<a name="index-adding-prefixes-to-a-unit_002dsystem"></a>
<a name="index-unit_002dsystem_002c-adding-prefixes-to-a"></a>

<p>A prefix is a word or symbol that is appended to the beginning of a word or
symbol that represents a unit in order to modify the value of that unit.  For
example, the prefix &ldquo;kilo&rdquo; in the word &ldquo;kiloamperes&rdquo; changes the value
from one ampere to one-thousand amperes.
</p>
<p>If you use <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you should not normally need to
add any new prefixes to a unit-system.
</p>
<a name="ut_005fadd_005fname_005fprefix_0028_0029"></a><dl>
<dt><a name="index-ut_005fadd_005fname_005fprefix"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_add_name_prefix</strong> <em><code>(ut_system* <var>system</var>, const char* <var>name</var>, double <var>value</var>)</code></em></dt>
<dd><p>Adds the name-prefix <var>name</var> with the value <var>value</var>
to the unit-system <var>system</var>.
A name-prefix is something like &ldquo;mega&rdquo; or &ldquo;milli&rdquo;.
Comparisons between name-prefixes are case-insensitive.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>name</var> is <code>NULL</code>, or <var>value</var> is <code>0</code>.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p><var>name</var> already maps to a different value.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fadd_005fsymbol_005fprefix_0028_0029"></a><dl>
<dt><a name="index-ut_005fadd_005fsymbol_005fprefix"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_add_symbol_prefix</strong> <em><code>(ut_system* <var>system</var>, const char* <var>symbol</var>, double <var>value</var>)</code></em></dt>
<dd><p>Adds the symbol-prefix <var>symbol</var> with the value <var>value</var>
to the unit-system <var>system</var>.
A symbol-prefix is something like &ldquo;M&rdquo; or &ldquo;m&rdquo;.
Comparisons between symbol-prefixes are case-sensitive.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>symbol</var> is <code>NULL</code>, or <var>value</var> is <code>0</code>.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p><var>symbol</var> already maps to a different value.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Misc"></a>
<div class="header">
<p>
Previous: <a href="#Prefixes" accesskey="p" rel="previous">Prefixes</a>, Up: <a href="#Unit_002dSystems" accesskey="u" rel="up">Unit-Systems</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Miscelaneous-Operations-on-Unit_002dSystems"></a>
<h3 class="section">3.5 Miscelaneous Operations on Unit-Systems</h3>

<a name="ut_005ffree_005fsystem_0028_0029"></a><dl>
<dt><a name="index-ut_005ffree_005fsystem"></a>Function: <em><code>void</code></em> <strong>ut_free_system</strong> <em><code>(ut_system* <var>system</var>)</code></em></dt>
<dd><p>Frees the unit-system referenced by <var>system</var>.  All unit-to-identifier and
identifier-to-unit mappings are removed.  Use of <code>system</code> after this
function returns results in undefined behavior.
</p></dd></dl>

<a name="ut_005fset_005fsecond_0028_0029"></a><dl>
<dt><a name="index-ut_005fset_005fsecond"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_set_second</strong> <em><code>(const ut_unit* <var>second</var>)</code></em></dt>
<dd><p>Sets the &ldquo;second&rdquo; unit of a unit-system.  This function must be called before
the first call to <code>ut_offset_by_time()</code> for a unit in the same unit-system.
<code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code> calls this function if the
unit-system it&rsquo;s reading contains a unit named &ldquo;second&rdquo;.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>The &ldquo;second&rdquo; unit of <var>system</var> was successfully set.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p>The &ldquo;second&rdquo; unit of <var>system</var> is set to a different unit.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>second</var> is <code>NULL</code>.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Value-Conversion"></a>
<div class="header">
<p>
Next: <a href="#Parsing" accesskey="n" rel="next">Parsing</a>, Previous: <a href="#Unit_002dSystems" accesskey="p" rel="previous">Unit-Systems</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Converting-Values-Between-Units"></a>
<h2 class="chapter">4 Converting Values Between Units</h2>
<a name="index-converting-values-between-units"></a>
<a name="index-unit-conversion"></a>

<p>You can convert numeric values in one unit to equivalent values in
another, compatible unit by means of a converter.
For example
</p>
<div class="example">
<pre class="example">#include &lt;udunits2.h&gt;
...
    ut_unit*      from = ...;
    ut_unit*      to = ...;
    cv_converter* converter = ut_get_converter(from, to);
    double       fromValue = ...;
    double       toValue = cv_convert_double(converter, fromValue);

    cv_free(converter);
</pre></div>

<p>The converter API is declared in the header-file <code>&lt;converter.h&gt;</code>,
which is automatically included by the UDUNITS-2 header-file
(<code>&lt;udunits2.h&gt;</code>) so you don&rsquo;t need to explicitly include it.
</p>
<a name="ut_005fare_005fconvertible_0028_0029"></a><dl>
<dt><a name="index-ut_005fare_005fconvertible"></a>Function: <em><code>int</code></em> <strong>ut_are_convertible</strong> <em><code>(const ut_unit* <var>unit1</var>, uconst t_unit* <var>unit2</var>)</code></em></dt>
<dd><p>Indicates if numeric values in unit <var>unit1</var> are convertible to numeric
values in unit <var>unit2</var> via <a href="#ut_005fget_005fconverter_0028_0029">ut_get_converter()</a>.
In making this determination, dimensionless units are ignored.
This function returns a non-zero value if conversion is possible;
otherwise, <code>0</code> is returned and <a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a> will return one
of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit1</var> or <var>unit2</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_NOT_SAME_SYSTEM</code></dt>
<dd><p><var>unit1</var> and <var>unit2</var> belong to different <a href="#unit_002dsystem">unit-system</a>s.
</p></dd>
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Conversion between the units is not possible (e.g., <var>unit1</var> refers
to a meter and <var>unit2</var> refers to a kilogram.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fget_005fconverter_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fconverter"></a>Function: <em><code>cv_converter*</code></em> <strong>ut_get_converter</strong> <em><code>(ut_unit* const <var>from</var>, ut_unit* const <var>to</var>)</code></em></dt>
<dd><p>Creates and returns a converter of numeric values in the <var>from</var> unit
to equivalent values in the <var>to</var> unit.
You should pass the returned pointer to <code>cv_free()</code> when you
no longer need the converter.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>from</var> or <var>to</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_NOT_SAME_SYSTEM</code></dt>
<dd><p>The units <var>from</var> and <var>to</var> don&rsquo;t belong to the same unit-system.
</p></dd>
<dt><code>UT_MEANINGLESS</code></dt>
<dd><p>The units belong to the same unit-system but conversion between them is
meaningless (e.g., conversion between seconds and kilograms is meaningless).
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
</dl>
</dd></dl>

<a name="cv_005fconvert_005ffloat_0028_0029"></a><dl>
<dt><a name="index-cv_005fconvert_005ffloat"></a>Function: <em><code>float</code></em> <strong>cv_convert_float</strong> <em><code>(const cv_converter* <var>converter</var>, const float <var>value</var>)</code></em></dt>
<dd><p>Converts the single floating-point value <var>value</var> and
returns the new value.
</p></dd></dl>

<a name="cv_005fconvert_005fdouble_0028_0029"></a><dl>
<dt><a name="index-cv_005fconvert_005fdouble"></a>Function: <em><code>double</code></em> <strong>cv_convert_double</strong> <em><code>(const cv_converter* <var>converter</var>, const double <var>value</var>)</code></em></dt>
<dd><p>Converts the single double-precision value <var>value</var> and
returns the new value.
</p></dd></dl>

<a name="cv_005fconvert_005ffloats_0028_0029"></a><dl>
<dt><a name="index-cv_005fconvert_005ffloats"></a>Function: <em><code>float*</code></em> <strong>cv_convert_floats</strong> <em><code>(const cv_converter* <var>converter</var>, const float* <var>in</var>, size_t <var>count</var>, float* <var>out</var>)</code></em></dt>
<dd><p>Converts the <var>count</var> floating-point values starting at <var>in</var>, writing
the new values starting at <var>out</var> and, as a convenience,
returns <var>out</var>.
The input and output arrays may overlap or be identical.
</p></dd></dl>

<a name="cv_005fconvert_005fdoubles_0028_0029"></a><dl>
<dt><a name="index-cv_005fconvert_005fdoubles"></a>Function: <em><code>double*</code></em> <strong>cv_convert_doubles</strong> <em><code>(const cv_converter* <var>converter</var>, const double* <var>in</var>, size_t <var>count</var>, double* <var>out</var>)</code></em></dt>
<dd><p>Converts the <var>count</var> double-precision values starting at <var>in</var>, writing
the new values starting at <var>out</var> and, as a convenience,
returns <var>out</var>.
The input and output arrays may overlap or be identical.
</p></dd></dl>

<a name="cv_005ffree_0028_0029"></a><dl>
<dt><a name="index-cv_005ffree"></a>Function: <em><code>void</code></em> <strong>cv_free</strong> <em><code>(cv_converter* <var>conv</var>)</code>;</em></dt>
<dd><p>Frees resources associated with the converter referenced by <var>conv</var>.
You should call this function when you no longer need the converter.
Use of <var>conv</var> upon return results in undefined behavior.
</p></dd></dl>

<hr>
<a name="Parsing"></a>
<div class="header">
<p>
Next: <a href="#Syntax" accesskey="n" rel="next">Syntax</a>, Previous: <a href="#Value-Conversion" accesskey="p" rel="previous">Value Conversion</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Parsing-a-String-into-a-Unit"></a>
<h2 class="chapter">5 Parsing a String into a Unit</h2>
<a name="index-parsing-a-string-into-a-unit"></a>
<a name="index-string_002c-parsing-into-a-unit"></a>

<p>Here&rsquo;s an example of parsing a string representation of a unit into
its binary representation:
</p>
<div class="example">
<pre class="example">#include &lt;stdlib.h&gt;
#include &lt;udunits2.h&gt;
...
    ut_system*   unitSystem = <a href="#ut_005fread_005fxml_0028_0029">ut_read_xml(NULL)</a>;
    const char* string = &quot;kg.m2/s3&quot;;
    ut_unit*     watt = <a href="#ut_005fparse_0028_0029">ut_parse</a>(unitSystem, string, UT_ASCII);

    if (watt == NULL) {
        /* Unable to parse string. */
    }
    else {
        /* Life is good. */
    }
</pre></div>

<a name="ut_005fparse_0028_0029"></a><dl>
<dt><a name="index-ut_005fparse"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_parse</strong> <em><code>(const ut_system* <var>system</var>, const char* <var>string</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Returns the binary unit representation corresponding to the string unit
representation <var>string</var> in the character-set <var>encoding</var> using the
unit-system <var>system</var>.
<var>string</var> must have no leading or trailing whitespace (see
<code><a href="#ut_005ftrim_0028_0029">ut_trim()</a></code>).
If an error occurs, then this function returns <code>NULL</code> and
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>string</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_SYNTAX</code></dt>
<dd><p><var>string</var> contained a syntax error.
</p></dd>
<dt><code>UT_UNKNOWN</code></dt>
<dd><p><var>string</var> contained an unknown identifier.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code> for the reason.
</p></dd>
</dl>

<p>You should pass the returned unit to <code>ut_free()</code> when it is no longer
needed.
</p></dd></dl>

<a name="ut_005ftrim_0028_0029"></a><dl>
<dt><a name="index-ut_005ftrim"></a>Function: <em><code>size_t</code></em> <strong>ut_trim</strong> <em><code>(char* <var>string</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Removes all leading and trailing whitespace from the NUL-terminated string
<var>string</var>.  Returns <var>string</var>, which is modified if it contained leading
or trailing whitespace.
</p></dd></dl>

<hr>
<a name="Syntax"></a>
<div class="header">
<p>
Next: <a href="#Formatting" accesskey="n" rel="next">Formatting</a>, Previous: <a href="#Parsing" accesskey="p" rel="previous">Parsing</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unit-Syntax"></a>
<h2 class="chapter">6 Unit Syntax</h2>
<a name="index-unit-syntax"></a>
<a name="index-syntax_002c-unit"></a>

<p>For the most part, the UDUNITS-2 package follows the syntax for unit-strings
promulgated by the US National Institute for Standards and Technology (NIST).
Details, of which, can be found at <a href="http://physics.nist.gov/cuu/Units/index.html">http://physics.nist.gov/cuu/Units/index.html</a>.
The one general exception to this is the invention of a syntax for
&ldquo;offset&rdquo;-units (e.g., the definition of the degree Celsius is &ldquo;K @
273.15&rdquo;).
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Examples" accesskey="1">Examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Examples of unit specifications
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Grammar" accesskey="2">Grammar</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Formal unit grammar
</td></tr>
</table>

<hr>
<a name="Examples"></a>
<div class="header">
<p>
Next: <a href="#Grammar" accesskey="n" rel="next">Grammar</a>, Up: <a href="#Syntax" accesskey="u" rel="up">Syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unit-Specification-Examples"></a>
<h3 class="section">6.1 Unit Specification Examples</h3>
<a name="index-unit-specification-examples"></a>
<a name="index-examples_002c-unit-specification"></a>

<blockquote>
<table>
<thead><tr><th>String Type</th><th>Using Names</th><th>Using Symbols</th><th>Comment</th></tr></thead>
<tr><td>Simple</td><td>meter</td><td>m</td></tr>
<tr><td>Raised</td><td>meter^2</td><td>m2</td><td>higher precedence than multiplying or
dividing</td></tr>
<tr><td>Product</td><td>newton meter</td><td>N.m</td></tr>
<tr><td>Quotient</td><td>meter per second</td><td>m/s</td></tr>
<tr><td>Scaled</td><td>60 second</td><td>60 s</td></tr>
<tr><td>Prefixed</td><td>kilometer</td><td>km</td></tr>
<tr><td>Offset</td><td>kelvin from 273.15</td><td>K @ 273.15</td><td>lower
precedence than multiplying or dividing</td></tr>
<tr><td>Logarithmic</td><td>lg(re milliwatt)</td><td>lg(re mW)</td><td>&quot;lg&quot; is base 10, 
&quot;ln&quot; is base e, and &quot;lb&quot; is base 2</td></tr>
<tr><td>Grouped</td><td>(5 meter)/(30 second)</td><td>(5 m)/(30 s)</td></tr>
</table>
</blockquote>

<p>The above may be combined, e.g., &quot;0.1 lg(re m/(5 s)^2) @ 50&quot;.
</p>
<p>You may also look at the <code>&lt;def&gt;</code> elements in <a href="#Database">the
units database</a> to see examples of string unit specifications.
</p>
<p>You may use the <code><a href="udunits2prog.html#Top">(udunits2prog)udunits2</a></code> utility 
to experiment with string unit specifications.
</p>
<hr>
<a name="Grammar"></a>
<div class="header">
<p>
Previous: <a href="#Examples" accesskey="p" rel="previous">Examples</a>, Up: <a href="#Syntax" accesskey="u" rel="up">Syntax</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unit-Grammar"></a>
<h3 class="section">6.2 Unit Grammar</h3>
<a name="index-unit-grammar"></a>
<a name="index-grammar_002c-unit"></a>

<p>Here is the unit-syntax understood by the UDUNITS-2 package.  Words printed
<em>Thusly</em> indicate non-terminals; words printed THUSLY indicate terminals;
and words printed &lt;thusly&gt; indicate lexical elements.
</p>
<div class="example">
<pre class="example"><em>Unit-Spec: one of</em>
        nothing
        <em>Shift-Spec</em>

<em>Shift-Spec: one of</em>
        <em>Product-Spec</em>
        <em>Product-Spec</em> SHIFT REAL
        <em>Product-Spec</em> SHIFT INT
        <em>Product-Spec</em> SHIFT <em>Timestamp</em>

<em>Product-Spec: one of</em>
        <em>Power-Spec</em>
        <em>Product-Spec</em> <em>Power-Spec</em>
        <em>Product-Spec</em> MULTIPLY <em>Power-Spec</em>
        <em>Product-Spec</em> DIVIDE <em>Power-Spec</em>

<em>Power-Spec: one of</em>
        <em>Basic-Spec</em>
        <em>Basic-Spec</em> INT
        <em>Basic-Spec</em> EXPONENT
        <em>Basic-Spec</em> RAISE INT

<em>Basic-Spec: one of</em>
        ID
        &quot;(&quot; <em>Shift-Spec</em> &quot;)&quot;
        LOGREF <em>Product_Spec</em> &quot;)&quot;
        <em>Number</em>

<em>Number: one of</em>
        INT
        REAL

<em>Timestamp: one of</em>
        DATE
        DATE CLOCK
        DATE CLOCK CLOCK
        DATE CLOCK INT
        DATE CLOCK ID
        TIMESTAMP
        TIMESTAMP INT
        TIMESTAMP ID

SHIFT:
        &lt;space&gt;* &lt;shift_op&gt; &lt;space&gt;*

&lt;shift_op&gt;: one of
        &quot;@&quot;
        &quot;after&quot;
        &quot;from&quot;
        &quot;since&quot;
        &quot;ref&quot;

REAL:
        the usual floating-point format

INT:
        the usual integer format

MULTIPLY: one of
        &quot;-&quot;
        &quot;.&quot;
        &quot;*&quot;
        &lt;space&gt;+
        &lt;centered middot&gt;

DIVIDE:
        &lt;space&gt;* &lt;divide_op&gt; &lt;space&gt;*

&lt;divide_op&gt;: one of
        per
        PER
        &quot;/&quot;

EXPONENT:
        ISO-8859-9 or UTF-8 encoded exponent characters

RAISE: one of
        &quot;^&quot;
        &quot;**&quot;

ID: one of
        &lt;id&gt;
        &quot;%&quot;
        &quot;'&quot;
        &quot;\&quot;&quot;
        degree sign
        greek mu character

&lt;id&gt;:
        &lt;alpha&gt; &lt;alphanum&gt;*

&lt;alpha&gt;:
        [A-Za-z_]
        ISO-8859-1 alphabetic characters
        non-breaking space

&lt;alphanum&gt;: one of
        &lt;alpha&gt;
        &lt;digit&gt;

&lt;digit&gt;:
        [0-9]

LOGREF:
        &lt;log&gt; &lt;space&gt;* &lt;logref&gt;

&lt;log&gt;: one of
        &quot;log&quot;
        &quot;lg&quot;
        &quot;ln&quot;
        &quot;lb&quot;

&lt;logref&gt;:
        &quot;(&quot; &lt;space&gt;* &lt;re&gt; &quot;:&quot;? &lt;space&gt;*

DATE:
        &lt;year&gt; &quot;-&quot; &lt;month&gt; (&quot;-&quot; &lt;day&gt;)?

&lt;year&gt;:
        [+-]?[0-9]{1,4}

&lt;month&gt;:
        &quot;0&quot;?[1-9]|1[0-2]

&lt;day&gt;:
        &quot;0&quot;?[1-9]|[1-2][0-9]|&quot;30&quot;|&quot;31&quot;

CLOCK:
        &lt;hour&gt; &quot;:&quot; &lt;minute&gt; (&quot;:&quot; &lt;second&gt;)?

TIMSTAMP:
        &lt;year&gt; (&lt;month&gt; &lt;day&gt;?)? &quot;T&quot; &lt;hour&gt; (&lt;minute&gt; &lt;second&gt;?)?

&lt;hour&gt;:
        [+-]?[0-1]?[0-9]|2[0-3]

&lt;minute&gt;:
        [0-5]?[0-9]

&lt;second&gt;:
        (&lt;minute&gt;|60) (\.[0-9]*)?

</pre></div>

<hr>
<a name="Formatting"></a>
<div class="header">
<p>
Next: <a href="#Operations" accesskey="n" rel="next">Operations</a>, Previous: <a href="#Syntax" accesskey="p" rel="previous">Syntax</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Formatting-a-Unit-into-a-String"></a>
<h2 class="chapter">7 Formatting a Unit into a String</h2>
<a name="index-formatting-a-unit-into-a-string"></a>
<a name="index-unit_002c-formatting-into-a-string"></a>
<a name="index-string_002c-formatting-a-unit-into-a"></a>

<p>Use the <code><a href="#ut_005fformat_0028_0029">ut_format()</a></code> function to obtain the string representation
of a binary unit.
For example, the following gets the definition of the unit &quot;watt&quot; in
ASCII characters using unit-symbols rather than unit-names:
</p>
<div class="example">
<pre class="example">ut_unit*     watt = ...;
char        buf[128];
unsigned    opts = <a href="#ut_005fencoding">UT_ASCII</a> | UT_DEFINITION;
int         len = <a href="#ut_005fformat_0028_0029">ut_format</a>(watt, buf, sizeof(buf), opts);

if (len == -1) {
    /* Couldn't get string */
}
else if (len == sizeof(buf)) {
    /* Entire buffer used: no terminating NUL */
}
else {
    /* Have string with terminating NUL */
}
</pre></div>

<a name="ut_005fformat_0028_0029"></a><dl>
<dt><a name="index-ut_005fformat"></a>Function: <em><code>int</code></em> <strong>ut_format</strong> <em><code>(const ut_unit* <var>unit</var>, char* <var>buf</var>, size_t <var>size</var>, unsigned <var>opts</var>)</code></em></dt>
<dd><p>Formats the unit <var>unit</var> (i.e., returns its string representation)
into the buffer pointed-to by <var>buf</var> of size <var>size</var>.
The argument <var>opts</var> specifies how the formatting is to be done and
is a bitwise OR of a <a href="#ut_005fencoding">ut_encoding</a> value and zero or more of the following:
</p>
<dl compact="compact">
<dt><code>UT_NAMES</code></dt>
<dd><p>Use unit names instead of symbols.
</p></dd>
<dt><code>UT_DEFINITION</code></dt>
<dd><p>The formatted string should be the definition of <var>unit</var> in terms
of basic-units instead of stopping any expansion at the highest level
possible.
</p></dd>
</dl>

<p>On success, this function returns either the number of bytes &ndash; excluding the
terminating <code>NUL</code> &ndash; that were written into <code>buf</code> or the number of
bytes that <em>would have been written</em>. The difference is due to the
runtime <code>snprinf()</code> function that was used.
</p>
<p>On failure, this function returns <code>-1</code> and <a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a> will
return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> or <var>buf</var> is <code>NULL</code>, or 
<var>opts</var> contains the bit patterns of both <code>UT_LATIN1</code> and
<code>UT_UTF8</code>.
</p></dd>
<dt><code>UT_CANT_FORMAT</code></dt>
<dd><p><var>unit</var> can&rsquo;t be formatted in the desired manner (e.g., <var>opts</var>
contains <code>UT_ASCII</code> but <var>unit</var> doesn&rsquo;t have an identifier in
that character-set or <var>opts</var> doesn&rsquo;t contain UT_NAMES and a necessary
symbol doesn&rsquo;t exist).
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Operations"></a>
<div class="header">
<p>
Next: <a href="#Mapping" accesskey="n" rel="next">Mapping</a>, Previous: <a href="#Formatting" accesskey="p" rel="previous">Formatting</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unit-Operations"></a>
<h2 class="chapter">8 Unit Operations</h2>
<a name="index-unit-operations"></a>
<a name="index-operations_002c-unit"></a>

<p>You can use unit operations to construct new units, get information
about units, or compare units.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Unary" accesskey="1">Unary</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Operations on a single unit
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Binary" accesskey="2">Binary</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Operations on pairs of units
</td></tr>
</table>

<hr>
<a name="Unary"></a>
<div class="header">
<p>
Next: <a href="#Binary" accesskey="n" rel="next">Binary</a>, Up: <a href="#Operations" accesskey="u" rel="up">Operations</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unary-Unit-Operations"></a>
<h3 class="section">8.1 Unary Unit Operations</h3>
<a name="index-unary-unit-operations"></a>

<a name="ut_005ffree_0028_0029"></a><dl>
<dt><a name="index-ut_005ffree"></a>Function: <em><code>void</code></em> <strong>ut_free</strong> <em><code>(ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Frees resources associated with <var>unit</var>.
You should invoke this function on every unit that you no longer need.
Use of <var>unit</var> upon
return from this function results in undefined behavior.
</p></dd></dl>

<a name="ut_005fscale_0028_0029"></a><dl>
<dt><a name="index-ut_005fscale"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_scale</strong> <em><code>(double <var>factor</var>, const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Returns a unit equivalent to another unit scaled by a numeric factor.
For example:
</p><div class="example">
<pre class="example">const ut_unit*   meter = ...
const ut_unit*   kilometer = ut_scale(1000, meter);
</pre></div>
<p>The returned unit is equivalent to <var>unit</var> multiplied by
<var>factor</var>.
You should pass the returned pointer to <code><a href="#ut_005ffree_0028_0029">ut_free()</a></code> when you
no longer need the unit.
</p></dd></dl>

<a name="ut_005foffset_0028_0029"></a><dl>
<dt><a name="index-ut_005foffset"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_offset</strong> <em><code>(const ut_unit* <var>unit</var>, double <var>offset</var>)</code></em></dt>
<dd><p>Returns a unit equivalent to another unit relative to a particular
origin.
For example:
</p><div class="example">
<pre class="example">const ut_unit*   kelvin = ...
const ut_unit*   celsius = ut_offset(kelvin, 273.15);
</pre></div>
<p>The returned unit is equivalent to <var>unit</var> with an origin of
<var>offset</var>.
You should pass the returned pointer to <code><a href="#ut_005ffree_0028_0029">ut_free()</a></code> when you
no longer need the unit.
If an error occurs, then this function returns <code>NULL</code> and
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error.  See <code>errno</code> for the reason.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005foffset_005fby_005ftime_0028_0029"></a><dl>
<dt><a name="index-ut_005foffset_005fby_005ftime"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_offset_by_time</strong> <em><code>(const ut_unit* const <var>unit</var>, const double <var>origin</var>)</code></em></dt>
<dd><p>Returns a timestamp-unit equivalent to the time unit <var>unit</var>
referenced to the time-origin <var>origin</var> (as returned by
<code><a href="#ut_005fencode_005ftime_0028_0029">ut_encode_time()</a></code>).
For example:
</p><div class="example">
<pre class="example">const ut_unit*   second = ...
const ut_unit*   secondsSinceTheEpoch =
    ut_offset_by_time(second, ut_encode_time(1970, 1, 1, 0, 0, 0.0));
</pre></div>
<p>Leap seconds are not taken into account.
You should pass the returned pointer to <code><a href="#ut_005ffree_0028_0029">ut_free()</a></code> when you
no longer need the unit.
If an error occurs, then this function returns <code>NULL</code> and
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error.  See <code>errno</code> for the reason.
</p></dd>
<dt><code>UT_MEANINGLESS</code></dt>
<dd><p>Creation of a timestamp unit based on <var>unit</var> is not meaningful.  It
might not be a time-unit, for example.
</p></dd>
<dt><code>UT_NO_SECOND</code></dt>
<dd><p>The associated unit-system doesn&rsquo;t contain a &ldquo;second&rdquo; unit.  See
<code><a href="#ut_005fset_005fsecond_0028_0029">ut_set_second()</a></code>.
</p></dd>
</dl>

<p><strong>CAUTION:</strong>
The timestamp-unit was created to be analogous to, for example, the degree
celsius&mdash;but for the time dimension.
I&rsquo;ve come to believe, however, that creating
such a unit was a mistake, primarily because users try to use the unit in
ways for which it was not designed (such as converting dates in a
calendar whose year is exactly 365 days long).
Such activities are much better handled by a dedicated calendar package.
Please be careful about using timestamp-units.
See also the section on <a href="#Time">The Handling of Time</a>.
</p>
</dd></dl>

<a name="ut_005finvert_0028_0029"></a><dl>
<dt><a name="index-ut_005finvert"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_invert</strong> <em><code>(const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Returns the inverse (i.e., reciprocal) of the unit <var>unit</var>.
This convenience function is equal to 
<code><a href="#ut_005fraise_0028_0029">ut_raise(<var>unit</var>,-1)</a></code>.
You should pass the returned pointer to <code><a href="#ut_005ffree_0028_0029">ut_free()</a></code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error. See <code>errno</code> for the reason.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fraise_0028_0029"></a><dl>
<dt><a name="index-ut_005fraise"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_raise</strong> <em><code>(const ut_unit* <var>unit</var>, int <var>power</var>)</code></em></dt>
<dd><p>Returns the unit equal to unit <var>unit</var> raised to the power <var>power</var>.
You should pass the returned pointer to <code>ut_free()</code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error. See <code>errno</code> for the reason.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005froot_0028_0029"></a><dl>
<dt><a name="index-ut_005froot"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_root</strong> <em><code>(const ut_unit* <var>unit</var>, int <var>root</var>)</code></em></dt>
<dd><p>Returns the unit equal to the <var>root</var> root of unit <var>unit</var>.
You should pass the returned pointer to <code>ut_free()</code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_MEANINGLESS</code></dt>
<dd><p>It&rsquo;s meaningless to take the given root of the given unit.
This could be because the
resulting unit would have fractional (i.e., non-integral) dimensionality,
or because the unit is, for example, a logarithmic unit.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error. See <code>errno</code> for the reason.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005flog_0028_0029"></a><dl>
<dt><a name="index-ut_005flog"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_log</strong> <em><code>(double <var>base</var>, const ut_unit* <var>reference</var>)</code></em></dt>
<dd><p>Returns the logarithmic unit corresponding to the logarithmic base
<var>base</var> and a reference level specified as the unit <var>reference</var>.
For example, the following creates a decibel unit with a
one milliwatt reference level:
</p><div class="example">
<pre class="example">     const ut_unit* milliWatt = ...;
     const ut_unit* bel_1_mW = ut_log(10.0, milliWatt);

     if (bel_1_mW != NULL) {
         const ut_unit* decibel_1_mW = <a href="#ut_005fscale_0028_0029">ut_scale</a>(0.1, bel_1_mW);

         <a href="#ut_005ffree_0028_0029">ut_free</a>(bel_1_mW);   /* no longer needed */

         if (decibel_1_mW != NULL) {
             /* Have decibel unit with 1 mW reference */
             ...
             <a href="#ut_005ffree_0028_0029">ut_free</a>(decibel_1_mW);
         }                 /* &quot;decibel_1_mW&quot; allocated */
     }
</pre></div>
<p>You should pass the returned pointer to <code>ut_free()</code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>reference</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error. See <code>errno</code> for the reason.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>base</var> is invalid (e.g., it must be greater than one).
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fget_005fname_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fname"></a>Function: <em><code>const char*</code></em> <strong>ut_get_name</strong> <em><code>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Returns the name to which the unit referenced by <var>unit</var> maps in the
character-encoding specified by <var>encoding</var>.
If this function returns <code>NULL</code>, then
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return
one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>name</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_SUCCESS</code></dt>
<dd><p><var>unit</var> doesn&rsquo;t map to a name in the given character-set.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fget_005fsymbol_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fsymbol"></a>Function: <em><code>const char*</code></em> <strong>ut_get_symbol</strong> <em><code>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Returns the symbol to which the unit referenced by <var>unit</var> maps in the
character-encoding specified by <var>encoding</var>.
If this function returns <code>NULL</code>, then
<code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return
one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>symbol</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_SUCCESS</code></dt>
<dd><p><var>unit</var> doesn&rsquo;t map to a symbol in the given character-set.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fget_005fsystem_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fsystem"></a>Function: <em><code>ut_system*</code></em> <strong>ut_get_system</strong> <em><code>(const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Returns the unit-system to which the unit referenced by <var>unit</var> belongs.
If <var>unit</var> is <code>NULL</code>, then this function writes an error-message
using <code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return <code>UT_BAD_ARG</code>.
</p></dd></dl>

<a name="ut_005fis_005fdimensionless_0028_0029"></a><dl>
<dt><a name="index-ut_005fis_005fdimensionless"></a>Function: <em><code>int</code></em> <strong>ut_is_dimensionless</strong> <em><code>(const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Indicates if unit <var>unit</var> is dimensionless (like &ldquo;radian&rdquo;).
This function returns a non-zero value if the unit is dimensionfull;
otherwise, <code>0</code> is returned and
<a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit1</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_SUCCESS</code></dt>
<dd><p>The unit is dimensionless.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fclone_0028_0029"></a><dl>
<dt><a name="index-ut_005fclone"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_clone</strong> <em><code>(const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Returns a copy of the unit referenced by <var>unit</var>.
You should pass the returned pointer to <code>ut_free()</code> when you
no longer need the unit.
If an error occurs,
then this function writes an error-message using
<code><a href="#ut_005fhandle_005ferror_005fmessage_0028_0029">ut_handle_error_message()</a></code>
and returns <code>NULL</code>.
Also, <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
</dl>
<p>If you use <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you should not normally
need to call this function.
</p></dd></dl>

<a name="ut_005faccept_005fvisitor_0028_0029"></a><dl>
<dt><a name="index-ut_005faccept_005fvisitor"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_accept_visitor</strong> <em><code>(const ut_unit* <var>unit</var>, const <a href="#ut_005fvisitor">ut_visitor</a>* <var>visitor</var>, void* <var>arg</var>)</code></em></dt>
<dd><p>Accepts the visitor <var>visitor</var> to the unit <var>unit</var>.
The argument <var>arg</var> is passed to the visitor&rsquo;s functions.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>visitor</var> or <var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_VISIT_ERROR</code></dt>
<dd><p>An error occurred in <var>visitor</var> while visiting <var>unit</var>.
</p></dd>
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fvisitor"></a><dl>
<dt><a name="index-ut_005fvisitor"></a>Data type: <strong>ut_visitor</strong> <em>int foo(int) int bar(int, int)</em></dt>
<dd><p>You pass a pointer to a data object of this type if and when you call
<code><a href="#ut_005faccept_005fvisitor_0028_0029">ut_accept_visitor()</a></code>.
It contains the following pointers to functions that implement your
unit-visitor:
</p>
<dl compact="compact">
<dt><code><a href="#ut_005fstatus">ut_status</a> (*visit_basic)(const ut_unit* <var>unit</var>, void* <var>arg</var>);</code></dt>
<dd><p>Visits the basic-unit <var>unit</var>.  A basic-unit is a base unit like
&ldquo;meter&rdquo; or a non-dimensional but named unit like &ldquo;radian&rdquo;.
This function returns <code><a href="#ut_005fstatus">UT_SUCCESS</a></code> on and only on success.
</p></dd>
<dt><code><a href="#ut_005fstatus">ut_status</a> (*visit_product)(const ut_unit* <var>unit</var>, int <var>count</var>, const ut_unit* const* <var>basicUnits</var>, const int* <var>powers</var>, void* <var>arg</var>);</code></dt>
<dd><p>Visits the product-unit <var>unit</var>.
The product-unit is a product of the <var>count</var>
basic-units referenced by <var>basicUnits</var>, each raised to their respective,
non-zero power in <var>powers</var>.
This function returns <code><a href="#ut_005fstatus">UT_SUCCESS</a></code> on and only on success.
</p></dd>
<dt><code><a href="#ut_005fstatus">ut_status</a> (*visit_galilean)(const ut_unit* <var>unit</var>, double <var>scale</var>, const ut_unit* <var>underlyingUnit</var>, double <var>origin</var>, void* arg);</code></dt>
<dd><p>Visits the Galilean-unit <var>unit</var>.
The Galilean-unit has the underlying unit <var>underlyingUnit</var> and either the
non-unity scale factor <var>scale</var> or the non-zero origin <var>origin</var>, or both.
This function returns <code><a href="#ut_005fstatus">UT_SUCCESS</a></code> on and only on success.
</p></dd>
<dt><code><a href="#ut_005fstatus">ut_status</a> (*visit_timestamp)(const ut_unit* <var>unit</var>, const ut_unit* <var>timeUnit</var>, double <var>origin</var>, void* <var>arg</var>);</code></dt>
<dd><p>Visits the timestamp-unit <var>unit</var>.
The timestamp-unit has the underlying unit of time <var>timeUnit</var>
and the <code><a href="#ut_005fencode_005ftime_0028_0029">ut_encode_time()</a></code>-encoded time-origin <var>origin</var>.
This function returns <code><a href="#ut_005fstatus">UT_SUCCESS</a></code> on and only on success.
</p></dd>
<dt><code><a href="#ut_005fstatus">ut_status</a> (*visit_logarithmic)(const ut_unit* <var>unit</var>, double <var>base</var>, const ut_unit* <var>reference</var>, void* <var>arg</var>);</code></dt>
<dd><p>Visits the logarithmic-unit <var>unit</var>.
The logarithmic-unit has the logarithmic base <var>base</var> and
the reference-level is specified by the unit <var>reference</var>.
This function returns <code><a href="#ut_005fstatus">UT_SUCCESS</a></code> on and only on success.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Binary"></a>
<div class="header">
<p>
Previous: <a href="#Unary" accesskey="p" rel="previous">Unary</a>, Up: <a href="#Operations" accesskey="u" rel="up">Operations</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Binary-Unit-Operations"></a>
<h3 class="section">8.2 Binary Unit Operations</h3>
<a name="index-binary-unit-operations"></a>

<p>Binary unit operations act on two units.
</p>
<p><strong>NOTE\:</strong> The functions
<code><a href="#ut_005fare_005fconvertible_0028_0029">ut_are_convertible()</a></code> and <code><a href="#ut_005fget_005fconverter_0028_0029">ut_get_converter()</a></code> are also
binary unit operations but are documented elsewhere.
</p>
<a name="ut_005fmultiply_0028_0029"></a><dl>
<dt><a name="index-ut_005fmultiply"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_multiply</strong> <em><code>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>)</code></em></dt>
<dd><p>Returns the result of multiplying unit <var>unit1</var> by unit <var>unit2</var>.
You should pass the pointer to <a href="#ut_005ffree_0028_0029">ut_free()</a> when you no longer need the unit
On failure, this function returns <code>NULL</code> and <a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a>
will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit1</var> or <var>unit2</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_NOT_SAME_SYSTEM</code></dt>
<dd><p><var>unit1</var> and <var>unit2</var> belong to different <a href="#unit_002dsystem">unit-system</a>s.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error. See <var>errno</var> for the reason.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fdivide_0028_0029"></a><dl>
<dt><a name="index-ut_005fdivide"></a>Function: <em><code>ut_unit*</code></em> <strong>ut_divide</strong> <em><code>(const ut_unit* <var>numer</var>, const ut_unit* <var>denom</var>)</code></em></dt>
<dd><p>Returns the result of dividing unit <var>numer</var> by unit <var>denom</var>.
You should pass the pointer to <a href="#ut_005ffree_0028_0029">ut_free()</a> when you no longer need the unit
On failure, this function returns <code>NULL</code> and <a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a> 
will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>numer</var> or <var>denom</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_NOT_SAME_SYSTEM</code></dt>
<dd><p><var>unit1</var> and <var>unit2</var> belong to different <a href="#unit_002dsystem">unit-system</a>s.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error. See <code>errno</code> for the reason.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fcompare_0028_0029"></a><dl>
<dt><a name="index-ut_005fcompare"></a>Function: <em><code>int</code></em> <strong>ut_compare</strong> <em><code>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>)</code></em></dt>
<dd><p>Compares two units.  Returns a value less than, equal to, or greater than
zero as <var>unit1</var> is considered less than, equal to, or greater than
<var>unit2</var>, respectively.
Units from different <a href="#unit_002dsystem">unit-system</a>s never compare equal.
The value zero is also returned if both unit pointers are <code>NULL</code>.
</p></dd></dl>

<a name="ut_005fsame_005fsystem_0028_0029"></a><dl>
<dt><a name="index-ut_005fsame_005fsystem"></a>Function: <em><code>int</code></em> <strong>ut_same_system</strong> <em><code>(const ut_unit* <var>unit1</var>, const ut_unit* <var>unit2</var>)</code></em></dt>
<dd><p>Indicates if two units belong to the same unit-system.
This function returns a non-zero value if the two units belong to the
same <a href="#unit_002dsystem">unit-system</a>; otherwise, <code>0</code> is returned and
<a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a> will return one of the following:
</p>
<dl compact="compact">
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit1</var> or <var>unit2</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_SUCCESS</code></dt>
<dd><p>The units belong to different <a href="#unit_002dsystem">unit-system</a>s.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Mapping"></a>
<div class="header">
<p>
Next: <a href="#Time" accesskey="n" rel="next">Time</a>, Previous: <a href="#Operations" accesskey="p" rel="previous">Operations</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Mapping-Between-Identifiers-and-Units"></a>
<h2 class="chapter">9 Mapping Between Identifiers and Units</h2>
<a name="index-mapping-units"></a>
<a name="index-mapping-identifiers"></a>
<a name="index-units_002c-mapping-to-identifiers"></a>

<p>Within a unit-system, you can map an identifier to a unit and vice
versa.
If an identifier maps to a unit, then the unit can be retrieved from the
unit-system via the identifier.
Similarly, if a unit maps to an identifier, then the unit can be printed
using the identifier.
</p>
<p>There a two kinds of identifiers: names and symbols.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Names" accesskey="1">Names</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Mapping between units and names.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Symbols" accesskey="2">Symbols</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Mapping between units and symbols.
</td></tr>
</table>

<hr>
<a name="Names"></a>
<div class="header">
<p>
Next: <a href="#Symbols" accesskey="n" rel="next">Symbols</a>, Up: <a href="#Mapping" accesskey="u" rel="up">Mapping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Names-1"></a>
<h3 class="section">9.1 Names</h3>
<a name="index-names"></a>

<p>You can map a name to a unit and vice versa.  If you use
<code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you shouldn&rsquo;t normally need to do this.
</p>
<a name="ut_005fmap_005fname_005fto_005funit_0028_0029"></a><dl>
<dt><a name="index-ut_005fmap_005fname_005fto_005funit"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_map_name_to_unit</strong> <em><code>(const char* <var>name</var>, const ut_encoding <var>encoding</var>, const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Maps the name referenced by <var>name</var>, in character-set <var>encoding</var>,
to the unit referenced by <var>unit</var>
in the unit-system that contains <var>unit</var>.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>name</var> or <var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p><var>name</var> already maps to a different unit.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005funmap_005fname_005fto_005funit_0028_0029"></a><dl>
<dt><a name="index-ut_005funmap_005fname_005fto_005funit"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_unmap_name_to_unit</strong> <em><code>(ut_system* <var>system</var>, const char* <var>name</var>, const ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Removes any mapping from name <var>name</var>, in character-set <var>encoding</var>, to a unit in unit-system <var>system</var>.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>name</var> is <code>NULL</code>.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fmap_005funit_005fto_005fname_0028_0029"></a><dl>
<dt><a name="index-ut_005fmap_005funit_005fto_005fname"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_map_unit_to_name</strong> <em><code>(const ut_unit* <var>unit</var>, const char* <var>name</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Maps the unit <var>unit</var> to the name <var>name</var>, which is in character-set
<var>encoding</var>, in the unit-system that contains the unit.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> or <var>name</var> is <code>NULL</code>, or <var>name</var> is not in the
character-set <var>encoding</var>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p><var>unit</var> already maps to a different name.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005funmap_005funit_005fto_005fname_0028_0029"></a><dl>
<dt><a name="index-ut_005funmap_005funit_005fto_005fname"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_unmap_unit_to_name</strong> <em><code>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Removes any mapping from unit <var>unit</var> to a name in character-set
<var>encoding</var> from the unit-system that contains the unit.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Symbols"></a>
<div class="header">
<p>
Previous: <a href="#Names" accesskey="p" rel="previous">Names</a>, Up: <a href="#Mapping" accesskey="u" rel="up">Mapping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Symbols-1"></a>
<h3 class="section">9.2 Symbols</h3>
<a name="index-symbols"></a>

<p>You can map a symbol to a unit and vice versa.  If you use
<code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code>, then you shouldn&rsquo;t normally need to do this.
</p>
<a name="ut_005fmap_005fsymbol_005fto_005funit_0028_0029"></a><dl>
<dt><a name="index-ut_005fmap_005fsymbol_005fto_005funit"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_map_symbol_to_unit</strong> <em><code>(const char* <var>symbol</var>, const ut_encoding <var>encoding</var>, const ut_unit* <var>unit</var>)</code></em></dt>
<dd><p>Maps the symbol referenced by <var>symbol</var>, in character-set <var>encoding</var>,
to the unit referenced by <var>unit</var>
in the unit-system that contains <var>unit</var>.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>symbol</var> or <var>unit</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p><var>symbol</var> already maps to a different unit.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005funmap_005fsymbol_005fto_005funit_0028_0029"></a><dl>
<dt><a name="index-ut_005funmap_005fsymbol_005fto_005funit"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_unmap_symbol_to_unit</strong> <em><code>(ut_system* <var>system</var>, const char* <var>symbol</var>, const ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Removes any mapping from symbol <var>symbol</var>, in character-set <var>encoding</var>, to a unit in unit-system <var>system</var>.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>system</var> or <var>symbol</var> is <code>NULL</code>.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005fmap_005funit_005fto_005fsymbol_0028_0029"></a><dl>
<dt><a name="index-ut_005fmap_005funit_005fto_005fsymbol"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_map_unit_to_symbol</strong> <em><code>(const ut_unit* <var>unit</var>, const char* <var>symbol</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Maps the unit <var>unit</var> to the symbol <var>symbol</var>, which is in character-set
<var>encoding</var>, in the unit-system that contains the unit.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> or <var>symbol</var> is <code>NULL</code>.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p>Symbol <var>symbol</var> is not in the character-set <var>encoding</var>.
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system failure.  See <code>errno</code>.
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p><var>unit</var> already maps to a different symbol.
</p></dd>
</dl>
</dd></dl>

<a name="ut_005funmap_005funit_005fto_005fsymbol_0028_0029"></a><dl>
<dt><a name="index-ut_005funmap_005funit_005fto_005fsymbol"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_unmap_unit_to_symbol</strong> <em><code>(const ut_unit* <var>unit</var>, ut_encoding <var>encoding</var>)</code></em></dt>
<dd><p>Removes any mapping from unit <var>unit</var> to a symbol in character-set
<var>encoding</var> from the unit-system that contains the unit.
This function returns one of the following:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success.
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p><var>unit</var> is <code>NULL</code>.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Time"></a>
<div class="header">
<p>
Next: <a href="#Errors" accesskey="n" rel="next">Errors</a>, Previous: <a href="#Mapping" accesskey="p" rel="previous">Mapping</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-Handling-of-Time"></a>
<h2 class="chapter">10 The Handling of Time</h2>
<a name="index-time_002c-handling-of"></a>

<p>You should use a true calendar package rather than the UDUNITS-2 package 
to handle time.  Having said that, many people use the time-handling
capabilities of the UDUNITS-2 package because it supports &quot;units&quot; like
&quot;<code>seconds since 1970-01-01</code>&quot;.  You should be aware, however, that the
hybrid Gregorian/Julian calendar used by the UDUNITS-2 package <em>cannot be
changed</em>.  Dates on or after 1582-10-15 are assumed to be Gregorian dates;
dates before that are assumed to be Julian dates.  In particular,
the year 1 BCE is immediately followed by the year 1 CE.
</p>
<p>In general, the UDUNITS-2 package handles time by encoding it as
double-precision value, which can then be acted upon arithmetically.
</p>
<a name="ut_005fencode_005ftime_0028_0029"></a><dl>
<dt><a name="index-ut_005fencode_005ftime"></a>Function: <em><code>double</code></em> <strong>ut_encode_time</strong> <em><code>(int <var>year</var>, int <var>month</var>, int <var>day</var>, int <var>hour</var>, int <var>minute</var>, double <var>second</var>)</code></em></dt>
<dd><p>Encodes a time as a double-precision value.
This convenience function is equivalent to
</p><div class="example">
<pre class="example"><a href="#ut_005fencode_005fdate_0028_0029">ut_encode_date</a>(<var>year</var>,<var>month</var>,<var>day</var>) + <a href="#ut_005fencode_005fclock_0028_0029">ut_encode_clock</a>(<var>hour</var>,<var>minute</var>,<var>second</var>)
</pre></div>
</dd></dl>

<a name="ut_005fencode_005fdate_0028_0029"></a><dl>
<dt><a name="index-ut_005fencode_005fdate"></a>Function: <em><code>double</code></em> <strong>ut_encode_date</strong> <em><code>(int <var>year</var>, int <var>month</var>, int <var>day</var>)</code></em></dt>
<dd><p>Encodes a date as a double-precision value.
You probably won&rsquo;t use this function.
Dates on or after 1582-10-15 are assumed to be Gregorian dates;
dates before that are assumed to be Julian dates.  In particular,
the year 1 BCE is immediately followed by the year 1 CE.
</p></dd></dl>

<a name="ut_005fencode_005fclock_0028_0029"></a><dl>
<dt><a name="index-ut_005fencode_005fclock"></a>Function: <em><code>double</code></em> <strong>ut_encode_clock</strong> <em><code>(int <var>hour</var>, int <var>minute</var>, double <var>second</var>)</code></em></dt>
<dd><p>Encodes a clock-time as a double-precision value.
You probably won&rsquo;t use this function.
</p></dd></dl>

<a name="ut_005fdecode_005ftime_0028_0029"></a><dl>
<dt><a name="index-ut_005fdecode_005ftime"></a>Function: <em><code>void</code></em> <strong>ut_decode_time</strong> <em><code>(double <var>time</var>, int* <var>year</var>, int* <var>month</var>, int* <var>day</var>, int* <var>hour</var>, int* <var>minute</var>, double* <var>second</var>, double* <var>resolution</var>)</code></em></dt>
<dd><p>Decodes a time from a double-precision value into its individual components.
The variable referenced by <var>resolution</var> will be set to the resolution
(i.e., uncertainty) of the time in seconds.
</p></dd></dl>

<hr>
<a name="Errors"></a>
<div class="header">
<p>
Next: <a href="#Database" accesskey="n" rel="next">Database</a>, Previous: <a href="#Time" accesskey="p" rel="previous">Time</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error-Handling"></a>
<h2 class="chapter">11 Error Handling</h2>
<a name="index-error-handling"></a>

<p>Error-handling in the units module has two aspects: the status of
the last operation performed by the module and the handling of error-messages:
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Status" accesskey="1">Status</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The status of the last operation.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Messages" accesskey="2">Messages</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The handling of error-messages.
</td></tr>
</table>

<hr>
<a name="Status"></a>
<div class="header">
<p>
Next: <a href="#Messages" accesskey="n" rel="next">Messages</a>, Up: <a href="#Errors" accesskey="u" rel="up">Errors</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Status-of-Last-Operation"></a>
<h3 class="section">11.1 Status of Last Operation</h3>
<a name="index-status-of-last-operation"></a>
<a name="index-module-status"></a>

<p>UDUNITS-2 functions set their status by calling <code><a href="#ut_005fset_005fstatus_0028_0029">ut_set_status()</a></code>.
You can use the function <code><a href="#ut_005fget_005fstatus_0028_0029">ut_get_status()</a></code> to retrieve that
status.
</p>
<a name="ut_005fget_005fstatus_0028_0029"></a><dl>
<dt><a name="index-ut_005fget_005fstatus"></a>Function: <em><code><a href="#ut_005fstatus">ut_status</a></code></em> <strong>ut_get_status</strong> <em><code>(void)</code></em></dt>
<dd><p>Returns the value specified in the last call to
<code><a href="#ut_005fset_005fstatus_0028_0029">ut_set_status()</a></code>
</p></dd></dl>

<a name="ut_005fset_005fstatus_0028_0029"></a><dl>
<dt><a name="index-ut_005fset_005fstatus"></a>Function: <em><code>void</code></em> <strong>ut_set_status</strong> <em><code>(<a href="#ut_005fstatus">ut_status</a> <var>status</var>)</code></em></dt>
<dd><p>Set the status of the units module to <var>status</var>.
</p></dd></dl>

<a name="ut_005fstatus"></a><dl>
<dt><a name="index-ut_005fstatus"></a>Data type: <strong>ut_status</strong></dt>
<dd><p>This enumeration has the following values:
</p>
<dl compact="compact">
<dt><code>UT_SUCCESS</code></dt>
<dd><p>Success
</p></dd>
<dt><code>UT_BAD_ARG</code></dt>
<dd><p>An argument violates the the function&rsquo;s contract (e.g., it&rsquo;s <code>NULL</code>).
</p></dd>
<dt><code>UT_EXISTS</code></dt>
<dd><p>Unit, prefix, or identifier already exists
</p></dd>
<dt><code>UT_NO_UNIT</code></dt>
<dd><p>No such unit exists
</p></dd>
<dt><code>UT_OS</code></dt>
<dd><p>Operating-system error.  See <code>errno</code> for the reason.
</p></dd>
<dt><code>UT_NOT_SAME_SYSTEM</code></dt>
<dd><p>The units belong to different unit-systems
</p></dd>
<dt><code>UT_MEANINGLESS</code></dt>
<dd><p>The operation on the unit or units is meaningless
</p></dd>
<dt><code>UT_NO_SECOND</code></dt>
<dd><p>The unit-system doesn&rsquo;t have a unit named &ldquo;second&rdquo;
</p></dd>
<dt><code>UT_VISIT_ERROR</code></dt>
<dd><p>An error occurred while visiting a unit
</p></dd>
<dt><code>UT_CANT_FORMAT</code></dt>
<dd><p>A unit can&rsquo;t be formatted in the desired manner
</p></dd>
<dt><code>UT_SYNTAX</code></dt>
<dd><p>String unit representation contains syntax error
</p></dd>
<dt><code>UT_UNKNOWN</code></dt>
<dd><p>String unit representation contains unknown word
</p></dd>
<dt><code>UT_OPEN_ARG</code></dt>
<dd><p>Can&rsquo;t open argument-specified unit database
</p></dd>
<dt><code>UT_OPEN_ENV</code></dt>
<dd><p>Can&rsquo;t open environment-specified unit database
</p></dd>
<dt><code>UT_OPEN_DEFAULT</code></dt>
<dd><p>Can&rsquo;t open installed, default, unit database
</p></dd>
<dt><code>UT_PARSE</code></dt>
<dd><p>Error parsing unit database
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Messages"></a>
<div class="header">
<p>
Previous: <a href="#Status" accesskey="p" rel="previous">Status</a>, Up: <a href="#Errors" accesskey="u" rel="up">Errors</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error_002dMessages"></a>
<h3 class="section">11.2 Error-Messages</h3>
<a name="index-messages_002c-error"></a>
<a name="index-error_002dmessages"></a>

<a name="ut_005fhandle_005ferror_005fmessage_0028_0029"></a><dl>
<dt><a name="index-ut_005fhandle_005ferror_005fmessage"></a>Function: <em><code>int</code></em> <strong>ut_handle_error_message</strong> <em><code>(const char* <var>fmt</var>, ...)</code></em></dt>
<dd><p>Handles the error-message corresponding to the format-string <var>fmt</var> and
any subsequent arguments referenced by it.
The interpretation of the formatting-string is identical to that of
the UNIX function <code>printf()</code>.
On success, this function returns the number of bytes in the
error-message; otherwise, this function returns <code>-1</code>.
</p>
<p>Use the function <code><a href="#ut_005fset_005ferror_005fmessage_005fhandler_0028_0029">ut_set_error_message_handler()</a></code> to change how
error-messages are handled.
</p></dd></dl>

<a name="ut_005fset_005ferror_005fmessage_005fhandler_0028_0029"></a><dl>
<dt><a name="index-ut_005fset_005ferror_005fmessage_005fhandler"></a>Function: <em><code><a href="#ut_005ferror_005fmessage_005fhandler">ut_error_message_handler</a></code></em> <strong>ut_set_error_message_handler</strong> <em><code>(<a href="#ut_005ferror_005fmessage_005fhandler">ut_error_message_handler</a> <var>handler</var>)</code></em></dt>
<dd><p>Sets the function that handles error-messages and returns the previous
error-message handler.
The initial error-message handler is <code><a href="#ut_005fwrite_005fto_005fstderr_0028_0029">ut_write_to_stderr()</a></code>.
</p></dd></dl>

<a name="ut_005fwrite_005fto_005fstderr_0028_0029"></a><dl>
<dt><a name="index-ut_005fwrite_005fto_005fstderr"></a>Function: <em><code>int</code></em> <strong>ut_write_to_stderr</strong> <em><code>(const char* <var>fmt</var>, va_list <var>args</var>)</code></em></dt>
<dd><p>Writes the variadic error-message
corresponding to formatting-string <var>fmt</var> and arguments <var>args</var>
to the standard-error stream and appends a newline.
The interpretation of the formatting-string is identical to that of
the UNIX function <code>printf()</code>.
On success, this function returns the number of bytes in the
error-message; otherwise, this function returns <code>-1</code>.
</p></dd></dl>

<a name="ut_005fignore_0028_0029"></a><dl>
<dt><a name="index-ut_005fignore"></a>Function: <em><code>int</code></em> <strong>ut_ignore</strong> <em><code>(const char* <var>fmt</var>, va_list <var>args</var>)</code></em></dt>
<dd><p>Does nothing.
In particular, it ignores the variadic error-message
corresponding to formatting-string <var>fmt</var> and arguments <var>args</var>.
Pass this function to <code><a href="#ut_005fset_005ferror_005fmessage_005fhandler_0028_0029">ut_set_error_message_handler()</a></code> 
when you don&rsquo;t want the unit module to print any error-messages.
</p></dd></dl>

<a name="ut_005ferror_005fmessage_005fhandler"></a><dl>
<dt><a name="index-ut_005ferror_005fmessage_005fhandler"></a>Data type: <strong>ut_error_message_handler</strong></dt>
<dd><p>This is the type of an error-message handler.
It&rsquo;s definition is
</p><div class="example">
<pre class="example">typedef int (*ut_error_message_handler)(const char* fmt, va_list args);
</pre></div>
</dd></dl>

<hr>
<a name="Database"></a>
<div class="header">
<p>
Next: <a href="#Types" accesskey="n" rel="next">Types</a>, Previous: <a href="#Errors" accesskey="p" rel="previous">Errors</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-Units-Database"></a>
<h2 class="chapter">12 The Units Database</h2>
<a name="index-units-database"></a>
<a name="index-database_002c-units"></a>

<p>The database of units that comes with the UDUNITS-2 package is an
XML-formatted file that is based on the SI system of units.
It contains the names and symbols of most of the units that you will ever
encounter.
The pathname of the installed file is
<code><em>datadir</em>/udunits2.xml</code>, where <em>datadir</em> is the
installation-directory for read-only, architecture-independent data
(e.g., <code>/usr/local/share</code>).
This pathname is the default that <code><a href="#ut_005fread_005fxml_0028_0029">ut_read_xml()</a></code> uses.
</p>
<p>Naturally, because the database is a regular file, it can be edited
to add new units or remove existing ones.
Be very careful about doing this, however, because you might lose
the benefit of exchanging unit-based information with others who
haven&rsquo;t modified their database.
</p>
<hr>
<a name="Types"></a>
<div class="header">
<p>
Next: <a href="#Complete-Index" accesskey="n" rel="next">Complete Index</a>, Previous: <a href="#Database" accesskey="p" rel="previous">Database</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Data-Types"></a>
<h2 class="chapter">13 Data Types</h2>
<a name="index-data-types"></a>
<a name="index-types_002c-data"></a>

<p>The data types <code><a href="#ut_005fvisitor">ut_visitor</a></code>, <code><a href="#ut_005fstatus">ut_status</a></code>, and
<code><a href="#ut_005ferror_005fmessage_005fhandler">ut_error_message_handler</a></code> are documented elsewhere.
</p>
<a name="ut_005fencoding"></a><dl>
<dt><a name="index-ut_005fencoding"></a>Data type: <strong>ut_encoding</strong></dt>
<dd><p>This enumeration has the following values:
</p>
<dl compact="compact">
<dt><code>UT_ASCII</code></dt>
<dd><p><a href="http://en.wikipedia.org/wiki/Ascii">US ASCII</a> character-set.
</p></dd>
<dt><code>UT_ISO_8859_1</code></dt>
<dd><p>The <a href="http://en.wikipedia.org/wiki/Iso-8859-1">ISO-8859-1</a> character-set.
</p></dd>
<dt><code>UT_LATIN1</code></dt>
<dd><p>Synonym for <code>UT_ISO_8859_1</code>.
</p></dd>
<dt><code>UT_UTF8</code></dt>
<dd><p>The <a href="http://en.wikipedia.org/wiki/Utf-8">UTF-8</a> encoding of the Unicode
character-set.
</p></dd>
</dl>
</dd></dl>

<hr>
<a name="Complete-Index"></a>
<div class="header">
<p>
Previous: <a href="#Types" accesskey="p" rel="previous">Types</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Complete-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Index"></a>
<h2 class="unnumbered">Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Complete-Index_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-U"><b>U</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-cp" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-A">A</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-adding-prefixes-to-a-unit_002dsystem">adding prefixes to a unit-system</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Prefixes">Prefixes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-adding-units-to-a-unit_002dsystem">adding units to a unit-system</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Adding">Adding</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-B">B</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-base-unit">base unit</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unit_002dSystems">Unit-Systems</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-binary-unit-operations">binary unit operations</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary">Binary</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-C">C</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-converting-values-between-units">converting values between units</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cv_005fconvert_005fdouble"><code>cv_convert_double</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cv_005fconvert_005fdoubles"><code>cv_convert_doubles</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cv_005fconvert_005ffloat"><code>cv_convert_float</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cv_005fconvert_005ffloats"><code>cv_convert_floats</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cv_005ffree"><code>cv_free</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-data-types">data types</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Types">Types</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-database_002c-unit_002c-obtaining-predefined">database, unit, obtaining predefined</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-database_002c-units">database, units</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Database">Database</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-E">E</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-error-handling">error handling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Errors">Errors</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-error_002dmessages">error-messages</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-examples_002c-unit-specification">examples, unit specification</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Examples">Examples</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-F">F</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-formatting-a-unit-into-a-string">formatting a unit into a string</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Formatting">Formatting</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-G">G</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-getting-a-unit-by-its-name">getting a unit by its name</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-getting-a-unit-by-its-symbol">getting a unit by its symbol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-grammar_002c-unit">grammar, unit</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Grammar">Grammar</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-mapping-identifiers">mapping identifiers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mapping">Mapping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mapping-units">mapping units</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mapping">Mapping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-messages_002c-error">messages, error</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-module-status">module status</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status">Status</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-N">N</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-names">names</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Names">Names</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-O">O</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-operations_002c-unit">operations, unit</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-P">P</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-parsing-a-string-into-a-unit">parsing a string into a unit</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parsing">Parsing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-prefixes_002c-adding-to-a-unit_002dsystem">prefixes, adding to a unit-system</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Prefixes">Prefixes</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-S">S</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-status-of-last-operation">status of last operation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status">Status</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-string_002c-formatting-a-unit-into-a">string, formatting a unit into a</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Formatting">Formatting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-string_002c-parsing-into-a-unit">string, parsing into a unit</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parsing">Parsing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbols">symbols</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-synopsis">synopsis</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Synopsis">Synopsis</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-syntax_002c-unit">syntax, unit</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Syntax">Syntax</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-system-of-units">system of units</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unit_002dSystems">Unit-Systems</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-T">T</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-time_002c-handling-of">time, handling of</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Time">Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-types_002c-data">types, data</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Types">Types</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Complete-Index_cp_letter-U">U</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-unary-unit-operations">unary unit operations</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit-conversion">unit conversion</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit-database_002c-obtaining-predefined">unit database, obtaining predefined</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit-grammar">unit grammar</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Grammar">Grammar</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit-operations">unit operations</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit-specification-examples">unit specification examples</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Examples">Examples</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit-syntax">unit syntax</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Syntax">Syntax</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002c-adding-to-a-unit_002dsystem">unit, adding to a unit-system</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Adding">Adding</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002c-base">unit, base</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unit_002dSystems">Unit-Systems</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002c-formatting-into-a-string">unit, formatting into a string</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Formatting">Formatting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002c-getting-by-name">unit, getting by name</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002c-getting-by-symbol">unit, getting by symbol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002dsystem">unit-system</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unit_002dSystems">Unit-Systems</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002dsystem_002c-adding-a-unit-to">unit-system, adding a unit to</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Adding">Adding</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002dsystem_002c-adding-prefixes-to-a">unit-system, adding prefixes to a</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Prefixes">Prefixes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unit_002dsystem_002c-obtaining-predefined">unit-system, obtaining predefined</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-units-database">units database</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Database">Database</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-units_002c-mapping-to-identifiers">units, mapping to identifiers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mapping">Mapping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-units_002c-obtaining-predefined">units, obtaining predefined</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005faccept_005fvisitor"><code>ut_accept_visitor</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fadd_005fname_005fprefix"><code>ut_add_name_prefix</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Prefixes">Prefixes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fadd_005fsymbol_005fprefix"><code>ut_add_symbol_prefix</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Prefixes">Prefixes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fare_005fconvertible"><code>ut_are_convertible</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fclone"><code>ut_clone</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fcompare"><code>ut_compare</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary">Binary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fdecode_005ftime"><code>ut_decode_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Time">Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fdivide"><code>ut_divide</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary">Binary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fencode_005fclock"><code>ut_encode_clock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Time">Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fencode_005fdate"><code>ut_encode_date</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Time">Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fencode_005ftime"><code>ut_encode_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Time">Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fencoding"><code>ut_encoding</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Types">Types</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005ferror_005fmessage_005fhandler"><code>ut_error_message_handler</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fformat"><code>ut_format</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Formatting">Formatting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005ffree"><code>ut_free</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005ffree_005fsystem"><code>ut_free_system</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Misc">Misc</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fconverter"><code>ut_get_converter</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Value-Conversion">Value Conversion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fdimensionless_005funit_005fone"><code>ut_get_dimensionless_unit_one</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fname"><code>ut_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fpath_005fxml"><code>ut_get_path_xml</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fstatus"><code>ut_get_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status">Status</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fsymbol"><code>ut_get_symbol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005fsystem"><code>ut_get_system</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005funit_005fby_005fname"><code>ut_get_unit_by_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fget_005funit_005fby_005fsymbol"><code>ut_get_unit_by_symbol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extracting">Extracting</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fhandle_005ferror_005fmessage"><code>ut_handle_error_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fignore"><code>ut_ignore</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005finvert"><code>ut_invert</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fis_005fdimensionless"><code>ut_is_dimensionless</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005flog"><code>ut_log</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fmap_005fname_005fto_005funit"><code>ut_map_name_to_unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Names">Names</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fmap_005fsymbol_005fto_005funit"><code>ut_map_symbol_to_unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fmap_005funit_005fto_005fname"><code>ut_map_unit_to_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Names">Names</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fmap_005funit_005fto_005fsymbol"><code>ut_map_unit_to_symbol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fmultiply"><code>ut_multiply</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary">Binary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fnew_005fbase_005funit"><code>ut_new_base_unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Adding">Adding</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fnew_005fdimensionless_005funit"><code>ut_new_dimensionless_unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Adding">Adding</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fnew_005fsystem"><code>ut_new_system</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005foffset"><code>ut_offset</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005foffset_005fby_005ftime"><code>ut_offset_by_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fparse"><code>ut_parse</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parsing">Parsing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fraise"><code>ut_raise</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fread_005fxml"><code>ut_read_xml</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fread_005fxml_0028_0029_002c-discussion-of"><code>ut_read_xml()</code>, discussion of</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Obtaining">Obtaining</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005froot"><code>ut_root</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fsame_005fsystem"><code>ut_same_system</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary">Binary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fscale"><code>ut_scale</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fset_005ferror_005fmessage_005fhandler"><code>ut_set_error_message_handler</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fset_005fsecond"><code>ut_set_second</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Misc">Misc</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fset_005fstatus"><code>ut_set_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status">Status</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fstatus"><code>ut_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Status">Status</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005ftrim"><code>ut_trim</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parsing">Parsing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005funmap_005fname_005fto_005funit"><code>ut_unmap_name_to_unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Names">Names</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005funmap_005fsymbol_005fto_005funit"><code>ut_unmap_symbol_to_unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005funmap_005funit_005fto_005fname"><code>ut_unmap_unit_to_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Names">Names</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005funmap_005funit_005fto_005fsymbol"><code>ut_unmap_unit_to_symbol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fvisitor"><code>ut_visitor</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unary">Unary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ut_005fwrite_005fto_005fstderr"><code>ut_write_to_stderr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Messages">Messages</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Complete-Index_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Complete-Index_cp_letter-U"><b>U</b></a>
 &nbsp; 
</td></tr></table>

<hr>



</body>
</html>