NEWSOVERVIEW(3)

NAME
newsoverview: novopen, novstream, novall, novnext, novthread, novclose - parse and thread netnews overview files

SYNOPSIS
#include <stdio.h>
#include <hash.h>
#include <hdbm.h>
#include <newsoverview.h>

novartdir(dir)
char *dir;

struct novgroup *novopen(grp)
char *grp;

struct novgroup *novstream(stream)
FILE *stream;

struct novart *novall(gp)
struct novgroup *gp;

struct novart *novnext(gp)
struct novgroup *gp;

novthread(gp)
struct novgroup *gp;

novclose(gp)
struct novgroup *gp;

DESCRIPTION
This library provides access for news readers to the adjunct data maintained for each news group by C News. Memory consumption is one struct novgroup and one hash table per open group, plus one struct novart per article per open group that has had one of novall, novnext, and novthread executed on its behalf, plus one hash table per open group that has had novthread executed on its behalf.

Novartdir may be called to set the news spool directory to dir rather than the default of /usr/spool/news. Novopen opens the overview data for newsgroup grp, and returns a pointer to a structure of type struct novgroup containing at least these members:
    	HASHTABLE *g_msgids;
    	HASHTABLE *g_roots;
or NULL if there is no overview data for grp or it is inaccessible. Novstream is a variant that arranges that stream will be read when needed rather than the overview data for grp. G_msgids is a hash table mapping message-ids to pointers to their corresponding summary data (struct novarts); it will be NULL until novall, novnext, or novthread are called for this group. G_roots is a hash table mapping the message-ids of root messages to pointers to their corresponding summary data; it will be NULL until novthread is run on this group. Either hash table may be walked to enumerate its members (see hashwalk in hash(3)).

Novall returns a pointer to the first structure of a linked list of structures of type struct novart containing at least these members:
    	char *a_num;
    	char *a_subj;
    	char *a_from;
    	char *a_date;
    	char *a_msgid;
    	char *a_refs;
    	char *a_bytes;
    	char *a_lines;		/* a waste of bits */
    	char *a_others;
    	/* these members are message-ids, filled in by novthread() */
    	char *a_parent;
    	char *a_child1;		/* first child of a chain */
    	char *a_sibling;	/* next sibling in this chain */
    	/* end message-ids */
    	struct novart *a_nxtnum;	/* next in numeric order */
All structures in the linked list will be in memory upon return from novall. A_num is the number (file name) of the article in its spool directory. A_subj is the value of the article's Subject: header; a_from its From: header; a_date its Date: header; a_msgid its message-id; a_refs its References: header; a_bytes the number of bytes in the article on disk, including headers and signature(s); a_lines is its Lines: header. A_others is any other headers, for this article, stored in the database by the local database maintenance program. This set of headers is empty by default. If a_others is a non-empty string, it will consist of complete headers (keyword, colon, value and all) with any newlines and tabs turned into spaces, and separated by tabs.

A_parent is the message-id of this article's parent article, if the parent article is described by the overview data for this group; a_child1 the message-id of this article's first child article, if any; a_sibling the message-id of this article's next sibling in a chain, if any. Any of the three members may be NULL if no article applies, and all three will be NULL until novthread is run on the group this article belongs to.

Novnext returns a pointer to the numerically-next (possibly first) article summary structure, or NULL if the group is exhausted. (Numerical order in the database is assumed and not checked.) Novthread constructs a hash table in gp→g_roots of the roots of the trees formed by following References: headers backward. This forest can be walked by traversing these roots using hashwalk (see hash(3)) and looking up the message-ids a_parent, a_child1, and a_sibling in gp→g_msgids (a hash table of all articles in gp). Novclose destroys gp and its substructure.

EXAMPLES
Building, walking and printing a group's reference trees.
    rootvisit(key, data, hook)
    char *key, *data, *hook;
    {
    	prtree((struct novgroup *)hook, ((struct novart *)data)→a_msgid, 1);
    }
    process(in, inname)
    FILE *in;
    char *inname;
    {
    	register struct novgroup *gp;
    	gp = novopen(inname);
    	if (gp == NULL)
    		error("can't open overview file for group `%s'", inname);
    	novthread(gp);
    	if (gp→g_roots != NULL)
    		hashwalk(gp→g_roots, rootvisit, (char *)gp);
    	novclose(gp);
    }
    prtree(gp, msgid, level)
    register struct novgroup *gp;
    register char *msgid;
    register int level;
    {
    	register int i;
    	register struct novart *art;
    	if (gp == NULL || gp→g_msgids == NULL || msgid == NULL)
    		return;
    	art = (struct novart *)hashfetch(gp→g_msgids, msgid);
    	if (art == NULL)
    		return;
    	for (i = 1; i < level; i++)
    		(void) putchar('\t');
    	(void) printf("%s\t%s", art→a_from, msgid);
    	if (level == 1)
    		(void) printf("\t%s", art→a_subj);
    	(void) putchar('\n');
    	prtree(gp, art→a_child1, level + 1);
    	prtree(gp, art→a_sibling, level);	/* next sibling */
    }

FILES
/usr/spool/news/group/.overview
    summary of articles in group

SEE ALSO
nn(1), trn(1), fgetfln(3), hash(3), split(3), newsdb(5), newsoverview(5), relaynews(8)

DIAGNOSTICS
Returns 0 on failure.

HISTORY
Written by Geoff Collyer, as part of the C News project, to provide access to the adjunct data maintained by C News for the benefit of newsreaders.

BUGS
The contents of a_lines should not be believed and are really pretty worthless yet popular.