<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %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. -->PathSystem
<!-- %% -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<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 java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 0
avoided becausesome  operatingoperating 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
eratingjava.lang.StringIndexOutOfBoundsException: Range [65, 61) out of bounds for length 73
problems only lower 
</
Another statements are read from the terminal stream until the user enters the

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

<Description>
<Ref Func="LastSystemError"/> returns a record describing the last system
error that has occurrede ofjava.lang.StringIndexOutOfBoundsException: Range [22, 21) out of bounds for length 54
java.lang.StringIndexOutOfBoundsException: Range [24, 4) out of bounds for length 70
string. This <>/> java.lang.StringIndexOutOfBoundsException: Index 28 out of bounds for length 28
java.lang.StringIndexOutOfBoundsException: Range [40, 39) out of bounds for length 61
<
</ controljava.lang.StringIndexOutOfBoundsException: Range [21, 20) out of bounds for length 74

</stillreturn endof  &AP; will terminate.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="GAP Root Directories">
<Heading>GAP Root Directories</Heading>
<Index Key<P/>
<Index Key="GAPInfoThe   <>*errin*"</C> denotes the stream connected to the

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  java.lang.StringIndexOutOfBoundsException: Range [23, 22) out of bounds for length 51
<P/>
  &; java.lang.StringIndexOutOfBoundsException: Range [49, 48) out of bounds for length 69
 when  to
<F>lib/group.gd<  C*java.lang.StringIndexOutOfBoundsException: Range [36, 35) out of bounds for length 48
<>./> 
The first file java.lang.StringIndexOutOfBoundsException: Index 17 out of bounds for length 7
<P/>
Any subdirectories named <Frrout*"</C> can be used to print to the standard
java.lang.StringIndexOutOfBoundsException: Range [10, 9) out of bounds for length 91
which controls where &GAP; even if the standard output was
<P/>
The root  are specified via one or several ofthe
<C>-l paths</C> command line options, see <Ref Sect="Command Line Options">.
Furthermore, by default &GAP; automatically prepends a user specific &java.lang.StringIndexOutOfBoundsException: Index 73 out of bounds for length 0
to the list; this can be avoided by calling &GAP; with
C>r/>.  ofjava.lang.StringIndexOutOfBoundsException: Range [71, 63) out of bounds for length 71
onyoursystem,itcanbe  in <>APInfo.serGapRoot<C.
This directory can be used to tell &GAP; about personal preferences,
ditional ,to  additionalpackages
or to overwrite
ManSection>
After &FuncName="Arg=filename'/>
via the java.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 0
<P>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="GAP Package Directories">
<>  Directories/>
<Index and can be seen by the &GAP; process. Otherwise <K>false</K> is returned.

When >java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 65
containing ( /bin/new ; java.lang.StringIndexOutOfBoundsException: Range [46, 45) out of bounds for length 70
Inirectories</C>java.lang.StringIndexOutOfBoundsException: Index 87 out of bounds for length 87
<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
<gap LastSystemError(.;
  &;has startedvia   Ref"xtendPackageDirectories.
The order of the java.lang.StringIndexOutOfBoundsException: Index 23 out of bounds for length 13
first the package java.lang.StringIndexOutOfBoundsException: Index 26 out of bounds for length 13
 the  <>kg/>of &AP;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</<Eand</E> the &AP  has  for  java.lang.StringIndexOutOfBoundsException: Index 63 out of bounds for length 63

<#Include Label="IsDirectory">
<#Include Label="Directory">
<#java.lang.StringIndexOutOfBoundsException: Index 5 out of bounds for length 4
<#Include Label="DirectoryCurrent">
<#Include Label=gap> ().message;
<#Include Label="DirectoriesLibrary">
<#Include Label="DirectoriesSystemPrograms">
<#"No such   "
<#Include Label]><Example>
<#/Description
</>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->java.lang.StringIndexOutOfBoundsException: Range [12, 11) out of bounds for length 12
<Section Label="
<Heading>FileDescription

clude ="Filename>
<#Include Label="returns <K>true</K> if file with the  <A>filename</A> exists

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="gap> IsWritableFile( "/bin/date" );  # file `/bin/date' is not writable
<Heading>Special Filenames</Heading>

The java.lang.StringIndexOutOfBoundsException: Range [21, 20) out of bounds for length 71
the >
 of C>*<> operating 
dependent, but usually the java.lang.StringIndexOutOfBoundsException: Index 35 out of bounds for length 0
If &GAP; was started with no java.lang.StringIndexOutOfBoundsException: Range [0, 34) out of bounds for length 0
e terminal stream until the user enters the
end of file character, which is usually <B>Ctrl-D</B>.
java.lang.StringIndexOutOfBoundsException: Range [10, 9) out of bounds for length 77
<E>after</E> an end of file.
Thus when control<>and</E>the &APprocesshas executepermissions the file,
or <K>false</K> if this is not the case.
If &GAP; was started  that execute permissions not  that  is 
java.lang.StringIndexOutOfBoundsException: Range [16, 7) out of bounds for length 61
When control returns to P>
still return   file,&AP;will.
<P/>
The filename <C""C denotes thestream   
UNIX <C>stderr</
This stream ]>java.lang.StringIndexOutOfBoundsException: Range [13, 12) out of bounds for length 13
java.lang.StringIndexOutOfBoundsException: Index 3 out of bounds for length 0
Name=" java.lang.StringIndexOutOfBoundsException: Range [33, 32) out of bounds for length 45
<P/>
The special filename <C>"*stdout*"</C> can be used to print to the standardK><> java.lang.StringIndexOutOfBoundsException: Range [27, 26) out of bounds for length 72
output.
<P/>
The special filename <>errout*"/C>    to   standard
error  file  usually    ,
even if the/>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section <java.lang.StringIndexOutOfBoundsException: Range [13, 12) out of bounds for length 13
<Heading>File Access</Heading>

When the following functions return <K>false<File /java.lang.StringIndexOutOfBoundsException: Range [34, 33) out of bounds for length 34
<RefFunc=" find the a  by the
operating system), see the examples.

<ManSection>
<" Arg=java.lang.StringIndexOutOfBoundsException: Range [43, 41) out of bounds for length 44

<Description>
<Ref Func="IsExistingFile"/>
returns <K>true</K> if Func ="" =,,.]>
java.lang.StringIndexOutOfBoundsException: Range [4, 3) out of bounds for length 73
<P/>
<Example><![java.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 13
gap> except  A>/><>ljava.lang.StringIndexOutOfBoundsException: Range [49, 48) out of bounds for length 77
true
gap> IsExistingFile( "/bin/date.new" ); # non existing `/bin/date.new'
false
gap> IsExistingFile( "/bin/date/new" ); # `/bin/date' is not a directory
false
gap> LastSystemError().message;
"Not a directory"
]]></Example>
<>
</of this file  java.lang.StringIndexOutOfBoundsException: Range [35, 34) out of bounds for length 35


<ManSection>
<Func Name="IsReadableFile" 

java.lang.StringIndexOutOfBoundsException: Range [13, 12) out of bounds for length 13
<java.lang.StringIndexOutOfBoundsException: Range [7, 6) out of bounds for length 76
returns <K>true</K> if   java.lang.StringIndexOutOfBoundsException: Range [16, 15) out of bounds for length 28
<>and<E>the &GAP; process has read permissions for the file,
or <K>false</K> if this is not the case.
<P/>
<Example>that  be open .
gap> ( "bin")      file `/ is 
true
gap> java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 70
false
gap> LastSystemError().message;
"No such file or directory"
]<
</java.lang.StringIndexOutOfBoundsException: Range [76, 10) out of bounds for length 76
</ManSection>


<ManSection>
<Func Name="

<Description>
<Ref Func Name"ogTo" Arg=  java.lang.StringIndexOutOfBoundsException: Range [56, 55) out of bounds for length 58
returns <K>true<
<E><> & java.lang.StringIndexOutOfBoundsException: Range [29, 28) out of bounds for length 64
K/ if java.lang.StringIndexOutOfBoundsException: Range [35, 34) out of bounds for length 40
<A/ java.lang.StringIndexOutOfBoundsException: Range [23, 22) out of bounds for length 74
<Example><![with the name <A>filename</A>,
gap> IsWritableFile( "/bin/date" );  #.e,    java.lang.StringIndexOutOfBoundsException: Range [52, 51) out of bounds for length 72

]]></Example>
<P/>
</Description
</ManSection>


<ManSection>
<previousof   java.lang.StringIndexOutOfBoundsException: Range [45, 44) out of bounds for length 53

<Description>
<Ref Func="IsExecutableFile"/>
returns <K>true</K> if a file with the filename <</escription>
<E>and</E> the &GAP; process has execute permissions for the file,
or
Note
to the , .,  only be  ajava.lang.StringIndexOutOfBoundsException: Index 76 out of bounds for length 76
<P/>
<<[java.lang.StringIndexOutOfBoundsException: Range [18, 17) out of bounds for length 18
java.lang.StringIndexOutOfBoundsException: Range [28, 3) out of bounds for length 60
rue
]]></Example>
</Description>
</ManSection>


<ManSection>
<Func

<Description
<Ref Func="IsDirectoryPath Ref ="" Label="or a ">with  string
returnsKtrue<K>ifthe file  the  A>java.lang.StringIndexOutOfBoundsException: Range [63, 61) out of bounds for length 72
<irectory
java.lang.StringIndexOutOfBoundsException: Range [12, 3) out of bounds for length 27
 function    java.lang.StringIndexOutOfBoundsException: Range [60, 59) out of bounds for length 72
write or execute<Ijava.lang.StringIndexOutOfBoundsException: Range [29, 27) out of bounds for length 57
You <Ref Op=OutputLogTo =for  ">can.
resp <Func=IsExecutableFile"> to check such permissionsjava.lang.StringIndexOutOfBoundsException: Index 63 out of bounds for length 63
</Description>
<ManSection>>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<" "
<Heading>File Operations .

<#Include java.lang.StringIndexOutOfBoundsException: Range [0, 15) out of bounds for length 13
<#Include Label==java.lang.StringIndexOutOfBoundsException: Range [24, 23) out of bounds for length 64

<ManSection>
<Heading
<"java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 50
<uncName"ppendTo"=[  .]>

<Description>
<Ref Func="PrintTo"/> works like <Ref Func="Print"/>,
except that the arguments <<A></A causes  java.lang.StringIndexOutOfBoundsException: Index 30 out of bounds for length 30
standard output.
This file must of course be writable by &GAP;.
 an   .
Note that Ref Oper=O =for afilename/>.
of this file if it already existed;
in particular RefFunc=PrintTo/  just  A<> argument
empties that file.
<P/>
<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/
<P/>java.lang.StringIndexOutOfBoundsException: Range [6, 5) out of bounds for length 40
java.lang.StringIndexOutOfBoundsException: Range [34, 5) out of bounds for length 59
that may be open simultaneously.
<P/>
<that one should be careful not to write to a logfile
(see <Ref Oper="LogTo" Label="for a filename"/>) with
<""><java.lang.StringIndexOutOfBoundsException: Range [30, 29) out of bounds for length 48
<!-- % The same holds of course for the redirection of output to a file. -->
</<java.lang.StringIndexOutOfBoundsException: Range [14, 13) out of bounds for length 14
</ManSection=java.lang.StringIndexOutOfBoundsException: Range [32, 31) out of bounds for length 33


<ManSection>
<Heading>LogTo
<Oper Name
<Oper Name="<java.lang.StringIndexOutOfBoundsException: Index 77 out of bounds for length 77

<Description>
Calling <Ref Oper="LogTo" Label="for a filename"/> with a string
<A>filename</A> causes the subsequent interaction to be logged to the file
with the name <A>filename</A>,
i.e., everything you see on your terminal will also appear in this file.
(<Ref Oper="LogTo" Label="for streams"/> may also be used to log to a stream.)
This file must of course be writable by &GAP;, otherwise an error is
signalled.
Note that <Ref Oper="LogTo" Label="for a filename"/> will overwrite the
previous contents of this file if it already existed.
<P/>
Called without arguments,
<Ref Oper="LogTo" Label="stop logging"/> stops logging to a file or stream.
</Description>
</ManSection>


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

<Description>
Calling <Ref Oper="InputLogTo" Label="for a filename"/> with a string
<A>filename</A> causes the subsequent input to be logged to the file
with the name <A>filename</A>,
i.e., everything you type on your terminal will also appear in this file.
Note that <Ref Oper="InputLogTo" Label="for a filename"/> and
<Ref Oper="LogTo" Label="for a filename"/> cannot be used at the same time
while <Ref Oper="InputLogTo" Label="for a filename"/> and
<Ref Oper="OutputLogTo" Label="for a filename"/> can.
Note that <Ref Oper="InputLogTo" Label="for a filename"/> will overwrite the
previous contents of this file if it already existed.
<P/>
Called without arguments,
<Ref Oper="InputLogTo" Label="stop logging input"/> stops logging to a file
or stream.
</Description>
</ManSection>


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

<Description>
Calling <Ref Oper="OutputLogTo" Label="for a filename"/> with a string
<A>filename</A> causes the subsequent 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 used at the same time
while <Ref Oper="InputLogTo" Label="for a filename"/> and
<Ref Oper="OutputLogTo" Label="for a filename"/> can.
Note that <Ref Oper="OutputLogTo" Label="for a filename"/> will overwrite the
previous contents of this file if it already existed.
<P/>
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 filename <A>filename</A> and returns <K>true</K> in case
of  success.  The function returns <K>fail</K> if a system error occurred, for
example, if your permissions do not allow the removal of <A>filename</A>.
In this case the function <Ref Func="LastSystemError"/>
can be used to get information about the error.
</Description>
</ManSection>

<#Include Label="UserHomeExpand">

<#Include Label="Reread">

</Section>
</Chapter>


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