diff --git a/doc/lyskomd.texi b/doc/lyskomd.texi index 701745e2d44f76d5087e72f6c21180401005a16f..42e3d3d6856e5466fe6618b46060d3cdae46b950 100644 --- a/doc/lyskomd.texi +++ b/doc/lyskomd.texi @@ -1,5 +1,5 @@ \input texinfo -@c $Id: lyskomd.texi,v 1.20 1999/05/21 12:40:59 byers Exp $ +@c $Id: lyskomd.texi,v 1.21 1999/05/23 11:45:53 ceder Exp $ @c %**start of header @setfilename lyskomd.info @include version.texi @@ -67,7 +67,7 @@ another language under the same conditions as for modified versions. @end titlepage @ifinfo -@node Top, Copying, (dir), (dir) +@node Top @top lyskomd lyskomd is a server for the LysKOM conferencing system. This info file @@ -90,31 +90,31 @@ documents version @value{VERSION} of lyskomd. @end ifinfo -@node Copying, Overview, Top, Top +@node Copying @chapter Copying -lyskomd is free software. It is distributed under the Gnu General Public -License version 2. The file COPYING in the top level of the distribution +lyskomd is free software. It is distributed under the Gnu General Public +License version 2. The file COPYING in the top level of the distribution contains the text of the license. -@node Overview, Installation, Copying, Top +@node Overview @chapter Overview LysKOM is a conferencing system@footnote{Or in modern terms, enabling technology for Computer-Supported Cooperative Work (CSCW).}. Similar systems were QZ-KOM and PortaCOM@footnote{Also known as ``PottaKOM'' and ``BortaKOM''.}. The LysKOM system is copyrighted by Lysator Academic -Computing Society and distributed under conditions of the GNU Public -License. LysKOM and its documentation is provided ``as is'' without +Computing Society and distributed under conditions of the GNU General Public +License version 2. LysKOM and its documentation is provided ``as is'' without warranty of any kind. This reference manual documents version @value{VERSION} of the lyskomd LysKOM server. The lyskomd server is the work of several people. The main contributors have been -Per Cederqvist @email{ceder@@lysator.liu.se}, -Inge Wallin @email{inge@@lysator.liu.se}, -Thomas Bellman @email{bellman@@lysator.liu.se}, +Per Cederqvist @email{ceder@@lysator.liu.se}, +Inge Wallin @email{inge@@lysator.liu.se}, +Thomas Bellman @email{bellman@@lysator.liu.se}, David Byers @email{byers@@lysator.liu.se} and Peter Eriksson @email{pen@@lysator.liu.se}. @@ -129,28 +129,25 @@ In 1990, Per Cederqvist @email{ceder@@lysator.liu.se} and Peter Eriksson server. It was operational in the summer of 1990, even though the members of Lysator discovered a thing called MUD. We started using RCS on 20 May 1991. The first release was made on 16 Sept 1991. Around that -time we switched from RCS to CVS, and ceder started to write pcl-cvs (a -GNU Emacs front-end to CVS) instead of LysKOM. After a while, he started -writing Bugtrack, to be able to handle all bug reports he recieved about -pcl-cvs. He hopes to be able to devote some more time to LysKOM in the -future. +time we switched from RCS to CVS to handle our source code. -@node Installation, Configuration, Overview, Top +@node Installation @chapter Installation -Instructions for compiling and installing lyskomd are in the file -INSTALL, located in the top level of the lyskomd distribution. -Installation should be straightforward on most platforms. +Instructions for compiling and installing lyskomd are in the files +@file{README} and @file{INSTALL}, located in the top level of the +lyskomd distribution. Installation should be straightforward on most +platforms. -@node Configuration, Running lyskomd, Installation, Top +@node Configuration @chapter Configuration There are two configuration files for lyskomd. One defines the server options and the other defines aux-item types @ref{(protocol-a)The -Aux-Item List,The Aux-Item List}. +Aux-Item List,The Aux-Item List}. @menu * Server Configuration File:: The server configuration file. @@ -158,7 +155,7 @@ Aux-Item List,The Aux-Item List}. @end menu -@node Server Configuration File, Aux-Item Definition File, Configuration, Configuration +@node Server Configuration File @section Server Configuration File The server reads its configuration from a configuration file. The @@ -176,7 +173,7 @@ ignored. * Parameters:: Valid configuration parameters. @end menu -@node Parameter Types, Parameters, Server Configuration File, Server Configuration File +@node Parameter Types @subsection Parameter Types Every parameter has a type. The legal types are: @@ -188,13 +185,13 @@ The parameter can be true or false. Legal values are @code{on}, @code{false}, @code{no} and @code{0} for false. @item locale-name -The parameter is a locale name. The value must be a legal locale name of +The parameter is a locale name. The value must be a legal locale name of the system where lyskomd is running. @item path The parameter is a path name. The value must be a legal path on the system where lyskomd is running. Most paths you can specify can be -either absolute paths (if they begin with a @samp{/}) or paths relative +either absolute paths (if they begin with a @samp{/}) or paths relative to the installation prefix which is specified at compile time or with the @samp{Prefix} parameter in the configuration file. @@ -204,12 +201,12 @@ The parameter is a TCP/IP port. It can be a symbolic port name @item int The parameter is a number of some sort. It can be a conference number, -text number or perhaps a timeout. +text number or perhaps a timeout. @end table -@node Parameters, , Parameter Types, Server Configuration File +@node Parameters @subsection Parameters @table @code @@ -238,7 +235,7 @@ is off. @item Prefix: @var{path} All files that the server uses are found in sub-directories of this -directory. The default value of this parameter is set at compile time. +directory. The default value of this parameter is set at compile time. The default at compile time is @file{/usr/lyskom}. @item Send async: @var{bool} @@ -259,19 +256,19 @@ is what all clients expect. Do not change this parameter without really good reason. @item Presentation of conferences: @var{int} -The number of the conference where presentations should be sent. +The number of the conference where presentations should be sent. Defaults to 1. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}. @item Presentation of persons: @var{int} -The number of the conference where presentations should be sent. +The number of the conference where presentations should be sent. Defaults to 2. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}. @item Motd-conference: @var{int} The number of the conference where "message-of-the-day" messages should -be sent. Defaults to 3. This option is ignored in lyskomd 1.9 and later. +be sent. Defaults to 3. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}. @item News-conference: @var{int} @@ -304,7 +301,7 @@ This parameter can only be set if the server has been compiled with @code{LOGACCESSES} defined. It will save a trace of all activity in the database to a file, for later use in simulations et c. Compiling with @code{LOGACCESSES} slows the server down quite a lot, so it is normally -not defined. +not defined. @item Data file: @var{path} The path relative to the installation prefix where part of the database @@ -312,7 +309,7 @@ is kept. The default is @file{db/lyskomd-data}. @item Backup file: @var{path} The path relative to the installation prefix where a backup of the -database is kept. This file will always contain a complete database, but +database is kept. This file will always contain a complete database, but it may be a little out-of-date. Default is @file{db/lyskomd-backup}. @item Backup file 2: @var{path} @@ -365,12 +362,12 @@ Default is @file{etc/memory-usage}. @item Aux-item definition file: @var{path} This file defines which aux-items the server should support and how it -should handle them. @xref{Aux-Item Definition File} for more details. +should handle them. @xref{Aux-Item Definition File} for more details. The path is relative to the installation prefix. Default is @file{etc/aux-items.conf}. @item Core directory: @var{path} -The Directory where core dumps are written. This path is relative to the +The Directory where core dumps are written. This path is relative to the installation prefix. Default is @file{cores}. @item Status file: @var{path} @@ -398,7 +395,7 @@ Defaults to 0. @item Permissive sync: @var{bool} Turning this option on lets any session sync the LysKOM database. -Turning it off restricts the operation to LysKOM administrators. Default +Turning it off restricts the operation to LysKOM administrators. Default is off. @item Garb interval: @var{int} @@ -627,7 +624,7 @@ status file. Actually, it is the age of the status file (named with @end table -@node Aux-Item Definition File, , Server Configuration File, Configuration +@node Aux-Item Definition File @section Aux-Item Definition File The default aux-item definition file should not be changed unless it is @@ -657,8 +654,8 @@ Each entry has the following format: @} @end example -@var{tag} is an integer, the aux-item's tag. If a tag is defined more than -once, the last definition is used. +@var{tag} is an integer, the aux-item's tag. If a tag is defined more than +once, the last definition is used. The @var{target}s specify what kind of objects aux-items with tag @var{tag} can be added to. Valid targets are: @@ -692,7 +689,7 @@ specified, aux-items with the specified tag can only be added after an object has been created. They cannot be added when the object is being created. -Each @var{field}/@var{value} pair specifies a property of aux-items with the +Each @var{field}/@var{value} pair specifies a property of aux-items with the specified tag. Most values are boolean or trillian. Legal values for either type are @code{true} and @code{false}. Boolean values have reasonable defaults; trillian values can be unset. @@ -701,7 +698,7 @@ reasonable defaults; trillian values can be unset. @item author-only Boolean, default false. When true, only the author of a text or -supervisor of a conference can create items with this tag. +supervisor of a conference can create items with this tag. @item supervisor-only Boolean, default false. When true, only the supervisors of the author or @@ -709,11 +706,11 @@ letterbox can create items with this tag. In all likelihood, the implementation of this flag is screwed up in version 2.0 of lyskomd. @item system-only -Boolean, default false. When true, only the server can initiate creation +Boolean, default false. When true, only the server can initiate creation of items with this tag. This is normally used for items that are created automatically in response to events in the system. -@item permanent +@item permanent Boolean, default false. When true, aux-items with this tag cannot be deleted once they have been created. (They will be deleted automatically when the object they are assigned to is deleted.) @@ -737,11 +734,11 @@ to the specified value. Trillian. When set, the secret bit on new items with this tag is forced to the specified value. -@item hide-creator +@item hide-creator Trillian. When set, the hide-creator bit on new items with this tag is forced to the specified value. -@item dont-garb +@item dont-garb Trillian. When set, the dont-garb bit on new items will be forced to the specified value. @@ -752,11 +749,11 @@ Trillian. When set, these flags force the values of the three reserved bits in the aux-item flags field. These should only be used by lyskomd developers, and then only very carefully. -@item validate +@item validate String or function, default none. When set to a string, this specifies a regexp that must match the data field in newly created items with this -tag. If the regexp fails to match, then the item will not be created. +tag. If the regexp fails to match, then the item will not be created. The syntax for strings is essentially the same as the syntax used in C files. When set to a function, this specified a built-in validation function to call. @@ -820,7 +817,7 @@ validation function. -@node Running lyskomd, Invoking updateLysKOM, Configuration, Top +@node Running lyskomd @chapter Running lyskomd This section explains how to run lyskomd, the files it uses and how it @@ -833,7 +830,7 @@ can be controlled while running. @end menu -@node Invoking lyskomd, Signals, Running lyskomd, Running lyskomd +@node Invoking lyskomd @section Invoking lyskomd @example @@ -854,7 +851,7 @@ The optional @var{config-file} argument can be used to specify the server configuration file. @xref{Server Configuration File}. -@node Signals, Files, Invoking lyskomd, Running lyskomd +@node Signals @section Signals It is possible to control some aspects of lyskomd using Unix signals. @@ -878,7 +875,7 @@ until the child is done and then continues. @end table -@node Files, , Signals, Running lyskomd +@node Files @section Files Used by lyskomd All file names can be changed in the server configuration file. @@ -905,12 +902,12 @@ base. Most of the time this is the only complete database file! File with the pid of the lyskom-process. @item @code{Prefix}/etc/memory-usage -On normal exit, @code{lyskomd} will append some statistics to this file. +On normal exit, @code{lyskomd} will append some statistics to this file. It can be used for detecting memory leaks. @item @code{Prefix}/etc/aux-items.conf This file contains definitions of the aux-items that the server should -support. It is read by @code{lyskomd} at startup. +support. It is read by @code{lyskomd} at startup. @item /etc/nologin If this file exists, lyskomd will not allow anyone to connect to the @@ -920,7 +917,7 @@ the server configuration file. @end table -@node Invoking updateLysKOM, Invoking komrunning, Running lyskomd, Top +@node Invoking updateLysKOM @chapter Invoking updateLysKOM @example @@ -941,7 +938,7 @@ number and exit. @code{updateLysKOM} is normally run from @code{cron}; @pxref{Administration}. -@node Invoking komrunning, Administration, Invoking updateLysKOM, Top +@node Invoking komrunning @chapter Invoking komrunning @example @@ -970,7 +967,7 @@ the boot sequence. @samp{-v} and @samp{-V} causes @code{komrunning} to report its version number and exit. -@node Administration, Bugs, Invoking komrunning, Top +@node Administration @chapter Administration The first thing you will have to do is to follow the instructions in the @@ -1023,7 +1020,7 @@ The shell script @code{komrunning} can be used to start and stop the LysKOM server. With no arguments, it will report the status. @example - komrunning off + komrunning off @end example will (attempt to) shut down the server, creating the file @@ -1033,16 +1030,15 @@ shutdown will be delayed until the next time that @code{updateLysKOM} is run. @example - komrunning on + komrunning on @end example will restart the server. The actual starting of the server will be done by @code{updateLysKOM} the next time it is run. @code{komrunning} only -removes the lock file. +removes the @file{/usr/lyskom/etc/status} file. -@node Bugs, DBCK Reference, Administration, Top -@comment node-name, next, previous, up +@node Bugs @chapter Known Bugs @itemize @bullet @@ -1072,8 +1068,7 @@ the edges. @c ====================================================================== @c ====================================================================== -@node DBCK Reference, Hacking, Bugs, Top -@comment node-name, next, previous, up +@node DBCK Reference @chapter DBCK Reference dbck is a program that can is used for minor database maintenance tasks @@ -1088,8 +1083,7 @@ and for repairing a corrupt lyskomd database. @end menu -@node DBCK Overview, Invoking dbck, DBCK Reference, DBCK Reference -@comment node-name, next, previous, up +@node DBCK Overview @section Overview The dbck program is used for minor maintenance of the LysKOM database @@ -1108,8 +1102,7 @@ functions: @end itemize -@node Invoking dbck, DBCK Notes, DBCK Overview, DBCK Reference -@comment node-name, next, previous, up +@node Invoking dbck @section Invoking dbck The functionality of dbck is controlled through command-line switches. @@ -1127,8 +1120,7 @@ and report on its integrity. No files will be modified. @end menu -@node General Options, Database Repair Options, Invoking dbck, Invoking dbck -@comment node-name, next, previous, up +@node General Options @subsection General Options These options control the general behavior of lyskomd. @@ -1142,15 +1134,14 @@ compiled-in default location of the config file) and exit immediately. Verbose mode. Report not only errors but the status of the database. @item @code{-F} or @code{--force-output} -This option forces dbck to write the database file. Normally @code{dbck} +This option forces dbck to write the database file. Normally @code{dbck} will only write a new database file if changes have been made for some other reason. If you want to simply convert a database from one version to another, you will probably have to give this option. @end table -@node Database Repair Options, Format Conversion Options, General Options, Invoking dbck -@comment node-name, next, previous, up +@node Database Repair Options @subsection Database Repair Options The following options control database repair. @@ -1164,15 +1155,14 @@ be suggested and the user must confirm the correction. Repair simple errors without asking. @item @code{-c} or @code{--set-change-name} -Consider it an error if the @code{change-name} capability of a person is +Consider it an error if the @code{change-name} capability of a person is not set. Due to a bug that capability was never set for newly created persons in release 1.6.1 of lyskomd. This option can be used to repair the damage. @end table -@node Format Conversion Options, Database Maintenance Options, Database Repair Options, Invoking dbck -@comment node-name, next, previous, up +@node Format Conversion Options @subsection Format Conversion Options dbck can be used to conver the LysKOM database from one storage format @@ -1181,7 +1171,7 @@ server version. @table @asis @item @code{-F} or @code{--force-output} -This option forces dbck to write the database file. Normally @code{dbck} +This option forces dbck to write the database file. Normally @code{dbck} will only write a new database file if changes have been made for some other reason. If you want to simply convert a database from one version to another, you will probably have to give this option. @@ -1198,8 +1188,7 @@ requires an argument: the output format version. @end table -@node Database Maintenance Options, Reporting Options, Format Conversion Options, Invoking dbck -@comment node-name, next, previous, up +@node Database Maintenance Options @subsection Database Update Options dbck can be used to update certain aspects of the database that either @@ -1209,7 +1198,7 @@ inconvenient in all protocol versions. @table @asis @item @code{-g} or @code{--compact-text-mass} Do garbage collection on the texts part of the database. This removes -all unreferenced texts from the database. +all unreferenced texts from the database. @item @code{-P} or @code{--clear-password} Clear the password of a specified user. This option is silently ignored @@ -1223,22 +1212,22 @@ the ID of the person who is to be granted all privileges. @item @code{--pers-pres-conf} Set the person presentation conference of the server to the specified -conference. Since version 1.9 of lyskomd the @code{set-info} call can be +conference. Since version 1.9 of lyskomd the @code{set-info} call can be used to do this. @item @code{--conf-pres-conf} Set the conference presentation conference of the server to the specified -conference. Since version 1.9 of lyskomd the @code{set-info} call can be +conference. Since version 1.9 of lyskomd the @code{set-info} call can be used to do this. @item @code{--motd-conf} Set the message-of-the-day conference of the server to the specified -conference. Since version 1.9 of lyskomd the @code{set-info} call can be +conference. Since version 1.9 of lyskomd the @code{set-info} call can be used to do this. @item @code{--kom-news-conf} Set the news-about-lyskom conference of the server to the specified -conference. Since version 1.9 of lyskomd the @code{set-info} call can be +conference. Since version 1.9 of lyskomd the @code{set-info} call can be used to do this. @item @code{--motd-of-kom} @@ -1247,8 +1236,7 @@ version 1.9 of lyskomd the @code{set-info} call can be used to do this. @end table -@node Reporting Options, , Database Maintenance Options, Invoking dbck -@comment node-name, next, previous, up +@node Reporting Options @subsection Reporting Options These options control reporting of information about the database. @@ -1264,8 +1252,7 @@ Print ``Checking @i{text-no}'' for every text that examined. @end table -@node DBCK Notes, DBCK Files, Invoking dbck, DBCK Reference -@comment node-name, next, previous, up +@node DBCK Notes @section Notes for DBCK The messages ``Conference @var{conf-no} has a bad Text-list. Starts with @@ -1275,8 +1262,7 @@ you specify the @code{-g} option, let @code{dbck} repair them and run @code{dbck -g} again. -@node DBCK Files, DBCK Bugs, DBCK Notes, DBCK Reference -@comment node-name, next, previous, up +@node DBCK Files @section Files Used by dbck dbck uses the same files as @code{lyskomd} (@xref{(lyskomd)}.) @@ -1286,7 +1272,7 @@ All file names can be changed in the server configuration file. @table @file @item /usr/lyskom -Default value of @code{Prefix}. The default of this value is set at compile +Default value of @code{Prefix}. The default of this value is set at compile time, but it can be changed in the server configuration file. @xref{(lyskomd)Parameters}. @@ -1304,13 +1290,10 @@ base. Most of the time this is the only complete database file! @end table -@node DBCK Bugs, , DBCK Files, DBCK Reference -@comment node-name, next, previous, up +@node DBCK Bugs @section Known Bugs @itemize @bullet -@item Does not lock the database. -@item Never checks if the database is locked. @item Should have an unlock database option. @item Does not check that the data file and text file are consistent. @end itemize @@ -1328,8 +1311,7 @@ base. Most of the time this is the only complete database file! @c ====================================================================== -@node Hacking, lyskomd Database Specification, DBCK Reference, Top -@comment node-name, next, previous, up +@node Hacking @chapter Hacking lyskomd @@ -1342,14 +1324,14 @@ base. Most of the time this is the only complete database file! * Modifying Stored Types:: Modifying types stored in the DB. * Notes:: Mixed notes. * Debugging and Testing:: How to test and debug the server. +* local-to-global:: The Local_to_global structure. @end menu -@node The Database, Adding Configuration Parameters, Hacking, Hacking -@comment node-name, next, previous, up +@node The Database @section The Database @c FIXME: ramkomd �r d�d! L�nge leve LysKOM! -@c FIXME: +@c FIXME: @c FIXME: Jag har tillsammans med Inge kommit p� ett s�tt att dels f� ner @c FIXME: v�ntetiden i samband med syncningar till <1 sekund, dels f� ner @c FIXME: storleken p� serverprocessen till mer rimliga niv�er. Denna l�sning @@ -1357,181 +1339,180 @@ base. Most of the time this is the only complete database file! @c FIXME: diskutrymme som den egentligen beh�ver. Det g�r �ven ramkomd, s� det @c FIXME: �r ingen f�rs�mring i det avseendet. Dock �r detta bara en tempor�r @c FIXME: l�sning i v�ntan p� ldb. -@c FIXME: +@c FIXME: @c FIXME: Varf�r spara allt p� en g�ng? Varf�r inte spara en liten del av filen @c FIXME: i taget, och utf�ra n�gra atomiska anrop mellan varje liten @c FIXME: delsynkning? Ungef�r s� t�nkte jag n�r jag kom p� f�ljande schema f�r @c FIXME: hur man kan g�ra det hela b�ttre �n det �r nu. -@c FIXME: +@c FIXME: @c FIXME: Den databas som ligger p� fil �r en �gonblickbild (snapshot) av det @c FIXME: som finns i LysKOM. S� �r det i ramkomd; s� blir det i diskomd. @c FIXME: (B�ttre namn, n�gon? lyskomd tycker jag �r reserverat f�r den version @c FIXME: som har en riktig cache&ldb.) I ramkomd skrivs allt ut p� disk @c FIXME: samtidigt. I diskomd minns man bara vad som skall sparas, och sparar @c FIXME: bara en bit i taget. -@c FIXME: +@c FIXME: @c FIXME: I ramkomd finns allt inne i ram-minnet (i teorin. I praktiken �r det @c FIXME: mesta utswappat - n�got som m�rks varje g�ng det �r dags att synca!). @c FIXME: I diskomd ligger det mesta p� disk. I minnet finns dels det som har @c FIXME: anv�nts nyligen, dels det som �r �ndrat och �nnu ej syncat. Diskomd @c FIXME: har alltid minst en, ofta tv�, databasfiler �ppna: -@c FIXME: -@c FIXME: Fil A Senaste kompletta fil. -@c FIXME: Fil B Fil under uppbyggnad. +@c FIXME: +@c FIXME: Fil A Senaste kompletta fil. +@c FIXME: Fil B Fil under uppbyggnad. @c FIXME FIXME: Fil Z N�st senast kompletta fil @c FIXME FIXME: (den h�r gick att kopiera en g�ng i @c FIXME FIXME: tiden, �ven om A inte g�r att kopiera @c FIXME FIXME: just nu.) -@c FIXME: +@c FIXME: @c FIXME: (Dessutom textmassefilen, precis som ramkomd nuf�rtiden.) -@c FIXME: +@c FIXME: @c FIXME: S� till detaljerna: -@c FIXME: +@c FIXME: @c FIXME: Det finns tre typer av objekt som ber�rs av den h�r �ndringen: @c FIXME: Text_stat, Person och Conference. Jag anv�nder Person som ett exempel @c FIXME: nedan. -@c FIXME: -@c FIXME: I ram-cache.c finns en array -@c FIXME: +@c FIXME: +@c FIXME: I ram-cache.c finns en array +@c FIXME: @c FIXME: Person *pers_arr[ MAX_CONF ]; -@c FIXME: +@c FIXME: @c FIXME: Den byts mot -@c FIXME: +@c FIXME: @c FIXME: Cache_node *pers_arr[ MAX_CONF ]; -@c FIXME: -@c FIXME: typedef struct cache_node � -@c FIXME: Bool exists; -@c FIXME: Bool exists_b; -@c FIXME: Bool dirty; /* �r *ptr modifierad? */ +@c FIXME: +@c FIXME: typedef struct cache_node @{ +@c FIXME: Bool exists; +@c FIXME: Bool exists_b; +@c FIXME: Bool dirty; /* �r *ptr modifierad? */ @c FIXME: void *snap_shot; @c FIXME: void *ptr; @c FIXME: off_t pos; @c FIXME: off_t pos_b; @c FIXME: struct cache_node *lru_link; -@c FIXME: int lock_cnt; -@c FIXME: � Cache_node; -@c FIXME: -@c FIXME: -@c FIXME: +@c FIXME: int lock_cnt; +@c FIXME: @} Cache_node; +@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: UPPSTART -@c FIXME: +@c FIXME: @c FIXME: N�r servern startas scannar den igenom datafilen (fil A) och fyller i @c FIXME: f�ltet exists till TRUE/FALSE och pos till att peka p� b�rjan av det @c FIXME: st�lle i filen d�r data ligger. �vriga f�lt s�tts till FALSE/NULL/0. -@c FIXME: -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: CACHE_GET_PERSON -@c FIXME: +@c FIXME: @c FIXME: N�r ovanliggande rutiner vill l�sa en person h�nder f�ljande: -@c FIXME: -@c FIXME: !exists Returnera NULL -@c FIXME: ptr != NULL L�gg noden f�rst i lru_link. Returnera ptr. -@c FIXME: snap_shot != NULL Kopiera snap_shot till ptr. L�gg noden f�rst i +@c FIXME: +@c FIXME: !exists Returnera NULL +@c FIXME: ptr != NULL L�gg noden f�rst i lru_link. Returnera ptr. +@c FIXME: snap_shot != NULL Kopiera snap_shot till ptr. L�gg noden f�rst i @c FIXME: lru_link. Returnera ptr. -@c FIXME: annars L�s in fr�n fil A, s�tt ptr till den inl�sta +@c FIXME: annars L�s in fr�n fil A, s�tt ptr till den inl�sta @c FIXME: structen, l�gg noden f�rst i lru_link, @c FIXME: returnera ptr. -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: MARK_PERSON_AS_CHANGED -@c FIXME: +@c FIXME: @c FIXME: N�r n�got har �ndrats s�tts dirty-flaggan till TRUE. -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: CREATE_PERSON -@c FIXME: +@c FIXME: @c FIXME: S�tt exists=TRUE, dirty=TRUE, ptr och lru. -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: DELETE_PERSON -@c FIXME: +@c FIXME: @c FIXME: S�tt exists=FALSE. ptr=NULL. Troligtvis error om lock_cnt != 0. -@c FIXME: -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: THROW-OUT -@c FIXME: +@c FIXME: @c FIXME: F�r att inte diskomd ska bli f�r stor sl�ngs saker ut ur cachen. @c FIXME: Algoritm: tag f�rsta elementet i lru_list. Om dirty==FALSE och @c FIXME: ptr!=NULL och lock_cnt==0 s� frig�r ptr. Upprepa tills antalet noder @c FIXME: med ptr!=NULL och dirty==FALSE �r mindre �n antalet "rena" element man @c FIXME: vill ha inne i minnet. (Smutsiga element sl�ngs aldrig ut.) -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: LOCK_PERSON -@c FIXME: +@c FIXME: @c FIXME: �ka lock_cnt. -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: UNLOCK_PERSON -@c FIXME: +@c FIXME: @c FIXME: Minska lock_cnt. -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: PRE-SYNC -@c FIXME: +@c FIXME: @c FIXME: Utsparningen till fil sker i tre steg. F�rst sveper man �ver alla @c FIXME: Cache_noder. F�r alla som har dirty=TRUE g�r man f�ljande: -@c FIXME: -@c FIXME: if ( lock_cnt == 0 ) � -@c FIXME: snap_shot = ptr; (Pekartilldelning, ej kopiering av inneh�llet.) +@c FIXME: +@c FIXME: if ( lock_cnt == 0 ) @{ +@c FIXME: snap_shot = ptr; (Pekartilldelning, ej kopiering av inneh�llet.) @c FIXME: ptr = NULL; @c FIXME: Ta bort ptr ur lru-kedjan. -@c FIXME: � else � +@c FIXME: @} else @{ @c FIXME: snap_shot = copy(ptr); -@c FIXME: � -@c FIXME: +@c FIXME: @} +@c FIXME: @c FIXME: dirty = FALSE; -@c FIXME: +@c FIXME: @c FIXME: F�r _alla_ noder g�rs dessutom f�ljande: -@c FIXME: +@c FIXME: @c FIXME: b_exists==exists; -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: SYNC -@c FIXME: +@c FIXME: @c FIXME: Steg tv� utf�rs en liten bit i taget. Till exempel s� skulle man kunna @c FIXME: spara en person efter varje atomiskt anrop, eller s�. -@c FIXME: -@c FIXME: b_exists==FALSE? S�tt pos_b. Skriv "@@\n" till fil B. -@c FIXME: �r snap_shot != NULL? S�tt pos_b. Skriv ut inneh�llet i snap_shot +@c FIXME: +@c FIXME: b_exists==FALSE? S�tt pos_b. Skriv "@@\n" till fil B. +@c FIXME: �r snap_shot != NULL? S�tt pos_b. Skriv ut inneh�llet i snap_shot @c FIXME: till fil B. @c FIXME: dirty==FALSE && ptr!=NULL Skriv ut inneh�llet i ptr till fil B. -@c FIXME: annars: Kopiera fr�n fil A till fil B. (Eftersom man +@c FIXME: annars: Kopiera fr�n fil A till fil B. (Eftersom man @c FIXME: vet b�de var blocket b�rjar och slutar kan man @c FIXME: kopiera blocket utan att bry sig om vad som @c FIXME: st�r i det -> v�ldigt lite CPU g�r �t). -@c FIXME: -@c FIXME: -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: POST-SYNC -@c FIXME: +@c FIXME: @c FIXME: N�r alla Person:er har hanterats som i SYNC ovan �r det dags f�r det @c FIXME: tredje steget. D� g�r man igenom alla Cache_node:er och g�r f�ljande: -@c FIXME: +@c FIXME: @c FIXME: pos = pos_b; @c FIXME: file_b = FALSE; @c FIXME: free(snap_shot); @c FIXME: snap_shot = NULL; -@c FIXME: +@c FIXME: @c FIXME: Fil B som man f�rut hade �ppen f�r skrivning �ppnar man i st�llet f�r @c FIXME: l�sning som fil A. -@c FIXME: -@c FIXME: -@c FIXME: -@c FIXME: +@c FIXME: +@c FIXME: +@c FIXME: +@c FIXME: @c FIXME: ANM�RKNINGAR -@c FIXME: +@c FIXME: @c FIXME: Inneh�llet i snap_shot �r alltid "smutsigt" j�mf�rt med inneh�llet i @c FIXME: fil A. Det som snap_shot pekar p� finns aldrig med i lru-kedjan. -@c FIXME: +@c FIXME: -@node Adding Configuration Parameters, Adding Asynchronous Messages, The Database, Hacking -@comment node-name, next, previous, up +@node Adding Configuration Parameters @section Adding Configuration Parameters Make sure that you really understand what you want to configure. Think @@ -1551,8 +1532,7 @@ Make sure that the parameter is used instead of any previous hard-coded value. Make sure that @code{dbck} can cope with it. -@node Adding Asynchronous Messages, Adding a New Protocol Request, Adding Configuration Parameters, Hacking -@comment node-name, next, previous, up +@node Adding Asynchronous Messages @section Adding Asynchronous Messages @table @code @@ -1595,29 +1575,27 @@ is dealt with elsewhere. @end menu -@node Function Templates for prot-a-send-async.c, Function Templates for send-async.c, Adding Asynchronous Messages, Adding Asynchronous Messages -@comment node-name, next, previous, up +@node Function Templates for prot-a-send-async.c @subsection Function Templates for prot-a-send-async.c This is what a typical function in @code{prot-a-send-async.c} should look like. This function is responsible for checking that the client is -accepting the message and writing the message itself to the connection. +accepting the message and writing the message itself to the connection. @example void -prot_a_async_@i{something}(Connection *cptr, - @i{parameters}) +prot_a_async_@var{something}(Connection *cptr, + @var{parameters}) @{ - ASYNC_CHECK_ACCEPT(cptr, ay_@i{something}); - async_header(cptr, @i{num_tokens}, ay_@i{something}); + ASYNC_CHECK_ACCEPT(cptr, ay_@var{something}); + async_header(cptr, @var{num_tokens}, ay_@var{something}); /* Output the body of the message */ async_trailer(cptr); @} @end example -@node Function Templates for send-async.c, , Function Templates for prot-a-send-async.c, Adding Asynchronous Messages -@comment node-name, next, previous, up +@node Function Templates for send-async.c @subsection Function Templates for send-async.h This is what a typical function in @code{send-async.c} should look like. @@ -1633,28 +1611,28 @@ void async_@i{something}( @i{parameters} ) Session_no i = 0; if (!param.send_async_messages) - return; + return; while ((i = traverse_connections(i)) != 0) @{ - cptr = get_conn_by_number(i); + cptr = get_conn_by_number(i); - switch(cptr->protocol) - @{ - case 0: + switch(cptr->protocol) + @{ + case 0: /* No protocol specified yet */ - break; - case 'A': + break; + case 'A': /* Check that connection is logged on. We might want to check other things here too, such as if the connection is allowed to see the message */ - if (cptr->username_valid == TRUE) - prot_a_async_@i{something}(cptr, @i{parameters}); - break; - default: - restart_kom("async_@i{something}(): bad protocol.\n"); - break; - @} + if (cptr->username_valid == TRUE) + prot_a_async_@i{something}(cptr, @i{parameters}); + break; + default: + restart_kom("async_@i{something}(): bad protocol.\n"); + break; + @} @} @} @end example @@ -1665,30 +1643,29 @@ void async_@i{something}(struct connection *cptr, @i{parameters}) @{ if (!param.send_async_messages) - return; + return; switch(cptr->protocol) @{ case 0: /* No protocol specified yet */ - break; + break; case 'A': /* Check that connection is logged on. We might want to check other things here too, such as if the connection is allowed to see the message */ - if (cptr->username_valid == TRUE) - prot_a_async_@i{something}(cptr, @i{parameters}); - break; + if (cptr->username_valid == TRUE) + prot_a_async_@i{something}(cptr, @i{parameters}); + break; default: - restart_kom("async_@i{something}(): bad protocol.\n"); - break; + restart_kom("async_@i{something}(): bad protocol.\n"); + break; @} @} @end example -@node Adding a New Protocol Request, Adding Aux-Item Types, Adding Asynchronous Messages, Hacking -@comment node-name, next, previous, up +@node Adding a New Protocol Request @section Adding a New Protocol Request Before doing anything, think again. Make sure that the protocol request @@ -1705,11 +1682,11 @@ idea. should be given a call number one higher than the currently existing highest contiguous call number. -@item If the function takes a pn input parameter of a new type, changes +@item If the function takes an input parameter of a new type, changes need to be made in several places. @xref{Adding New Input Types}. @item If the function takes too many parameters of type @code{num}, -@code{string} or @code{c_string}, the definition of @code{Connection} in +@code{string} or @code{c_string}, the definition of @code{Connection} in @code{server/connection.h} has to be changed. @item If the function has an output parameter of a new type, changes @@ -1719,7 +1696,7 @@ need to be made in several plaves. @xref{Adding New Result Types}. @item Write tests for the new function in @code{server/testsuite/lyskomd.0}. Write one file for testing the -functionality. Write tests in @code{01.exp} (behavior when the client is +functionality. Write tests in @code{01.exp} (behavior when the client is not logged on) and @code{03.exp} (normal behavior.) @item Run the testsuite to make sure nothing old has been broken. @@ -1736,8 +1713,7 @@ generated automatically. @end menu -@node Adding New Input Types, Adding New Result Types, Adding a New Protocol Request, Adding a New Protocol Request -@comment node-name, next, previous, up +@node Adding New Input Types @subsection Adding New Input Types Changes need to be made in the following files: @@ -1747,17 +1723,17 @@ Changes need to be made in the following files: Document the new type. @item server/call-switch.awk -The new type has to be added to the cascaded ifs that translate the type +The new type has to be added to the cascaded ifs that translate the type name to code that points to the appropriate field in a @code{Connection} structure. @item server/prot-a-parse-arg-c.awk The new type has to be added to the cascaded ifs that create the -argument list parser. +argument list parser. @item server/connections.h The definition of @code{Connection} must be extended with a field where -the parse value can be stored. Don't even think about trying to reuse an +the parse value can be stored. Don't even think about trying to reuse an existing field. It's more trouble than it's worth. @item server/connection.c @@ -1773,8 +1749,7 @@ Initialize the contents of the field in @code{init_connection()}. -@node Adding New Result Types, Modifying Output Types, Adding New Input Types, Adding a New Protocol Request -@comment node-name, next, previous, up +@node Adding New Result Types @subsection Adding New Result Types Changes need to be made in the following files: @@ -1785,10 +1760,10 @@ Document the new type. @item server/prot-a.c Add a line in the @code{prot_a_reply} switch that calls the correct -output function. +output function. @item server/connections.h -Add the type in @code{Res_type}and @code{Result_holder}. +Add the type in @code{Res_type}and @code{Result_holder}. @item server/prot-a-output.c @item server/prot-a-output.h @@ -1797,8 +1772,7 @@ to a connection. Use the existing functions as templates. @end table -@node Modifying Output Types, , Adding New Result Types, Adding a New Protocol Request -@comment node-name, next, previous, up +@node Modifying Output Types @subsection Modifying Output Types When you modify an existing type you have to rename the old version of @@ -1823,7 +1797,7 @@ type in the type documentation and in all calls that return it. Be thorough! @item fncdef.txt -Rewrite all calls that use the modified type so they use the old version +Rewrite all calls that use the modified type so they use the old version of the type. @item prot-a.c @@ -1852,8 +1826,7 @@ If the type you modify is stored in the database, make sure it gets saved properly. @xref{Modifying Stored Types}. -@node Adding Aux-Item Types, Modifying Stored Types, Adding a New Protocol Request, Hacking -@comment node-name, next, previous, up +@node Adding Aux-Item Types @section Adding Aux-Item Types @enumerate @@ -1878,8 +1851,7 @@ step. @end enumerate -@node Modifying Stored Types, Notes, Adding Aux-Item Types, Hacking -@comment node-name, next, previous, up +@node Modifying Stored Types @section Modifying Stored Types If you want to modify an existing type that is stored in the database, @@ -1903,11 +1875,11 @@ Update all old functions in @file{ram-output.c} that are database version dependent so that they can deal with the new database format. @item Write a function in @file{ram-parse.c} to read the new format. -Update all old functions in @file{ram-parse.c} that are database version +Update all old functions in @file{ram-parse.c} that are database version dependent so that they can deal with the new database format. @item Set the default database format in @file{ram-parse.c} and -@code{ram-output.c}. The variables to change are @code{input_format} and +@code{ram-output.c}. The variables to change are @code{input_format} and @code{output_format}, respectively. @item Don't forget to update the functions in @file{memory.c} @@ -1920,8 +1892,7 @@ dependent so that they can deal with the new database format. @end menu -@node Template for ram-output.c, Template for ram-parse.c, Modifying Stored Types, Modifying Stored Types -@comment node-name, next, previous, up +@node Template for ram-output.c @subsection Template for ram-output.c For types that can be output in several different formats, use the @@ -1970,11 +1941,10 @@ void foutput_@i{something}(FILE *fp, @i{something} *o) Note that if two versions are the same, only write one functions. For example, if version 0 and version 1 are the same, only write an -@code{foutput_@i{something}_0} function and call it from both case 0 and +@code{foutput_@i{something}_0} function and call it from both case 0 and case 1. -@node Template for ram-parse.c, , Template for ram-output.c, Modifying Stored Types -@comment node-name, next, previous, up +@node Template for ram-parse.c @subsection Template for ram-parse.c @example @@ -2004,9 +1974,9 @@ fparse_@i{something}(FILE *fp, @i{something} *o) @{ if ( fparse_long_errors != 0 ) @{ - log("fparse_info(): fparse_long_errors == %d on entry. Reset.\n", - fparse_long_errors); - fparse_long_errors = 0; + log("fparse_info(): fparse_long_errors == %d on entry. Reset.\n", + fparse_long_errors); + fparse_long_errors = 0; @} switch (input_format) @@ -2030,12 +2000,11 @@ fparse_@i{something}(FILE *fp, @i{something} *o) Note that if two versions are the same, only write one functions. For example, if version 0 and version 1 are the same, only write an -@code{fparse_@i{something}_0} function and call it from both case 0 and +@code{fparse_@i{something}_0} function and call it from both case 0 and case 1. -@node Notes, Debugging and Testing, Modifying Stored Types, Hacking -@comment node-name, next, previous, up +@node Notes @section Hacking Notes @menu @@ -2047,11 +2016,10 @@ case 1. @end menu -@node Parsing Bit Fields, Membership Notes, Notes, Notes -@comment node-name, next, previous, up +@node Parsing Bit Fields @subsection Parsing Bit Fields -The parser for a bit field parameter type should be very tolerant of the +The parser for a bit field parameter type should be very tolerant of the length of the token. Anything from a single bit and up should be permitted. The parser should use default values for bits that are not provided and ignore extra bits. @@ -2075,14 +2043,14 @@ prot_a_parse_bitfield(Connection *client, switch (len = s_strlen(token)) @{ default: - case 8: res->bit_8 = token.string[ 7 ]; - case 7: res->bit_7 = token.string[ 6 ]; - case 6: res->bit_6 = token.string[ 5 ]; - case 5: res->bit_5 = token.string[ 4 ]; - case 4: res->bit_4 = token.string[ 3 ]; - case 3: res->bit_3 = token.string[ 2 ]; - case 2: res->bit_2 = token.string[ 1 ]; - case 1: res->bit_1 = token.string[ 0 ]; + case 8: res->bit_8 = token.string[7]; + case 7: res->bit_7 = token.string[6]; + case 6: res->bit_6 = token.string[5]; + case 5: res->bit_5 = token.string[4]; + case 4: res->bit_4 = token.string[3]; + case 3: res->bit_3 = token.string[2]; + case 2: res->bit_2 = token.string[1]; + case 1: res->bit_1 = token.string[0]; @} @} @end example @@ -2094,42 +2062,40 @@ the server knows about. The fall-through ensures that all bits in the token are read. -@node Membership Notes, Linking Pairs of Aux Items, Parsing Bit Fields, Notes -@comment node-name, next, previous, up +@node Membership Notes @subsection Membership Notes -The @code{position} field in the membership is @i{not} stored. It has to +The @code{position} field in the membership is @i{not} stored. It has to be set every time a membership is requested for transmission to the client. -@node Linking Pairs of Aux Items, Notes for fncdef.txt, Membership Notes, Notes -@comment node-name, next, previous, up +@node Linking Pairs of Aux Items @subsection Linking Pairs of Aux Items Sometimes two aux items need to work in tandem. The first instance of -this was the FAQ and FAQ-for-conference items. The FAQ item contains the +this was the FAQ and FAQ-for-conference items. The FAQ item contains the text number of a text that is a FAQ for a conference. The FAQ-for-conference item contains the conference for which a text is a FAQ. This is needed so that deletion of the text properly removes the -aux-item on the conf (plus, it's nice to be able to see that a text is a +aux-item on the conf (plus, it's nice to be able to see that a text is a FAQ.) The @code{linked_item} field in the Aux_item structure is for linking items. The linking must be managed through the use of triggers. This -field is not visible in the protocol. It is saved in the database. It is +field is not visible in the protocol. It is saved in the database. It is not possible to have more than one link per item. Please remember the following points. @itemize @bullet -@item The target of a link should have a link back. All links need to go +@item The target of a link should have a link back. All links need to go both ways. @item In the add trigger for one end, create the other end of the link -and set the @code{linked_item} field in both items. Don't forget to mark +and set the @code{linked_item} field in both items. Don't forget to mark the objects at both ends as changed. @item Deletion and undeletion of the other side of the link will be @@ -2147,8 +2113,7 @@ continue working. -@node Notes for fncdef.txt, Traversing Connections, Linking Pairs of Aux Items, Notes -@comment node-name, next, previous, up +@node Notes for fncdef.txt @subsection Notes for fncdef.txt The fncdef.txt file is used to define the RPC functions. Each line @@ -2165,7 +2130,7 @@ Some examples: The first line defines a call named @code{create_conf_old} that takes two arguments, a string that can only be as long as @code{param.conf_name_len} and a @code{conf_type}. It returns a number -to the client. If the service call returns -1, the server will return an +to the client. If the service call returns -1, the server will return an error. The @code{create_conf_old} call has RPC number 10. The second line defines a call named @code{lookup_name} that takes a @@ -2203,8 +2168,7 @@ Generates @code{prot-a-parse-arg.c} and @code{prot-a-parse-arg.h}. @end table -@node Traversing Connections, , Notes for fncdef.txt, Notes -@comment node-name, next, previous, up +@node Traversing Connections @subsection Traversing Connections Since session 0 is interpreted as the currently active session by @@ -2237,8 +2201,7 @@ This code has @code{session} set to a session number before ever entering the loop. -@node Debugging and Testing, , Notes, Hacking -@comment node-name, next, previous, up +@node Debugging and Testing @section Debugging and Testing We're slowly adding support for debugging and testing lyskomd properly. @@ -2250,8 +2213,7 @@ We're slowly adding support for debugging and testing lyskomd properly. * Debug Calls:: Special protocol A calls for testing. @end menu -@node The Test Suite, Configuration Options, Debugging and Testing, Debugging and Testing -@comment node-name, next, previous, up +@node The Test Suite @subsection The Test Suite The lyskomd test suite is in src/server/testsuite. Please extend this @@ -2261,9 +2223,9 @@ break anything. The file config/prot-a.exp contains some support for protocol A. Don't use these functions in test cases. Use them to set up the inital -database and for things tht have to be done, such as logins and enabling +database and for things that have to be done, such as logins and enabling privileges, but that don't need to be tested. Also, don't count on all -the code in prot-a.exp to be fully functional. Add new functions to this +the code in prot-a.exp to be fully functional. Add new functions to this file as you see fit. The basic structure of a test case is the following: @@ -2293,8 +2255,7 @@ lyskomd_death Use the existing test cases as templates. -@node Configuration Options, Coverage Testing, The Test Suite, Debugging and Testing -@comment node-name, next, previous, up +@node Configuration Options @subsection Configuration Options There are several testing and debugging-related configuration options @@ -2309,29 +2270,37 @@ Build lyskomd with Electric Fence for checking buffer overruns. This option does work. @item --with-checker -Build lyskomd with Gnu Checker for checking memory accesses, leaks, file +Build lyskomd with Gnu Checker for checking memory accesses, leaks, file descriptors and all kinds of stuff. As of Checker version 0.99.6, Gnu Checker cannot deal with lyskomd. Once built, and this requires modifications to Checker (at least on Linux) it reports spurious errors. Still, the option is here for those who want to try it out. @item --with-gcov -Build lyskomd with instrumentation for @code{gcov}. You have to use this +Build lyskomd with instrumentation for @code{gcov}. You have to use this option if you want to run @code{gcov} on lyskomd. For @code{gcov} to be effective, you should turn off optimization as well. +@item --with-traced-allocations +There is some builtin support for detecting memory leaks in lyskomd. +Whenever the server exits normally it reports how much memory it still +uses to @file{etc/memory-usage}. The count should always be 0. + +If there is a leak you can use this option to trace it down. See +@file{src/server/ram-smalloc.c} for more information. You need gdb and +a lot of time to use this option. + @item --with-optimization=@i{value} Build lyskomd with the specified level of optimization. Use either numeric values to select the level of optimization, or say @code{--with-optimization=no} or @code{--without-optimization} to turn -optimization off. +optimization off. @end table -@node Coverage Testing, Debug Calls, Configuration Options, Debugging and Testing -@comment node-name, next, previous, up +@node Coverage Testing @subsection Coverage Testing When you write new code, make sure that it is completely covered by the @@ -2351,13 +2320,12 @@ The resulting file @i{filename}@code{.gcov} shows which lines have been executed, and which haven't been run. Try to get 100% coverage. -@node Debug Calls, , Coverage Testing, Debugging and Testing -@comment node-name, next, previous, up +@node Debug Calls @subsection Debug Calls Run the configure script with @code{--with-debug-calls} to compile in support for debugging calls in the server. These calls are strictly for -making testing easier (or possible.) They are not official, and they may +making testing easier (or possible.) They are not official, and they may change at any time. @menu @@ -2366,8 +2334,7 @@ change at any time. * backdate-text:: Change the creation date of a text (1002) @end menu -@node memory-info, set-marks, Debug Calls, Debug Calls -@comment node-name, next, previous, up +@node memory-info @subsubsection memory-info (DEBUG) Experimential @findex memory-info @@ -2385,11 +2352,10 @@ change at any time. keepcost : INT32; )); @end example -This call returns the data returned by @code{mallinfo} in the server. +This call returns the data returned by @code{mallinfo} in the server. See the man page for @code{mallinfo} for explanations of the fields. -@node set-marks, backdate-text, memory-info, Debug Calls -@comment node-name, next, previous, up +@node set-marks @subsubsection set-marks (DEBUG) Experimental @findex set-marks @@ -2401,12 +2367,11 @@ See the man page for @code{mallinfo} for explanations of the fields. Set the number of marks on text @code{text-no} to @code{no-of-marks}, regardless of how many marks it really has. This call is useful for -forcing the database into a state where the number of marks is incorrect -in some way. +forcing the database into a state where the number of marks is incorrect +in some way. -@node backdate-text, , set-marks, Debug Calls -@comment node-name, next, previous, up +@node backdate-text @subsubsection backdate-text (DEBUG) Experimental @findex backdate-text @@ -2417,13 +2382,115 @@ in some way. @end example Backdate a text in the server. Change the creation date of text -@code{text-no} so it appears to have been created @code{seconds} earlier +@code{text-no} so it appears to have been created @code{seconds} earlier than it was actually created. This can be used to test the garbage collector. +@node local-to-global +@section The local-to-global structure + +The data structure that stores the mapping from local to global text +numbers is currently one of the more advanced structures used by +lyskomd. + +@ignore +@c FIXME: Translate this + +@subsection Background + +The + +Det s�tt som textnummer l�ggs till har ett antal egenskaper: + + - Texter l�ggs hela tiden p� bakifr�n, aldrig i mitten eller i + b�rjan. + - Numren p� de lokala textnumren �r konsekutiva, dvs inga h�l + finns. S�dana h�l kan dock uppst� (och uppst�r!) n�r texter tas + bort. + + +L�sning +======= + +Det f�rsta man ser n�r man analyserar inneh�llet i en mapp, �r att det +finns l�nga avsnitt av idel nollor, och l�nga avsnitt d�r det inte +finns n�gra nollor alls, eller �tminstone v�ldigt f�. Detta antyder +allts� att man b�r ha en adaptiv datastruktur som anpassar sig till +det lokala f�rh�llanden. Vi f�resl�r allts� f�ljande. + +Mappen lagras i block (sm� arrayer). Det finns tv� sorters block: + +1. Glesa block. Glesa block best�r egentligen av tv� block. I det +ena blocket ligger nycklar (Local_text_no) och i det andra blocket +ligger data (Text_no). Inom ett block anv�nder man bin�rs�kning i det +ena blocket f�r att hitta just den Local_text_no man �r ute efter. + +2. T�ta block. T�ta block best�r av ett enda block som inneh�ller +data (Text_no). Man vet vilket lokalt textnummer det f�rsta entryt +svarar mot. Det kan finnas enstaka lokala nummer i ett t�tt block som +inte finns -- d� inneh�ller data 0. + +Blockstorleken �r fixerad till t ex 100 entries. (Det verkar som om +man tj�nar n�stan exakt samma antal bytes oavsett om man v�ljer +blockstorlek 50 eller 1000). Ett fullt t�tt block inneh�ller alltid +exakt 100 lokala textnummer. Ett fullt glest block inneh�ller alltid +100 existerande globala textnummer. (Ett glest block tar dubbelt s� +mycket plats som ett t�tt block, eftersom ett glest block ju +egentligen best�r av b�de ett nyckelblock och ett v�rdeblock). + +F�r att h�lla reda p� sina block har man en array av block_info: + + typedef struct block_info { + int first_free; + int zeroes; + + Local_text_no start; + Local_text_no * key_block; + Text_no * value_block; + } L2g_block_info; + +Om key_block == NULL s� �r det ett t�tt block. + +first_free + F�ltet first_free visar var i blocket som man kan fylla p� med + fler v�rden. Det �r 100 f�r fulla block. F�r block som inte �r + fulla pekar det ut det entry i value_block som n�sta v�rde ska + hamna i. Det g�ller t ex det sista blocket, som fylls p� allt + eftersom nya inl�gg skickas till m�tet eller block d�r texter har + tagits bort. + +zeroes + F�ltet zeroes anv�nds bara f�r t�ta block, och r�knar antalet + nollor i blocket. Om zeroes blir st�rre �n 50% av blockstorleken + g�r man om blocket till ett glest block. F�ltet zeroes �r en + optimering som troligtvis underl�ttar ihopslagning av block. Det + �r m�jligt att den inte beh�vs. + +start + F�ltet start inneh�ller numret p� det f�rsta lokala textnumret i + blocket. + +key_block + F�ltet key_block �r en pekare till blocket med Local_text_no, dvs + nycklarna i blocket. Detta f�lt �r NULL om detta �r ett t�tt + block. + +value_block + F�ltet value_block �r en pekare till blocket med Text_no, dvs + v�rdena i blocket. + + +F�rutom detta beh�vs en struct per m�te som h�ller reda p� arrayen med +block: + typedef struct local_to_global { + int num_blocks; + int block_size; + L2g_block_info * blocks; + } Local_to_global; +@end ignore @@ -2438,8 +2505,7 @@ collector. @ifinfo -@node lyskomd Database Specification, , Hacking, Top -@comment node-name, next, previous, up +@node lyskomd Database Specification @chapter lyskomd Database Specification This document specifies the format of the lyskomd database files. The @@ -2454,8 +2520,7 @@ actual data records are documented. @end ifinfo -@node Version 0, Version 1, lyskomd Database Specification, lyskomd Database Specification -@comment node-name, next, previous, up +@node Version 0 @section Data File Version 0 Version 0 was used by lyskomd versions up to 1.8. @@ -2499,10 +2564,10 @@ empty-record : @BB{@@} @BB{NL} The number of person and conference records is exactly one less than @II{next-free-num}. The number of text records is exactly one less than -@II{next-text-num}. +@II{next-text-num}. Records are stored sequentially. Conference number 18 is the 18th -conference record in the file. This implies that deleted records must be +conference record in the file. This implies that deleted records must be stored as @II{empty-record} records. @II{next-text-num} is the number of the highest text. There are exactly @@ -2519,11 +2584,10 @@ header says ``DIRTY'', the server has not finished writing it completely. -@node Version 1, Version 2, Version 0, lyskomd Database Specification -@comment node-name, next, previous, up +@node Version 1 @section Data File Version 1 -Version 1 was used by lyskomd version 1.9. +Version 1 was used by lyskomd version 1.9. @example database : header @BB{NL} @BB{records} @@ -2542,7 +2606,7 @@ record : next-free-num | text | deleted ; -next-free-num : @BB{#C} @II{INTEGER} +next-free-num : @BB{#C} @II{INTEGER} ; next-text-num : @BB{#P} @II{INTEGER} ; @@ -2572,15 +2636,14 @@ A conference or text must have a number lower than the closest @II{next-free-num} or @II{next-text-num} preceding it. The deletion records are used to indicate that an object found earlier -in the database has been deleted. The implementation of these in lyskomd +in the database has been deleted. The implementation of these in lyskomd 1.9 does not work, and they are not used. The @II{-C} record indicates deletion of a conference. The @II{-P} record indicates deletion of a person. The @II{-T} record indicates deletion of a text. The integer in the deletion record is the ID of the object being deleted. -@node Version 2, , Version 1, lyskomd Database Specification -@comment node-name, next, previous, up +@node Version 2 @section Data File Version 2 Version 2 is used by lyskomd version 2.0. @@ -2589,7 +2652,7 @@ The structure of this data file version is identical to that of version 1. The @II{server-info}, @II{conf-record} and @II{text-record} include information about aux-items (highest-aux-no and aux-item-list.) The @II{conf-record} contains the expire field added to the conf-stat -structure. The @II{conf-record} and @II{person-record} records use the new +structure. The @II{conf-record} and @II{person-record} records use the new local-to-global structure for storing maps.