GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRUCTS_FIXEDARRAY_TYPE (3)

NAME

STRUCTS_ARRAY_TYPE, STRUCTS_FIXEDARRAY_TYPE - structs types for arrays

CONTENTS

Library
Synopsis
Description
     Macros
     Functions
See Also
Examples
History
Authors

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In pdel/structs/structs.h
.In 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 structure (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 array 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 elements 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 initially 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


.An Archie Cobbs Aq archie@freebsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.