Added documentation of modbus_write_and_read_registers

NEWS

@@ -10,6 +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
 
 libmodbus 2.9.4 (2011-06-05)
 ============================

doc/Makefile.am

@@ -28,6 +28,7 @@ MAN3 = \
         modbus_strerror.3 \
         modbus_write_bits.3 \
         modbus_write_bit.3 \
+        modbus_write_and_read_registers.3 \
         modbus_write_registers.3 \
         modbus_write_register.3
 MAN7 = libmodbus.7

doc/libmodbus.txt

@@ -154,6 +154,9 @@ Write data::
      linkmb:modbus_write_bits[3]
      linkmb:modbus_write_registers[3]
 
+Write and read data::
+      linkmb:modbus_write_and_read_registers[3]
+
 Raw requests::
     linkmb:modbus_send_raw_request[3]
     linkmb:modbus_receive_confirmation[3]

doc/modbus_write_and_read_registers.txt

@@ -0,0 +1,51 @@
+modbus_write_and_read_registers(3)
+==================================
+
+
+NAME
+----
+modbus_write_and_read_registers - write and read many registers in a single transaction
+
+
+SYNOPSIS
+--------
+*int modbus_write_and_read_registers(modbus_t *'ctx', int 'write_addr', int 'write_nb', const uint16_t *'src', int 'read_addr', int 'read_nb', const uint16_t *'dest')*
+
+
+DESCRIPTION
+-----------
+The _modbus_write_and_read_registers()_ function shall write the content of the
+'write_nb' holding registers from the array 'src' to the address 'write_addr' of
+the remote device then shall read the content of the 'read_nb' holding registers to
+the address 'read_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 0x17 (write/read registers).
+
+
+RETURN VALUE
+------------
+The _modbus_write_and_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, Too many registers to write
+
+
+SEE ALSO
+--------
+linkmb:modbus_read_registers[3]
+linkmb:modbus_write_register[3]
+linkmb:modbus_write_registers[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>