docs/modbus_mapping_new.md

   1 # modbus_mapping_new
   2
   3 ## Name
   4
   5 modbus_mapping_new - allocate four arrays of bits and registers
   6
   7 ## Synopsis
   8
   9 ```c
  10 modbus_mapping_t* modbus_mapping_new(int nb_bits, int nb_input_bits, int nb_registers, int nb_input_registers);
  11 ```
  12
  13 ## Description
  14
  15 The *modbus_mapping_new()* function shall allocate four arrays to store bits,
  16 input bits, registers and inputs registers. The pointers are stored in
  17 modbus_mapping_t structure. All values of the arrays are initialized to zero.
  18
  19 This function is equivalent to a call of the
  20 [modbus_mapping_new_start_address](modbus_mapping_new_start_address.md) function
  21 with all start addresses to `0`.
  22
  23 If it isn't necessary to allocate an array for a specific type of data, you can
  24 pass the zero value in argument, the associated pointer will be NULL.
  25
  26 This function is convenient to handle requests in a Modbus server/slave.
  27
  28 ## Return value
  29
  30 The function shall return the new allocated structure if successful. Otherwise
  31 it shall return NULL and set errno.
  32
  33 ## Errors
  34
  35 - *ENOMEM*, not enough memory.
  36
  37 ## Example
  38
  39 ```c
  40 /* The first value of each array is accessible from the 0 address. */
  41 mb_mapping = modbus_mapping_new(
  42     BITS_ADDRESS + BITS_NB,
  43     INPUT_BITS_ADDRESS + INPUT_BITS_NB,
  44     REGISTERS_ADDRESS + REGISTERS_NB,
  45     INPUT_REGISTERS_ADDRESS + INPUT_REGISTERS_NB
  46 );
  47 if (mb_mapping == NULL) {
  48     fprintf(
  49         stderr, "Failed to allocate the mapping: %s\n",
  50         modbus_strerror(errno)
  51     );
  52     modbus_free(ctx);
  53     return -1;
  54 }
  55 ```
  56
  57 ## See also
  58
  59 - [modbus_mapping_free](modbus_mapping_free.md)
  60 - [modbus_mapping_new_start_address](modbus_mapping_new_start_address.md)