"Fossies" - the Fresh Open Source Software Archive 
Member "tin-2.6.2/doc/internals.txt" (3 Nov 2021, 3790 Bytes) of package /linux/misc/tin-2.6.2.tar.xz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "internals.txt":
2.6.0_vs_2.6.1.
1 I/O in tin (updated 05/01/98)
2 ----------
3
4 All critical I/O, be it NNTP data or not, should be done with
5 tin_fgets() This handles data formatting, removes any trailing \n and \r
6 and deals with timeouts, reconnections and user aborts.
7 It always returns a full line of data - all memory management is handled
8 internally.
9
10 It supports the use of 'q' to cancel the operation and 'Q' to exit tin
11 without error recovery.
12
13 tin_errno will be set to !0 to flag errors. Currently the only
14 supported error is 'user aborted with q'.
15
16 Closing data streams should be done with TIN_FCLOSE(fp) as the NNTP
17 socket should be kept open, whereas local spool fd's must be closed.
18 TIN_FCLOSE() takes care of this.
19
20 If you wish to quit reading an NNTP stream, then call drain_buffer(fp) to
21 clear out any pending data on the NNTP socket.
22
23 nntp_command(command, valid_response, rest_of_data) should be used for
24 sending all generic NNTP command. It returns an fd to the open stream
25 for reading the rest of the data.
26
27
28 Example of a typical exchange:
29
30 if ((fp = nntp_command ("GROUP comp.thing", OK_GROUP, NULL)) != NULL) {
31
32 while ((ptr = tin_fgets(fp, FALSE)) != NULL)
33 process_data(ptr);
34
35 #ifdef NNTP_ABLE
36 if (ptr)
37 drain_buffer(fp);
38 #endif /* NNTP_ABLE */
39
40 TIN_FCLOSE(fp);
41
42 if (tin_errno)
43 handle_abort();
44 }
45
46
47
48 Hashing in tin (updated 05/01/98)
49 --------------
50
51 All the main arrays in tin are dynamically managed by functions in memory.c
52 They are preallocated to an initial size and then grown if the high
53 water mark is exceeded.
54
55 The main structures are:
56
57 active[]
58 An array of all the groups in the active file
59
60 arts[]
61 This is an array of the article headers for the current group. Only headers
62 present in the overview (NOV) database are stored.
63
64 base[]
65 An array of integers that represent the index in arts[] of the current
66 root article for each displayed thread.
67
68 group_hash[]
69 active[] is hashed for faster access. An entry of -1 denotes no group at
70 this hashnode, >= 0 denotes an index into active[]
71 Multiple groups on one node are chained via the .next field (another index
72 ptr to active[])
73
74 my_group[]
75 List of integer pointers into active[]
76 These are the groups that actually appear on the selection screen
77
78 msgids[]
79 Hashed array of all the individual message-ids in arts[]
80 All the Message-ID and Reference headers are broken down and stored here.
81 They are linked together by parent, sibling and child pointers
82
83 table[]
84 Hash of the key text headers from the articles, to save space and speed up
85 searches and compares.
86
87
88 The functions that manipulate the above include:
89
90 active.c:
91 read_news_active_file() populates active[] using group_add()
92
93 art.c:
94 Many of the overview headers are stored with hash_str()
95 base[] is populated by find_base()
96
97 hashstr.c:
98 hash_str() Hashes text strings
99 In the article header, the following text is hashed:
100 From: (including full name if supplied)
101 Subject:
102
103 list.c:
104 init_group_hash() clears group_hash[]
105 find_group_index() returns index of group in active[]
106 group_find() returns a pointer to a group in active[]
107 group_add() adds a group into active[] and hashes it in group_hash[]
108 hash_groupname() returns hash key for a group
109 This is also used to hash the actual filenames written
110 in ~/.tin/.news (when not using NNTP)
111 There is experimental code here for a (presumably)
112 improved hash function that was never completed.
113
114 main.c:
115 Just the initializers for hashing
116
117 memory.c:
118 Dynamic array management.
119 hash_reclaim() - free up table[] which holds the
120 text cache
121
122 refs.c:
123 Handling for msgids[]
124 When threading, each msgid in the hash has a pointer back to
125 its article header in arts[] or ART_UNAVAILABLE if the article is not
126 available
127
128 select.c:
129 my_group_add() adds a group to my_group[]
130 my_group_find() returns the index of a group in my_group[]