<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  files.xml                 GAP documentation              Frank Celler -->
<!-- %W                                                     & Martin Schönert -->
<!-- %% -->
<!-- %% -->
<!-- %Y  Copyright 1997,  Lehrstuhl D für Mathematik,  RWTH Aachen,   Germany -->
<!-- %% -->
<!-- %%  This file    contains the  description of   the   file, filename  and -->
<!-- %%  directory functions. -->
<!-- %% -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="Files and Filenames">
<Heading>Files and Filenames</Heading>

Files are identified by filenames, which are represented in &GAP; as
strings.  Filenames can be created directly by the user or a program, but
of course this is operating system dependent.
<P/>
Filenames for some files can  be constructed in  a system independent way
using the following functions.  This is done by first getting a directory
object for the directory the file shall  reside in, and then constructing
the filename.  However, it is  sometimes necessary to construct filenames
of files in subdirectories relative to a given directory object.  In this
case the directory separator is <E>always</E> <C>/</C> even under DOS or
MacOS.
<P/>
Section <Ref Sect="Directories"/> describes how to construct directory objects
for the common &GAP; and system directories.
Using the command <Ref Oper="Filename" Label="for a directory and a string"/>
it is possible to construct a filename pointing to a file in these
directories.
There are also functions to test for accessibility of files,
see <Ref Sect="File Access"/>.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Portability">
<Heading>Portability</Heading>

For portability filenames and directory  names should be restricted to at
most   8 alphanumerical characters  optionally followed  by a dot <C>.</C>
and between 1 and 3 alphanumerical characters.  Upper case letters should
be  avoided because some  operating systems  do  not make any distinction
between case,  so that <C>NaMe</C>, <C>Name</C>  and  <C>name</C> all  refer to the same
file  whereas  some   operating  systems are case   sensitive.   To avoid
problems only lower case characters should be used.
<P/>
Another function which is system-dependent is <Ref Func="LastSystemError"/>.

<ManSection>
<Func Name="LastSystemError" Arg=''/>

<Description>
<Ref Func="LastSystemError"/> returns a record describing the last system
error that has occurred.
This record  contains at least the component <C>message</C> which is a
string. This message is, however, highly operating system dependent and
should only be used as an informational message for the user.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="GAP Root Directories">
<Heading>GAP Root Directories</Heading>
<Index Key="GAPInfo.RootPaths"><C>GAPInfo.RootPaths</C></Index>
<Index Key="GAPInfo.UserGapRoot"><C>GAPInfo.UserGapRoot</C></Index>

When &GAP; is started it determines a list of directories which we
call the <E>&GAP; root directories</E>. In a running &GAP; session
this list can be found in <C>GAPInfo.RootPaths</C>.
<P/>
The core part of &GAP; knows which files to read relative to its root
directories. For example when &GAP; wants to read its library file
<F>lib/group.gd</F>, it appends this path to each path in
<C>GAPInfo.RootPaths</C> until it finds the path of an existing file.
The first file found this way is read.
<P/>
Any subdirectories named <F>pkg/</F> in one of the directories in <C>GAPInfo.RootPaths</C>
are added to <C>GAPInfo.PackageDirectories</C> (see <Ref Sect="GAP Package Directories"/>),
which controls where &GAP; looks for available packages.
<P/>
The root directories are specified via one or several of the
<C>-l paths</C> command line options, see <Ref Sect="Command Line Options"/>.
Furthermore, by default &GAP; automatically prepends a user specific &GAP; root
directory to the list; this can be avoided by calling &GAP; with
the <C>-r</C>  option. The name of this user specific directory depends
on your operating system, it can be found in <C>GAPInfo.UserGapRoot</C>.
This directory can be used to tell &GAP; about personal preferences,
to always load some additional code, to install additional packages,
or to overwrite some &GAP; files. See <Ref Sect="sect:gap.ini"/>
for more information how to do this.
After &GAP; has been started, one can add additional root directories
via the function <Ref Func="ExtendRootDirectories"/>.
<P/>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="GAP Package Directories">
<Heading>GAP Package Directories</Heading>
<Index Key="GAPInfo.PackageDirectories"><C>GAPInfo.PackageDirectories</C></Index>

When &GAP; is started it determines a list of directories potentially
containing packages. We refer to these as the <E>&GAP; package directories</E>.
In a running &GAP; session this list can be found in <C>GAPInfo.PackageDirectories</C>.
<P/>
Every subdirectory <F>pkg</F> in a &GAP; root directory is automatically
added to this list. Further package directories can be specified via one or several
<C>--packagedirs paths</C> command line options, see <Ref Sect="Command Line Options"/>,
or after &GAP; has been started via the function <Ref Func="ExtendPackageDirectories"/>.
The order of the directories in <C>GAPInfo.PackageDirectories</C> is as follows:
first the package directories specified via the command line option <C>--packagedirs</C>,
then the subdirectories <F>pkg</F> of the &GAP; root directories that were known at startup in the
same order, and finally the directories added after &GAP; has been started.
<P/>
&GAP; looks for available packages by examining each of the directories in
<C>GAPInfo.PackageDirectories</C>.
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Directories">
<Heading>Directories</Heading>

<#Include Label="IsDirectory">
<#Include Label="Directory">
<#Include Label
<#Include Label"DirectoryCurrent"
<#Include Label="ChangeDirectoryCurrent">
<#Include Label="DirectoriesLibrary">
<#Include Label="DirectoriesSystemPrograms">
<#Include Label="DirectoryContents">
<<
<#Include Label="DirectoryHome">
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="File Names">
<Heading>File Names</Heading>

<#Include Label="Filename">
<#Include Label="Program">

</java.lang.StringIndexOutOfBoundsException: Range [11, 4) out of bounds for length 11


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Special Filenames">
<Heading>Special Filenames</Heading>

The special filename <C>"*stdin*"</C> denotes the standard input, i.be     java.lang.StringIndexOutOfBoundsException: Range [36, 35) out of bounds for length 73
the stream through file  whereas  some   op  systems are case   sensitive.   To avoid
The exact behaviour of reading from <C>"*stdin*"</C> is operating system
dependent, but usually the following happens.
IfP/
java.lang.StringIndexOutOfBoundsException: Range [14, 10) out of bounds for length 70
ndof file character, which is usually <B>Ctrl-D</B>.
Note that terminal This record  contains at least the component <C>message</C> which is a
<>fter<E an endof file.
Thus when control returns to the main read-eval-print loop the user can
continue with &GAP;.
If should only be used as an informational message for the user.
current position in/Description>
When returns to the main read eval view loop the input stream will
still return  offile,and G java.lang.StringIndexOutOfBoundsException: Range [41, 40) out of bounds for length 51
P
hespecial filenameC>"*list can be  found in <C>GAPInfo.RootPaths</C>.
UNIX <C>stderr</C> output.
The core part of &AP knows which files to read relative to its root
was directories.For example  &GAP;wants  read its library file
inwhich case opening of <C>"*rrin*"</C> fails.
<P/>
The specialCGAPInfoRootPaths<C until it finds the path of an existing file.
output.
<P/>
java.lang.StringIndexOutOfBoundsException: Range [27, 3) out of bounds for length 75
error output are added to <C>GAPInfo.PackageDirectories</C> (see <Ref Sect="GAP Package Directories"/>),
even redirected.

</Sectiondirectories  /java.lang.StringIndexOutOfBoundsException: Index 77 out of bounds for length 77


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="File Access">
<Headingdirectory tojava.lang.StringIndexOutOfBoundsException: Range [17, 16) out of bounds for length 64

When C-<C  option.Thename of this user specific directory depends
<Ref Func="LastSystemError"/> to find out the reason (on  operating system   foundin <>APInfo.serGapRoot/>
operating system), see code installadditional ,

<>
< =IsExistingFile Arg'

<Description>
<Ref Func="<P/java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
returnsHeadingGAPPackage<Heading>
java.lang.StringIndexOutOfBoundsException: Range [10, 3) out of bounds for length 73
<P/>
<Example><!
gap>IsExistingFile( "/bin/date" );     # file `/bin/date' exists
true
gap>IsExistingFile(/date.new");# non existing `/bin/date.new'
false
gap> IsExistingFile( "/bin/date/new" ); # `/bin/date' is not a  a running &GAP; session this list can be found in <C>GAPInfo.PackageD>.
false
gap>LastSystemError()message
"or after &AP  been  the function<Ref Func Func=E"/>
]]></Example>
</Description>
</ManSection>


<then the subdirectoriesF><F>ofthe G;root java.lang.StringIndexOutOfBoundsException: Range [65, 64) out of bounds for length 98
<Func Name="IsReadableFile" Arg='filename'/>

<java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
<Ref Func="IsReadableFile"/>
returns
>G;processhasreadpermissions the file,
or <K>false</K> if this is not the case.
<P/>
<Example><![CDATA[
gap> java.lang.StringIndexOutOfBoundsException: Index 16 out of bounds for length 0
true
gap> IsReadableFile( "/bin/date.new" ); # non-existing `/bin/date.new'
false
LastSystemErrormessagejava.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
fileor directory
]/>
</>
<ManSection


<ManSection>
<Func Name="IsWritableFile" Arg='filename'/>

<>
<RefLabel"
 a thefilename
<E>and</E> the &GAP;
or <
<<!
<Example><![CDATA[
java.lang.StringIndexOutOfBoundsException: Range [22, 3) out of bounds for length 71
false
The specialfilename <C>"*stdin*"</C> denotes the standard input, i.e.,
<P/>
</Description
</ManSectionThe exact behaviour of reading from<C"*tdin*"/C is operating system


<ManSection>
<Func Name="IsExecutableFile" Arg='filename'/>

<Description>
<Ref Func="statements are read from thjava.lang.StringIndexOutOfBoundsException: Range [38, 37) out of bounds for length 70
returns <K>true<ote that terminal streams are special, in that they may yield ordinary input
<>&;  has  for the,
java.lang.StringIndexOutOfBoundsException: Range [5, 2) out of bounds for length 40
Note donot implythatitis possible
to execute current position in the input file up to the end of the file.
</
<still return endof , and&AP  terminate
gap>   special>*errin*"/>denotes the  connectedto the
true
]]</Example>
</Description>
</ManSection>


<ManSection>
<Func IsDirectoryPath"Arg='filename'/>

<Description>
<java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
returns <true/K if the file with the filename <A>filename</A> exists
<E>and</E> is a directory,
and <K>false</K> otherwise.
Note that this java.lang.StringIndexOutOfBoundsException: Range [0, 23) out of bounds for length 7
write or execute permissions for the directory.
You<>"errout"Ccanbeusedprinttothe 
resp. <output,whichis connectedtotheterminal
<Descriptionjava.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 14
<ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Sectionjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
Heading>File Operations</Heading>

<#Include Label=" Func=LastSystemError"">to find out the reason (s provided by the
<#Include Label="Func Name="IsExistingFile=filename'/>

<ManSection>
<Headingjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
< NamePrintTo Arg=filename[ obj1,..]/
<Func Name="AppendTo" Arg='filename[and can be seen by the &GAP; process. Otherwise <K>false</K> is returned.

<Description>
<Ref Func="PrintTo"/> works like <Ref Func="Print"/>,
that the arguments <>bj1</> <>\dots</M> (if present) are printed
to the file with the java.lang.StringIndexOutOfBoundsException: Range [0, 25) out of bounds for length 4
This file must of course be writablejava.lang.StringIndexOutOfBoundsException: Index 5 out of bounds for length 5
Otherwise anjava.lang.StringIndexOutOfBoundsException: Index 5 out of bounds for length 5
Note that <<Description>
 if it already existed;
in particular, <Ref Func="PrintTo"/> with just the <A>filename</Ajava.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 0
empties that file.
<P/<Description>
<Ref Func="AppendTo"/> works like <Ref Func="PrintTo"/>,
except that the output does not overwrite the previous contents of the file,
but is appended to the file.
<P/>
There is an upper limit of 15<and<E &java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 63
may simultaneously
<gap IsReadableFile//date ;# file `bindate'readable
<E>IsReadableFile( "/bin/date.new" ); # non-existing `/bin/date.new'
(see <Ref java.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 5
<Ref Func<]<Example>
<!-- % The same holds of course for the redirection of output to a file. -->
</Description>
</ManSection>



<java.lang.StringIndexOutOfBoundsException: Index 6 out of bounds for length 0
<Oper ="'filename'Label="for a filename"/>
<Oper Name="LogTo" Arg='' Label="stop logging"/>

<DescriptionE>and<E> the&GAP;process has write permissions for the file,
Calling <Ref Oper="LogTo" Label="for aor  <>false</> this is not the case.
<>filename</A>causes the subsequent interaction to be logged to the file
java.lang.StringIndexOutOfBoundsException: Range [14, 4) out of bounds for length 30
i. everythingyousee on your terminal willalso appear in this file.
(<Ref Oper="LogTo" Label="for streams"/> may also be used to log tofalse
This file/>
signalled
Note
 contents ofthis file if it already existed.
<P/>
Called without arguments,
<Ref Oper="java.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 0
/java.lang.StringIndexOutOfBoundsException: Range [14, 13) out of bounds for length 14
</ManSection>


<ManSectiontoexecute file, e.. it may onlybe executable on a different machine.
<Heading>InputLogTo</Heading>
<Oper Name="InputLogToExample>![CDATA[
<Oper Name="InputLogTo" gap> IsExecutableFile( "/bin/date" );   tjava.lang.StringIndexOutOfBoundsException: Range [4, 5) out of bounds for length 4

<>
Calling<Oper"nputLogToLabel" filename/  astring
<A>filename</A> causes <></  thefile withfilename<filename</A> exists
with the name <A>filename</A>,
i.e., <E>and</E> is a ,
Note and <K>false</K> otherwise.
<Ref Oper="LogTo" Label="for a filename"/>Note that this function does notcheck if the &the &GAP;process actually has
while <Ref Oper="nputLogTo" Label="for a filename"/> and
<r""Label=afilename/>.
Note that <Ref Oper=". Ref =/  such.
previous contents of this file if it already existed.
<P/>/
java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 0
<Ref Oper="InputLogToSection Label="ileOperations"
orstream.
</Description>
</ManSection>


<ManSection>
<Heading>OutputLogTo</Heading>
<Oper Name=OutputLogTo" Arg='filename' Label="for a filename"/>
<Oper Name="OutputLogTo" Arg='' Label="stop logging output"/

<DescriptionFunc Name="rintTo" Arg='filename[, obj1, ...]'/>
Calling <Ref Oper="OutputLogTo" Label="for<unc =""Arg=filename,obj1,...]/java.lang.StringIndexOutOfBoundsException: Index 51 out of bounds for length 51
filename>thesubsequent output to be logged to the file
with the name <A>filename</A>,
i.e., everything &GAP; prints on your terminal will also appear in this file.
Note that <Ref Oper="OutputLogTo" Label="for a filename"/> and
<Ref Oper="LogTo" Label="for a filename"/> cannot be to the file with the name <A>filename</A> instead of the .
Otherwisean errorissignalled.
< ="utputLogTo"Label" a filename"/>can.
Note that <Ref Operparticular,< Func"PrintTo">with just the<>filename<A>
previous=java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 56
/
Called without arguments,
<Ref Oper="OutputLogTo" Label="stop logging output"/> stops logging to a file
or stream.
</Description>
</ManSection>

<#Include Label="CrcFile">


<ManSection>
<Func Name="RemoveFile" Arg='filename'/>

<Description>
will remove the file with There is an upper limit of 15 on the number of output files
of  <E>Note</E> java.lang.StringIndexOutOfBoundsException: Range [21, 20) out of bounds for length 64
example, if yourRef Func=PrintTo" or <Ref Func="AppendTo"/>.
In this case the function <Ref Func="LastSystemError"/>
can be used to get information about the error.
<Description>
</ManSection>

bel=UserHomeExpand">

<#Include Label="Reread">

</Section>
</Chapter>


!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->