Library: gafslib - Chess Endings
Version: 1.11 - October 2006
Author: Guido Antonelli - Email:rigel_g@iol.it


The library GAFSLIB consists of a set of functions which permits the use of
the endgame tablebases with number of men <= 6 (<= 5 in the Windows version)
generated by program GAFS in the standard version of 8 bits or more per
position or in the reduced version with 2 bits per position (bitbases).

From an external point of view the user program can call only the following
two functions:

1. iniz_tabelle() = executes the initialization of the vector of structures
                    containing the description of the available tablebases
                    and performs other minor functions.

char iniz_tabelle(char *path, char flag_tab, short int memram)
   Input parameters:
         char *path       = tablebases pathname
         char flag_tab    0 = tablebases
                          1 = bitbases
         short int memram = RAM memory in Mb available for tablebases
   Return value:      >= 3 no errors (the returned value is the max number
                           of men of the utilizable chess endgames)
                      1 error (also tablebases pathname > 50 characters)


NOTE: The functions iniz_tabelle() can be called more than once during the
      same run. This possibility is allowed to the user program in order
      to pass from one type of tablebases to the other, in general from 2
      bits per position to 8 bits or more per position tablebases. 


2. calc_posizione() = returns the result found in the tablebases given the
                      men positions.

char calc_posizione(char np, char pez[], char pos[], char gioc,
          char flag_mem, char enpas, char *prisult, short int *pnmosse);
   Input parameters:
         char np      = total numbers of men (Kings included)
         char pez[]   = contains the men in this sequence:
                        White King - Other white men - Black King - Other
                        black men. Men codes are as follows:
                          PAWN   = 0     KNIGHT = 1     BISHOP = 2
                          ROOK   = 3     QUEEN  = 4     KING   = 5
         char pos[]   = contains the corresponding positions of the men
                        with the following convention:
                          0 = a1, 1 = b1 ... 62 = g8, 63 = h8
         char gioc    = player who moves (White = 0, Black = 1)
         char flag_mem  0 tablebases are read from disk
                        <> 0 tablebases are read from RAM (with automa-
                             tic loading at the first request)
         char enpas     0  no en passant capture
                        n = number of square where en passant capture is
                            possible
   Output parameters:
         char *prisult  0 draw
                        1 win
                       -1 loss
         short int *pnmosse = number of moves to win or to lose (significant
                              only if flag_tab = 0)
   Return value:        0 no errors
                        1 first man != King
                        2 wrong man code ( < 0 or > 5)
                        3 wrong position ( < 0 or > 63)
                        4 square occupied by two men
                        5 number of Kings != 2
                        6 illegal Kings positions
                        7 illegal position in ep capture
                        8 tablebases not present in the structures vector
                        9 tablebases not present on disk
                       10 insufficient allocation space
                       11 error in fread()
                       12 error in fseek()
                       13 illegal chess position
                       14 max number of RAM memory cleaning up reached (5)