Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
STRUCTS_TYPE_ARRAY(3)	 BSD Library Functions Manual	 STRUCTS_TYPE_ARRAY(3)

NAME
     STRUCTS_ARRAY_TYPE, STRUCTS_FIXEDARRAY_TYPE -- structs types for arrays

LIBRARY
     PDEL Library (libpdel, -lpdel)

SYNOPSIS
     #include <sys/types.h>
     #include <pdel/structs/structs.h>
     #include <pdel/structs/type/array.h>

     DEFINE_STRUCTS_ARRAY(struct_name, elem_ctype);

     STRUCTS_ARRAY_TYPE(elem_stype, mtype, xml_tag);

     STRUCTS_FIXEDARRAY_TYPE(elem_stype, elem_size, array_len, xml_tag);

     int
     structs_array_length(const	struct structs_type *type, const char *name,
	 const void *data);

     int
     structs_array_reset(const struct structs_type *type, const	char *name,
	 void *data);

     int
     structs_array_insert(const	struct structs_type *type, const char *name,
	 u_int index, void *data);

     int
     structs_array_delete(const	struct structs_type *type, const char *name,
	 u_int index, void *data);

     int
     structs_array_prep(const struct structs_type *type, const char *name,
	 void *data);

DESCRIPTION
   Macros
     The STRUCTS_ARRAY_TYPE() and STRUCTS_FIXEDARRAY_TYPE() macros define a
     structs(3)	type (i.e., a struct structs_type) for describing variable and
     fixed length arrays, respectively.	 In both macros, elem_stype is a
     pointer to	the structs type describing the	array elements,	and xml_tag is
     an	XML tag	(ASCII string) used to tag individual array elements when the
     array is expressed	in XML.

     For STRUCTS_ARRAY_TYPE(), the described data structure must be a struct
     structs_array:

	 struct	structs_array {
	     u_int   length;	   /* number of	elements */
	     void    *elems;	   /* elements */
	 };

     The length	field contains the number of elements in the array.  The array
     itself is pointed to by elems, which must be cast to the appropriate
     type.  mtype is the typed_mem(3) type used	to dynamically allocate	the
     array.

     The elements of the array are subfields whose names are their index in
     the array.	 For example, if a subfield of a data structure	named
     "foo.bar" has an array type, then the elements of the array are named
     "foo.bar.0," "foo.bar.1," etc.

     As	a special case,	"foo.bar.length" is a read-only	virtual	subfield of
     type structs_type_uint(3) that returns the	length of the array.  This
     "length" field does not appear in the output of structs_xml_output(3) or
     structs_traverse(3).

     To	define a structure equivalent to a struct structs_array	that declares
     elems to have the correct C type for the array elements, use the
     DEFINE_STRUCTS_ARRAY() macro, where struct_name is	the name of the	struc-
     ture (or empty if no name is desired) and elem_ctype is the C type	of a
     single element.  Then the elems field will	be declared to have type
     elem_ctype	*.

     STRUCTS_FIXEDARRAY_TYPE() defines a structs type for an array that	has a
     fixed length specified by array_len.  The described data structure	is
     simply array_len consecutive instances of elem_stype, each	of which must
     have size elem_size.  In other words, elem_size must be equal to
     elem_stype-_size.

   Functions
     The following functions are included to facilitate	handling variable
     length arrays.  In	all cases, type	is the structs(3) type for the data
     structure pointed to by data, and name indicates the variable length ar-
     ray sub-field of data.  If	name is	NULL or	the empty string, then data
     itself is the variable length array.

     structs_array_length() returns the	length of the array.

     structs_array_reset() resets the array to zero length.  Any existing ele-
     ments are automatically freed.

     structs_array_insert() inserts a new element into the array at position
     index, which must be between zero and the length of the array, inclusive.
     The new element is	automatically initialized to the default value for its
     type.

     structs_array_delete() frees and removes the element at position index,
     which must	be greater than	or equal to zero and strictly less than	the
     length of the array.

     structs_array_prep() can be used when filling in an array that is ini-
     tially empty by consecutively setting each	element.  The prefixes of name
     are taken in order	from shortest to longest (i.e.,	name itself).  For
     each prefix that corresponds to an	array element, the element index is
     examined.	If the index is	less than the length of	the array, nothing
     happens.  If the index is greater than the	length of the array, an	error
     occurs.  Otherwise, a new element is added	to the end of the array.
     Therefore,	if structs_array_prep()	is invoked before setting each leaf
     element (such as returned by structs_traverse(3)),	then the extension of
     any internal arrays will happen automatically.

SEE ALSO
     libpdel(3), structs(3), structs_type(3), typed_mem(3)

EXAMPLES
     /*	Define my variable length array	of IP addresses	structure */
     DEFINE_STRUCTS_ARRAY(ip_array, struct in_addr);

     /*	My variable length array of IP addresses */
     static struct ip_array variable_ip_array;

     /*	Structs	type describing	"variable_ip_array": >=	0 IP addresses */
     static const struct structs_type vip_array_type
	 = STRUCTS_ARRAY_TYPE(&structs_type_ip4, "vip_array_memory", "ip");

     #define FIXED_ARRAY_LEN  12

     /*	My fixed length	array of IP addresses */
     static struct in_addr fixed_ip_array[FIXED_ARRAY_LEN];

     /*	Structs	type describing	"fixed_ip_array": 12 IP	addresses */
     static const struct structs_type vip_array_type
	 = STRUCTS_FIXEDARRAY_TYPE(&structs_type_ip4,
	     sizeof(struct in_addr), FIXED_ARRAY_LEN, "ip");

HISTORY
     The PDEL library was developed at Packet Design, LLC.
     http://www.packetdesign.com/

AUTHORS
     Archie Cobbs <archie@freebsd.org>

BSD				April 22, 2002				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO | EXAMPLES | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=STRUCTS_ARRAY_TYPE&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help