Merge bk-internal.mysql.com:/home/bk/mysql-4.0

into mashka.mysql.fi:/home/my/mysql-4.0

Docs/internals.texi

@@ -273,7 +273,7 @@ and then we read the rows in the sorted order into a row buffer
 @itemize @bullet
 
 @item
-We are using @uref{http://www.bitkeeper.com/, BitKeeper} for source management.
+We use @uref{http://www.bitkeeper.com/, BitKeeper} for source management.
 
 @item
 You should use the @strong{MySQL} 4.0 source for all developments.
@@ -3135,9 +3135,9 @@ bdb  --  The Berkeley Database table handler
 @item
 BitKeeper  --  BitKeeper administration (not part of the source distribution)
 @item
-BUILD  --  Some very often used build scripts
+BUILD  --  Frequently used build scripts
 @item
-Build-tools  --  Build tools
+Build-tools  --  Build tools (not part of the source distribution)
 @item
 client  --  Client library
 @item
@@ -3145,28 +3145,24 @@ cmd-line-utils  --  Command-line utilities (libedit and readline)
 @item
 dbug  --  Fred Fish's dbug library
 @item
-Docs  --  Preliminary documents about internals and new modules 
+Docs  --  Preliminary documents about internals and new modules; will eventually be moved to the mysqldoc repository
 @item
 extra  --  Some minor standalone utility programs
 @item
 heap  --  The HEAP table handler
 @item
-include  --  Include (*.h) files
+include  --  Header (*.h) files for most libraries; includes all header files distributed with the MySQL binary distribution
 @item
 innobase  --  The Innobase (InnoDB) table handler
 @item
-isam  --  The ISAM (MySQL) table handler
+libmysql  --  For producing MySQL as a library (e.g. a Windows .DLL)
 @item
-libmysql  --  For producing a thread-safe libmysql library
-@item
-libmysql_r  --  Only one file, a makefile
+libmysql_r  --  For building a thread-safe libmysql library
 @item
 libmysqld  --  The MySQL Server as an embeddable library
 @item
 man  --  Some user-contributed manual pages
 @item
-merge  --  The MERGE table handler (see Reference Manual section 7.2)
-@item
 myisam  --  The MyISAM table handler 
 @item
 myisammrg  --  The MyISAM Merge table handler 
@@ -3177,7 +3173,7 @@ mysys  --  MySQL system library (Low level routines for file access etc.)
 @item
 netware  --  Files related to the Novell NetWare version of MySQL 
 @item
-NEW-RPMS  --  Directory to place RPMS while making a distribution
+NEW-RPMS  --  Directory to place RPMs while making a distribution
 @item
 os2  --  Routines for working with the OS/2 operating system
 @item
@@ -3189,25 +3185,25 @@ SCCS  --  Source Code Control System (not part of source distribution)
 @item
 scripts  --  SQL batches, e.g. mysqlbug and mysql_install_db
 @item
-sql  --  Programs for handling SQL commands. The "core" of MySQL 
+sql  --  Programs for handling SQL commands; the "core" of MySQL 
 @item
 sql-bench  --  The MySQL benchmarks 
 @item
-SSL  --  Secure Sockets Layer 
+SSL  --  Secure Sockets Layer; includes an example certification one can use to test an SSL (secure) database connection
 @item
 strings  --  Library for C string routines, e.g. atof, strchr 
 @item
 support-files  --  Files used to build MySQL on different systems
 @item
-tests  --  Tests in Perl 
+tests  --  Tests in Perl and in C
 @item
-tools  --  mysqlmanager.c (under development, not yet useful)
+tools  --  mysqlmanager.c (tool under development, not yet useful)
 @item
 VC++Files  --  Includes this entire directory, repeated for VC++ (Windows) use
 @item
 vio  --  Virtual I/O Library 
 @item
-zlib  --  data compression library, used on Windows
+zlib  --  Data compression library, used on Windows
 @end itemize
 
 @subsection bdb
@@ -3231,19 +3227,21 @@ in this document.
 BitKeeper administration.
 @*@*
 
-This directory may be present if you downloaded the MySQL source using
+Bitkeeper administration is not part of the source distribution. This 
+directory may be present if you downloaded the MySQL source using
 BitKeeper rather than via the mysql.com site. The files in the
 BitKeeper directory are for maintenance purposes only -- they are not
 part of the MySQL package.
 @*@*
 
 The MySQL Reference Manual explains how to use Bitkeeper to get the
-MySQL source.
+MySQL source. Please see @url{http://www.mysql.com/doc/en/Installing_source_tree.html}
+for more information.
 @*@*
 
 @subsection BUILD
 
-Build switches.
+Frequently used build scripts.
 @*@*
 
 This directory contains the build switches for compilation on various
@@ -3266,11 +3264,11 @@ solaris
 Build tools.
 @*@*
 
-This directory contains batch files for extracting, making
-directories, and making programs from source files. There are 
-several subdirectories with different scripts -- for building 
-Linux executables, for compiling, for performing all build steps, 
-and so on.
+Build-tools is not part of the source distribution. This directory
+contains batch files for extracting, making directories, and making
+programs from source files. There are several subdirectories with
+different scripts -- for building Linux executables, for compiling,
+for performing all build steps, and so on.
 @*@*
 
 @subsection client
@@ -3288,21 +3286,15 @@ server.
 The C program files in the directory are:
 @itemize @bullet
 @item
-connect_test.c  --  test that a connect is possible
-@item
 get_password.c  --  ask for a password from the console
 @item
-insert_test.c  --  test that an insert is possible
-@item
-list_test.c  --  test that a select is possible
-@item
 mysql.cc  --  "The MySQL command tool"
 @item
-mysqladmin.c  --  maintenance of MYSQL databases
+mysqladmin.c  --  maintenance of MySQL databases
 @item
 mysqlcheck.c  --  check all databases, check connect, etc.
 @item
-mysqldump.c  --  dump table's contents as SQL statements
+mysqldump.c  --  dump table's contents as SQL statements, suitable to backup a MySQL database
 @item
 mysqlimport.c  --  import text files in different formats into tables
 @item
@@ -3314,29 +3306,20 @@ mysqlshow.c  --  show databases, tables or columns
 @item
 mysqltest.c  --  test program used by the mysql-test suite, mysql-test-run
 @item
-password.c  --  password checking routines 
-@item
-select_test.c  --  test that a select is possible 
-@item
-showdb_test.c  --  test that a show-databases is possible 
-@item
-ssl_test.c  --  test that SSL is possible 
-@item
-thread_test.c  --  test that threading is possible 
+password.c  --  password checking routines (version 4.1 and up)
 @end itemize
 @*@*
 
 @subsection cmd-line-utils
 
-Command-line utilities.
+Command-line utilities (libedit and readline).
 @*@*
 
 There are two subdirectories: \readline and \libedit. All the files
-here are "non-MYSQL" files, in the sense that MySQL AB didn't produce
+here are "non-MySQL" files, in the sense that MySQL AB didn't produce
 them, it just uses them. It should be unnecessary to study the
-programs in these files unless
-you are writing or debugging a tty-like client for MySQL, such as
-mysql.exe.
+programs in these files unless you are writing or debugging a tty-like
+client for MySQL, such as mysql.exe.
 @*@*
 
 The \readline subdirectory contains the files of the GNU Readline
@@ -3442,14 +3425,15 @@ sanity.c  --   Declaration of a variable
 
 @subsection Docs
 
-Preliminary documents about internals and new modules.
+Preliminary documents about internals and new modules, which will eventually
+be moved to the mysqldoc repository.
 @*@*
 
 This directory doesn't have much at present that's very useful to the
 student, but the plan is that some documentation related to the source
 files and the internal workings of MySQL, including perhaps some
-documentation from developers themselves, will be placed here. Some of 
-these files will eventually be moved to the MySQL documentation repository.
+documentation from developers themselves, will be placed here. Files in
+this directory will eventually be moved to the MySQL documentation repository.
 @*@*
 
 These sub-directories are part of this directory:
@@ -3480,16 +3464,16 @@ has any importance -- internals.texi -- The "MySQL Internals"
 document.
 @*@*
 
-Despite the name, internals.texi is not really much of a description
-of MySQL internals. However, there is some useful description of the
-functions in the mysys directory (see below), and of the structure of
-client/server messages (doubtless very useful for people who want to
-make their own JDBC drivers, or just sniff).
+Despite the name, internals.texi is not yet much of a description of MySQL
+internals although work is in progress to make it so. However, there is 
+some useful description of the functions in the mysys directory (see below), 
+and of the structure of client/server messages (doubtless very useful for 
+eople who want to make their own JDBC drivers, or just sniff).
 @*@*
 
 @subsection extra
 
-Eight minor standalone utility programs.
+Some minor standalone utility programs.
 @*@*
 
 These programs are all standalone utilities, that is, they have
@@ -3498,56 +3482,20 @@ MySQL server needs or produces. Most are unimportant. They are as
 follows:
 @itemize @bullet
 @item
-my_print_defaults.c  --  print all parameters in a default file 
-@item
-mysql_install.c  --  startup: install MySQL server 
+my_print_defaults.c  --  print parameters from my.ini files. Can also be used in scripts to enable processing of my.ini files.
 @item
-mysql_waitpid.c  --  wait for a program to terminate 
+mysql_waitpid.c  --  wait for a program to terminate. Useful for shell scripts when one needs to wait until a process terminates.
 @item
 perror.c  --  "print error" -- given error number, display message
 @item
 replace.c  --  replace strings in text files or pipe
 @item
-resolve_stack_dump.c  --  show symbolic info from a stack dump 
+resolve_stack_dump.c  --  show symbolic information from a MySQL stack dump, normally found in the mysql.err file
 @item
 resolveip.c  --  convert an IP address to a hostname, or vice versa
 @end itemize
 @*@*
 
-@subsection fs
-
-File System.
-@*@*
-
-Here the word "File System" does not refer to the mere idea of a
-directory of files on a disk drive, but to object-based access. The
-concept has been compared with Oracle's Internet File System (iFS).
-@*@*
-
-The original developer of the files on this directory is Tonu Samuel,
-a former MySQL AB employee. Here is a quote (somewhat edited) from
-Tonu Samuel's web page (http://no.spam.ee/~tonu/index.php): 
-"Question: What is it? 
-Answer: Actually this is not filesystem in common terms. MySQL FS
-makes it possible to make SQL tables and some functions available over
-a filesystem. MySQL does not require disk space, it uses an ordinary
-MySQL daemon to store data." 
-The descriptions imply that this is a development project.
-@*@*
-
-There are four program files in the directory:
-@itemize @bullet
-@item
-database.c  --  "emulate filesystem behaviour on top of SQL database" 
-@item
-libmysqlfs.c  --  Search/replace, show-functions, and parse routines
-@item
-mysqlcorbafs.c  --  Connection with the CORBA "Object Request Broker" 
-@item
-mysqlcorbafs_test.c  --  Utility to test the working of mysqlcorbafs.c
-
-@*@*
-
 @subsection heap
 
 The HEAP table handler.
@@ -3622,7 +3570,8 @@ for a \myisam\mi_cache.c equivalent (to cache reads) or a
 
 @subsection include
 
-Include (*.h) files.
+Header (*.h) files for most libraries; includes all header files distributed
+with the MySQL binary distribution.
 @*@*
 
 These files may be included in C program files. Note that each
@@ -3637,7 +3586,7 @@ rijndael.h. Looking further, you'll find that rijndael.h is also
 included in other places: by my_aes.c and my_aes.h.
 @*@*
 
-The include directory contains 51 *.h (include) files.
+The include directory contains 51 *.h (header) files.
 @*@*
 
 @subsection innobase
@@ -3649,100 +3598,6 @@ A full description of these files can be found elsewhere in this
 document.
 @*@*
 
-@subsection isam
-
-The ISAM table handler.
-@*@*
-
-The C files in this directory are:
-@itemize @bullet
-@item
-_cache.c  --  for reading records from a cache 
-@item
-changed.c  --  a single routine for setting a "changed" flag (very
-short)
-@item
-close.c  --  close database 
-@item
-create.c  --  create a table 
-@item
-_dbug.c  --  support routines for use with "dbug" (see the \dbug
-description)
-@item
-delete.c  --  delete a row 
-@item
-_dynrec.c  --  functions to handle space-packed records and blobs 
-@item
-extra.c  --  setting options and buffer sizes when optimizing table
-handling 
-@item
-info.c  --  Information about database status 
-@item
-_key.c  --  for handling keys 
-@item
-_locking.c  --  lock database 
-@item
-log.c  --  save commands in log file which myisamlog program can read 
-@item
-_packrec.c  --  compress records 
-@item
-_page.c  --  read and write pages containing keys 
-@item
-panic.c  --  the mi_panic routine, probably for sudden shutdowns 
-@item
-range.c  --  approximate count of how many records lie between two
-keys 
-@item
-rfirst.c  --  read first row through a specific key (very short)
-@item
-rkey.c  --  read a record using a key 
-@item
-rlast.c  --  read last row with same key as previously-read row 
-@item
-rnext.c  --  read next row with same key as previously-read row 
-@item
-rprev.c  --  read previous row with same key as previously-read row 
-@item
-rrnd.c  --  read a row based on position 
-@item
-rsame.c  --  find current row using positional read or key-based read 
-@item
-rsamepos.c  --  positional read 
-@item
-_search.c  --  key-handling functions 
-@item
-static.c  --  static variables (very short)
-@item
-_statrec.c  --  functions to handle fixed-length records 
-@item
-test1.c  --  testing basic functions 
-@item
-test2.c  --  testing database and storing results 
-@item
-test3.c  --  testing locking 
-@item
-update.c  --  update an existing row 
-@item
-write.c  --  insert a new row 
-@item
-pack_isam.c  --  pack isam file (NOTE TO SELF ?? equivalent to
-\myisam\myisampack.c)
-@end itemize
-@*@*
-
-Except for one minor C file (pack_isam.c) every program in the ISAM
-directory has a counterpart in the MyISAM directory. For example
-\isam\update.c corresponds to \myisam\mi_update.c. However, the
-reverse is not true -- there are many files in the MyISAM directory
-which have no counterpart in the ISAM directory.
-@*@*
-
-The reason is simple -- it's because the ISAM files are becoming
-obsolete. When MySQL programmers add new features, they add them for
-MyISAM only. The student can therefore ignore all files in this
-directory and study the MyISAM programs instead.
-@*@*
-
 @subsection libmysql
 
 The MySQL Library, Part 1.
@@ -3772,7 +3627,7 @@ errmsg.c  --  English error messages, compare \mysys\errors.c
 @item
 get_password.c  --  get password 
 @item
-libmysql.c  --  the main "packet-sending emulation" program 
+libmysql.c  --  the code that implements the MySQL API, i.e. the functions a client that wants to connect to MySQL will call
 @item
 manager.c  --  initialize/connect/fetch with MySQL manager 
 @end itemize
@@ -3784,7 +3639,7 @@ The MySQL Library, Part 2.
 @*@*
 
 This is a continuation of the libmysql directory. There is only one
-file here:
+file here, used to build a thread-safe libmysql library:
 @itemize @bullet
 @item
 makefile.am
@@ -3796,8 +3651,9 @@ makefile.am
 The MySQL library, Part 3.
 @*@*
 
-This is a continuation of the libmysql directory. The program files on
-this directory are:
+This is a continuation of the libmysql directory and contains the MySQL
+Server as an embeddable library. The program files on this directory
+are:
 @itemize @bullet
 @item
 libmysqld.c  --  The called side, compare the mysqld.exe source
@@ -3808,73 +3664,13 @@ lib_vio.c --  Emulate the vio directory's communication buffer
 
 @subsection man
 
-Manual pages.
+Some user-contributed manual pages
 @*@*
 
 These are not the actual "man" (manual) pages, they are switches for
 the production.
 @*@*
 
-@subsection merge
-
-The MERGE table handler.
-@*@*
-
-For a description of the MERGE table handler, see the MySQL Reference
-Manual, section 7.2.
-@*@*
-
-You'll notice that there seem to be several directories with
-similar-sounding names of C files in them. That's because the MySQL
-table handlers are all quite similar.
-@*@*
-
-The related directories are:
-@itemize @bullet
-@item
-\isam  --  for ISAM 
-@item
-\myisam  --  for MyISAM 
-@item
-\merge  --  for ISAM MERGE (mostly call functions in \isam programs)
-@item
-\myisammrg  --  for MyISAM MERGE (mostly call functions in \myisam
-programs)
-@end itemize
-@*@*
-
-To avoid duplication, only the \myisam program versions are discussed.
-@*@*
-
-The C programs in this (merge) directory are:
-@itemize @bullet
-@item
-mrg_close.c  --  compare \isam's close.c 
-@item
-mrg_create.c  --  "" create.c 
-@item
-mrg_delete.c  --  "" delete.c 
-@item
-mrg_extra.c  --  "" extra.c 
-@item
-mrg_info.c  --  "" info.c 
-@item
-mrg_locking.c  --  "" locking.c 
-@item
-mrg_open.c  --  "" open.c 
-@item
-mrg_panic.c  --  "" panic.c 
-@item
-mrg_rrnd.c  --  "" rrnd.c 
-@item
-mrg_rsame.c  --  "" rsame.c 
-@item
-mrg_static.c  --  "" static.c 
-@item
-mrg_update.c  --  "" update.c 
-@end itemize
-@*@*
-
 @subsection myisam
 
 The MyISAM table handler.
@@ -3910,10 +3706,9 @@ programs. They are:
 @item
 mi_cache.c  --  for reading records from a cache 
 @item
-mi_changed.c  --  a single routine for setting a "changed" flag (very
-short)
+mi_changed.c  --  a single routine for setting a "changed" flag (very short)
 @item
-mi_check.c  --  doesn't just do checks, ?? for myisamchk program? 
+mi_check.c  --  for checking and repairing tables. Used by the myisamchk program and by the MySQL server.
 @item
 mi_checksum.c  --  calculates a checksum for a row 
 @item
@@ -3921,8 +3716,7 @@ mi_close.c  --  close database
 @item
 mi_create.c  --  create a table 
 @item
-mi_dbug.c  -- support routines for use with "dbug" (see \dbug
-description)
+mi_dbug.c  -- support routines for use with "dbug" (see \dbug description)
 @item
 mi_delete.c  --  delete a row 
 @item
@@ -3940,7 +3734,7 @@ mi_key.c  --  for handling keys
 @item
 mi_locking.c  --  lock database 
 @item
-mi_log.c  --  save commands in log file which myisamlog program can read
+mi_log.c  --  save commands in a log file which myisamlog program can read. Can be used to exactly replay a set of changes to a table.
 @item
 mi_open.c  --  open database 
 @item
@@ -3968,8 +3762,7 @@ mi_rprev.c  --  read previous row with same key as previously-read row
 @item
 mi_rrnd.c  --  read a row based on position
 @item
-mi_rsame.c  --  find current row using positional read or key-based
-read 
+mi_rsame.c  --  find current row using positional read or key-based read
 @item
 mi_rsamepos.c  --  positional read
 @item
@@ -4104,7 +3897,7 @@ tests
 
 @subsection mysys
 
-MySQL system library (Low level routines for file access etc.).
+MySQL system library. Low level routines for file access and so on.
 @*@*
 
 There are 115 *.c programs in this directory:
@@ -4112,13 +3905,11 @@ There are 115 *.c programs in this directory:
 @item
 array.c  --  Dynamic array handling 
 @item
-charset.c  --  Using dynamic character sets, set default character
-set, ... 
+charset.c  --  Using dynamic character sets, set default character set, ...
 @item
-charset2html.c  --  Checking what character set a browser is using 
+charset2html.c  --  Check what character set a browser is using
 @item
-checksum.c  --  Calculate checksum for a memory block, used for
-pack_isam 
+checksum.c  --  Calculate checksum for a memory block, used for pack_isam
 @item
 default.c  --  Find defaults from *.cnf or *.ini files 
 @item
@@ -4128,13 +3919,11 @@ hash.c  --  Hash search/compare/free functions "for saving keys"
 @item
 list.c  --  Double-linked lists 
 @item
-make-conf.c  --  "Make a charset .conf file out of a ctype-charset.c
-file" 
+make-conf.c  --  "Make a charset .conf file out of a ctype-charset.c file"
 @item
 md5.c  --  MD5 ("Message Digest 5") algorithm from RSA Data Security
 @item
-mf_brkhant.c  --  Prevent user from doing a Break during critical
-execution 
+mf_brkhant.c  --  Prevent user from doing a Break during critical execution (not used in MySQL; can be used by standalone MyISAM applications)
 @item
 mf_cache.c  --  "Open a temporary file and cache it with io_cache"
 @item
@@ -4160,7 +3949,7 @@ mf_path.c  --  Determine where a program can find its files
 @item
 mf_qsort.c  --  Quicksort
 @item
-mf_qsort2.c  --  Quicksort, part 2 
+mf_qsort2.c  --  Quicksort, part 2 (allows the passing of an extra argument to the sort-compare routine)
 @item
 mf_radix.c  --  Radix sort
 @item
@@ -4168,8 +3957,7 @@ mf_same.c  --  Determine whether filenames are the same
 @item
 mf_sort.c  --  Sort with choice of Quicksort or Radix sort
 @item
-mf_soundex.c  --  Soundex algorithm derived from EDN Nov. 14, 1985
-(pg. 36)
+mf_soundex.c  --  Soundex algorithm derived from EDN Nov. 14, 1985 (pg. 36)
 @item
 mf_strip.c  --  Strip trail spaces from a string
 @item
@@ -4300,8 +4088,7 @@ my_rename.c  --  Rename without delete
 @item
 my_seek.c  --  Seek, i.e. point to a spot within a file 
 @item
-my_semaphore.c  --  Semaphore routines, for use on OS that doesn't
-support them 
+my_semaphore.c  --  Semaphore routines, for use on OS that doesn't support them
 @item
 my_sleep.c  --  Wait n microseconds 
 @item
@@ -4313,8 +4100,7 @@ my_symlink2.c  --  Part 2 of my_symlink.c
 @item
 my_tempnam.c  --  Obsolete temporary-filename routine used by ISAM table handler
 @item
-my_thr_init.c  --  initialize/allocate "all mysys & debug thread
-variables" 
+my_thr_init.c  --  initialize/allocate "all mysys & debug thread variables"
 @item
 my_wincond.c  --  Windows-specific: emulate Posix conditions
 @item
@@ -4330,23 +4116,19 @@ queues.c  --  Handle priority queues as in Robert Sedgewick's book
 @item
 raid2.c  --  RAID support (the true implementation is in raid.cc)
 @item
-rijndael.c  --  "Optimised ANSI C code for the Rijndael cipher (now
-AES")
+rijndael.c  --  "Optimised ANSI C code for the Rijndael cipher (now AES")
 @item
-safemalloc.c  --  A version of the standard malloc() with safety
-checking 
+safemalloc.c  --  A version of the standard malloc() with safety checking
 @item
 sha1.c  --  Implementation of Secure Hashing Algorithm 1
 @item
-string.c  --  Initialize/append/free dynamically-sized strings 
+string.c  --  Initialize/append/free dynamically-sized strings; see also sql_string.cc in the /sql directory
 @item
 testhash.c  --  Standalone program: test the hash library routines
 @item
-test_charset.c  --  Standalone program: display character set
-information 
+test_charset.c  --  Standalone program: display character set information
 @item
-test_dir.c  --  Standalone program: placeholder for "test all
-functions" idea 
+test_dir.c  --  Standalone program: placeholder for "test all functions" idea
 @item
 test_fn.c  --  Standalone program: apparently tests a function
 @item
@@ -4358,18 +4140,17 @@ thr_lock.c  --  "Read and write locks for Posix threads"
 @item
 thr_mutex.c  --  A wrapper for mutex functions
 @item
-thr_rwlock.c  --  Synchronizes the readers' thread locks with the
-writer's lock 
+thr_rwlock.c  --  Synchronizes the readers' thread locks with the writer's lock
 @item
 tree.c  --  Initialize/search/free binary trees
 @item
-typelib.c  --  Determine what type a field has 
+typelib.c  --  Find a string in a set of strings; returns the offset to the string found
 @end itemize
 @*@*
 
 You can find documentation for the main functions in these files
-elsewhere in this document.
-For example, the main functions in my_getwd.c are described thus:
+elsewhere in this document. For example, the main functions in my_getwd.c 
+are described thus:
 @*@*
 
 @example
@@ -4425,7 +4206,7 @@ NetWare AMP" at:
 
 @subsection NEW-RPMS
 
-New "RPM Package Manager" files.
+Directory to place RPMs while making a distribution.
 @*@*
 
 This directory is not part of the Windows distribution. It is
@@ -4460,7 +4241,7 @@ there have been no updates for MySQL 4.0 for this section.
 
 @subsection pstack
 
-Process stack display.
+Process stack display (not currently used).
 @*@*
 
 This is a set of publicly-available debugging aids which all do pretty
@@ -4478,7 +4259,7 @@ and it crashes.
 
 @subsection regex
 
-Regular Expression library for support of REGEXP function.
+Henry Spencer's Regular Expression library for support of REGEXP function.
 @*@*
 
 This is the copyrighted product of Henry Spencer from the University
@@ -4504,7 +4285,7 @@ This program calls the 'regcomp' function, which is the entry point in
 
 @subsection SCCS
 
-Source Code Control System.
+Source Code Control System (not part of source distribution).
 @*@*
 
 You will see this directory if and only if you used BitKeeper for
@@ -4514,7 +4295,7 @@ administration and are not of interest to application programmers.
 
 @subsection scripts
 
-SQL batches, e.g. for converting msql to MySQL.
+SQL batches, e.g. mysqlbug and mysql_install_db.
 @*@*
 
 The *.sh filename extension stands for "shell script". Linux
@@ -4529,7 +4310,7 @@ fill_help_tables.sh  --  Create help-information tables and insert
 @item
 make_binary_distribution.sh  --  Get configure information, make, produce tar
 @item
-msql2mysql.sh  --  Convert mSQL programs and scripts to MySQL, partly
+msql2mysql.sh  --  Convert (partly) mSQL programs and scripts to MySQL
 @item
 mysqlbug.sh  --  Create a bug report and mail it
 @item
@@ -4553,15 +4334,14 @@ mysql_find_rows.sh  --  Search for queries containing <regexp>
 @item
 mysql_fix_extensions.sh  --  Renames some file extensions, not recommended
 @item
-mysql_fix_privilege_tables.sh  --  Fix mysql.user etc. if upgrading to MySQL 3.23.14+
+mysql_fix_privilege_tables.sh  --  Fix mysql.user etc. when upgrading. Can be safely run during any upgrade to get the newest 
+MySQL privilege tables
 @item
 mysql_install_db.sh  --  Create privilege tables and func table
 @item
-mysql_secure_installation.sh  --  Disallow remote root login,
-eliminate test, etc.
+mysql_secure_installation.sh  --  Disallow remote root login, eliminate test, etc.
 @item
-mysql_setpermission.sh  --  Aid to add users or databases, sets
-privileges
+mysql_setpermission.sh  --  Aid to add users or databases, sets privileges
 @item
 mysql_tableinfo.sh  --  Puts info re MySQL tables into a MySQL table
 @item
@@ -4577,15 +4357,14 @@ Programs for handling SQL commands. The "core" of MySQL.
 These are the .c and .cc files in the sql directory:
 @itemize @bullet
 @item
-cache_manager.cc  --  manages a number of blocks 
-@item
 convert.cc  --  convert tables between different character sets
 @item
 derror.cc  --  read language-dependent message file
 @item
 des_key_file.cc  --  load DES keys from plaintext file
 @item
-field.cc  --  "implement classes defined in field.h" (long)
+field.cc  --  "implement classes defined in field.h" (long); defines all storage methods MySQL uses to store field information 
+into records that are then passed to handlers
 @item
 field_conv.cc  --  functions to copy data between fields
 @item
@@ -4593,13 +4372,13 @@ filesort.cc  --  sort a result set, using memory or temporary files
 @item
 frm_crypt.cc  --  contains only one short function: get_crypt_for_frm
 @item
-gen_lex_hash.cc  --  Knuth's algorithm from Vol 3 Sorting and Searching, Chapter 6.3
+gen_lex_hash.cc  --  Knuth's algorithm from Vol 3 Sorting and Searching, Chapter 6.3; used to search for SQL keywords in a query
 @item
 gstream.cc  --  GTextReadStream, used to read GIS objects
 @item
 handler.cc  --  handler-calling functions
 @item
-hash_filo.cc  --  static-sized hash tables 
+hash_filo.cc  --  static-sized hash tables, used to store info like hostname -> ip tables in a FIFO manner
 @item
 ha_berkeley.cc  --  Handler: BDB
 @item
@@ -4641,23 +4420,23 @@ item_timefunc.cc  --  Date/time functions, e.g. week of year
 @item
 item_uniq.cc  --  Empty file, here for compatibility reasons
 @item
-key.cc  --  Functions to handle keys and fields in forms 
+key.cc  --  Functions to create keys from records and compare a key to a key in a record
 @item
 lock.cc  --  Locks
 @item
 log.cc  --  Logs
 @item
-log_event.cc  --  Log event 
+log_event.cc  --  Log event (a binary log consists of a stream of log events)
 @item
 matherr.c  --  Handling overflow, underflow, etc.
 @item
 mf_iocache.cc  --  Caching of (sequential) reads and writes
 @item
-mini_client.cc  --  Client included in server for server-server messaging
+mini_client.cc  --  Client included in server for server-server messaging; used by the replication code
 @item
-mysqld.cc  --  Source of mysqld.exe 
+mysqld.cc  --  Source of mysqld.exe; includes the main() program that starts mysqld, handling of signals and connections
 @item
-my_lock.c  --  Lock part of a file 
+my_lock.c  --  Lock part of a file (like /mysys/my_lock.c, but with timeout handling for threads)
 @item
 net_serv.cc  --  Read/write of packets on a network socket
 @item
@@ -4671,9 +4450,9 @@ opt_sum.cc  --  Optimize functions in presence of (implied) GROUP BY
 @item
 password.c  --  Password checking
 @item
-procedure.cc  --  Procedure
+procedure.cc  --  Procedure interface, as used in SELECT * FROM Table_name PROCEDURE ANALYSE
 @item
-protocol.cc  --  Low level functions for storing data to be sent to client
+protocol.cc  --  Low level functions for PACKING data that is sent to client; actual sending done with net_serv.cc
 @item
 records.cc  --  Functions for easy reading of records, possible through a cache
 @item
@@ -4685,15 +4464,15 @@ slave.cc  --  Procedures for a slave in a master/slave (replication) relation
 @item
 spatial.cc  --  Geometry stuff (lines, points, etc.)
 @item
-sql_acl.cc  --  Functions related to ACL security
+sql_acl.cc  --  Functions related to ACL security; checks, stores, retrieves, and deletes MySQL user level privileges
 @item
-sql_analyse.cc  --  Analyse an input string (?)
+sql_analyse.cc  --  Implements the PROCEDURE analyse, which analyses a query result and returns the 'optimal' data type for each result column
 @item
-sql_base.cc  --  Basic functions needed by many modules
+sql_base.cc  --  Basic functions needed by many modules, like opening and closing tables with table cache management
 @item
 sql_cache.cc  --  SQL query cache, with long comments about how caching works
 @item
-sql_class.cc  --  SQL class
+sql_class.cc  --  SQL class; implements the SQL base classes, of which THD (THREAD object) is the most important
 @item
 sql_crypt.cc  --  Encode / decode, very short
 @item
@@ -4707,26 +4486,26 @@ sql_do.cc  --  The DO statement
 @item
 sql_error.cc  --  Errors and warnings
 @item
-sql_handler.cc  --  Direct access to ISAM
+sql_handler.cc  --  Implements the HANDLER interface, which gives direct access to rows in MyISAM and InnoDB
 @item
-sql_help.cc  --  The HELP statement (if there is one?)
+sql_help.cc  --  The HELP statement
 @item
 sql_insert.cc  --  The INSERT statement
 @item
-sql_lex.cc  --  Related to lex or yacc
+sql_lex.cc  --  Does lexical analysis of a query; i.e. breaks a query string into pieces and determines the basic type (number,
+string, keyword, etc.) of each piece
 @item
-sql_list.cc  --  Only list_node_end_of_list, short 
+sql_list.cc  --  Only list_node_end_of_list, short (the rest of the list class is implemented in sql_list.h)
 @item
-sql_load.cc  --  The LOAD DATA statement? 
+sql_load.cc  --  The LOAD DATA statement
 @item
-sql_map.cc  --  Memory-mapped files? 
+sql_map.cc  --  Memory-mapped files (not yet in use)
 @item
-sql_manager.cc  --  Maintenance tasks, e.g. flushing the buffers
-periodically 
+sql_manager.cc  --  Maintenance tasks, e.g. flushing the buffers periodically; used with BDB table logs
 @item
 sql_olap.cc  --  ROLLUP
 @item
-sql_parse.cc  --  Parse an SQL statement 
+sql_parse.cc  --  Parse an SQL statement; do initial checks and then jump to the function that should execute the statement
 @item
 sql_prepare.cc  --  Prepare an SQL statement
 @item
@@ -4738,8 +4517,7 @@ sql_select.cc  --  Select and join optimisation
 @item
 sql_show.cc  --  The SHOW statement
 @item
-sql_string.cc  --  String functions: alloc, realloc, copy, convert,
-etc. 
+sql_string.cc  --  String functions: alloc, realloc, copy, convert, etc.
 @item
 sql_table.cc  --  The DROP TABLE and ALTER TABLE statements
 @item
@@ -4751,11 +4529,11 @@ sql_union.cc  --  The UNION operator
 @item
 sql_update.cc  --  The UPDATE statement
 @item
-stacktrace.c  --  Display stack trace (Linux/Intel only?)
+stacktrace.c  --  Display stack trace (Linux/Intel only)
 @item
-table.cc  --  Table metadata retrieval, mostly 
+table.cc  --  Table metadata retrieval; read the table definition from a .frm file and store it in a TABLE object
 @item
-thr_malloc.cc  --  Mallocs used in threads 
+thr_malloc.cc  --  Thread-safe interface to /mysys/my_alloc.c
 @item
 time.cc  --  Date and time functions
 @item
@@ -4763,7 +4541,7 @@ udf_example.cc  --  Example file of user-defined functions
 @item
 uniques.cc  --  Function to handle quick removal of duplicates
 @item
-unireg.cc  --  Create a unireg form file from a FIELD and field-info struct 
+unireg.cc  --  Create a unireg form file (.frm) from a FIELD and field-info struct
 @end itemize
 @*@*
 
@@ -4781,13 +4559,11 @@ available all the material necessary to reproduce all the tests.
 There are five subdirectories and sub-subdirectories:
 @itemize @bullet
 @item
-\Comments  --  Comments about results from tests of Access, Adabas,
-etc. 
+\Comments  --  Comments about results from tests of Access, Adabas, etc.
 @item
 \Data\ATIS  --  .txt files containing input data for the "ATIS" tests
 @item
-\Data\Wisconsin  --  .txt files containing input data for the
-"Wisconsin" tests 
+\Data\Wisconsin  --  .txt files containing input data for the "Wisconsin" tests
 @item
 \Results  --  old test results
 @item
@@ -4807,7 +4583,8 @@ There is one README file and one TODO file.
 
 @subsection SSL
 
-Secure Sockets Layer.
+Secure Sockets Layer; includes an example certification one can use
+test an SSL (secure) database connection.
 @*@*
 
 This isn't a code directory. It contains a short note from Tonu Samuel
@@ -4885,7 +4662,7 @@ r_strinstr.c  --  see if one string is within another
 @item
 str2int.c  --  convert string to integer 
 @item
-strappend.c  --  append one string to another 
+strappend.c  --  fill up a string to n characters
 @item
 strcat.c  --  concatenate strings 
 @item
@@ -4905,11 +4682,11 @@ strinstr.c  --  find string within string
 @item
 strlen.c  --  return length of string in bytes 
 @item
-strmake.c  --  move n characters, or move till end 
+strmake.c  --  create new string from old string with fixed length, append end \0 if needed
 @item
 strmov.c  --  move source to dest and return pointer to end
 @item
-strnlen.c  --  return length of string, or return n 
+strnlen.c  --  return min(length of string, n)
 @item
 strnmov.c  --  move source to dest for source size, or for n bytes 
 @item
@@ -4933,9 +4710,9 @@ strxnmov.c  --  like strxmov.c but with a maximum length n
 @item
 str_test.c  --  test of all the string functions encoded in assembler 
 @item
-udiv.c  --  unsigned long divide 
+udiv.c  --  unsigned long divide, for operating systems that don't support these
 @item
-xml.c  --  read and parse XML strings 
+xml.c  --  read and parse XML strings; used to read character definition information stored in /sql/share/charsets
 @end itemize
 @*@*
 
@@ -4947,21 +4724,41 @@ members of the Intel processor family.
 
 @subsection support-files
 
-Support files.
+Files used to build MySQL on different systems.
 @*@*
 
 The files here are for building ("making") MySQL given a package
 manager, compiler, linker, and other build tools. The support files
-provide instructions and switches for the build processes.
+provide instructions and switches for the build processes. They 
+include example my.cnf files one can use as a default setup for
+MySQL.
 @*@*
 
 @subsection tests
 
-Tests in Perl.
+Tests in Perl and in C.
 @*@*
 
-These are tests that were run once to check for bugs in various
-scenarios: forks, locks, big records, exporting, truncating, etc.
+The files in this directory are test programs that can be used 
+as a base to write a program to simulate problems in MySQL in various
+scenarios: forks, locks, big records, exporting, truncating, and so on. 
+Some examples are:
+@itemize @bullet
+@item
+connect_test.c  --  test that a connect is possible
+@item
+insert_test.c  --  test that an insert is possible
+@item
+list_test.c  --  test that a select is possible
+@item
+select_test.c  --  test that a select is possible
+@item
+showdb_test.c  --  test that a show-databases is possible
+@item
+ssl_test.c  --  test that SSL is possible
+@item
+thread_test.c  --  test that threading is possible
+@end itemize
 @*@*
 
 @subsection tools
@@ -4972,7 +4769,9 @@ Tools -- well, actually, one tool.
 The only file is:
 @itemize @bullet
 @item
-mysqlmanager.c  --  A "server management daemon" by Sasha Pachev 
+mysqlmanager.c  --  A "server management daemon" by Sasha Pachev. This
+is a tool under development and is not yet useful. Related to fail-safe 
+replication.
 @end itemize
 @*@*
 
@@ -4984,11 +4783,16 @@ Visual C++ Files.
 Includes this entire directory, repeated for VC++ (Windows) use.
 @*@*
 
-VC++Files has subdirectories which are copies of the main directories.
-For example there is a subdirectory \VC++Files\heap, which has the
-same files as \heap. So for a description of the files in
-\VC++Files\heap, see the description of the files in \heap. The same
-applies for almost all of VC++Files's subdirectories (bdb, client,
+VC++Files includes a complete environment to compile MySQL with the VC++
+compiler. To use it, just copy the files on this directory; the make_win_src_distribution.sh
+script uses these files to create a Windows source installation.
+@*@*
+
+This directory has subdirectories which are copies of the main directories.
+For example, there is a subdirectory \VC++Files\heap, which has the Microsoft
+developer studio project file to compile \heap with VC++. So for a description 
+of the files in \VC++Files\heap, see the description of the files in \heap. The 
+same applies for almost all of VC++Files's subdirectories (bdb, client,
 isam, libmysql, etc.). The difference is that the \VC++Files variants
 are specifically for compilation with Microsoft Visual C++ in 32-bit
 Windows environments.
@@ -5003,7 +4807,7 @@ comp_err  --  (nearly empty)
 @item
 contrib  --  (nearly empty)
 @item
-InstallShield     script files 
+InstallShield  --  script files
 @item
 isamchk  --  (nearly empty)
 @item
@@ -5043,10 +4847,16 @@ thr_insert_test  --  (nearly empty)
 @item
 thr_test  --  one short program used to test for memory-allocation bug
 @item
-winmysqladmin  --  the winmysqladmin.exe source. machine-generated? 
+winmysqladmin  --  the winmysqladmin.exe source
 @end itemize
 @*@*
 
+The "nearly empty" subdirectories noted above (e.g. comp_err and isamchk) 
+are needed because VC++ requires one directory per project (i.e. executable). 
+We are trying to keep to the MySQL standard source layout and compile only 
+to different directories.
+@*@*
+
 @subsection vio
 
 Virtual I/O Library.
@@ -5094,7 +4904,12 @@ obsolete.
 
 @subsection zlib
 
-Data compression library.
+Data compression library, used on Windows.
+@*@*
+
+zlib is a data compression library used to support the compressed
+protocol and the COMPRESS/UNCOMPRESS functions under Windows.
+On Unix, MySQL uses the system libgz.a library for this purpose.
 @*@*
 
 Zlib -- which presumably stands for "Zip Library" -- is not a MySQL

innobase/include/trx0trx.h

@@ -418,10 +418,6 @@ struct trx_struct{
 	lock_t*		auto_inc_lock;	/* possible auto-inc lock reserved by
 					the transaction; note that it is also
 					in the lock list trx_locks */
-        ibool           ignore_duplicates_in_insert;
-                                        /* in an insert roll back only insert
-                                        of the latest row in case
-                                        of a duplicate key error */
 	UT_LIST_NODE_T(trx_t)
 			trx_list;	/* list of transactions */
 	UT_LIST_NODE_T(trx_t)

innobase/srv/srv0start.c

@@ -1441,6 +1441,8 @@ innobase_start_or_create_for_mysql(void)
 			srv_force_recovery);
 	}
 
+	fflush(stderr);
+
 	return((int) DB_SUCCESS);
 }
 

innobase/trx/trx0trx.c

@@ -102,8 +102,6 @@ trx_create(
 	trx->mysql_master_log_file_name = (char*) "";
 	trx->mysql_master_log_pos = 0;
 	
-	trx->ignore_duplicates_in_insert = FALSE;
-
 	mutex_create(&(trx->undo_mutex));
 	mutex_set_level(&(trx->undo_mutex), SYNC_TRX_UNDO);
 

sql/ha_innodb.cc

@@ -1911,13 +1911,6 @@ ha_innobase::write_row(
 		build_template(prebuilt, NULL, table, ROW_MYSQL_WHOLE_ROW);
 	}
 
-	if (user_thd->lex.sql_command == SQLCOM_INSERT
-	    && user_thd->lex.duplicates == DUP_IGNORE) {
-	        prebuilt->trx->ignore_duplicates_in_insert = TRUE;
-        } else {
-	        prebuilt->trx->ignore_duplicates_in_insert = FALSE;
-	}
-
 	srv_conc_enter_innodb(prebuilt->trx);
 
 	error = row_insert_for_mysql((byte*) record, prebuilt);
@@ -1958,8 +1951,6 @@ ha_innobase::write_row(
 		}
 	}
 
-	prebuilt->trx->ignore_duplicates_in_insert = FALSE;
-
 	error = convert_error_code_to_mysql(error, user_thd);
 
 	/* Tell InnoDB server that there might be work for