resolveLinks.c

Includes:

<inttypes.h>
<unistd.h>
<stdlib.h>
<stdio.h>
<dirent.h>
<sys/param.h>
<libxml/HTMLparser.h>
<libxml/HTMLtree.h>
<libxml/tree.h>
<libxml/parserInternals.h>
<sys/types.h>
<fcntl.h>
<dirent.h>
<libgen.h>
<string.h>
<pthread.h>
<errno.h>
<sys/resource.h>
"strcompat.h"
<stdarg.h>

Introduction

Resolves links between HTML fies generated by headerdoc2html and gatherheaderdoc.

Functions

addAttribute: Adds an attribute to an HTML node, deleting any preexisting attribute with the same name as it does so.
addXRef: Inserts a new cross-reference into the cross-reference tree for later use in link resolution.
addXRefFromLine: Takes a line from an xref cache file, splits it into its components, and adds the xref into the xref tree.
addXRefSub: Recursive tree walk subroutine used by addXRef when adding cross-references to the xref tree.
checkDoc: Debug code. Not actually used during normal operation.
closelogfile: Closes the log file.
countfiles: Counts the number of files in a list of files.
db_free: Debug version of free that uses guard bytes to detect buffer overflows.
db_malloc: Debug version of malloc that uses guard bytes to detect buffer overflows.
EnableCoreDumps: Debug code. Not actually used during normal operation.
findAnchor: Searches a parse tree for the first anchor.
fix_xrefbyname_t_to_head: Walks the xrefbyname_t AVL tree from the current node up to the head, fixing any incorrect maximum depth values as it does so.
fix_xrefnode_t_to_head: Walks the xrefnode_t AVL tree from the current node up to the head, fixing any incorrect maximum depth values as it does so.
fixpath: Fixes a path by removing double slashes and trailing slashes from a path.
free_xrefbyname_t_tree: Releases the xrefbyname_t tree (used for looking up symbols by name).
free_xrefbyname_t_tree_sub: Recursively releases nodes in the xrefbyname_t tree (used for looking up symbols by name).
free_xrefnode_t_tree: Releases the xrefnode_t tree (used for looking up symbols by API reference marker).
free_xrefnode_t_tree_sub: Recursively releases nodes in the xrefnode_t tree (used for looking up symbols by API reference marker).
gatherXRefs: Walks the parse tree of an HTML file, gathers all API reference anchors, and adds then into the xref tree with addXRef.
getFiles: Returns a list of HTML files within a given directory.
getHashPos: Truncates a link at the first hash mark (#) in a jump link and returns its position (or -1 if not found).
getNextXRefPart: Returns the next part of an API reference and null-terminates the current one.
getrefparts: Divides an API reference into some of its constituent parts.
has_target: Returns whether an HTML node has a valid target property set (but not if the retarget property is also set).
insertName: Inserts a name node into the tree used by refByName.
installedpath: Calculates the final absolute filesystem path for a link destination.
isCommentedAnchor: Checks a comment to see if it looks like a commented-out anchor with a logicalPath attribute.
isEndOfLinkRequest: Returns true if the text (from an HTML comment) represents the end of a link request
ishdindex: Returns whether the filename looks like a frameset-based index.html file generated by HeaderDoc.
ispartialmatch: Returns whether a known symbol marker is a suitable partial match for a partial symbol marker in a link request.
isStartOfLinkRequest: Returns true if the text (from an HTML comment) represents the start of a link request
isURI: Returns whether a filename is a recognized URI scheme.
main: The main program body.
makeurl: Takes a filename (absolute paths only) and an anchor within that file and concatenates them into a full URL.
malloccopypart: Returns a newly allocated string containing a range of characters from a source string.
matchingPathParts: Returns the number of leading path parts that match.
nameFromAppleRef: Returns the actual object name from an API reference (UID).
nodefilenamerealpath: Returns (and caches) the realpath result on the node's filename field.
nodeline: Generates a line in a cross-reference file for the specified path, UID, and title.
nodelist: Recursively descends an HTML parse tree, returning a list of nodes matching a given name.
nodelist_rec: The recursive tree walk subroutine used by the nodelist function.
nodematching: Returns the first node whose element name matches a given node.
nodepath: Calculates the absolute filesystem path for a relative path.
onSameLevel: Returns true if the two nodes are at the same level in the XML parse tree, else false.
openlogfile: Opens the log file.
partsOfPath: Returns an array of indices to parts of a path.
print_statistics: Prints cumulative statistics about this run of the tool.
printNodeRange: Dumps information about a range of HTML nodes for debugging purposes.
printNodeRangeSub: The recursive portion of printNodeRange.
printusage: Prints command-line usage information.
propString: Returns a string containing the text representation of a node's properties.
proptext: Returns the text contents of a named attribute in a list of attributes.
propval: Returns the value of a numeric property.
quietErrors: A function that throws away parse errors without spewing warnings.
readXRefFile: This function reads a cross-reference cache file.
realpath_workaround: Workaround for a bug in realpath.
rebalance_xrefbyname_t_tree: Rebalances the xrefbyname_t AVL tree after insertion of the node fromnode as a child of the node node.
rebalance_xrefnode_t_tree: Rebalances the xrefnode_t AVL tree after insertion of the node fromnode as a child of the node node.
redirect_stderr_to_null: Redirects standard error to /dev/null
refByName: Searches the (binary) tree of names for a symbol matching that name.
refByNameRec: Recursive portion of refByName.
refLangChange: Takes an API reference and rewrites it, changing the language to the language specified by lang.
refpartsfree: Frees a refparts_t object.
refRefChange: Rewrites an API reference, changing the apple_ref bit to the external ref specified by extref.
relpath: Generates a relative path from one file to another.
resolve: Attempts to resolve a space-delimited list of cross-references, allowing language fallback (c++ to C, etc.), and returns the URL associated with it.
resolve_main: The main pthread body for link resolution
resolve_mainsub: Processes all of the files assigned to a given thread.
resolveLinks: The actual link resolution function.
restore_stderr: Restores standard error after a call to redirect_stderr_to_null.
rotate_xrefbyname_t_leftleft: Handles rotations of the xrefbyname_t AVL tree in which the left child of the left child needs to be pulled up.
rotate_xrefbyname_t_leftright: Handles rotations of the xrefbyname_t AVL tree in which the right child of the left child needs to be pulled up.
rotate_xrefbyname_t_rightleft: Handles rotations of the xrefbyname_t AVL tree in which the left child of the right child needs to be pulled up.
rotate_xrefbyname_t_rightright: Handles rotations of the xrefbyname_t AVL tree in which the right child of the right child needs to be pulled up.
rotate_xrefnode_t_leftleft: Handles rotations of the xrefnode_t AVL tree in which the left child of the left child needs to be pulled up.
rotate_xrefnode_t_leftright: Handles rotations of the xrefnode_t AVL tree in which the right child of the left child needs to be pulled up.
rotate_xrefnode_t_rightleft: Handles rotations of the xrefnode_t AVL tree in which the left child of the right child needs to be pulled up.
rotate_xrefnode_t_rightright: Handles rotations of the xrefnode_t AVL tree in which the right child of the right child needs to be pulled up.
round4: Rounds up a number to the nearest 4-byte boundary.
safe_asprintf: Compatibility shim for Linux
searchfree: Releases a searchobj_t object.
searchref: Searches for an xref in the xref tree, returning the filename and anchor within that file, concatenated using makeurl.
setup_redirection: Opens a file descriptor to /dev/null for use by redirect_stderr_to_null.
tailcompare: Compares the end of a filename to a given substring.
test_xrefbyname_t_tree: Tests the xrefbyname_t tree (used for looking up symbols by name).
test_xrefnode_t_tree: Tests the xrefbyname_t tree (used for looking up symbols by name).
textmatching: Returns the text contents of the first node whose element name matches a given node.
ts_basename: Thread-safe wrapper for basename function.
ts_dirname: Thread-safe wrapper for dirname function.
verify_xrefbyname_t_tree: Verifies the depth values at all levels of an xrefbyname_t AVL tree and returns the number of errors.
verify_xrefbyname_t_tree_sub: Verifies the depth values at all levels of an xrefbyname_t AVL tree.
verify_xrefnode_t_tree: Verifies the depth values at all levels of an xrefnode_t AVL tree and returns the number of errors.
verify_xrefnode_t_tree_sub: Verifies the depth values at all levels of an xrefnode_t AVL tree.
writeFile: Writes an HTML parse tree to a file on disk.
writeFile_sub: Walks a tree recursively and writes an HTML parse tree to disk.
writeProps: Writes a node's properties to a file.
writeXRefFile: Writes a cross-reference cache file.
writeXRefFileSub: Walks the tree and writes cross-references to a cache file.
xmlNodeForComment: Returns a parsed XML node for a commented-out link.
xmlNodeGetRawString: Gets the raw text (with entities intact) for a single node.

addAttribute

Adds an attribute to an HTML node, deleting any preexisting attribute with the same name as it does so.

void addAttribute(
    xmlNode *node,
    char *attname,
    char *attstring)

Discussion

This differs from the core XML routines because it performs the matching in a casse-insensitive fashion like HTML does.

addXRef

Inserts a new cross-reference into the cross-reference tree for later use in link resolution.

void addXRef(
    xmlNode *node,
    char *filename)

addXRefFromLine

Takes a line from an xref cache file, splits it into its components, and adds the xref into the xref tree.

int addXRefFromLine(
    char *line,
    char *basepath,
    int force_absolute)

Discussion

Each line in an xref file is in the following format:

Relative URI fragment or absolute URI (/foo/bar.html or http://www.example.com/foo.html, for example)
control-A
API reference (//apple_ref/c/func/myFunc, for example)
control-A
Link title (used to provide debug info)

Note: This format is subject to change at any time. No forwards or backwards compatibility is guaranteed between different versions of the resolveLinks tool.

addXRefSub

Recursive tree walk subroutine used by addXRef when adding cross-references to the xref tree.

void addXRefSub(
    xrefnode_t newnode,
    xrefnode_t tree)

checkDoc

Debug code. Not actually used during normal operation.

void checkDoc(
    xmlNode *node,
    xmlNode *parent,
    xmlNode *prev,
    htmlDocPtr dp)

closelogfile

Closes the log file.

void closelogfile()

countfiles

Counts the number of files in a list of files.

int countfiles(
    fileref_t rethead)

Discussion

This function is used for debugging purposes.

db_free

Debug version of free that uses guard bytes to detect buffer overflows.

void db_free(
    void *ptr)

db_malloc

Debug version of malloc that uses guard bytes to detect buffer overflows.

void *db_malloc(
    size_t length)

EnableCoreDumps

Debug code. Not actually used during normal operation.

static int EnableCoreDumps(
    void)

findAnchor

Searches a parse tree for the first anchor.

xmlNode *findAnchor(
    xmlNode *node)

fix_xrefbyname_t_to_head

Walks the xrefbyname_t AVL tree from the current node up to the head, fixing any incorrect maximum depth values as it does so.

void fix_xrefbyname_t_to_head(
    xrefbyname_t node)

fix_xrefnode_t_to_head

Walks the xrefnode_t AVL tree from the current node up to the head, fixing any incorrect maximum depth values as it does so.

void fix_xrefnode_t_to_head(
    xrefnode_t node)  ;

fixpath

Fixes a path by removing double slashes and trailing slashes from a path.

char *fixpath(
    char *name)

Discussion

NOTE: This function has a side-effect. The string passed via the name argument is modified in place. Since it can only shrink, not grow, it wasn't worth the potential for memory leaks to avoid this side effect.

free_xrefbyname_t_tree

Releases the xrefbyname_t tree (used for looking up symbols by name).

void free_xrefbyname_t_tree(
    xrefbyname_t node)

Discussion

The resolveLinks tool runs some internal consistency checks on its AVL tree code at each launch. This ensures that those checks do not leak.

free_xrefbyname_t_tree_sub

Recursively releases nodes in the xrefbyname_t tree (used for looking up symbols by name).

void free_xrefbyname_t_tree_sub(
    xrefbyname_t node)

Discussion

The resolveLinks tool runs some internal consistency checks on its AVL tree code at each launch. This ensures that those checks do not leak.

free_xrefnode_t_tree

Releases the xrefnode_t tree (used for looking up symbols by API reference marker).

void free_xrefnode_t_tree(
    xrefnode_t node)

Discussion

The resolveLinks tool runs some internal consistency checks on its AVL tree code at each launch. This ensures that those checks do not leak.

free_xrefnode_t_tree_sub

Recursively releases nodes in the xrefnode_t tree (used for looking up symbols by API reference marker).

void free_xrefnode_t_tree_sub(
    xrefnode_t node)

Discussion

The resolveLinks tool runs some internal consistency checks on its AVL tree code at each launch. This ensures that those checks do not leak.

gatherXRefs

Walks the parse tree of an HTML file, gathers all API reference anchors, and adds then into the xref tree with addXRef.

void gatherXRefs(
    xmlNode *node,
    htmlDocPtr dp,
    char *filename)

getFiles

Returns a list of HTML files within a given directory.

fileref_t getFiles(
    char *curPath)

getHashPos

Truncates a link at the first hash mark (#) in a jump link and returns its position (or -1 if not found).

int getHashPos(
    char *a)

getNextXRefPart

Returns the next part of an API reference and null-terminates the current one.

char *getNextXRefPart(
    char *data)

Return Value

Returns the next part of the API reference (the first character after the slash), or NULL if the string in data does not contain a slash).

Discussion

This function null-terminates the current part of an API reference by replacing the next slash (/) with a null byte (\0), then returns a pointer to the next part.

WARNING:

Modifies the string pointed to by data.

getrefparts

Divides an API reference into some of its constituent parts.

refparts_t getrefparts(
    char *origref,
    int parts)

Return Value

Returns the parts in a dynamically allocated refparts_t structure that must be released with a call to free().

has_target

Returns whether an HTML node has a valid target property set (but not if the retarget property is also set).

int has_target(
    xmlNode *node)

insertName

Inserts a name node into the tree used by refByName.

int insertName(
    xrefbyname_t node,
    xrefbyname_t tree)

installedpath

Calculates the final absolute filesystem path for a link destination.

char *installedpath(
    char *filename)

Return Value

Returns an allocated chunk of memory (allocated by realpath()) that must be released with a call to free().

Discussion

This takes into account the base path, whether the path is a (known) URI or not, and the global installation path (if set, else the global base path).

This is similar to nodepath, except that it gives the path in terms of where the user intends the file to live after installation, rather than where the file lives currently.

isCommentedAnchor

Checks a comment to see if it looks like a commented-out anchor with a logicalPath attribute.

int isCommentedAnchor(
    char *commentString)

isEndOfLinkRequest

Returns true if the text (from an HTML comment) represents the end of a link request

int isEndOfLinkRequest(
    char *text)

ishdindex

Returns whether the filename looks like a frameset-based index.html file generated by HeaderDoc.

int ishdindex(
    char *filename)

ispartialmatch

Returns whether a known symbol marker is a suitable partial match for a partial symbol marker in a link request.

int ispartialmatch(
    char *partial_ref,
    char *complete_ref)

Parameters

partial_ref: The (possibly partial) API reference marker from the link request.
complete_ref: The (known complete) API reference marker from the tree of known link destinations.

Discussion

The API reference convention for languages with classes allows for multiple methods with the same name and different parameters and/or return types. The unfortunate result of this is that it is impossible to programmatically generate a "best guess" link request that matches it precisely because there is no way to guess the return type or parameter signature.

This function looks at the link request and checks to see if it is of one of the symbol types that are affected by this limitation. If so, it appends a slash to the link request and checks to see if it is an exact match for the first part of the actual link destination (including the slash). If it is, this function returns 1. If any of these conditions fail, it returns 0.

This is used in searchref to determine whether to treat the link request as a match in spite of its inexactness.

isStartOfLinkRequest

Returns true if the text (from an HTML comment) represents the start of a link request

int isStartOfLinkRequest(
    char *text)

isURI

Returns whether a filename is a recognized URI scheme.

int isURI(
    char *filename)

main

The main program body.

int main(
    int argc,
    char *argv[])

Discussion

This tool processes links (both in anchor form and in a commented-out form) and named anchors, rewriting link destinations to point to those anchors.

Debugging Note:

If nthreads is negative, the files will be copied and whitespace reformatting will occur automatically, but resolution will be skipped. This is used for debugging.

makeurl

Takes a filename (absolute paths only) and an anchor within that file and concatenates them into a full URL.

char *makeurl(
    char *rawfilename,
    char *offset,
    int retarget,
    int relativeToInput)

malloccopypart

Returns a newly allocated string containing a range of characters from a source string.

char *malloccopypart(
    char *source,
    int start,
    int length)

matchingPathParts

Returns the number of leading path parts that match.

int matchingPathParts(
    char *a,
    char *b,
    int *isbelowme)

Parameters

a: The path of the candidate link destination.
b: The path of the file the link itself is in.
isbelowme: On return, contains 1 if the match ended early because the candidate destination (a) is deeper in the hierarchy than the source (b).

Discussion

This is used to determine which of multiple possible link destinations is the closest match (for resolving API reference symbol conflicts).

nameFromAppleRef

Returns the actual object name from an API reference (UID).

char *nameFromAppleRef(
    char *ref)

nodefilenamerealpath

Returns (and caches) the realpath result on the node's filename field.

char *nodefilenamerealpath(
    xrefnode_t node)

nodeline

Generates a line in a cross-reference file for the specified path, UID, and title.

char *nodeline(
    char *path,
    char *xref,
    char *title)

Discussion

Used by test_xrefnode_t_tree.

nodelist

Recursively descends an HTML parse tree, returning a list of nodes matching a given name.

struct nodelistitem *nodelist(
    char *name,
    xmlNode *root)

nodelist_rec

The recursive tree walk subroutine used by the nodelist function.

void nodelist_rec(
    char *name,
    xmlNode *cur,
    struct nodelistitem **nl)

nodematching

Returns the first node whose element name matches a given node.

xmlNode *nodematching(
    char *name,
    xmlNode *cur,
    int recurse)

Discussion

If recurse is false, it begins at the current node and moves sideways across the parse tree to the next node until it runs out of nodes.

If recurse is true, it processes all of the children of each node before moving across to the next one.

This function is part of the xml2man library code and is not used in this tool.

nodepath

Calculates the absolute filesystem path for a relative path.

char *nodepath(
    xrefnode_t node)

Discussion

This differs from installedpath because it returns the current location of the files, not the final installed location.

It takes into account the base path specified for the folder containing the file in question and adds it back on.

If the path is a (known) URI, it returns the value unmodified.

onSameLevel

Returns true if the two nodes are at the same level in the XML parse tree, else false.

int onSameLevel(
    xmlNode *a,
    xmlNode *b)

openlogfile

Opens the log file.

void openlogfile()

partsOfPath

Returns an array of indices to parts of a path.

int *partsOfPath(
    char *path)

print_statistics

Prints cumulative statistics about this run of the tool.

void print_statistics(
    void)

printNodeRange

Dumps information about a range of HTML nodes for debugging purposes.

int printNodeRange(
    xmlNode *start,
    xmlNode *end)

printNodeRangeSub

The recursive portion of printNodeRange.

int printNodeRangeSub(
    xmlNode *start,
    xmlNode *end,
    int leading)

printusage

Prints command-line usage information.

void printusage()

propString

Returns a string containing the text representation of a node's properties.

char *propString(
    xmlNode *node)

proptext

Returns the text contents of a named attribute in a list of attributes.

char *proptext(
    char *name,
    struct _xmlAttr *prop)

Return Value

Returns an object that must be released with a call to free().

propval

Returns the value of a numeric property.

int propval(
    char *name,
    struct _xmlAttr *prop)

Discussion

This function is part of the xml2man library code and is not used in this tool.

quietErrors

A function that throws away parse errors without spewing warnings.

void quietErrors(
    void *userData,
    xmlErrorPtr error)

readXRefFile

This function reads a cross-reference cache file.

int readXRefFile(
    char *filename,
    char *basepath,
    int force_absolute)

Discussion

This is intended to allow eventual incorporation of cross-references that do not live in the same directory (or even on the same machine. It is currently unused.

realpath_workaround

Workaround for a bug in realpath.

char *realpath_workaround(
    char *path,
    char *buffer)

Discussion

In Mac OS X v10.6 and earlier, there is a bug in realpath such that it can return a static (non-malloc) chunk of memory if you pass a path of "/" with a NULL buffer. (Oops.)

This bug is specific to Mac OS X v10.6 and earlier, but the workaround is harmless enough that it isn't work special casing it.

rebalance_xrefbyname_t_tree

Rebalances the xrefbyname_t AVL tree after insertion of the node fromnode as a child of the node node.

void rebalance_xrefbyname_t_tree(
    xrefbyname_t node, 
    xrefbyname_t fromnode)

Parameters

fromnode: The newly inserted node initially. On recursion, the child of the current node in the direction of the newly inserted node.
node: The node that needs to be rebalanced. (Initially, the parent of the new node.)

rebalance_xrefnode_t_tree

Rebalances the xrefnode_t AVL tree after insertion of the node fromnode as a child of the node node.

void rebalance_xrefnode_t_tree(
    xrefnode_t node, 
    xrefnode_t fromnode)

Parameters

fromnode: The newly inserted node initially. On recursion, the child of the current node in the direction of the newly inserted node.
node: The node that needs to be rebalanced. (Initially, the parent of the new node.)

redirect_stderr_to_null

Redirects standard error to /dev/null

void redirect_stderr_to_null(
    void)

Discussion

Before calling this, you must first call setup_redirection.

refByName

Searches the (binary) tree of names for a symbol matching that name.

xrefnode_t refByName(
    char *name,
    char *basepath)

Return Value

Returns the cross-reference node (which provides the list of candidate API reference markers) that matches the specified name.

Discussion

This is a fallback for when exact matching fails. It allows certain "shot in the dark" link requests to match against something less exact.

refByNameRec

Recursive portion of refByName.

xrefnode_t refByNameRec(
    char *name,
    xrefbyname_t pos,
    char *basepath)

refLangChange

Takes an API reference and rewrites it, changing the language to the language specified by lang.

char *refLangChange(
    char *ref,
    char *lang)

refpartsfree

Frees a refparts_t object.

void refpartsfree(
    refparts_t rp)

Parameters

rp: The refparts_t object to free.

refRefChange

Rewrites an API reference, changing the apple_ref bit to the external ref specified by extref.

char *refRefChange(
    char *ref,
    char *extref)

relpath

Generates a relative path from one file to another.

char *relpath(
    char *target,
    char *fromFile,
    int isDir)

Return Value

Returns the relative path in a newly allocated chunk of memory that must be released with free().

Discussion

The value returned is the relative path of the file specified by target with respect to the file specified by fromFile.

Important:

Both files must be either relative or absolute paths; mixing absolute and relative paths in the same call is not allowed.

resolve

Attempts to resolve a space-delimited list of cross-references, allowing language fallback (c++ to C, etc.), and returns the URL associated with it.

char *resolve(
    char *xref,
    char *filename,
    int *retarget,
    char **frametgt)

resolve_main

The main pthread body for link resolution

static void *resolve_main(
    void *ref)

resolve_mainsub

Processes all of the files assigned to a given thread.

int resolve_mainsub(
    int pos)

Discussion

This function takes a single argument (the thread number) and processes all of the files in the file list corresponding with that thread number.

resolveLinks

The actual link resolution function.

void resolveLinks(
    xmlNode *node,
    htmlDocPtr dp,
    char *filename,
    char *filename_rp)

Discussion

Walks the parse tree of an HTML document and does the actual link resolution, inserting href attributes where applicable, converting anchors that fail to resolve into comments, and converting resolvable commented links back into anchors.

restore_stderr

Restores standard error after a call to redirect_stderr_to_null.

void restore_stderr(
    void)

rotate_xrefbyname_t_leftleft

Handles rotations of the xrefbyname_t AVL tree in which the left child of the left child needs to be pulled up.

xrefbyname_t rotate_xrefbyname_t_leftleft(
    xrefbyname_t node)

rotate_xrefbyname_t_leftright

Handles rotations of the xrefbyname_t AVL tree in which the right child of the left child needs to be pulled up.

xrefbyname_t rotate_xrefbyname_t_leftright(
    xrefbyname_t node)

rotate_xrefbyname_t_rightleft

Handles rotations of the xrefbyname_t AVL tree in which the left child of the right child needs to be pulled up.

xrefbyname_t rotate_xrefbyname_t_rightleft(
    xrefbyname_t node)

rotate_xrefbyname_t_rightright

Handles rotations of the xrefbyname_t AVL tree in which the right child of the right child needs to be pulled up.

xrefbyname_t rotate_xrefbyname_t_rightright(
    xrefbyname_t node)

rotate_xrefnode_t_leftleft

Handles rotations of the xrefnode_t AVL tree in which the left child of the left child needs to be pulled up.

xrefnode_t rotate_xrefnode_t_leftleft(
    xrefnode_t node)

rotate_xrefnode_t_leftright

Handles rotations of the xrefnode_t AVL tree in which the right child of the left child needs to be pulled up.

xrefnode_t rotate_xrefnode_t_leftright(
    xrefnode_t node)

rotate_xrefnode_t_rightleft

Handles rotations of the xrefnode_t AVL tree in which the left child of the right child needs to be pulled up.

xrefnode_t rotate_xrefnode_t_rightleft(
    xrefnode_t node)

rotate_xrefnode_t_rightright

Handles rotations of the xrefnode_t AVL tree in which the right child of the right child needs to be pulled up.

xrefnode_t rotate_xrefnode_t_rightright(
    xrefnode_t node)

round4

Rounds up a number to the nearest 4-byte boundary.

int round4(
    int k)

safe_asprintf

Compatibility shim for Linux

int safe_asprintf(
    char **ret,
    const char *format,
    ...)

Discussion

Unlike the BSD implementation of asprintf, the Linux implementation does not guarantee that the variable pointed to by ret is set to NULL in the event of an error.

Because it is poor programming practice to accept a pointer from a system routine without checking to see if the routine returned NULL, this results in a rather messy pair of checks in order to get the desired behavior (one check for the return value, then another for the pointer).

This function works around that flaw in the Linux implementation by simply checking the return value, then setting the variable pointed to by ret to NULL in the event of an error.

searchfree

Releases a searchobj_t object.

void searchfree(
    searchobj_t obj)

searchref

Searches for an xref in the xref tree, returning the filename and anchor within that file, concatenated using makeurl.

searchobj_t searchref(
    char *xref,
    xrefnode_t tree,
    int retarget,
    char *basepath)

setup_redirection

Opens a file descriptor to /dev/null for use by redirect_stderr_to_null.

void setup_redirection(
    void)

tailcompare

Compares the end of a filename to a given substring.

int tailcompare(
    char *string,
    char *tail)

Return Value

Returns 1 on a match or 0 on failure.

test_xrefbyname_t_tree

Tests the xrefbyname_t tree (used for looking up symbols by name).

int test_xrefbyname_t_tree()

Discussion

The resolveLinks tool runs some internal consistency checks on its AVL tree code at each launch. This runs some of those tests.

This test is not implemented. However, the tree does get abused significantly between the resolveLinks test suite and the built-in consistency tests in test_xrefnode_t_tree

test_xrefnode_t_tree

Tests the xrefbyname_t tree (used for looking up symbols by name).

int test_xrefnode_t_tree()

Discussion

The resolveLinks tool runs some internal consistency checks on its AVL tree code at each launch. This runs some of those tests.

textmatching

Returns the text contents of the first node whose element name matches a given node.

char *textmatching(
    char *name,
    xmlNode *node,
    int missing_ok,
    int recurse)

Discussion

This function is related to nodematching.

If the node name is "text" or "comment", it returns the text of the node itself. Otherwise, it returns the text of the node's first child.

This function is part of the xml2man library code and is not used in this tool.

ts_basename

Thread-safe wrapper for basename function.

char *ts_basename(
    char *path)

ts_dirname

Thread-safe wrapper for dirname function.

char *ts_dirname(
    char *path)

verify_xrefbyname_t_tree

Verifies the depth values at all levels of an xrefbyname_t AVL tree and returns the number of errors.

int verify_xrefbyname_t_tree(
    xrefbyname_t node)

verify_xrefbyname_t_tree_sub

Verifies the depth values at all levels of an xrefbyname_t AVL tree.

int verify_xrefbyname_t_tree_sub(
    xrefbyname_t node,
    int *errors)

verify_xrefnode_t_tree

Verifies the depth values at all levels of an xrefnode_t AVL tree and returns the number of errors.

int verify_xrefnode_t_tree(
    xrefnode_t node)

verify_xrefnode_t_tree_sub

Verifies the depth values at all levels of an xrefnode_t AVL tree.

int verify_xrefnode_t_tree_sub(
    xrefnode_t node,
    int *errors)

writeFile

Writes an HTML parse tree to a file on disk.

void writeFile(
    xmlNode *node,
    htmlDocPtr dp,
    char *filename)

writeFile_sub

Walks a tree recursively and writes an HTML parse tree to disk.

void writeFile_sub(
    xmlNode *node,
    htmlDocPtr dp,
    FILE *fp, 
    int this_node_and_children_only)

Discussion

Used by writeFile.

writeProps

Writes a node's properties to a file.

void writeProps(
    xmlNode *node,
    FILE *fp)

writeXRefFile

Writes a cross-reference cache file.

void writeXRefFile(
    char *filename,
    char *indir)

Discussion

A cross-reference cache file can be used to provide an initial seed for the resolver. It contains the information needed to create a link to any of the content processed (subject to passing the correct flags to strip off leading path components and prepend new leading path components).

This allows you to resolve the contents of multiple independent projects iteratively. For example, you could have two projects, A and B, each of which exports a cross-reference cache file, and also imports the cache file from the other project when you build it. By doing this, the two projects can know nothing about each other except for the location of the cache file and the relative path on the server, yet can still link to one another.

writeXRefFileSub

Walks the tree and writes cross-references to a cache file.

void writeXRefFileSub(
    xrefnode_t node,
    FILE *fp)

Discussion

Used by writeXRefFile.

xmlNodeForComment

Returns a parsed XML node for a commented-out link.

xmlNode *xmlNodeForComment(
    xmlChar *commentguts,
    htmlDocPtr parentDoc)

xmlNodeGetRawString

Gets the raw text (with entities intact) for a single node.

char *xmlNodeGetRawString(
    htmlDocPtr dp,
    xmlNode *node,
    int whatever)

Discussion

This is similar to xmlNodeListGetRawString (part of libxml) except that it does not traverse the node tree.

Typedefs

fileref_t: A node in a list that cantains pointers to HTML parse tree nodes that matched a specific pattern.
refparts_t: The parts of an API reference (UID).
searchobj_t: An object returned by searchref.
xrefbyname_t: A node in a tree of pointers to xrefnode_t nodes sorted by the name of the API symbol.
xrefnode_t: A node in a tree of nodes that each describe information about a possible link destination.

fileref_t

A node in a list that cantains pointers to HTML parse tree nodes that matched a specific pattern.

typedef struct fileref { 
    char name[MAXPATHLEN]; 
    struct fileref *next; 
    struct fileref *threadnext; 
} *fileref_t;

Discussion

Used by the nodelist function.

refparts_t

The parts of an API reference (UID).

typedef struct refparts { 
    char *refpart; 
    char *langpart; 
    char *rest; 
} *refparts_t;

Fields

refpart: The reference type (apple_ref, for example).
langpart: The language portion of the UID.
rest: The rest of the UID.

searchobj_t

An object returned by searchref.

typedef struct searchobj { 
    char *uri; 
    xrefnode_t obj; 
} *searchobj_t;

Fields

uri: The URI for the best matching destination.
obj: The tree object that matched. Used to gain access to the fromseed and force_absolute fields.

xrefbyname_t

A node in a tree of pointers to xrefnode_t nodes sorted by the name of the API symbol.

typedef struct _xrefbyname { 
    char *name; 
    xrefnode_t node; 
    int maxleftdepth, maxrightdepth; 
    struct _xrefbyname *left, *right, *dup, *parent; 
} *xrefbyname_t;

Fields

name: The name of the symbol described by node.
node: A node in the nodehead tree.
left: The left subtree.
right: The right subtree.

Discussion

Used for looking up certain machine-generated or ambiguously described symbols as a last resort.

The namehead variable contains the root of this tree.

xrefnode_t

A node in a tree of nodes that each describe information about a possible link destination.

typedef struct _xrefnode { 
    char *basepath; 
    char *filename; 
    #ifdef RP_CACHE 
    char *filename_rp; 
    #endif  
    char *fullpath; // 
    char *xref; 
    char *title; 
    int fromseed : 1; 
    int force_absolute : 1; 
    int maxleftdepth, maxrightdepth; 
    struct _xrefnode *left, *right, *dup, *parent; 
} *xrefnode_t;

Fields

basepath: The seed file base path (specified by the -S flag) associated with the file in question, or an empty string.
filename: The relative file path (either as passed on the command line or as read from the seed file).
fullpath: A cache for the nodepath function.
xref: The API reference marker(s) string.
title: The title attribute as parsed from the HTML.
fromseed: Contains 1 if the API reference marker was read from a seed file, or 0 if it was not.
force_absolute: Contains 1 if the -a flag was passed for the seed file in question (or prior to the first seed file), else 0.
left: The left subtree of the tree of cross references (sorted by the xref field).
right: The right subtree of the tree of cross references (sorted by the xref field).
dup: A chain of additional cross-reference nodes with matching values for xref. Used only when disambiguating duplicate link destinations.

Structs and Unions

nodelistitem: A node in a list that cantains pointers to HTML parse tree nodes that matched a specific pattern.

nodelistitem

A node in a list that cantains pointers to HTML parse tree nodes that matched a specific pattern.

struct nodelistitem { 
    xmlNode *node; 
    struct nodelistitem *next; 
    struct nodelistitem *prev; 
};

Fields

node: The HTML parse tree node pointer.
next: The next node in the list.
prev: The previous node in the list.

Discussion

Used by the nodelist function.

Globals

broken: The number of broken link requests (such as link requests without an end marker).
debug_relpath: Broken out storage for the relpath debug bit from the -d flag.
debug_reparent: Broken out storage for the reparent debug bit from the -d flag.
debugging: Storage for the -d flag.
duplicates: Number of duplicate API reference markers encountered.
extrefs: The array of external cross-reference seed files encountered during command-line argument handling.
filedebug: Broken out storage for the file debug bit from the -d flag.
force_absolute_globally: Set to 1 if the -a flag is passed prior to any -s flags, else 0.
global_basepath: Storage for the -b flag.
global_basepath_set: Set to 1 if the -b flag is passed in (to distinguish it definitively from the default value).
global_installedpath: Storage for the -i flag.
global_option_disable_name_matching: Set to 1 to disable by-name matching.
global_option_disable_partial_ref_matching: Set to 1 to disable partial matching.
inputDirectory: The input directory, as passed in on the command line.
logfile: A file pointer to a log file.
logname: The temporary filename for the log file, as generated by mkstemp.
namehead: The top of the tree of cross reference nodes sorted by the name of the symbol.
nextrefs: The number of external cross-reference seed files encountered during command-line argument handling.
nfiles: The total number of files processed.
nodehead: The top of the tree of cross reference nodes sorted by the API reference symbol marker.
nodot: Set to 1 to disable printing the dots. This makes debugging in Instruments less traumatic.
nopercent: Disables emission of percent success/failure.
nthreads: Number of threads to use (from the -t flag).
nullfd: File descriptor for /dev/null.
plain: The number of normal (non-logicalPath-based) links.
progname: A global copy of argv[0] so that it doesn't have to be passed around everywhere for use in error messages.
resolved: The number of successfully resolved links.
seeding_in_progress: Set to 1 while new reference markers are being added from seed files, 0 otherwise.
stderrfd: File descriptor for storing a copy of stderr.
thread_exit: Storage for the exit status of helper threads.
thread_processed_files: Per-thread storage for an index into each thread's array of files to be processed.
threadfiles: The array of files to be handled by each helper thread.
unresolved: The number of unresolved links.
unresolved_explicit: The number of unresolved links that were not machine-generated by automated processes.
warn_each: Broken out storage for the relpath warn_each bit from the -d flag.
writedebug: Broken out storage for the write debug bit from the -d flag.

broken

The number of broken link requests (such as link requests without an end marker).

int broken = 0;

debug_relpath

Broken out storage for the relpath debug bit from the -d flag.

int debug_relpath = 0;

Discussion

Used for debugging bugs in the code that calculates relative paths between two absolute paths.

debug_reparent

Broken out storage for the reparent debug bit from the -d flag.

int debug_reparent = 0;

Discussion

Used for debugging bugs in the code that converts commented-out link requests into live links.

debugging

Storage for the -d flag.

int debugging = 0;

duplicates

Number of duplicate API reference markers encountered.

int duplicates = 0;

extrefs

The array of external cross-reference seed files encountered during command-line argument handling.

char *extrefs[MAXEXTREFS];

filedebug

Broken out storage for the file debug bit from the -d flag.

int filedebug = 0;

force_absolute_globally

Set to 1 if the -a flag is passed prior to any -s flags, else 0.

int force_absolute_globally = 0;

global_basepath

Storage for the -b flag.

char *global_basepath = "/";

global_basepath_set

Set to 1 if the -b flag is passed in (to distinguish it definitively from the default value).

int global_basepath_set = 0;

global_installedpath

Storage for the -i flag.

char *global_installedpath = NULL;

global_option_disable_name_matching

Set to 1 to disable by-name matching.

int global_option_disable_name_matching = 0;

Discussion

By default, resolveLinks allows certain link requests to contain only a name and searches for all matching references. If you do not need this, you can significantly improve performance by disabling it.

global_option_disable_partial_ref_matching

Set to 1 to disable partial matching.

int global_option_disable_partial_ref_matching = 0;

Discussion

By default, resolveLinks looks for partial matching in C++ symbols. If you do not need this, you can significantly improve performance on larger docs by disabling this feature.

inputDirectory

The input directory, as passed in on the command line.

char *inputDirectory = NULL;

logfile

A file pointer to a log file.

FILE *logfile = NULL;

Discussion

Points to a file in /tmp for storing a detailed log of link resolution failures, etc.

logname

The temporary filename for the log file, as generated by mkstemp.

char *logname = NULL;

namehead

The top of the tree of cross reference nodes sorted by the name of the symbol.

xrefbyname_t namehead = NULL;

nextrefs

The number of external cross-reference seed files encountered during command-line argument handling.

int nextrefs = 0;

nfiles

The total number of files processed.

int nfiles = 0;

nodehead

The top of the tree of cross reference nodes sorted by the API reference symbol marker.

xrefnode_t nodehead = NULL;

nodot

Set to 1 to disable printing the dots. This makes debugging in Instruments less traumatic.

int nodot = 0;

nopercent

Disables emission of percent success/failure.

int nopercent = 0;

Discussion

To prevent bogus test failures caused by differences in floating point representation, this flag disables that bit of the output.

In the future, this flag may be overloaded for other purposes; its sole purpose is to tell resolveLinks that it is being run from within the test framework.

nthreads

Number of threads to use (from the -t flag).

int nthreads = 2;

nullfd

File descriptor for /dev/null.

int nullfd = -1;

Discussion

Used by setup_redirection, redirect_stderr_to_null, and restore_stderr.

plain

The number of normal (non-logicalPath-based) links.

int plain = 0;

progname

A global copy of argv[0] so that it doesn't have to be passed around everywhere for use in error messages.

char *progname;

resolved

The number of successfully resolved links.

int resolved = 0;

seeding_in_progress

Set to 1 while new reference markers are being added from seed files, 0 otherwise.

int seeding_in_progress = 0;

Discussion

Used to set the fromseed field in each xrefnode_t object.

stderrfd

File descriptor for storing a copy of stderr.

int stderrfd = -1;

Discussion

Used by setup_redirection, redirect_stderr_to_null, and restore_stderr.

thread_exit

Storage for the exit status of helper threads.

int thread_exit[MAXTHREADS];

thread_processed_files

Per-thread storage for an index into each thread's array of files to be processed.

int thread_processed_files[MAXTHREADS];

threadfiles

The array of files to be handled by each helper thread.

fileref_t threadfiles[MAXTHREADS];

unresolved

The number of unresolved links.

int unresolved = 0;

unresolved_explicit

The number of unresolved links that were not machine-generated by automated processes.

int unresolved_explicit = 0;

warn_each

Broken out storage for the relpath warn_each bit from the -d flag.

int warn_each = 0;

Discussion

If set, prints the file name and other info for each unresolvable link request.

writedebug

Broken out storage for the write debug bit from the -d flag.

int writedebug = 0;

Macro Definitions

FIX_TYPE_TO_TOP: When used, declares the function fix_X_to_head where X is a type name.
REBALANCE_TREE: When used, declares the function rebalance_X_tree where X is a type name.
ROTATE_LEFTLEFT: When used, declares the function rotate_X_leftleft where X is a type name.
ROTATE_LEFTRIGHT: When used, declares the function rotate_X_leftright where X is a type name.
ROTATE_RIGHTLEFT: When used, declares the function rotate_X_rightleft where X is a type name.
ROTATE_RIGHTRIGHT: When used, declares the function rotate_X_rightright where X is a type name.
VERIFY_TREE: When used, declares the function verify_X_tree where X is a type name.
VERIFY_TREE_SUB: When used, declares the function verify_X_tree_sub where X is a type name.

FIX_TYPE_TO_TOP

When used, declares the function fix_X_to_head where X is a type name.

#define FIX_TYPE_TO_TOP(TYPE, TOP)

Discussion

Part of the AVL code. The constructed function walks from the current node up to the head, fixing any incorrect maximum depth values as it does so.

REBALANCE_TREE

When used, declares the function rebalance_X_tree where X is a type name.

#ifdef NOAVL 
#define REBALANCE_TREE(TYPE)
#else 
 #define REBALANCE_TREE(TYPE)
#endif

Discussion

Part of the AVL code. The constructed function rebalances the AVL tree after insertion of the node fromnode as a child of the node node.

ROTATE_LEFTLEFT

When used, declares the function rotate_X_leftleft where X is a type name.

#define ROTATE_LEFTLEFT(TYPE, TOP)

Discussion

Part of the AVL code. The constructed function handles rotations in which the left child of the left child needs to be pulled up.

ROTATE_LEFTRIGHT

When used, declares the function rotate_X_leftright where X is a type name.

#define ROTATE_LEFTRIGHT(TYPE, TOP)

Discussion

Part of the AVL code. The constructed function handles rotations in which the right child of the left child needs to be pulled up.

ROTATE_RIGHTLEFT

When used, declares the function rotate_X_rightleft where X is a type name.

#define ROTATE_RIGHTLEFT(TYPE, TOP)

Discussion

Part of the AVL code. The constructed function handles rotations in which the left child of the right child needs to be pulled up.

ROTATE_RIGHTRIGHT

When used, declares the function rotate_X_rightright where X is a type name.

#define ROTATE_RIGHTRIGHT(TYPE, TOP)

Discussion

Part of the AVL code. The constructed function handles rotations in which the right child of the right child needs to be pulled up.

VERIFY_TREE

When used, declares the function verify_X_tree where X is a type name.

#define VERIFY_TREE(TYPE)

Discussion

Part of the AVL code. The constructed function verifies the depth values at all levels of an AVL tree and returns the number of errors.

VERIFY_TREE_SUB

When used, declares the function verify_X_tree_sub where X is a type name.

#ifdef NOAVL 
#define VERIFY_TREE_SUB(TYPE)
#else 
 #define VERIFY_TREE_SUB(TYPE)
#endif

Discussion

Part of the AVL code. The constructed function verifies the depth values at all levels of an AVL tree.

Last Updated: Saturday, August 06, 2016