ORT_DIFF(3) Library Functions Manual ORT_DIFF(3)

ort_diff — compute ort configuration differences

library “libort”

#include <sys/queue.h>
#include <stdio.h>
#include <ort.h>

struct diffq *
ort_diff(const struct config *from, const struct config *into);

Computes the differences from the old ort(5) configuration from and the new into.

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:

A struct bitf was added to into.
A struct bitidx was added to into.
A struct eitem was added to into.
A struct enm was added to into.
A struct field was added to into.
A struct insert was added to into.
A struct role was added to into.
Roles were added to into.
A struct search was added to into.
A struct strct was added to into.
A struct unique was added to into.
A struct update was added to into. This is raised for both update and delete types.
A struct bitf was removed from from.
A struct bitidx was removed from from.
A struct eitem was removed from from.
A struct enm was removed from from.
A struct field was removed from from.
A struct insert was removed from from.
A struct role was removed from from.
All roles were removed from from.
A struct search was removed from from.
A struct strct was removed from from.
A struct unique was removed from from.
A struct update was removed from from. This is raised for both update and delete types.
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.
The doc field of a struct bitf changed between from and into.
The labels_null or labels_unset field of a struct bitf changed between from and into.
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.
The doc field of a struct bitidx changed between from and into.
The labels field of a struct bitidx changed between from and into.
The value field of a struct bitidx changed between from and into.
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.
The doc field of a struct eitem changed between from and into.
The labels field of a struct eitem changed between from and into.
The value field of a struct eitem changed between from and into.
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.
The doc field of a struct enm changed between from and into.
The labels_null field of a struct enm changed between from and into.
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.
The actup or actdel field of a struct field changed between from and into.
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.
The doc field of a struct field changed between from and into.
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.
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.
The flags field of a struct field changed between from and into.
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.
The rolemap field of a struct field changed between from and into.
The type field of a struct field changed between from and into.
The fvq queue of a struct field changed between from and into.
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.
The structure's fields have changed by name.
One or more roles in the rolemap queue of a struct insert changed between from and into.
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.
One or more roles in the subrq field of a struct role changed between from and into.
The doc field of a struct role changed between from and into.
The parent field of a struct role changed between from and into.
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.
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.
The aggr field of a struct search changed between from and into.
The doc field of a struct search changed between from and into.
The dst field of a struct search changed between from and into.
The group field of a struct search changed between from and into.
The limit field of a struct search changed between from and into.
The offset field of a struct search changed between from and into.
The ordq queue of a struct search changed between from and into. This includes changing of the parameter order or number of parameters.
The sntq queue of a struct search changed between from and into. This includes changing of the parameter order or number of parameters.
The rolemap queue of a struct search changed between from and into.
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.
The doc field of a struct strct changed between from and into.
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.
The doc field of a struct update changed between from and into.
The flags field of a struct update changed between from and into.
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.
One or more roles in the rolemap queue of a struct update changed between from and into.
The struct bitf did not change.
The struct bitidx did not change.
The struct eitem did not change.
The struct enm did not change.
The struct field did not change.
Roles were specified in both from and into and they did not change.
The struct role did not change.
The struct search did not change.
The struct strct did not change.
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.

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

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;
August 31, 2024 OpenBSD 7.5