docs/modbus_read_registers.md

   1 # modbus_read_registers
   2
   3 ## Name
   4
   5 modbus_read_registers - read many registers
   6
   7 ## Synopsis
   8
   9 ```c
  10 int modbus_read_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);
  11 ```
  12
  13 ## Description
  14
  15 The *modbus_read_registers()* function shall read the content of the `nb`
  16 holding registers to the address `addr` of the remote device. The result of
  17 reading is stored in `dest` array as word values (16 bits).
  18
  19 You must take care to allocate enough memory to store the results in `dest`
  20 (at least `nb * sizeof(uint16_t)`).
  21
  22 The function uses the Modbus function code 0x03 (read holding registers).
  23
  24 ## Return value
  25
  26 The function shall return the number of read registers
  27 if successful. Otherwise it shall return -1 and set errno.
  28
  29 ## Errors
  30
  31 - *EMBMDATA*, too many registers requested.
  32
  33 ## Example
  34
  35 ```c
  36 modbus_t *ctx;
  37 uint16_t tab_reg[64];
  38 int rc;
  39 int i;
  40
  41 ctx = modbus_new_tcp("127.0.0.1", 502);
  42 if (modbus_connect(ctx) == -1) {
  43     fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  44     modbus_free(ctx);
  45     return -1;
  46 }
  47
  48 rc = modbus_read_registers(ctx, 0, 10, tab_reg);
  49 if (rc == -1) {
  50     fprintf(stderr, "%s\n", modbus_strerror(errno));
  51     return -1;
  52 }
  53
  54 for (i=0; i < rc; i++) {
  55     printf("reg[%d]=%d (0x%X)\n", i, tab_reg[i], tab_reg[i]);
  56 }
  57
  58 modbus_close(ctx);
  59 modbus_free(ctx);
  60 ```
  61
  62 ## See also
  63
  64 - [modbus_write_register](modbus_write_register.md)
  65 - [modbus_write_registers](modbus_write_registers.md)