Add documentation based on AsciiDoc tools

Each function is decribed in one txt file. The file libmodbus.txt
offers an overview of the library.

It's possible to generate HTML and man outputs from the txt file.
The documentation can be generated only if you have the required
tools (asciidoc and xmlto).

Better results are obtained with AsciiDoc v8.6+

Makefile.am

@@ -1,5 +1,5 @@
 EXTRA_DIST = MIGRATION README.rst libmodbus.spec
-SUBDIRS = src tests
+SUBDIRS = src doc tests
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libmodbus.pc

acinclude.m4

@@ -0,0 +1,44 @@
+dnl ##############################################################################
+dnl # AC_LIBMODBUS_CHECK_DOC_BUILD                                                     #
+dnl # Check whether to build documentation and install man-pages                 #
+dnl ##############################################################################
+AC_DEFUN([AC_LIBMODBUS_CHECK_DOC_BUILD], [{
+    # Allow user to disable doc build
+    AC_ARG_WITH([documentation], [AS_HELP_STRING([--without-documentation],
+        [disable documentation build even if asciidoc and xmlto are present [default=no]])])
+
+    if test "x$with_documentation" = "xno"; then
+        ac_libmodbus_build_doc="no"
+        ac_libmodbus_install_man="no"
+    else
+        # Determine whether or not documentation should be built and installed.
+        ac_libmodbus_build_doc="yes"
+        ac_libmodbus_install_man="yes"
+        # Check for asciidoc and xmlto and don't build the docs if these are not installed.
+        AC_CHECK_PROG(ac_libmodbus_have_asciidoc, asciidoc, yes, no)
+        AC_CHECK_PROG(ac_libmodbus_have_xmlto, xmlto, yes, no)
+        if test "x$ac_libmodbus_have_asciidoc" = "xno" -o "x$ac_libmodbus_have_xmlto" = "xno"; then
+            ac_libmodbus_build_doc="no"
+            # Tarballs built with 'make dist' ship with prebuilt documentation.
+            if ! test -f doc/modbus.7; then
+                ac_libmodbus_install_man="no"
+                AC_MSG_WARN([You are building an unreleased version of libmodbus and asciidoc or xmlto are not installed.])
+                AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.])
+            fi
+        fi
+
+        # Do not install man pages if on mingw
+        if test "x$ac_libmodbus_on_mingw32" = "xyes"; then
+            ac_libmodbus_install_man="no"
+        fi
+    fi
+
+    AC_MSG_CHECKING([whether to build documentation])
+    AC_MSG_RESULT([$ac_libmodbus_build_doc])
+
+    AC_MSG_CHECKING([whether to install manpages])
+    AC_MSG_RESULT([$ac_libmodbus_install_man])
+
+    AM_CONDITIONAL(BUILD_DOC, test "x$ac_libmodbus_build_doc" = "xyes")
+    AM_CONDITIONAL(INSTALL_MAN, test "x$ac_libmodbus_install_man" = "xyes")
+}])

configure.ac

@@ -79,6 +79,9 @@ AC_CHECK_HEADERS([ \
     netdb.h \
 ])
 
+# Check whether to build docs / install man pages
+AC_LIBMODBUS_CHECK_DOC_BUILD
+
 # Checks for header files.
 AC_HEADER_STDC
 
@@ -125,6 +128,7 @@ AC_CONFIG_FILES([
         Makefile
         src/Makefile
         src/modbus-version.h
+        doc/Makefile
         tests/Makefile
         libmodbus.pc
 ])

doc/Makefile.am

@@ -0,0 +1,71 @@
+MAN3 = \
+        modbus_close.3 \
+        modbus_connect.3 \
+        modbus_flush.3 \
+        modbus_free.3 \
+        modbus_get_header_length.3 \
+        modbus_get_timeout_begin.3 \
+        modbus_get_timeout_end.3 \
+        modbus_new_rtu.3 \
+        modbus_new_tcp_pi.3 \
+        modbus_new_tcp.3 \
+        modbus_read_bits.3 \
+        modbus_read_input_bits.3 \
+        modbus_read_input_registers.3 \
+        modbus_read_registers.3 \
+        modbus_set_debug.3 \
+        modbus_set_error_recovery.3 \
+        modbus_set_slave.3 \
+        modbus_set_timeout_begin.3 \
+        modbus_set_timeout_end.3 \
+        modbus_strerror.3 \
+        modbus_write_bits.3 \
+        modbus_write_bit.3 \
+        modbus_write_registers.3 \
+        modbus_write_register.3
+MAN7 = libmodbus.7
+
+MAN_DOC = $(MAN3) $(MAN7)
+
+MAN_TXT = $(MAN3:%.3=%.txt)
+MAN_TXT += $(MAN7:%.7=%.txt)
+MAN_HTML = $(MAN_TXT:%.txt=%.html)
+
+if INSTALL_MAN
+dist_man_MANS = $(MAN_DOC)
+doc : $(MAN_DOC)
+endif
+
+EXTRA_DIST = asciidoc.conf $(MAN_TXT)
+if BUILD_DOC
+EXTRA_DIST += $(MAN_HTML)
+html : $(MAN_HTML)
+endif
+
+MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML)
+
+dist-hook : $(MAN_DOC) $(MAN_HTML)
+
+html: $(MAN_HTML)
+
+if BUILD_DOC
+SUFFIXES=.html .txt .xml .1 .3 .7
+
+.txt.html:
+	asciidoc -d manpage -b xhtml11 -f asciidoc.conf \
+		-alibmodbus_version=@LIBMODBUS_VERSION@ $<
+.txt.xml:
+	asciidoc -d manpage -b docbook -f asciidoc.conf \
+		-alibmodbus_version=@LIBMODBUS_VERSION@ $<
+.xml.1:
+	xmlto man $<
+.xml.3:
+	xmlto man $<
+.xml.7:
+	xmlto man $<
+
+clean:
+	rm -f *.1 *.3 *.7
+	rm -f *.html
+
+endif

doc/asciidoc.conf

@@ -0,0 +1,51 @@
+[paradef-default]
+literal-style=template="literalparagraph"
+
+[macros]
+(?su)[\\]?(?P<name>linkmb):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+ifdef::backend-docbook[]
+[linkmb-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[linkmb-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">libmodbus</refmiscinfo>
+<refmiscinfo class="version">{libmodbus_version}</refmiscinfo>
+<refmiscinfo class="manual">Libmodbus Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[footer]
+</div>
+{disable-javascript%<div id="footnotes"><hr /></div>}
+<div id="footer">
+<div id="footer-text">
+libmodbus {libmodbus_version}<br />
+Last updated {docdate} {doctime}
+</div>
+</div>
+</body>
+</html>
+endif::backend-xhtml11[]

doc/libmodbus.txt

@@ -0,0 +1,184 @@
+libmodbus(7)
+============
+
+
+NAME
+----
+libmodbus - fast and portable Modbus library
+
+
+SYNOPSIS
+--------
+*#include <modbus.h>*
+
+*cc* \`pkg-config --cflags --libs libmodbus` 'files'
+
+
+DESCRIPTION
+-----------
+libmodbus is a library to send/receive data with a device which respects the
+Modbus protocol. This library contains various backends to communicate over
+different networks (eg. serial in RTU mode or Ethernet in TCP/IPv6). The
+http://www.modbus.org site provides documentation about the protocol at
+http://www.modbus.org/specs.php.
+
+libmodbus provides an abstraction of the lower communication layers and offers
+the same API on all supported platforms.
+
+This documentation presents an overview of libmodbus concepts, describes how
+libmodbus abstracts Modbus communication with different hardware and platforms
+and provides a reference manual for the functions provided by the libmodbus
+library.
+
+
+Contexts
+~~~~~~~~
+The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to
+ease the implementation of a variant, the library was designed to use a backend
+for each variant. The backends are also a convenient way to fulfill other
+requirements (eg. real-time operations). Each backend offers a specific function
+to create a new 'modbus_t' context. The 'modbus_t' context is an opaque
+structure containing all necessary information to etablish a connection with
+others Modbus devices according to the selected variant.
+
+You can choose the best context for your needs among:
+
+RTU Context
+^^^^^^^^^^^
+The RTU backend (Remote Terminal Unit) is used in serial communication and makes
+use of a compact, binary representation of the data for protocol
+communication. The RTU format follows the commands/data with a cyclic redundancy
+check checksum as an error check mechanism to ensure the reliability of
+data. Modbus RTU is the most common implementation available for Modbus. A
+Modbus RTU message must be transmitted continuously without inter-character
+hesitations (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus
+(as of Mar. 13, 2011, 20:51 GMT).
+
+Many Modbus devices can be connected together on the same physical link so you
+need to define which slave is concerned by the message with
+linkmb:modbus_set_slave[3]. If you're running a slave (server) the slave number
+is used to filter messages.
+
+Create a Modbus RTU context::
+    linkmb:modbus_new_rtu[3]
+
+TCP (IPv4) Context
+^^^^^^^^^^^^^^^^^^
+The TCP backend implements a Modbus variant used for communications over
+TCP/IPv4 networks. It does not require a checksum calculation as lower layer
+takes care of the same.
+
+Create a Modbus TCP context::
+    linkmb:modbus_new_tcp[3]
+
+
+TCP PI (IPv4 and IPv6) Context
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The TCP PI (Protocol Indepedent) backend implements a Modbus variant used for
+communications over TCP IPv4 and IPv6 networks. It does not require a checksum
+calculation as lower layer takes care of the same.
+
+Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
+resolution but it consumes about 1Kb of additional memory.
+
+Create a Modbus TCP context::
+    linkmb:modbus_new_tcp_pi[3]
+
+
+Common
+^^^^^^
+Before using any libmodbus functions, the caller must allocate and initialize a
+'modbus_t' context with functions explained above, then the following functions
+are provided to modify and free a 'context':
+
+Free libmodbus context::
+    linkmb:modbus_free[3]
+
+Context setters and getters::
+    linkmb:modbus_set_debug[3]
+    linkmb:modbus_set_error_recovery[3]
+    linkmb:modbus_set_slave[3]
+    linkmb:modbus_get_timeout_begin[3]
+    linkmb:modbus_set_timeout_begin[3]
+    linkmb:modbus_get_timeout_end[3]
+    linkmb:modbus_set_timeout_end[3]
+    linkmb:modbus_get_header_length[3]
+
+A libmodbus 'context' is thread safe and may be shared among as many application
+threads as necessary, without any additional locking required on the part of the
+caller.
+
+
+Connection
+~~~~~~~~~~
+The following functions are provided to establish and close a connection with
+Modbus devices:
+
+Establish a connection::
+    linkmb:modbus_connect[3]
+
+Close a connection::
+    linkmb:modbus_close[3]
+
+Flush a connection::
+    linkmb:modbus_flush[3]
+
+
+Data
+~~~~
+The Modbus protocol defines different data types and functions to read and write
+them from/to remote devices.
+
+Read data::
+     linkmb:modbus_read_bits[3]
+     linkmb:modbus_read_input_bits[3]
+     linkmb:modbus_read_registers[3]
+     linkmb:modbus_read_input_registers[3]
+
+Write data::
+     linkmb:modbus_write_bit[3]
+     linkmb:modbus_write_register[3]
+     linkmb:modbus_write_bits[3]
+     linkmb:modbus_write_registers[3]
+
+
+ERROR HANDLING
+--------------
+The libmodbus functions handle errors using the standard conventions found on
+POSIX systems. Generally, this means that upon failure a libmodbus function
+shall return either a NULL value (if returning a pointer) or a negative value
+(if returning an integer), and the actual error code shall be stored in the
+'errno' variable.
+
+The _modbus_strerror()_ function is provided to translate libmodbus-specific
+error codes into error message strings; for details refer to
+linkmb:modbus_strerror[3].
+
+
+MISCELLANEOUS
+-------------
+The _LIBMODBUS_VERSION_STRING_ constant indicates the libmodbus version the
+program has been compiled against. The variables 'libmodbus_version_major',
+'libmodbus_version_minor', 'libmodbus_version_micro' give the version the
+program is linked against.
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+
+
+RESOURCES
+---------
+Main web site: <http://www.libmodbus.org/>
+
+Report bugs on the issue tracker at
+<http://github.com/stephane/libmodbus/issues>.
+
+
+COPYING
+-------
+Free use of this software is granted under the terms of the GNU Lesser General
+Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
+included with the libmodbus distribution.

doc/modbus_close.txt

@@ -0,0 +1,52 @@
+modbus_close(3)
+===============
+
+
+NAME
+----
+modbus_close - close a Modbus connection
+
+
+SYNOPSIS
+--------
+*int modbus_close(*modbus_t 'ctx');*
+
+
+DESCRIPTION
+-----------
+The _modbus_close()_ function shall close the connection established with the
+backend set in the context.
+
+
+RETURN VALUE
+------------
+The _modbus_close()_ function shall return 0 if successful. Otherwise it shall
+return -1 and set errno.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_t *ctx;
+
+ctx = modbus_new_tcp("127.0.0.1", 502);
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+
+modbus_close(ctx);
+modbus_free(ctx);
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_connect[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_connect.txt

@@ -0,0 +1,52 @@
+modbus_connect(3)
+=================
+
+
+NAME
+----
+modbus_connect - establish a Modbus connection
+
+
+SYNOPSIS
+--------
+*int modbus_connect(*modbus_t 'ctx');*
+
+
+DESCRIPTION
+-----------
+The _modbus_connect()_ function shall etablish a connection to a Modbus server,
+a network or a bus using the context information of libmodbus context given in
+argument.
+
+
+RETURN VALUE
+------------
+The modbus_connect() function shall return 0 if successful. Otherwise it shall
+return -1 and set errno to one of the values defined by the system calls of the
+underlying platform.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_t *ctx;
+
+ctx = modbus_new_tcp("127.0.0.1", 502);
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_close[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_flush.txt

@@ -0,0 +1,30 @@
+modbus_flush(3)
+===============
+
+
+NAME
+----
+modbus_flush - flush non-transmitted data
+
+
+SYNOPSIS
+--------
+*int modbus_flush(*modbus_t 'ctx');*
+
+
+DESCRIPTION
+-----------
+The _modbus_flush()_ function shall discard data received but not read to the
+socket or file descriptor associated to the context 'ctx'.
+
+
+RETURN VALUE
+------------
+The _modbus_flush()_ function shall return 0 or the number of flushed bytes if
+successful. Otherwise it shall return -1 and set errno.
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_free.txt

@@ -0,0 +1,33 @@
+modbus_free(3)
+==============
+
+
+NAME
+----
+modbus_free - free a libmodbus context
+
+
+SYNOPSIS
+--------
+*void modbus_free(*modbus_t 'ctx');*
+
+
+DESCRIPTION
+-----------
+The _modbus_free()_ function shall free an allocated modbus_t structure.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+SEE ALSO
+--------
+linkmb:libmodbus[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_get_header_length.txt

@@ -0,0 +1,35 @@
+modbus_get_header_length(3)
+===========================
+
+
+NAME
+----
+modbus_get_header_length - retrieve the current header length
+
+
+SYNOPSIS
+--------
+*int modbus_get_header_length(*modbus_t 'ctx');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_header_length()_ function shall retrieve the current header
+length from the backend. This fonction is convenient to manipulate a message and
+so its limited to low-level operations.
+
+
+RETURN VALUE
+------------
+The header length as integer value.
+
+
+SEE ALSO
+--------
+linkmb:libmodbus[7]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_get_timeout_begin.txt

@@ -0,0 +1,53 @@
+modbus_get_timeout_begin(3)
+===========================
+
+
+NAME
+----
+modbus_get_timeout_begin - get timeout of begin of message
+
+
+SYNOPSIS
+--------
+*void modbus_get_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_timeout_begin()_ function shall store the current timeout of
+begin of message in the 'timeout' argument.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+struct timeval timeout_begin_old;
+struct timeval timeout_begin_new;
+
+/* Save original timeout */
+modbus_get_timeout_begin(ctx, &timeout_begin_old);
+
+/* Define a new and too short timeout! */
+timeout_begin_new.tv_sec = 0;
+timeout_begin_new.tv_usec = 0;
+modbus_set_timeout_begin(ctx, &timeout_begin_new);
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_timeout_begin[3]
+linkmb:modbus_get_timeout_end[3]
+linkmb:modbus_set_timeout_end[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_get_timeout_end.txt

@@ -0,0 +1,47 @@
+modbus_get_timeout_end(3)
+===========================
+
+
+NAME
+----
+modbus_get_timeout_end - get timeout of end of message
+
+
+SYNOPSIS
+--------
+*void modbus_get_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_timeout_end()_ function shall store the current timeout between
+the begin and the end of message in the 'timeout' argument.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+struct timeval timeout_end;
+
+/* Save original timeout */
+modbus_get_timeout_end(ctx, &timeout_end);
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_get_timeout_begin[3]
+linkmb:modbus_set_timeout_begin[3]
+linkmb:modbus_set_timeout_end[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_new_rtu.txt

@@ -0,0 +1,78 @@
+modbus_new_rtu(3)
+=================
+
+
+NAME
+----
+modbus_new_rtu - create a libmodbus context for RTU
+
+
+SYNOPSIS
+--------
+*modbus_t modbus_new_rtu(const char *'device', int 'baud',
+                         char 'parity', int 'data_bit', int 'stop_bit')*
+
+
+
+DESCRIPTION
+-----------
+
+The _modbus_new_rtu()_ function shall allocate and initialize a modbus_t
+structure to communicate in RTU mode on a serial line.
+
+The _device_ argument specifies the name of the serial port handled by the OS,
+eg. '/dev/ttyS0' or '/dev/ttyUSB0'. On Windons, it's necessary to prepend COM
+name with '\\.\' for COM number greater than 9, eg. '\\\\.\\COM10'. See
+http://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx for details
+
+The _baud_ argument specifies the baud rate of the communication, eg. 9600,
+19200, 57600, 115200, etc.
+
+The _parity_ argument can have one of the following values:::
+* _N_ for none
+* _E_ for even
+* _O_ for odd
+
+The _data_bits_ argument specifies the number of bits of data, the allowed
+values are 5, 6, 7 and 8.
+
+The _stop_bits_ argument specifies the bits of stop, the allowed values are 1
+and 2.
+
+
+RETURN VALUE
+------------
+The _modbus_new_rtu()_ function shall return a pointer to a *modbus_t* structure
+if successful. Otherwise it shall return NULL and set errno to one of the values
+defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+An invalid argument was given.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_t *ctx;
+
+ctx = modbus_new_ru("/dev/ttyUSB0", 115200, 'N', 8, 1);
+if (ctx == NULL) {
+    fprintf(stderr, "Unable to create the libmodbus context\n");
+    return -1;
+}
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_new_tcp[3]
+linkmb:modbus_free[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_new_tcp.txt

@@ -0,0 +1,70 @@
+modbus_new_tcp(3)
+=================
+
+
+NAME
+----
+modbus_new_tcp - create a libmodbus context for TCP/IPv4
+
+
+SYNOPSIS
+--------
+*modbus_t modbus_new_tcp(const char *'ip', int 'port');*
+
+
+DESCRIPTION
+-----------
+The _modbus_new_tcp()_ function shall allocate and initialize a modbus_t
+structure to communicate with a Modbus TCP/IPv4 server.
+
+The _ip_ argument specifies the IP address of the server to which the client
+wants etablish a connection.
+
+The _port_ argument is the TCP port to use. Set the port to
+_MODBUS_TCP_DEFAULT_PORT_ to use the default one (502). It’s convenient to use a
+port number greater than or equal to 1024 because it’s not necessary to have
+administrator privileges.
+
+
+RETURN VALUE
+------------
+The _modbus_new_tcp()_ function shall return a pointer to a *modbus_t* structure
+if successful. Otherwise it shall return NULL and set errno to one of the values
+defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+An invalid IP address was given.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_t *ctx;
+
+ctx = modbus_new_tcp("127.0.0.1", 1502);
+if (ctx == NULL) {
+    fprintf(stderr, "Unable to allocate libmodbus context\n");
+    return -1;
+}
+
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_new_rtu[3]
+linkmb:modbus_free[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_new_tcp_pi.txt

@@ -0,0 +1,72 @@
+modbus_new_tcp_pi(3)
+====================
+
+
+NAME
+----
+modbus_new_tcp_pi - create a libmodbus context for TCP Protocol Independent
+
+
+SYNOPSIS
+--------
+*modbus_t modbus_new_tcp_pi(const char *'node', const char *'service');*
+
+
+DESCRIPTION
+-----------
+The _modbus_new_tcp_pi()_ function shall allocate and initialize a modbus_t
+structure to communicate with a Modbus TCP IPv4 or Ipv6 server.
+
+The _node_ argument specifies the host name or IP address of the host to connect
+to, eg. '192.168.0.5' , '::1' or 'server.com'.
+
+The _service_ argument is the service name/port number to connect to. To use the
+default Modbus port use the string "502". On many Unix systems, it’s
+convenient to use a port number greater than or equal to 1024 because it’s not
+necessary to have administrator privileges.
+
+
+RETURN VALUE
+------------
+The _modbus_new_tcp_pi()_ function shall return a pointer to a *modbus_t* structure
+if successful. Otherwise it shall return NULL and set errno to one of the values
+defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The node string is empty or has been truncated. The service string is empty or
+has been truncated.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_t *ctx;
+
+ctx = modbus_new_tcp_pi("::1", "1502");
+if (ctx == NULL) {
+    fprintf(stderr, "Unable to allocate libmodbus context\n");
+    return -1;
+}
+
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_new_tcp[3]
+linkmb:modbus_new_rtu[3]
+linkmb:modbus_free[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_read_bits.txt

@@ -0,0 +1,48 @@
+modbus_read_bits(3)
+===================
+
+
+NAME
+----
+modbus_read_bits - read many bits
+
+
+SYNOPSIS
+--------
+*int modbus_read_bits(modbus_t *'ctx', int 'addr', int 'nb', uint8_t *'dest')*
+
+
+DESCRIPTION
+-----------
+The _modbus_read_bits()_ function shall read the status of the 'nb' bits (coils)
+to the address 'addr' of the remote device. The result of reading is stored in
+'dest' array as unsigned bytes (8 bits) set to _TRUE_ or _FALSE_.
+
+You must take care to allocate enough memory to store the results in 'dest'
+(at least 'nb' * sizeof(uint8_t)).
+
+The function uses the Modbus function code 0x01 (read coil status).
+
+
+RETURN VALUE
+------------
+The _modbus_read_bits()_ function shall return the number of read bits if
+successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EMBMDATA::
+Too many bits requested
+
+
+SEE ALSO
+--------
+linkmb:modbus_write_bit[3]
+linkmb:modbus_write_bits[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_read_input_bits.txt

@@ -0,0 +1,47 @@
+modbus_read_input_bits(3)
+=========================
+
+
+NAME
+----
+modbus_read_input_bits - read many input bits
+
+
+SYNOPSIS
+--------
+*int modbus_read_input_bits(modbus_t *'ctx', int 'addr', int 'nb', uint8_t *'dest');*
+
+
+DESCRIPTION
+-----------
+The _modbus_read_input_bits()_ function shall read the content of the 'nb' input
+bits to the address 'addr' of the remote device.  The result of reading is stored
+in 'dest' array as unsigned bytes (8 bits) set to _TRUE_ or _FALSE_.
+
+You must take care to allocate enough memory to store the results in 'dest'
+(at least 'nb' * sizeof(uint8_t)).
+
+The function uses the Modbus function code 0x03 (read input status).
+
+
+RETURN VALUE
+------------
+The _modbus_read_input_status()_ function shall return the number of read
+input status if successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EMBMDATA::
+Too many discrete inputs requested
+
+
+SEE ALSO
+--------
+linkmb:modbus_write_input_bits[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_read_input_registers.txt

@@ -0,0 +1,50 @@
+modbus_read_input_registers(3)
+==============================
+
+
+NAME
+----
+modbus_read_input_registers - read many input registers
+
+
+SYNOPSIS
+--------
+*int modbus_read_input_registers(modbus_t *'ctx', int 'addr', int 'nb', uint16_t *'dest')*
+
+
+DESCRIPTION
+-----------
+The _modbus_read_input_registers()_ function shall read the content of the 'nb'
+input registers to address 'addr' of the remote device. The result of the
+reading is stored in 'dest' array as word values (16 bits).
+
+You must take care to allocate enough memory to store the results in 'dest' (at
+least 'nb' * sizeof(uint16_t)).
+
+The function uses the Modbus function code 0x04 (read input registers). The
+holding registers and input registers have different historical meaning, but
+nowadays it's more common to use holding registers only.
+
+
+RETURN VALUE
+------------
+The _modbus_read_input_registers()_ function shall return the number of read
+input registers if successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EMBMDATA::
+Too many bits requested
+
+
+SEE ALSO
+--------
+linkmb:modbus_read_[3]
+linkmb:modbus_write_bit[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_read_registers.txt

@@ -0,0 +1,48 @@
+modbus_read_registers(3)
+========================
+
+
+NAME
+----
+modbus_read_registers - read many registers
+
+
+SYNOPSIS
+--------
+*int modbus_read_registers(modbus_t *'ctx', int 'addr', int 'nb', uint16_t *'dest')*
+
+
+DESCRIPTION
+-----------
+The _modbus_read_registers()_ function shall read the content of the 'nb'
+holding registers to the address 'addr' of the remote device. The result of
+reading is stored in 'dest' array as word values (16 bits).
+
+You must take care to allocate enough memory to store the results in 'dest'
+(at least 'nb' * sizeof(uint16_t)).
+
+The function uses the Modbus function code 0x03 (read holding registers).
+
+
+RETURN VALUE
+------------
+The _modbus_read_registers()_ function shall return the number of read registers
+if successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EMBMDATA::
+Too many registers requested
+
+
+SEE ALSO
+--------
+linkmb:modbus_write_register[3]
+linkmb:modbus_write_registers[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_debug.txt

@@ -0,0 +1,37 @@
+modbus_set_debug(3)
+===================
+
+NAME
+----
+modbus_set_debug - set debug flag of the context
+
+
+SYNOPSIS
+--------
+*void modbus_set_debug(*modbus_t 'ctx', int 'boolean');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_debug()_ function shall set the debug flag of the *modbus_t*
+context by using the argument 'boolean'. When the 'boolean' value is set to
+'TRUE', many verbose messages are displayed on stdout and stderr. For example,
+this flag is useful to display the bytes of the Modbus messages.
+
+[verse]
+___________________
+[00][14][00][00][00][06][12][03][00][6B][00][03]
+Waiting for a confirmation...
+<00><14><00><00><00><09><12><03><06><02><2B><00><00><00><00>
+___________________
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_error_recovery.txt

@@ -0,0 +1,48 @@
+modbus_set_error_recovery(3)
+============================
+
+
+NAME
+----
+modbus_set_error_recovery - set the error recovery mode
+
+
+SYNOPSIS
+--------
+*int modbus_set_error_recovery(modbus_t *'ctx', int 'enabled');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_error_recovery()_ function shall set the error recovery mode to
+apply when the connection fails.
+
+By default there is no error recovery so the application must check the error
+values returned by libmodbus functions and handle them if necessary.
+
+When enabled, the library will attempt an immediate reconnection which may hang
+for several seconds if the network to the remote target unit is down. The write
+will try a infinite close/connect loop until to be successful and the
+select/read calls will just try to retablish the connection one time then will
+return an error (if the connecton was down, the values to read are certainly not
+available anymore after reconnection, except for slave/server).
+
+It's not recommanded to enable error recovery for slave/server.
+
+
+RETURN VALUE
+------------
+The _modbus_close()_ function shall return 0 if successful. Otherwise it shall
+return -1 and set errno to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The value of the argument 'enabled' is not 'TRUE' of 'FALSE'.
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_slave.txt

@@ -0,0 +1,51 @@
+modbus_set_slave(3)
+===================
+
+
+NAME
+----
+modbus_set_slave - set slave number in the context
+
+
+SYNOPSIS
+--------
+*int modbus_set_slave(modbus_t *'ctx', int 'slave')*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_slave()_ function shall set the slave number in the libmodbus
+context.
+
+The behavior depends of network and the role of the device:
+
+*RTU*::
+Define the slave ID of the remote device to talk in master mode or set the
+internal slave ID in slave mode. According to the protocol, a Modbus device must
+only accept message holing its slave number or the special broadcast number.
+
+*TCP*::
+The slave number is only required in TCP if the message must reach a device
+on a serial network. The special value 'MODBUS_TCP_SLAVE' (0xFF) can be used in TCP mode to restore
+the default value.
+
+The broadcast address is 'MODBUS_BROADCAST_ADDRESS'. This special value must be
+use when you want all Modbus devices of the network receive the request.
+
+
+RETURN VALUE
+------------
+The _modbus_set_slave()_ function shall return 0 if successful. Otherwise it
+shall return -1 and set errno to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The slave number is invalid.
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_timeout_begin.txt

@@ -0,0 +1,54 @@
+modbus_set_timeout_begin(3)
+===========================
+
+
+NAME
+----
+modbus_set_timeout_begin - set timeout of begin of message
+
+
+SYNOPSIS
+--------
+*void modbus_set_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_timeout_begin()_ function shall set the timeout of begin of
+message. If the waiting before receiving a message is longer than the given
+timeout, an error will be raised.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+struct timeval timeout_begin_old;
+struct timeval timeout_begin_new;
+
+/* Save original timeout */
+modbus_get_timeout_begin(ctx, &timeout_begin_old);
+
+/* Define a new and too short timeout! */
+timeout_begin_new.tv_sec = 0;
+timeout_begin_new.tv_usec = 0;
+modbus_set_timeout_begin(ctx, &timeout_begin_new);
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_get_timeout_begin[3]
+linkmb:modbus_get_timeout_end[3]
+linkmb:modbus_set_timeout_end[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_timeout_end.txt

@@ -0,0 +1,37 @@
+modbus_set_timeout_end(3)
+===========================
+
+
+NAME
+----
+modbus_set_timeout_end - set timeout of end of message
+
+
+SYNOPSIS
+--------
+*void modbus_set_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_timeout_end()_ function shall set the timeout of end of
+message. If the delay between the begin and the end of message is longer than
+the given timeout, an error will be raised.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+SEE ALSO
+--------
+linkmb:modbus_get_timeout_begin[3]
+linkmb:modbus_set_timeout_begin[3]
+linkmb:modbus_get_timeout_end[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_strerror.txt

@@ -0,0 +1,54 @@
+modbus_strerror(3)
+=================
+
+
+NAME
+----
+modbus_strerror - return the error message
+
+
+SYNOPSIS
+--------
+*const char *modbus_strerror(*int 'errnum');*
+
+
+DESCRIPTION
+-----------
+The _modbus_strerror()_ function shall return a pointer to an error message
+string corresponding to the error number specified by the 'errnum' argument.  As
+libmodbus defines additional error numbers over and above those defined by the
+operating system, applications should use _modbus_strerror()_ in preference to
+the standard _strerror()_ function.
+
+
+RETURN VALUE
+------------
+The _modbus_strerror()_ function shall return a pointer to an error message
+string.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+.Displaying an error message when a Modbus connection cannot be established
+[source,c]
+-------------------
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    abort();
+}
+-------------------
+
+SEE ALSO
+--------
+linkmb:libmodbus
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_write_bit.txt

@@ -0,0 +1,38 @@
+modbus_write_bit(3)
+===================
+
+
+NAME
+----
+modbus_write_bit - write a single bit
+
+
+SYNOPSIS
+--------
+*int modbus_write_bit(modbus_t *'ctx', int 'addr', int 'status')*
+
+
+DESCRIPTION
+-----------
+The _modbus_write_bit()_ function shall write the status of 'status' at the
+address 'addr' of the remote device. The value must be set to _TRUE_ or _FALSE_.
+
+The function uses the Modbus function code 0x05 (force single coil).
+
+
+RETURN VALUE
+------------
+The _modbus_write_bit()_ function shall return 1 if successful. Otherwise it
+shall return -1 and set errno.
+
+
+SEE ALSO
+--------
+linkmb:modbus_read_bits[3]
+linkmb:modbus_write_bits[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_write_bits.txt

@@ -0,0 +1,45 @@
+modbus_write_bits(3)
+====================
+
+
+NAME
+----
+modbus_write_bits - write many bits
+
+
+SYNOPSIS
+--------
+*int modbus_write_bits(modbus_t *'ctx', int 'addr', int 'nb', const uint8_t *'src')*
+
+
+DESCRIPTION
+-----------
+The _modbus_write_bits()_ function shall write the status of the 'nb' bits
+(coils) from 'src' at the address 'addr' of the remote device. The
+'src' array must contains bytes set to _TRUE_ or _FALSE_.
+
+The function uses the Modbus function code 0x0F (force multiple coils).
+
+
+RETURN VALUE
+------------
+The _modbus_write_bits()_ function shall return the number of written bits if
+successful. Otherwise it shall return -1 and set errno.
+
+
+ERRORS
+------
+EMBMDATA::
+Writing too many bits
+
+
+SEE ALSO
+--------
+linkmb:modbus_read_bits[3]
+linkmb:modbus_write_bit[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_write_register.txt

@@ -0,0 +1,38 @@
+modbus_write_register(3)
+========================
+
+
+NAME
+----
+modbus_write_register - write a single register
+
+
+SYNOPSIS
+--------
+*int modbus_write_register(modbus_t *'ctx', int 'addr', int 'value')*
+
+
+DESCRIPTION
+-----------
+The _modbus_write_register()_ function shall write the value of 'value'
+holding registers at the address 'addr' of the remote device.
+
+The function uses the Modbus function code 0x06 (preset single register).
+
+
+RETURN VALUE
+------------
+The _modbus_write_register()_ function shall return 1 if successful. Otherwise
+it shall return -1 and set errno.
+
+
+SEE ALSO
+--------
+linkmb:modbus_read_register[3]
+linkmb:modbus_write_registers[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_write_registers.txt

@@ -0,0 +1,39 @@
+modbus_write_registers(3)
+=========================
+
+
+NAME
+----
+modbus_write_registers - write many registers
+
+
+SYNOPSIS
+--------
+*int modbus_write_registers(modbus_t *'ctx', int 'addr', int 'nb', const uint16_t *'src')*
+
+
+DESCRIPTION
+-----------
+The _modbus_write_registers()_ function shall write the content of the 'nb'
+holding registers from the array 'src' at address 'addr' of the
+remote device.
+
+The function uses the Modbus function code 0x10 (preset multiple registers).
+
+
+RETURN VALUE
+------------
+The _modbus_write_registers()_ function shall return the number of written registers
+if successful. Otherwise it shall return -1 and set errno.
+
+
+SEE ALSO
+--------
+linkmb:modbus_read_register[3]
+linkmb:modbus_write_register[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

src/modbus-tcp.c

@@ -665,6 +665,7 @@ modbus_t* modbus_new_tcp(const char *ip, int port)
     return ctx;
 }
 
+
 modbus_t* modbus_new_tcp_pi(const char *node, const char *service)
 {
     modbus_t *ctx;