Documentation of modbus_mapping_new and modbus_mapping_free

NEWS

@@ -10,7 +10,7 @@ libmodbus 2.9.5 (2011-06-XX)
     * modbus_read_and_write_registers -> modbus_write_and_read_registers
   The function name was confusing because the write operation is performed
   before the read. Take care to swap the arguments in the migration process.
-- Documentation of modbus_write_and_read_registers
+- Documentation of modbus_write_and_read_registers, modbus_mapping_new/free
 
 libmodbus 2.9.4 (2011-06-05)
 ============================

doc/Makefile.am

@@ -7,6 +7,8 @@ MAN3 = \
         modbus_get_header_length.3 \
         modbus_get_socket.3 \
         modbus_get_response_timeout.3 \
+        modbus_mapping_free.3 \
+        modbus_mapping_new.3 \
         modbus_new_rtu.3 \
         modbus_new_tcp_pi.3 \
         modbus_new_tcp.3 \

doc/libmodbus.txt

@@ -166,7 +166,11 @@ Server
 ~~~~~~
 The server is waiting for request from clients and must answer when it is
 concerned by the request. The libmodbus offers the following functions to
-receive and reply:
+handle requests:
+
+Data mapping:
+     linkmb:modbus_mapping_new[3]
+     linkmb:modbus_mapping_free[3]
 
 Receive::
      linkmb:modbus_receive[3]

doc/modbus_mapping_free.txt

@@ -0,0 +1,34 @@
+modbus_mapping_free(3)
+=====================
+
+
+NAME
+----
+modbus_mapping_free - free a modbus_mapping_t structure
+
+
+SYNOPSIS
+--------
+*void modbus_mapping_free(modbus_mapping_t *'mb_mapping')*
+
+
+DESCRIPTION
+-----------
+The _modbus_mapping_free()_ function shall free the four arrays of mb_mapping_t
+structure and finally the mb_mapping_t referenced by 'mb_mapping'.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+SEE ALSO
+--------
+linkmb:modbus_mapping_new[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_mapping_new.txt

@@ -0,0 +1,64 @@
+modbus_mapping_new(3)
+=====================
+
+
+NAME
+----
+modbus_mapping_new - allocate four arrays of bits and registers
+
+
+SYNOPSIS
+--------
+*modbus_mapping_t* modbus_mapping_new(int 'nb_bits', int 'nb_input_bits', int 'nb_registers', int 'nb_input_registers')*
+
+
+DESCRIPTION
+-----------
+The _modbus_mapping_new()_ function shall allocate four arrays to store bits,
+input bits, registers and inputs registers. The pointers are stored in
+modbus_mapping_t structure. All values of the arrays are initialized to zero.
+
+If it isn't necessary to allocate an array for a specific type of data, you can
+pass the zero value in argument, the associated pointer will be NULL.
+
+This function is convenient to handle requests in a Modbus server/slave.
+
+
+RETURN VALUE
+------------
+The _modbus_mapping_new()_ function shall return the new allocated structure if
+successful. Otherwise it shall return NULL and set errno.
+
+
+ERRORS
+------
+ENOMEM::
+Not enough memory
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+/* The fist value of each array is accessible from the 0 address. */
+mb_mapping = modbus_mapping_new(BITS_ADDRESS + BITS_NB,
+                                INPUT_BITS_ADDRESS + INPUT_BITS_NB,
+                                REGISTERS_ADDRESS + REGISTERS_NB,
+                                INPUT_REGISTERS_ADDRESS + INPUT_REGISTERS_NB);
+if (mb_mapping == NULL) {
+    fprintf(stderr, "Failed to allocate the mapping: %s\n",
+            modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_mapping_free[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>