Commit 6ee9dcb0 authored by David Byers's avatar David Byers
Browse files

Documentation updates:

        Merged lyskomd.texi, hacking.texi and dbck.texi
        Added what-is-unread.swe to Protocol-A.texi

        Handle disabled item types in a cleaner manner.
        Fixed bugs related to linked aux items. This feature
        should work pretty well now.
        Added test cases to test linking aux items.
parent 32965bf8
......@@ -5,6 +5,38 @@
* src/server/testsuite/lyskomd.0/08.exp: New file.
1999-05-18 David Byers <>
* doc/lyskomd.texi: Merged dbck.texi and hacking.texi into
* src/server/testsuite/lyskomd.0/03.exp: Updated
query-predefined-aux-items result.
* src/server/testsuite/lyskomd.0/01.exp: Updated
query-predefined-aux-items result.
* src/server/aux-items.c (undelete_aux_item_list): Fixed
conference/text mixup
(delete_aux_item_list): Same here.
(undelete_aux_item_list): Save kom_errno and err_stat across call.
* src/server/aux-item-def-parse.y: Deal with disabled definitions
in a more sensible manner.
* src/server/aux-items.c (aux_item_add_perm): Check the disabled
field of the aux-item definition.
* src/server/aux-items.h: Added disabled field.
1999-05-17 David Byers <>
* src/server/aux-items.c (aux_item_list_add_items): New utility
(system_add_aux_item_list): Use aux_item_list_add_items.
(text_stat_add_aux_item_list): Use aux_item_list_add_items.
(conf_stat_add_aux_item_list): Use aux_item_list_add_items.
1999-05-16 Per Cederqvist <>
Use a global variable to store the current time, so that it is
......@@ -111,6 +143,24 @@
* src/server/ram-smalloc.c: Don't test USE_GNU_MALLOC; that symbol
was removed 1998-08-09.
1999-05-16 David Byers <>
* src/server/aux-items.c (prepare_aux_item): Don't clear the link
field of the aux item.
(aux_inherit_items): Clear the link in the copied item before
calling add triggers.
(aux_item_link_items): New function.
(aux_item_trigger_mirror_faq): Use aux_item_link_items.
(aux_item_trigger_link_item): Use aux_item_link_items.
(aux_item_call_add_triggers): Fix the trigger data after calling
each trigger since one of them might move the aux item list in
1999-05-15 David Byers <>
* src/server/aux-items.c (aux_item_trigger_link_item): New
function for debugging linking aux items.
1999-05-14 Per Cederqvist <>
Fixes to the test suite.
......@@ -143,6 +193,116 @@
(lyskomd_fail_start): Likewise. Find the database files relative
to top_srcdir.
1999-05-14 David Byers <>
* src/server/text.c (do_create_text): Return long-array if there
are too many misc items.
(modify_text_info): Set err_stat to max length when returning
* src/include/kom-types.h (Info_datum): Added unknown_type to
* src/server/text.c (find_recipient): Add unknown_info to the
switch. Stop the server if COMPILE_CHECKS is undefined.
(is_member_in_recpt): Same here.
(do_delete_misc): Same here.
(do_sub_recpt): Same here.
(sender): Same here.
(is_sender): Same here.
(is_comm_sender): Same here.
(skip_recp): Same here.
(recp_sent_by): Same here.
(filter_secret_info): Same here.
(do_delete_text): Same here.
(check_double_subm): Same here.
(check_double_comm): Same here.
(create_text_check_misc): Return an illegal-info-typye if we see
an unknown info. Set err_stat to the index of the bad item when
returning a KOM_ILL_MISC.
(create_text_add_miscs): Same here.
* src/server/prot-a.c (prot_a_destruct): Free the misc_info_list
field of the connection.
* src/server/membership.c (add_rec_time): Handle unknown_info and
other unknown misc info types by shutting down the server.
* src/server/call-switch.awk: Add support for misc_info_list in
* src/server/text.c (create_text_old): Changed parameter list to
use Misc_info_list instead of an integer and a Misc_info pointer.
(create_text): Same here.
(create_anonymous_text): Same here.
(create_anonymous_text_old): Same here.
* src/server/fncdef.txt: Changed all "num c_misc_info_p" to
* src/server/prot-a-parse-arg-c.awk: The aux_item type works again.
Allow misc_info_list as a type name.
* src/server/prot-a-parse.c (prot_a_parse_misc_info_list): New
* src/server/prot-a.c (prot_a_init): Initialize the misc_info_list
* src/server/internal-connections.c (kill_client): Use
misc_info_list field of Connection.
* src/server/connections.c (free_parsed): Clear the misc_info_list
* src/include/kom-types.h (Misc_info_list): New type
* src/server/internal-connections.c (init_connection): Initialize
hunt_parse_pos, array_hunt_depth and array_hunt_num. Initialize
* src/server/prot-a-parse.c (prot_a_hunt_array_end): New function
hunts for the end of an array.c
* src/server/prot-a.c (prot_a_init): Initialize hunt_parse_pos and
* src/include/kom-types.h (Info_type): Added unknown info type.
* src/server/prot-a-parse.c (prot_a_parse_misc_info): Parse all
misc-info types that the server knows about. Unknown types
generate a protocol error.
* src/server/testsuite/lyskomd.0/prot-a-parse-cov.exp (1021):
Expcet long-array and not protocol-error.
* src/server/prot-a-parse.c (prot_a_parse_aux_item_list): Discard
the part of the list that is longer than the max rather than send
a protocol error.
1999-05-13 David Byers <>
* src/server/testsuite/lyskomd.0/prot-a-parse-cov.exp
(protocol_error): Removed expected failure.
* src/server/admin.c (modify_server_info): Return KOM_LONG_ARRAY
when we see a long array.
* src/server/conference.c (modify_conf_info): Return
KOM_LONG_ARRAY when we see a long array.
* src/server/text.c (modify_text_info): Return KOM_LONG_ARRAY when
we see a long array.
* src/server/prot-a-parse.c (prot_a_parse_num_list): Truncate a
parsed array to one more than the maximum length and skip all
other elements.
* src/server/aux-items.c (undelete_aux_item_list): Log if the link
type is undefined and do not attempt to undelete.
(delete_aux_item_list): Likewise.
1999-05-13 Per Cederqvist <ceder@gratia>
Distribute the leaks tests, and run them during "make check".
......@@ -9,11 +9,13 @@ Testfall f
* Showstoppers
** Make sure that there are no "expected failures" in the test suite.
** Consider changing many paths so that it is safe to install lyskomd
with prefix=/usr/local.
How about saving this for the next release and then support
various other path conventions?
** Consider removing the pid file on exit.
** Consider locking the database, so that dbck cannot do harm, and so
......@@ -29,25 +31,36 @@ Testfall f
** Documentation Issues
*** Document "%%Unsupported protocol" message
*** Document "%% No connections left" message
*** Remove the text "In all likelihood, the implementation of this flag
is screwed up." from lyskomd.texi after checking that
supervisor-only works properly.
*** Move dbck.texi, hacking.tex and lyskomdb.texi into lyskomd.texi.
Two reasons: there are too many manuals, and automake apparently
doesn't allow more than one file to include version.texi.
*** Document updateLysKOM in lyskomd.texi.
There should be an "Invoking updateLysKOM" node.
updateLysKOM should use the "Status file" parameter (and other
parameters). (DONE)
Use parameters in src/server/updateLysKOM.c`savecore(). (DONE)
I will do this --ceder
*** Fix doc/lyskomdb.texi (Version 1) (see FIXME comments).
*** Document komrunning in lyskomd.texi.
There should be an "Invoking komrunning" node.
komrunning should be rewritten i C; it only works with BSD-style ps
programs. (DONE, but it no longer displays the process)
I am doing this --ceder
*** Dump all little doc files into the texinfo manuals.
disc-cache.spec lyskomd.texi översätt, uppdatera
local-to-global.doc lyskomd.texi ceder?
prot-a-tankar *
prot_a *
security-levels.txt Protocol-A.texi DONE
what-is-unread.swe Protocol-A.texi DONE
I will do this --DCB
*** Fix the node structure of Protocol-A.texi (3228867).
I will do this --DCB
Looks done...
*** Update/rewrite README.
......@@ -62,8 +75,6 @@ Testfall f
*** The protocol revision section of is incomplete.
I will do this --ceder
*** Document that session number 0 can be used in call 55.
** Build Issues
*** Check that texinfo.tex is included in a proper place by automake.
......@@ -76,6 +87,12 @@ Testfall f
** Testing
*** Try sending in negative lengths whenever we can send an array.
DONE for misc-info-list, add-aux delete-aux
*** Check that we don't leak memory when truncating a long
aux_item_list send from the client.
*** In prot_a_get_token, what is an insane token length?
*** Test validation of regexps containing groups. Try "X\\(YZ\\)?X".
......@@ -87,13 +104,6 @@ Testfall f
*** Should anyone be able to set their letterbox to secret?
*** There is no way to set the Personal_flags. It's not even obvious
where it gets its initial value! This is Not Good At All.
*** If we try to create a pers or conf and have reached the limit
of how many confs we can create, lyskomd just dies. Nasty. It
should return index-out-of-range, like create-text.
*** Timestamps of various things are not synchronized.
This is seen easily when lyskomd executes really slowly.
Known cases: last-written does not match text-stat (FIXED)
......@@ -671,6 +681,59 @@ Testfall f
removed. (1108039).
REJECT: too much work to be worth it.
*** Document "%%Unsupported protocol" message
*** Document "%% No connections left" message
*** Fix doc/lyskomdb.texi (Version 1) (see FIXME comments).
*** Document that session number 0 can be used in call 55.
*** There is no way to set the Personal_flags. It's not even obvious
where it gets its initial value! This is Not Good At All.
*** If we try to create a pers or conf and have reached the limit
of how many confs we can create, lyskomd just dies. Nasty. It
should return index-out-of-range, like create-text.
** When we pass a read-only misc item in create-text we get a protocol
error. We should get an illegal-misc. We can't just pass it through
since create_text_add_miscs will abort if it sees one of these misc
** Parsing arrays that are longer than the maximum length is not
handled very well. Right now we return a protocol error most of the
time, but perhaps it would be better to return a protocol error
only when the array is insanely long, not just when it is longer
than the max. So we could have a global max array length parameter.
** Make sure that there are no "expected failures" in the test suite.
** Try sending a too-long aux-item list
** Send a too-long misc-item list
** Sending a too-long delete or add list crashes the server.
** Call add-recipient with really bogus info type
*** Move dbck.texi, hacking.tex and lyskomdb.texi into lyskomd.texi.
Two reasons: there are too many manuals, and automake apparently
doesn't allow more than one file to include version.texi.
* In progress
......@@ -2,7 +2,7 @@
@c FIXME: Explain how the garb works with nice and keep-commented
@c $Id: Protocol-A.texi,v 1.63 1999/05/13 11:35:24 ceder Exp $
@c $Id: Protocol-A.texi,v 1.64 1999/05/18 13:06:18 byers Exp $
@c %**start of header
@settitle LysKOM Protocol A
......@@ -61,7 +61,7 @@ another language under the same conditions as for modified versions.
@end titlepage
@node Top
@node Top, Overview, (dir), (dir)
@top LysKOM Protocol A
This document specifies version 10 of LysKOM Protocol A.
......@@ -87,7 +87,7 @@ publication.
@end menu
@end ifinfo
@node Overview
@node Overview, Introduction, Top, Top
@chapter Overview
LysKOM is a conferencing system@footnote{Or in modern terms, enabling
......@@ -132,7 +132,7 @@ The LysKOM developers can be reached by email to @code{}.
* Notation::
@end menu
@node Document Revision History
@node Document Revision History, Protocol Version History, Overview, Overview
@section Document Revision History
@table @asis
......@@ -170,7 +170,7 @@ Per Cederqvist started using version control for documentation.
Lars Aronsson documented the protocol that was in use at the time.
@end table
@node Protocol Version History
@node Protocol Version History, Notation, Document Revision History, Overview
@section Protocol Version History
@subsection Protocol version 10 (first implemented in lyskomd 2.0.0)
......@@ -412,7 +412,7 @@ All calls from 0--56.
@end table
@node Notation
@node Notation, , Protocol Version History, Overview
@section Notation
This specification uses a BNF-like grammar to describe the protocol and
......@@ -435,7 +435,7 @@ literal strings. There is to be no whitespace before or after literal
strings unless there is whitespace in the literal itself.
@node Introduction
@node Introduction, Data Types, Overview, Top
@chapter Introduction
This chapter introduces the concepts used in LysKOM, such as articles,
......@@ -452,7 +452,7 @@ conferences and sessions.
@end menu
@node Articles
@node Articles, Conferences, Introduction, Introduction
@section Articles
An article is represented as a value of the type @code{Text-Stat} and a
......@@ -482,7 +482,7 @@ The server call @code{local-to-global} does this.
@node Conferences
@node Conferences, The Misc-Info List, Articles, Introduction
@section Conferences
Conferences hold articles. They are represented in the protocol as a
......@@ -535,7 +535,7 @@ changed to this type, preexisting secret members remain secret.
* Persons and Sessions::
@end menu
@node Persons and Sessions
@node Persons and Sessions, , Conferences, Conferences
@subsection Persons and Sessions
Persons are represented in the protocol by values of the type
......@@ -553,7 +553,7 @@ the network connection is closed; a user can log in and out repeatedly
in a single session.
@node The Misc-Info List
@node The Misc-Info List, The Aux-Item List, Conferences, Introduction
@section The Misc-Info List
The @code{Misc-Info} list contains tagged data. The fields are sent in
......@@ -702,7 +702,7 @@ article number which is a footnote to this article.
@end table
@node The Aux-Item List
@node The Aux-Item List, Security, The Misc-Info List, Introduction
@section The Aux-Item List
The aux-item list is used as a generic extension mechanism in the LysKOM
......@@ -716,7 +716,7 @@ server and in protocol A.
* Defining New Aux-Item Types::
@end menu
@node About Aux-Items
@node About Aux-Items, Predefined Aux-Item Types, The Aux-Item List, The Aux-Item List
@subsection About Aux-Items
Aux-items were introduced in protocol version 10 as a mechanism for
......@@ -748,7 +748,7 @@ no understanding of the contents can successfully parse the item anyway
@node Predefined Aux-Item Types
@node Predefined Aux-Item Types, Client-Specific Aux-Item Types, About Aux-Items, The Aux-Item List
@subsection Predefined Aux-Item Types
Predefined Aux-Item types are part of Protocol A, and clients should
......@@ -1065,7 +1065,7 @@ collection.
@end table
@node Client-Specific Aux-Item Types
@node Client-Specific Aux-Item Types, Experimental Aux-Item Types, Predefined Aux-Item Types, The Aux-Item List
@subsection Client-Specific Aux-Item Types
Client-specific items do not cause the server to perform any magic. All
......@@ -1087,7 +1087,7 @@ If you want a range of numbers, send e-mail to the LysKOM development
@node Experimental Aux-Item Types
@node Experimental Aux-Item Types, Defining New Aux-Item Types, Client-Specific Aux-Item Types, The Aux-Item List
@subsection Experimental Aux-Item Types
Experimental numbers are free for all. Use 'em any way you want. All
......@@ -1095,7 +1095,7 @@ numbers in the range 20000-29999 are for experimental use.
@node Defining New Aux-Item Types
@node Defining New Aux-Item Types, , Experimental Aux-Item Types, The Aux-Item List
@subsection Defining New Aux-Item Types
If you want a new predefined item type, just document what it does, what
......@@ -1121,7 +1121,7 @@ much less painful process than adding new calls.
@node Security
@node Security, Membership and Reading, The Aux-Item List, Introduction
@section Security
Security in LysKOM is based on two components. Each person has a set of
......@@ -1195,7 +1195,7 @@ Create persons
@end table
@node Membership and Reading
@node Membership and Reading, Client-Server Dialog, Security, Introduction
@section Membership and Reading
Persons' memberships in conferences are represented in the protocol as
......@@ -1242,7 +1242,7 @@ global text numbers. If the server does not implement the
efficient but perfectly serviceable @pxref{get-map} call instead.
@node Client-Server Dialog
@node Client-Server Dialog, , Membership and Reading, Introduction
@section Client-Server Dialog
The client-server dialog consists of two phases, establishing the connection
......@@ -1259,7 +1259,7 @@ the user connecting is followed by a newline character.
When the server has accepted the connection its reply is
protocol-dependent. Protocol A servers will reply with the string
@code{LysKOM} on a single line.
@code{LysKOM} on a single line if the connection attampt is successful.
% telnet 4894
......@@ -1270,6 +1270,17 @@ protocol-dependent. Protocol A servers will reply with the string
@end example
Besides the string "LysKOM", the server may respond with "%%Unsupported
protocol" or "%% No connections left.".
The "%%Unsupported protocol" reply is sent if the server does not
understand the requested protocol.
The "%% No connections left" reply is sent if the server is not
accepting additional connections. This error is transient. The next
connection attempt may succeed. Clients should wait a few seconds before
attempting to make another connection after receiving this error.
After connecting, calls to the server can be made. Most calls require
the user to log in, but some calls can be made without a log-in. Calls
to the server are made by sending a reference number followed by the
......@@ -1288,7 +1299,7 @@ request or an error code preceded by an indicator and the reference
server-reply ::= ok-reply | error-reply;
server-reply ::= ok-reply | error-reply | protocol-error;
ok-reply ::=
( "="
......@@ -1304,6 +1315,8 @@ number.
error-no ::= INT32;
protocol-error ::= "%% LysKOM protocol error."
@end example
Our notation is not flexible enough to specify the two-way nature of the
......@@ -1311,8 +1324,8 @@ communication. @code{ref-no} in the reply is always the same as
@code{ref-no} in the corresponding request. @code{reply-data} depends on
which request was made and is specified together with each request.
Please note that there is no whitespace after the initial indicator in
the reply.
Note that there is no whitespace after the initial indicator in the
Error reporting is covered in more detail in chapter @ref{Error Codes}.
......@@ -1327,8 +1340,14 @@ and understand requests using the older conventions, but clients must
conform to the current convention of separating data elements with
spaces and terminating all requests with a linefeed character.
If the request is syntactically incorrect, the server will respond with
the string "%% LysKOM protocol error." The server will attempt to
recover from the error, but in some cases complete recovery may not be
possible, which may result in one or more subsequent requests being
@node Data Types
@node Data Types, Protocol Requests, Introduction, Top
@chapter Data Types
The data types in protocol A come in two flavors. The first (vanilla)
......@@ -1342,7 +1361,7 @@ while complex data types include things such as conferences and people.
* Name Expansion::
@end menu
@node Simple Data Types
@node Simple Data Types, LysKOM Data Types, Data Types, Data Types
@section Simple Data Types
@subsection Integers
......@@ -1531,7 +1550,7 @@ corresponding @code{<type>} is its type.
Structures are transmitted as a sequence of their fields.
@node LysKOM Data Types
@node LysKOM Data Types, Name Expansion, Simple Data Types, Data Types
@section LysKOM Data Types
In this section the data types specific to LysKOM are defined. Most of
......@@ -2711,7 +2730,7 @@ The dynamic session flags (see above.)
What the client is doing. This string is set by the client.
@end table
@node Name Expansion
@node Name Expansion, , LysKOM Data Types, Data Types
@section Name Expansion
Names in LysKOM can be expanded according to two rules, regexp matching
......@@ -2756,7 +2775,7 @@ equivalent according to swascii rules.
@node Protocol Requests
@node Protocol Requests, Asynchronous Messages, Data Types, Top
@chapter Protocol Requests
This chapter documents all calls that can be made to the server. All
......@@ -2893,10 +2912,9 @@ in the example.
* local-to-global:: r Map local text numbers to global ones (103)
* map-created-texts:: r Map texts created by a person to glogal (104)
* set-keep-commented:: r Set how new comments protect old texts (105)
* set-pers-flags:: r Set the flags on a person (106)
@end menu
@node login-old
@node login-old, logout, Protocol Requests, Protocol Requests
@section login-old (1) Obsolete
@findex login-old
......@@ -2922,7 +2940,7 @@ error-status indicates the person number.
@end table
@node logout
@node logout, change-conference, login-old, Protocol Requests
@section logout (1) Recommended
@findex logout
......@@ -2946,7 +2964,7 @@ places less load on the server than does creating new sessions.
This call never fails.
@node change-conference
@node change-conference, change-name, logout, Protocol Requests
@section change-conference (1) Recommended
@findex change-conference
......@@ -2975,7 +2993,7 @@ The user currently logged in is not a member of @code{conference}.
@end table
@node change-name
@node change-name, change-what-i-am-doing, change-conference, Protocol Requests
@section change-name (1) Recommended
@findex change-name
......@@ -3018,7 +3036,7 @@ There are invalid characters in @code{new-name}.
@end table
@node change-what-i-am-doing
@node change-what-i-am-doing, create-person-old, change-name, Protocol Requests
@section change-what-i-am-doing (1) Recommended
@findex change-what-i-am-doing
......@@ -3040,7 +3058,7 @@ using LysKOM. Clients are encouraged to use this call creatively.
@node create-person-old
@node create-person-old, get-person-stat-old, change-what-i-am-doing, Protocol Requests
@section create-person-old (1) Obsolete (10)
@findex create-person-old
......@@ -3092,7 +3110,7 @@ The string @code{passwd} is not a valid password.