Commit 5fe78896 authored by David Byers's avatar David Byers

Documentation

        Fixed uses of @code in texinfo manuals

Database
        Added timestamp to database file format
parent 9a38757d
No preview for this file type
......@@ -2,7 +2,7 @@
@c
@c FIXME: Explain how the garb works with nice and keep-commented
@c
@c $Id: Protocol-A.texi,v 1.65 1999/05/21 11:31:51 byers Exp $
@c $Id: Protocol-A.texi,v 1.66 1999/05/23 13:04:57 byers Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -104,27 +104,28 @@ is liable to change in future protocol versions.
This specification is the work of several people. The main contributors have
been
Per Cederqvist @code{<ceder@@lysator.liu.se>},
David Byers @code{<byers@@lysator.liu.se>},
Per Cederqvist @email{ceder@@lysator.liu.se},
David Byers @email{byers@@lysator.liu.se},
@ifinfo
Pär
@end ifinfo
@iftex
P@"ar
@end iftex
Emanuelsson @code{<pell@@lysator.liu.se>},
Thomas Bellman @code{<bellman@@lysator.liu.se>},
Lars Aronsson @code{<aronsson@@lysator.liu.se>},
Linus Tolke @code{<linus@@lysator.liu.se>} and
Emanuelsson @email{pell@@lysator.liu.se},
Thomas Bellman @email{bellman@@lysator.liu.se},
Lars Aronsson @email{aronsson@@lysator.liu.se},
Linus Tolke @email{linus@@lysator.liu.se} and
@ifinfo
Kent Engström
@end ifinfo
@iftex
Kent Eng@-str@"om@penalty-10000
@end iftex
@code{<kent@@lysator.liu.se>}.
@email{kent@@lysator.liu.se}.
The LysKOM developers can be reached by email to @code{lyskom@@lysator.liu.se}.
The LysKOM developers can be reached by email to
@email{lyskom@@lysator.liu.se}.
@menu
* Document Revision History::
......@@ -275,9 +276,9 @@ name was changed, but not the functionality.
@end itemize
@item Status change
@itemize @bullet
@item @code{63=who-is-on-ident} is now considered obsolete.
@item @code{64=get-session-info-ident} is now considered obsolete.
@item @code{59=create-anonymous-text-old} is now considered obsolete.
@item 63=@code{who-is-on-ident} is now considered obsolete.
@item 64=@code{get-session-info-ident} is now considered obsolete.
@item 59=@code{create-anonymous-text-old} is now considered obsolete.
@end itemize
@end table
......@@ -891,9 +892,9 @@ Signatures cannot be deleted once they have been created.
@item pgp-public-key [12] (letterbox)
Data is the public key of the person. It is desirable that the public
key contains a userid of the format "LysKOM <p\([0-9]\)@@\(.*\)>+", where
\1 is the number of the person in the LysKOM server specified in \2.
This rule is currently not enforced.
key contains a userid of the format "LysKOM <p@var{n}@@@var{server}>+",
where @var{n} is the number of the person in the LysKOM server specified
in @var{server}. This rule is currently not enforced.
This item can only be set by the person himself. The hide-creator,
secret and inherit bits are automatically cleared.
......@@ -997,8 +998,8 @@ the imported text will have been created at a later date.
Data is the @code{Message-ID} header of an imported e-mail. This is used
by e-mail importers. LysKOM exporters should set the message ID to
@code{<LysKOM%@i{text-no}@@@i{server}}, where @i{text-no} is the text
number and @i{server} is the name of the server.
@code{<LysKOM%@var{text-no}@@@var{server}}, where @var{text-no} is the text
number and @var{server} is the name of the server.
@item mx-in-reply-to [23] (text)
......@@ -1379,8 +1380,8 @@ transmitted to the server in ASCII-encoded decimal notation.
@tindex HOLLERITH
@dfn{HOLLERITH} denotes character strings of arbitrary length. They are
transmitted as @code{<n>H<text>} where @code{<text>} is the string and
@code{<n>} is the number of characters in @code{<text>} in decimal
transmitted as @code{@var{n}H@var{text}} where @var{text} is the string and
@var{n} is the number of characters in @var{text} in decimal
notation. All byte values are allowed in the string itself, including
nulls.
......@@ -1460,18 +1461,19 @@ integer 5.
@tindex ARRAY
@dfn{ARRAY} is a list of a fixed number of elements of a single type.
The specification for an array is @code{ARRAY <type>} where
@code{<type>} is the type of the array elements.
The specification for an array is @code{ARRAY @var{type}} where
@var{type} is the type of the array elements.
Arrays are transmitted as an @code{<n> @{ <element> <element> ... @}}
where @code{<n>} is the number of elements and each @code{<element>} is
an element of the array. A special case is when the array is empty, in
which case the server transmits it as @code{0 *}. Note that the client
must always transmit empty arrays as @code{0 @{ @}}.
Arrays are transmitted as an @code{@var{n} @{ @var{element}
@var{element} ... @}} where @var{n} is the number of elements and
each @var{element} is an element of the array. A special case is when
the array is empty, in which case the server transmits it as @code{0 *}.
Note that the client must always transmit empty arrays as @code{0 @{
@}}.
In some calls the client can ask the server not to send the array
contents, only its length. In these cases the array is transmitted as
@code{<n> *} where @code{<n>} is the number of elements in the array.
@code{@var{n} *} where @var{n} is the number of elements in the array.
@subsection Selection
......@@ -1482,14 +1484,14 @@ followed by a tail of an arbitrary type and is specified as
@example
SELECTION (
<n>=<name> <tail> : <type>;
<n>=<name> <tail> : <type>;
@var{n}=@var{name} @var{tail} : @var{type};
@var{n}=@var{name} @var{tail} : @var{type};
...
)
@end example
where each @code{<n>} is the selector value, @code{<name>} the selector
name and @code{<tail>} the name of the selector tail and @code{<type>}
where each @var{n} is the selector value, @var{name} the selector
name and @var{tail} the name of the selector tail and @var{type}
its type.
When transmitted, the selector is transmitted as an INT32 followed by
......@@ -1515,17 +1517,17 @@ specification has the following form:
@example
RPC (
<call> <<n>> ( <request> ) -> ( <reply> ) ;
<call> <<n>> ( <request> ) -> ( <reply> ) ;
@var{call} [@var{n}] ( @var{request} ) -> ( @var{reply} ) ;
@var{call} [@var{n}] ( @var{request} ) -> ( @var{reply} ) ;
)
@end example
where each @code{<call>} is the name of a call, @code{<n>} is the call
number, @code{<request>} is a single data element sent as a request and
@code{<reply>} is a single data element sent in reply from the server.
where each @var{call} is the name of a call, @var{n} is the call
number, @var{request} is a single data element sent as a request and
@var{reply} is a single data element sent in reply from the server.
RPC calls are transmitted as @code{<n> <request>} where @code{<n>} and
@code{<request>} have the same meaning as above. Note that in the
RPC calls are transmitted as @var{n} @var{request} where @var{n} and
@var{request} have the same meaning as above. Note that in the
client-server dialog a reference number must also be supplied with each
request. This reference number is not part of the RPC itself, but is
required for communications @xref{Client-Server Dialog}.
......@@ -1538,14 +1540,14 @@ Structures are collections of several data items. In the specification
they are written as
@example
( <name> : <type> ;
<name> : <type> ;
( @var{name} : @var{type} ;
@var{name} : @var{type} ;
...
)
@end example
where each @code{<name>} is the name of a data field and the
corresponding @code{<type>} is its type.
where each @var{name} is the name of a data field and the
corresponding @var{type} is its type.
Structures are transmitted as a sequence of their fields.
......@@ -1951,7 +1953,7 @@ grammar used in this document. This is as close as it gets:
@example
Conf-List-Archaic ::=
( conf-nos : ARRAY Conf-No;
conf-types : ARRAY Conf-Type; ! Sans <n>; see below
conf-types : ARRAY Conf-Type; ! Sans @var{n}; see below
)
@end example
......@@ -2060,11 +2062,11 @@ of @code{Info} and @code{Info-Old} are
@table @code
@item version
The server version encoded as a number @code{aabbcc} where @code{aa} is
the major version number, @code{bb} the minor number and @code{cc} the
secondary minor version. For instance, @code{10607} is version 1.6.7 of
the server. If greater than 10699 the @code{get-version-info} should be
used instead.
The server version encoded as a number @var{aa}@var{bb}@var{cc} where
@var{aa} is the major version number, @var{bb} the minor number and
@var{cc} the secondary minor version. For instance, @code{10607} is
version 1.6.7 of the server. If greater than 10699 the
@code{get-version-info} should be used instead.
@item conf-pres-conf
The conference that contains conference presentations.
@item pers-pres-conf
......@@ -2162,7 +2164,7 @@ The fields of @code{Person} are
@table @code
@item username
The name of the user.
FIXME: this is wrong/needs explanation/should be renamed.
@c FIXME: this is wrong/needs explanation/should be renamed.
@item privileges
The privileges of the person.
@item flags
......@@ -2523,7 +2525,7 @@ A client-supplied string saying what the person is doing.
@item username
The name of the ``real'' user constructed from @code{hostname} and
@code{ident-user} (see below) and information from the client.
FIXME: define the format
@c FIXME: define the format
@end table
......@@ -2541,7 +2543,7 @@ A client-supplied string saying what the person is doing.
@item username
The name of the ``real'' user constructed from @code{hostname} and
@code{ident-user}.
FIXME: define the format
@c FIXME: define the format
@item hostname
The host the connection originated at.
@item ident-user
......@@ -2739,7 +2741,7 @@ or KOM conventions.
@subsection Regexp Matching
This type of expansion, used by the @pxref{re-z-lookup} call and its
predecessors simply matches @code{ed(1)} style regular expressions to
predecessors simply matches @code{ed}(1) style regular expressions to
names in the database to find the list of matching names. The matching
is done without regard for character case.
......@@ -4131,10 +4133,10 @@ and more.
@example
1 26 100
=1 7 35 16 15 6 96 1 196 1 14 1 22 1
@t{7 @{ 0 7 6 85 0 15 6 1
8 13 9 12 37 16 15 6 96 1 196 1
3 311 @}}
@t{=1 7 35 16 15 6 96 1 196 1 14 1 22 1
7 @{ 0 7 6 85 0 15 6 1
8 13 9 12 37 16 15 6 96 1 196 1
3 311 @}}
@end example
In this example, text number 100 was created by person 7 at
......@@ -4433,11 +4435,11 @@ the author.
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1}
@t{ 3 @{ 1 5 6 1 9 34 34 17 17 6 97 4 197 1 @}}
1 31 1 5
=1
@t{=1}
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
1 31 1 5
%1 30 0
@t{%1 30 0}
@end example
In this example, conference 5 is removed from the recipient list of text
......@@ -4609,16 +4611,16 @@ If @code{first-local-no} is higher than the highest local text number,
the server will return an error.
If @code{first-local-no} is lower than the lowest number that still
exists, the server will set @code{result.first-local-no} in the returned
Text-List to the first text that still exists. The size of the returned
array will be decreased by the same amount as
@code{result.first-local-no} is increased. This may result in an empty
array being returned. (This paragraph applies even when
@code{first-local-no} is 0.)
exists, the server will set @code{first-local-no} in the returned
@code{Text-List} to the first text that still exists. The size of the
returned array will be decreased by the same amount as
@code{first-local-no} is increased. This may result in an empty array
being returned. (This paragraph applies even when @code{first-local-no}
is 0.)
If no texts at all exists in @code{conf-no} the resulting array will be
empty, and @code{result.first-local-no} will be set to the number the
next text to be created will receive.
empty, and @code{first-local-no} will be set to the number the next text
to be created will receive.
@example
1 34 119 10 5
......@@ -4957,9 +4959,10 @@ The text @code{text-no} already has the maximum number of marks.
-> ( );
@end example
Sets the security level for the current session to @code{level} (@pxref{Security} for details.) The only levels that make any sense right
now are 0 and 255. This call may be issued by any person, but without
the right privilege bits set, it has no effect.
Sets the security level for the current session to @code{level}
(@pxref{Security} for details.) The only levels that make any sense
right now are 0 and 255. This call may be issued by any person, but
without the right privilege bits set, it has no effect.
@example
1 41 1
......@@ -5889,7 +5892,7 @@ The session @code{session-no} does not exist.
This call is obsolete. It has been replaced by @pxref{re-z-lookup}. It
used to return a list of persons matching the regular expression
@code{regexp}. The regexp syntax used was that of the @code{ed(1)} Unix
@code{regexp}. The regexp syntax used was that of the @code{ed}(1) Unix
utility.
@unnumberedsubsec Error codes
......@@ -5912,7 +5915,7 @@ not a correct regexp.
This call is obsolete. It has been replaced by @pxref{re-z-lookup}. It
used to return a list of conferences matching the regular expression
@code{regexp}. The regexp syntax used was that of the @code{ed(1)} Unix
@code{regexp}. The regexp syntax used was that of the @code{ed}(1) Unix
utility.
@unnumberedsubsec Error codes
......@@ -6318,7 +6321,7 @@ a specific number of unread texts in a particular conference.
This example shows how person 7 originally had read everything up to and
including local text number 6 in conference 6. After the call to
@code{set-last=read}, the @pxref{query-read-texts} call reports that
@code{set-last-read}, the @pxref{query-read-texts} call reports that
person 7 has read everything up to and including local text number 3.
@unnumberedsubsec Error codes
......@@ -7177,14 +7180,15 @@ fields set to zero.
@example
1 99 5 0 3 1
@t{=1 2 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000}
@t{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 00000000 @}}
@t{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 }
@t{ 49 14 17 13 8 91 5 255 1 00000000 @}}
1 99 5 0 1 1
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000 @}}
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 }
@t{ 49 14 17 13 8 91 5 255 1 00000000 @}}
1 99 5 1 4 1
@t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 00000000 @}}
@t{=1 1 @{ 20 14 22 17 6 97 4 197 1 6 100 2 0 * 5 }
@t{ 49 14 17 13 8 91 5 255 1 00000000 @}}
@end example
FIXME: The above example appears to lack the added-at field, so it is
probably bogus.
In this example we retrieve the memberships of person 5. The first call
asks for three memberships, starting with number 0. Since this person is
......@@ -7400,19 +7404,19 @@ how many deleted texts there are after @code{first-local-no}.
@example
1 103 93 1 5
=1 1 7 1 1 1 6 @{ 1003 1005 1009 1029 0 1034 @}
@t{=1 1 7 1 1 1 6 @{ 1003 1005 1009 1029 0 1034 @}}
2 103 93 1 6
=2 1 63 1 0 6 @{
@t{=2 1 63 1 0 6 @{
1 1003
2 1005
3 1009
4 1029
6 1034
62 1302 @}
62 1302 @}}
3 103 93 50 10
=3 50 70 0 0 2 @{
@t{=3 50 70 0 0 2 @{
62 1302
69 1006 @}
69 1006 @}}
@end example
The above example shows three calls to @code{local-to-global}. (Extra
......@@ -7705,7 +7709,7 @@ old name in @code{old-name} and the new name in @code{new-name}.
This message is sent when a session's working conference,
what-i-am-doing string or username changes. The new information is sent
in @code{info}.
FIXME: can the username change?
@c FIXME: can the username change?
......@@ -8602,8 +8606,8 @@ the text was exported.
@item Message-ID
The message ID is to have the format
@code{<LysKOM%@i{textno}@@@i{server}>}, where @i{textno} is the text
number in the server and @i{server} is the name of the LysKOM server.
@code{<LysKOM%@var{textno}@@@var{server}>}, where @var{textno} is the text
number in the server and @var{server} is the name of the LysKOM server.
This allows the importer to figure out how to thread e-mail replies to
exported messages.
......@@ -8667,7 +8671,7 @@ importer want it.
@subsection Threading
T<he importer should do its best to thread messages. When the importer
The importer should do its best to thread messages. When the importer
sees a new message it needs to look at the @code{In-Reply-To} header to
see what the message is a reply to. If a previously imported message or
a LysKOM text is in the @code{In-Reply-To} header, the new text should
......
This diff is collapsed.
/*
* $Id: connections.c,v 0.61 1999/05/21 11:36:44 byers Exp $
* $Id: connections.c,v 0.62 1999/05/23 13:05:12 byers Exp $
* Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996 Lysator Academic Computer Association.
*
* This file is part of the LysKOM server.
......@@ -36,7 +36,7 @@
#endif
static const char *
rcsid = "$Id: connections.c,v 0.61 1999/05/21 11:36:44 byers Exp $";
rcsid = "$Id: connections.c,v 0.62 1999/05/23 13:05:12 byers Exp $";
#include "rcs.h"
USE(rcsid);
......@@ -659,6 +659,7 @@ message_request(IscEvent *event)
void
toploop(void)
{
time_t last_time;
IscEvent * event;
Bool pending_input = TRUE; /* Should be TRUE whenever there
is or might be pending input
......@@ -678,7 +679,14 @@ toploop(void)
event = isc_getnextevent(kom_server_mcb,
pending_input ? 0 : timeout );
last_time = current_time;
current_time = time(NULL);
if (current_time < last_time)
{
kom_log("WARNING: Time is moving in the wrong direction");
/* FIXME: Should we take more decisive action here */
}
timeout = 0;
if ( event == NULL )
......
/*
* $Id: dbck-cache.c,v 0.38 1999/05/12 13:25:06 byers Exp $
* $Id: dbck-cache.c,v 0.39 1999/05/23 13:05:13 byers Exp $
* Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996 Lysator Academic Computer Association.
*
* This file is part of the LysKOM server.
......@@ -39,7 +39,7 @@
static const char *
rcsid = "$Id: dbck-cache.c,v 0.38 1999/05/12 13:25:06 byers Exp $";
rcsid = "$Id: dbck-cache.c,v 0.39 1999/05/23 13:05:13 byers Exp $";
#include "rcs.h"
USE(rcsid);
......@@ -536,8 +536,11 @@ is_clean(const char *fn)
if ( (fp = fopen(fn, "rb")) == NULL )
return FALSE;
if ( getc(fp) == 'C' && getc(fp) == 'L' && getc(fp) == 'E'
&& getc(fp) == 'A' && getc(fp) == 'N' )
if ( getc(fp) == 'C' &&
getc(fp) == 'L' &&
getc(fp) == 'E' &&
getc(fp) == 'A' &&
getc(fp) == 'N' )
{
fclose(fp);
return TRUE;
......@@ -549,6 +552,29 @@ is_clean(const char *fn)
}
}
static void
sync_output_header(FILE* fp, char *state, int oformat)
{
switch (oformat)
{
case 0:
fprintf(fp, "DIRTY\n");
break;
case 1:
fprintf(fp, "DIRTY:%05ld\n", (long)oformat);
break;
case 2:
fprintf(fp, "DIRTY:%05ld\n", (long)oformat);
fprintf(fp, "%020lu\n", (unsigned long)time(NULL));
break;
default:
restart_kom("sync_output_header(): Unknown output format %d",
oformat);
}
}
#ifdef TIME_SYNC
static long
timerdiff(struct timeval a,
......@@ -606,11 +632,12 @@ cache_sync_all(void)
switch (oformat)
{
case 0:
fprintf(fp, "DIRTY\n"); /* DIRTY-FLAG */
sync_output_header(fp, "DIRTY", oformat);
fprintf(fp, "%d\n", next_free_num); /* NEXT_FREE_NUM */
break;
case 1:
fprintf(fp, "DIRTY:%05ld\n", oformat);
case 2:
sync_output_header(fp, "DIRTY", oformat);
fprintf(fp, "#C %d\n", next_free_num);
fprintf(fp, "#T %ld\n", next_text_num);
fprintf(fp, "I");
......@@ -636,6 +663,7 @@ cache_sync_all(void)
putc('\n', fp);
break;
case 1:
case 2:
if ( conf_arr[ i ] != NULL )
{
fprintf(fp, "C %lu", i);
......@@ -669,6 +697,7 @@ cache_sync_all(void)
putc('\n', fp);
break;
case 1:
case 2:
if ( pers_arr[ i ] != NULL )
{
fprintf(fp, "P %lu", i);
......@@ -719,6 +748,7 @@ cache_sync_all(void)
putc('\n', fp);
break;
case 1:
case 2:
if ( text_arr[ i ] != NULL )
{
fprintf(fp, "T %lu", i);
......@@ -745,6 +775,7 @@ cache_sync_all(void)
case 0:
break;
case 1:
case 2:
break;
default:
restart_kom("Unknown output file format: %ld\n", oformat);
......@@ -759,7 +790,7 @@ cache_sync_all(void)
#endif
rewind(fp);
fprintf(fp, "CLEAN");
sync_output_header(fp, "CLEAN", oformat);
fclose(fp);
#ifdef TIME_SYNC
......@@ -897,11 +928,15 @@ init_cache(void)
}
break;
case 1:
case 2:
fseek(fp, 12, SEEK_SET);
if (vflag)
kom_log("Data file version is '%ld'\n", data_file_version);
break;
case 2:
fseek(fp, 33, SEEK_SET);
if (vflag)
kom_log("Data file version is '%ld'\n", data_file_version);
break;
default:
restart_kom("Unknown input file format: %ld\n", data_file_version);
}
......
/*
* $Id: simple-cache.c,v 0.77 1999/05/21 11:36:58 byers Exp $
* $Id: simple-cache.c,v 0.78 1999/05/23 13:05:14 byers Exp $
* Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996 Lysator Academic Computer Association.
*
* This file is part of the LysKOM server.
......@@ -40,7 +40,7 @@
#endif
static const char *
rcsid = "$Id: simple-cache.c,v 0.77 1999/05/21 11:36:58 byers Exp $";
rcsid = "$Id: simple-cache.c,v 0.78 1999/05/23 13:05:14 byers Exp $";
#include "rcs.h"
USE(rcsid);
......@@ -1427,6 +1427,13 @@ get_version(const char *fn)
return version;
}
static void
sync_output_header(FILE* fp, const char *state)
{
fprintf(fp, "%s:%05ld\n", state, 2L); /* DIRTY-FLAG and VERSION*/
fprintf(fp, "%020lu\n", (unsigned long)current_time);
}
static void
pre_sync(void)
{
......@@ -1591,7 +1598,7 @@ pre_sync(void)
fprintf(file_b, "DIRTY:%05ld\n", 2L); /* DIRTY-FLAG and VERSION*/
sync_output_header(file_b, "DIRTY");
fprintf(file_b, "#C %d\n", highest_conf_no);
fprintf(file_b, "#T %ld\n", highest_text_no);
fprintf(file_b, "I");
......@@ -1990,15 +1997,17 @@ save_one_text(void)
return;
}
fprintf(file_b, "CLEAN");
sync_output_header(file_b, "CLEAN");
if ( ferror(file_b) != 0 )
{
kom_log ("save_one_text(): fprintf(CLEAN) failed.\n");
kom_log ("save_one_text(): Set state to CLEAN failed.\n");
sync_state = sync_error;
return;
}
if (fflush(file_b) != 0)
{
kom_log ("save_one_text(): fflush failed.\n");
......@@ -2206,6 +2215,7 @@ init_cache(void)
Bool read_text_no = FALSE;
Bool read_conf_no = FALSE;
int c = 0;
time_t saved_time = 0;
small_conf_arr = smalloc(sizeof(*small_conf_arr) * param.max_conf);
pers_mcb = create_cache_node_mcb(100, param.max_conf);
......@@ -2298,7 +2308,17 @@ init_cache(void)
restart_kom("You need to run dbck to convert your datafile to version 2.\n");
break;
case 2:
/*
* Read timestamp