ORT_DIFF(3)

NAME
ort_diff - compute ort configuration differences

LIBRARY
libort

SYNOPSIS
#include <sys/queue.h>
#include <stdio.h>
#include <ort.h>
struct diffq *
ort_diff(const struct config *from, const struct config *into);

DESCRIPTION
Computes the differences from the old ort(5) configuration from and the new into. It does not return all differences yet: it's a work in progress.

The differences are returned as a queue of structures that indicate whether any configuration component has changed, has not changed, has been added, or has been removed.

The result should be freed by ort_diffq_free(3) after use.

Both from and into must be fully linked as driven by ort_parse_close(3).

The differences are typed according to enum difftype, which may be any of the following:

DIFF_ADD_BITF
    A struct bitf was added to into.

DIFF_ADD_BITIDX
    A struct bitidx was added to into.

DIFF_ADD_EITEM
    A struct eitem was added to into.

DIFF_ADD_ENM
    A struct enm was added to into.

DIFF_ADD_FIELD
    A struct field was added to into.

DIFF_ADD_INSERT
    A struct insert was added to into.

DIFF_ADD_ROLE
    A struct role was added to into.

DIFF_ADD_ROLES
    Roles were added to into.

DIFF_ADD_SEARCH
    A struct search was added to into.

DIFF_ADD_STRCT
    A struct strct was added to into.

DIFF_ADD_UNIQUE
    A struct unique was added to into.

DIFF_ADD_UPDATE
    A struct update was added to into. This is raised for both update and delete types.

DIFF_DEL_BITF
    A struct bitf was removed from from.

DIFF_DEL_BITIDX
    A struct bitidx was removed from from.

DIFF_DEL_EITEM
    A struct eitem was removed from from.

DIFF_DEL_ENM
    A struct enm was removed from from.

DIFF_DEL_FIELD
    A struct field was removed from from.

DIFF_DEL_INSERT
    A struct insert was removed from from.

DIFF_DEL_ROLE
    A struct role was removed from from.

DIFF_DEL_ROLES
    All roles were removed from from.

DIFF_DEL_SEARCH
    A struct search was removed from from.

DIFF_DEL_STRCT
    A struct strct was removed from from.

DIFF_DEL_UNIQUE
    A struct unique was removed from from.

DIFF_DEL_UPDATE
    A struct update was removed from from. This is raised for both update and delete types.

DIFF_MOD_BITF
    A struct bitf changed between from and into. This stipulates that one or more of DIFF_MOD_BITF_COMMENT, DIFF_MOD_BITF_LABELS, DIFF_ADD_BITIDX, DIFF_DEL_BITIDX, or DIFF_MOD_BITIDX will also be set for the given object.

DIFF_MOD_BITF_COMMENT
    The doc field of a struct bitf changed between from and into.

DIFF_MOD_BITF_LABELS
    The labels_null or labels_unset field of a struct bitf changed between from and into.

DIFF_MOD_BITIDX
    A struct bitidx changed between from and into. This stipulates that one or more of DIFF_MOD_BITIDX_COMMENT, DIFF_MOD_BITIDX_LABELS, or DIFF_MOD_BITIDX_VALUE will also be set for the given object.

DIFF_MOD_BITIDX_COMMENT
    The doc field of a struct bitidx changed between from and into.

DIFF_MOD_BITIDX_LABELS
    The labels field of a struct bitidx changed between from and into.

DIFF_MOD_BITIDX_VALUE
    The value field of a struct bitidx changed between from and into.

DIFF_MOD_EITEM
    A struct eitem changed between from and into. This stipulates that one or more of DIFF_MOD_EITEM_COMMENT, DIFF_MOD_EITEM_LABELS, or DIFF_MOD_EITEM_VALUE will also be set for the given object.

DIFF_MOD_EITEM_COMMENT
    The doc field of a struct eitem changed between from and into.

DIFF_MOD_EITEM_LABELS
    The labels field of a struct eitem changed between from and into.

DIFF_MOD_EITEM_VALUE
    The value field of a struct eitem changed between from and into.

DIFF_MOD_ENM
    A struct enm changed between from and into. This stipulates that one or more of DIFF_MOD_ENM_COMMENT, DIFF_MOD_ENM_LABELS, DIFF_ADD_EITEM, DIFF_DEL_EITEM, or DIFF_MOD_EITEM will also be set for the given object.

DIFF_MOD_ENM_COMMENT
    The doc field of a struct enm changed between from and into.

DIFF_MOD_ENM_LABELS
    The labels_null field of a struct enm changed between from and into.

DIFF_MOD_FIELD
    A struct field changed between from and into. This stipulates that one or more of DIFF_MOD_FIELD_ACTIONS, DIFF_MOD_FIELD_BITF, DIFF_MOD_FIELD_COMMENT, DIFF_MOD_FIELD_DEF, DIFF_MOD_FIELD_ENM, DIFF_MOD_FIELD_FLAGS, DIFF_MOD_FIELD_REFERENCE, DIFF_MOD_FIELD_ROLEMAP, DIFF_MOD_FIELD_TYPE, or DIFF_MOD_FIELD_VALIDS will also be set for the given object.

DIFF_MOD_FIELD_ACTIONS
    The actup or actdel field of a struct field changed between from and into.

DIFF_MOD_FIELD_BITF
    The bitf field of a struct field changed between from and into. This is only for a change: if the type is newly or no longer a bit-field, this is not raised.

DIFF_MOD_FIELD_COMMENT
    The doc field of a struct field changed between from and into.

DIFF_MOD_FIELD_DEF
    The def field of a struct field changed between from and into. This is only for a change: if the type changes, or if a default is newly or no longer defined, this is not raised.

DIFF_MOD_FIELD_ENM
    The enm field of a struct field changed between from and into. This is only for a change: if the type is newly or no longer a enumeration, this is not raised.

DIFF_MOD_FIELD_FLAGS
    The flags field of a struct field changed between from and into.

DIFF_MOD_FIELD_REFERENCE
    The ref field of a struct field changed between from and into. There are three reasons this might occur: gaining or losing reference status, source of a local reference changing, target of a local or remote reference changing.

DIFF_MOD_FIELD_ROLEMAP
    The rolemap field of a struct field changed between from and into.

DIFF_MOD_FIELD_TYPE
    The type field of a struct field changed between from and into.

DIFF_MOD_FIELD_VALIDS
    The fvq queue of a struct field changed between from and into.

DIFF_MOD_INSERT
    A struct insert changed between from and into. This stipulates that DIFF_MOD_INSERT_PARAMS or DIFF_MOD_INSERT_ROLEMAP will also be set for the given object.

DIFF_MOD_INSERT_PARAMS
    The structure's fields have changed by name.

DIFF_MOD_INSERT_ROLEMAP
    One or more roles in the rolemap queue of a struct insert changed between from and into.

DIFF_MOD_ROLE
    A struct role changed between from and into. This stipulates that one or more of DIFF_MOD_ROLE_CHILDREN, DIFF_MOD_ROLE_COMMENT, or DIFF_MOD_ROLE_PARENT will also be set for the given object.

DIFF_MOD_ROLE_CHILDREN
    One or more roles in the subrq field of a struct role changed between from and into.

DIFF_MOD_ROLE_COMMENT
    The doc field of a struct role changed between from and into.

DIFF_MOD_ROLE_PARENT
    The parent field of a struct role changed between from and into.

DIFF_MOD_ROLES
    A struct role changed between from and into. This stipulates that one or more of DIFF_ADD_ROLE, DIFF_DEL_ROLE, or DIFF_MOD_ROLE will also be set for the given object.

DIFF_MOD_SEARCH
    A struct search changed between from and into. This stipulates that one or more of DIFF_MOD_SEARCH_AGGR, DIFF_MOD_SEARCH_COMMENT, DIFF_MOD_SEARCH_DISTINCT, DIFF_MOD_SEARCH_GROUP, DIFF_MOD_SEARCH_LIMIT, DIFF_MOD_SEARCH_OFFSET, DIFF_MOD_SEARCH_ORDER, DIFF_MOD_SEARCH_PARAMS, or DIFF_MOD_SEARCH_ROLEMAP will also be set for the given object.

DIFF_MOD_SEARCH_AGGR
    The aggr field of a struct search changed between from and into.

DIFF_MOD_SEARCH_COMMENT
    The doc field of a struct search changed between from and into.

DIFF_MOD_SEARCH_DISTINCT
    The dst field of a struct search changed between from and into.

DIFF_MOD_SEARCH_GROUP
    The group field of a struct search changed between from and into.

DIFF_MOD_SEARCH_LIMIT
    The limit field of a struct search changed between from and into.

DIFF_MOD_SEARCH_OFFSET
    The offset field of a struct search changed between from and into.

DIFF_MOD_SEARCH_ORDER
    The ordq queue of a struct search changed between from and into. This includes changing of the parameter order or number of parameters.

DIFF_MOD_SEARCH_PARAMS
    The sntq queue of a struct search changed between from and into. This includes changing of the parameter order or number of parameters.

DIFF_MOD_SEARCH_ROLEMAP
    The rolemap queue of a struct search changed between from and into.

DIFF_MOD_STRCT
    A struct strct changed between from and into. This stipulates that one or more of DIFF_ADD_FIELD, DIFF_ADD_INSERT, DIFF_ADD_SEARCH, DIFF_ADD_UNIQUE, DIFF_ADD_UPDATE, DIFF_DEL_FIELD, DIFF_DEL_INSERT, DIFF_DEL_STRCT, DIFF_DEL_UNIQUE, DIFF_DEL_UPDATE, DIFF_MOD_FIELD, DIFF_MOD_INSERT, DIFF_MOD_SEARCH, DIFF_MOD_STRCT_COMMENT, or DIFF_MOD_UPDATE will also be set for the given object.

DIFF_MOD_STRCT_COMMENT
    The doc field of a struct strct changed between from and into.

DIFF_MOD_UPDATE
    A struct update changed between from and into. This is raised for both update and delete types. It will only apply to those with a name that is not NULL. This stipulates that one or more of DIFF_MOD_UPDATE_COMMENT, DIFF_MOD_UPDATE_FLAGS, DIFF_MOD_UPDATE_PARAMS, or DIFF_MOD_UPDATE_ROLEMAP will also be set for the given object.

DIFF_MOD_UPDATE_COMMENT
    The doc field of a struct update changed between from and into.

DIFF_MOD_UPDATE_FLAGS
    The flags field of a struct update changed between from and into.

DIFF_MOD_UPDATE_PARAMS
    One or more fields in the crq or mrq queue of a struct update changed between from and into. This includes changing of the parameter order or number of parameters.

DIFF_MOD_UPDATE_ROLEMAP
    One or more roles in the rolemap queue of a struct update changed between from and into.

DIFF_SAME_BITF
    The struct bitf did not change.

DIFF_SAME_BITIDX
    The struct bitidx did not change.

DIFF_SAME_EITEM
    The struct eitem did not change.

DIFF_SAME_ENM
    The struct enm did not change.

DIFF_SAME_FIELD
    The struct field did not change.

DIFF_SAME_ROLES
    Roles were specified in both from and into and they did not change.

DIFF_SAME_ROLE
    The struct role did not change.

DIFF_SAME_SEARCH
    The struct search did not change.

DIFF_SAME_STRCT
    The struct strct did not change.

DIFF_SAME_UPDATE
    The struct update did not change. This is raised for both update and delete types.

The returned structure is a queue of struct diff, which consists of the following:

enum difftype type
    The type of change (or non-change). This affects which of the following union fields will be set.

<anon union>
    This is a union consisting of the following:

    const struct bitf *bitf
        Set by DIFF_ADD_BITF and DIFF_DEL_BITF.

    struct diff_bitf bitf_pair
        Set by DIFF_MOD_BITF, DIFF_MOD_BITF_COMMENT, DIFF_MOD_BITF_LABELS, and DIFF_SAME_BITF.

    const struct bitidx *bitidx
        Set by DIFF_ADD_BITIDX and DIFF_DEL_BITIDX.

    struct diff_bitidx bitidx_pair
        Set by DIFF_MOD_BITIDX, DIFF_MOD_BITIDX_COMMENT, DIFF_MOD_BITIDX_LABELS, DIFF_MOD_BITIDX_VALUE, and DIFF_SAME_BITIDX.

    const struct enm *enm
        Set by DIFF_ADD_ENM and DIFF_DEL_ENM.

    struct diff_enm enm_pair
        Set by DIFF_MOD_ENM, DIFF_MOD_ENM_COMMENT, DIFF_MOD_ENM_LABELS, and DIFF_SAME_ENM.

    const struct eitem *eitem
        Set by DIFF_ADD_EITEM and DIFF_DEL_EITEM.

    struct diff_eitem eitem_pair
        Set by DIFF_MOD_EITEM, DIFF_MOD_EITEM_COMMENT, DIFF_MOD_EITEM_LABELS, DIFF_MOD_EITEM_VALUE, and DIFF_SAME_EITEM.

    const struct field *field
        Set by DIFF_ADD_FIELD and DIFF_DEL_FIELD.

    struct diff_field field_pair
        Set by DIFF_MOD_FIELD, DIFF_MOD_FIELD_ACTIONS, DIFF_MOD_FIELD_BITF, DIFF_MOD_FIELD_COMMENT, DIFF_MOD_FIELD_DEF, DIFF_MOD_FIELD_ENM, DIFF_MOD_FIELD_FLAGS, DIFF_MOD_FIELD_REFERENCE, DIFF_MOD_FIELD_ROLEMAP, DIFF_MOD_FIELD_TYPE, DIFF_MOD_FIELD_VALIDS, and DIFF_SAME_FIELD.

    const struct role *role
        Set by DIFF_ADD_ROLE and DIFF_DEL_ROLE. Also used by DIFF_ADD_ROLES and DIFF_DEL_ROLES, where role is the first of the new or deleted roles.

    struct diff_role role_pair
        Set by DIFF_MOD_ROLES and DIFF_SAME_ROLES, where into and from are set to the first of the modified or same roles. Also set by DIFF_MOD_ROLE_CHILDREN, DIFF_MOD_ROLE_COMMENT, DIFF_MOD_ROLE_PARENT, and DIFF_SAME_ROLE.

    const struct search *search
        Set by DIFF_ADD_SEARCH, and DIFF_DEL_SEARCH.

    struct diff_search search_pair
        Set by DIFF_MOD_SEARCH, DIFF_MOD_SEARCH_AGGR, DIFF_MOD_SEARCH_COMMENT, DIFF_MOD_SEARCH_DISTINCT, DIFF_MOD_SEARCH_GROUP, DIFF_MOD_SEARCH_LIMIT, DIFF_MOD_SEARCH_OFFSET, DIFF_MOD_SEARCH_ORDER, DIFF_MOD_SEARCH_PARAMS, and DIFF_MOD_SEARCH_ROLEMAP.

    const struct strct *strct
        Set by DIFF_ADD_INSERT, DIFF_ADD_STRCT, DIFF_DEL_INSERT. and DIFF_DEL_STRCT.

    struct diff_strct strct_pair
        Set by DIFF_MOD_INSERT, DIFF_MOD_INSERT_PARAMS, DIFF_MOD_INSERT_ROLEMAP, DIFF_MOD_STRCT, DIFF_MOD_STRCT_COMMENT, DIFF_SAME_INSERT, and DIFF_SAME_FIELD.

    const struct unique *unique
        Set by DIFF_ADD_UNIQUE and DIFF_DEL_UNIQUE.

    const struct update *update
        Set by DIFF_ADD_UPDATE and DIFF_DEL_UPDATE.

    struct diff_update update_pair
        Set by DIFF_MOD_UPDATE, DIFF_MOD_UPDATE_COMMENT, DIFF_MOD_UPDATE_FLAGS, DIFF_MOD_UPDATE_PARAMS, DIFF_MOD_UPDATE_ROLEMAP, and DIFF_SAME_UPDATE.

A configuration that has not changed at all will consists solely of DIFF_SAME_xxxx entries.

RETURN VALUES
Returns the queue of differences or NULL on memory allocation failure.

EXAMPLES
The following passes the differences between two files, old.ort and new.ort, to a function differ().

    struct config *oldcfg, *newcfg;
    struct diffq *diff;
    FILE *old, *new;
    if ((old = fopen("old.ort", "r")) == NULL)
      err(1, "old.ort");
    if ((new = fopen("new.ort", "r")) == NULL)
      err(1, "new.ort");
    if ((oldcfg = ort_config_alloc()) == NULL) {
      err(1, NULL);
    if (!ort_parse_file(oldcfg, old, "old.ort"))
      errx(1, "old.ort: parse failure");
    if (!ort_parse_close(oldcfg))
      errx(1, "old.ort: parse failure");
    fclose(old);
    if ((newcfg = ort_config_alloc()) == NULL) {
      err(1, NULL);
    if (!ort_parse_file(newcfg, new, "new.ort"))
      errx(1, "new.ort: parse failure");
    if (!ort_parse_close(newcfg))
      errx(1, "new.ort: parse failure");
    fclose(new);
    if ((diff = ort_diff(old, new)) == NULL)
      errx(1, "old.ort -> new.ort");
    differ(diff);
    ort_config_free(oldcfg);
    ort_config_free(newcfg);
    return 0;