This file is indexed.

/usr/share/gap/doc/ref/chap3.html is in gap-doc 4r7p5-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (ref) - Chapter 3: Running GAP</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap3"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap2.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap4.html">[Next Chapter]</a>&nbsp;  </div>

<p id="mathjaxlink" class="pcenter"><a href="chap3_mj.html">[MathJax on]</a></p>
<p><a id="X79CCD3A6821E5A37" name="X79CCD3A6821E5A37"></a></p>
<div class="ChapSects"><a href="chap3.html#X79CCD3A6821E5A37">3 <span class="Heading">Running GAP</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap3.html#X782751D5858A6EAF">3.1 <span class="Heading">Command Line Options</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap3.html#X7FD66F977A3B02DF">3.2 <span class="Heading">The gap.ini and gaprc files</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X87DF11C885E73583">3.2-1 <span class="Heading">The gap.ini file</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X84D4CF587D437C00">3.2-2 <span class="Heading">The gaprc file</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X7B0AD104839B6C3C">3.2-3 <span class="Heading">Configuring User preferences</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X7F1DF6757B248014">3.2-4 DeclareUserPreference</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap3.html#X7CB282757ACB1C09">3.3 <span class="Heading">Saving and Loading a Workspace</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X876544A57C73C488">3.3-1 SaveWorkspace</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap3.html#X83BF07587F2CC6CD">3.4 <span class="Heading">Testing for the System Architecture</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X7C825AF087A27884">3.4-1 ARCH_IS_UNIX</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X82A6893A7EC8FA72">3.4-2 ARCH_IS_MAC_OS_X</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X7A14B659847B8627">3.4-3 ARCH_IS_WINDOWS</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap3.html#X7F1E823886F3681B">3.5 <span class="Heading">Global Values that Control the <strong class="pkg">GAP</strong> Session</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X8354754E7935F935">3.5-1 GAPInfo</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap3.html#X818F2DDC863C381E">3.6 <span class="Heading">Coloring the Prompt and Input</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap3.html#X84F3481C8466C7FC">3.6-1 ColorPrompt</a></span>
</div></div>
</div>

<h3>3 <span class="Heading">Running GAP</span></h3>

<p>This chapter informs about command line options for <strong class="pkg">GAP</strong> (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>), some files in user specific <strong class="pkg">GAP</strong> root directory (see <a href="chap3.html#X7FD66F977A3B02DF"><span class="RefLink">3.2</span></a>) and saving and loading a <strong class="pkg">GAP</strong> workspace (see <a href="chap3.html#X7CB282757ACB1C09"><span class="RefLink">3.3</span></a>).</p>

<p><a id="X782751D5858A6EAF" name="X782751D5858A6EAF"></a></p>

<h4>3.1 <span class="Heading">Command Line Options</span></h4>

<p>When you start <strong class="pkg">GAP</strong> from a command line or from a script you may specify a number of options on the command-line to change the default behaviour of <strong class="pkg">GAP</strong>. All these options start with a hyphen <code class="code">-</code>, followed by a single letter. Options must not be grouped, e.g., <code class="code">gap -gq</code> is invalid, use <code class="code">gap -g -q</code> instead. Some options require an argument, this must follow the option and must be separated by whitespace, e.g., <code class="code">gap -m 256m</code>, it is not correct to say <code class="code">gap -m256m</code> instead. Certain Boolean options (<code class="code">-b</code>, <code class="code">-q</code>, <code class="code">-e</code>, <code class="code">-r</code>, <code class="code">-A</code>, <code class="code">-D</code>, <code class="code">-M</code>, <code class="code">-T</code>, <code class="code">-X</code>, <code class="code">-Y</code>) toggle the current value so that <code class="code">gap -b -b</code> is equivalent to <code class="code">gap</code> and to <code class="code">gap -b -q -b -q</code> etc.</p>

<p><strong class="pkg">GAP</strong> for UNIX will distinguish between upper and lower case options.</p>

<p>As described in the <strong class="pkg">GAP</strong> installation instructions (see the <code class="file">INSTALL</code> file in the <strong class="pkg">GAP</strong> root directory, or at <span class="URL"><a href="http://www.gap-system.org/Download/INSTALL">http://www.gap-system.org/Download/INSTALL</a></span>), usually you will not execute <strong class="pkg">GAP</strong> directly. Instead you will call a (shell) script, with the name <code class="code">gap</code>, which in turn executes <strong class="pkg">GAP</strong>. This script sets some options which are necessary to make <strong class="pkg">GAP</strong> work on your system. This means that the default settings mentioned below may not be what you experience when you execute <strong class="pkg">GAP</strong> on your system.</p>

<p>During a <strong class="pkg">GAP</strong> session, one can find the current values of command line options in the record <code class="code">GAPInfo.CommandLineOptions</code> (see <code class="func">GAPInfo</code> (<a href="chap3.html#X8354754E7935F935"><span class="RefLink">3.5-1</span></a>)), whose component names are the command line options (without the leading <code class="code">-</code>).</p>


<dl>
<dt><strong class="Mark">
<code class="code">-A</code></strong></dt>
<dd><p>By default, some needed and suggested <strong class="pkg">GAP</strong> packages (see <a href="chap76.html#X7B6CD527825945CD"><span class="RefLink">76</span></a>) are loaded, if present, into the <strong class="pkg">GAP</strong> session when it starts. This option disables (actually toggles) the loading of suggested packages, which can be useful for debugging or testing. The needed packages (and their needed packages, and so on) are loaded in any case.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-a </code><var class="Arg">memory</var></strong></dt>
<dd><p>GASMAN, the storage manager of <strong class="pkg">GAP</strong> uses <code class="code">sbrk</code> to get blocks of memory from (certain) operating systems and it is required that subsequent calls to <code class="code">sbrk</code> produce adjacent blocks of memory in this case because <strong class="pkg">GAP</strong> only wants to deal with one large block of memory. If the C function <code class="code">malloc</code> is called for whatever reason, it is likely that <code class="code">sbrk</code> will no longer produce adjacent blocks, therefore <strong class="pkg">GAP</strong> does not use <code class="code">malloc</code> itself.</p>

<p>However some operating systems insist on calling <code class="code">malloc</code> to create a buffer when a file is opened, or for some other reason. In order to catch these cases <strong class="pkg">GAP</strong> preallocates a block of memory with <code class="code">malloc</code> which is immediately freed. The amount preallocated can be controlled with the <code class="code">-a</code> option. (Most users do not need this option.)</p>

<p>The option argument <var class="Arg">memory</var> is specified as with the <code class="code">-m</code> option.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-B </code><var class="Arg">architecture</var></strong></dt>
<dd><p>Executable binary files that form part of <strong class="pkg">GAP</strong> or of a <strong class="pkg">GAP</strong> package are kept in a subdirectory of the <code class="file">bin</code> directory within the <strong class="pkg">GAP</strong> or package root directory. The subdirectory name is determined from the operating system, processor and compiler details when <strong class="pkg">GAP</strong> (resp. the package) is installed. Under rare circumstances, it may be necessary to override this name, and this can be done using the <code class="code">-B</code> option.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-b</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to suppress the banner. That means that <strong class="pkg">GAP</strong> immediately prints the prompt. This is useful when, after a while, you get tired of the banner. This option can be repeated to enable the banner; each <code class="code">-b</code> toggles the state of banner display.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-D</code></strong></dt>
<dd><p>The <code class="code">-D</code> option tells <strong class="pkg">GAP</strong> to print short messages when it is reading files or loading modules. This option may be repeated to toggle this behavior on and off. The message,</p>


<div class="example"><pre>
#I  READ_GAP_ROOT: loading 'lib/kernel.g' as GAP file
</pre></div>

<p>tells you that <strong class="pkg">GAP</strong> has started to read the library file <code class="file">lib/kernel.g</code>.</p>


<div class="example"><pre>
#I  READ_GAP_ROOT: loading 'lib/kernel.g' statically
</pre></div>

<p>tells you that <strong class="pkg">GAP</strong> has used the compiled version of the library file <code class="file">lib/kernel.g</code>. This compiled module was statically linked to the <strong class="pkg">GAP</strong> kernel at the time the kernel was created.</p>


<div class="example"><pre>
#I  READ_GAP_ROOT: loading 'lib/kernel.g' dynamically
</pre></div>

<p>tells you that <strong class="pkg">GAP</strong> has loaded the compiled version of the library file <code class="file">lib/kernel.g</code>. This compiled module was dynamically loaded to the <strong class="pkg">GAP</strong> kernel at runtime from a corresponding <code class="code">.so</code> file.</p>

<p>Obviously, this is a debugging option and most users will not need it.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-E</code></strong></dt>
<dd><p>If your <strong class="pkg">GAP</strong> installation uses the <code class="code">readline</code> library for command line editing (see <a href="chap6.html#X7E95EB017803F53C"><span class="RefLink">6.9</span></a>), this may be disabled by using <code class="code">-E</code> option. This option may be repeated to toggle this behavior on and off. If your <strong class="pkg">GAP</strong> installation does not use the <code class="code">readline</code> library (you can check by <code class="code">IsBound(GAPInfo.UseReadline);</code> if this is the case), this option will have no effect at all.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-e</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> not to quit when receiving a <strong class="button">Ctrl-D</strong> on an empty input line (see <a href="chap6.html#X83033EEB81CF4F49"><span class="RefLink">6.4-1</span></a>). This option should not be used when the input is a file or pipe. This option may be repeated to toggle this behavior on and off.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-f</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to enable the line editing and history (see <a href="chap6.html#X82234FD181899530"><span class="RefLink">6.8</span></a>).</p>

<p>In general line editing will be enabled if the input is connected to a terminal. There are rare circumstances, for example when using a remote session with a corrupted telnet implementation, when this detection fails. Try using <code class="code">-f</code> in this case to enable line editing. This option does not toggle; you must use <code class="code">-n</code> to disable line editing.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-g</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to print a message every time a full garbage collection is performed.</p>


<div class="example"><pre>
#G  FULL 44580/2479kb live   57304/4392kb dead   734/4096kb free
</pre></div>

<p>For example, this tells you that there are 44580 live objects that survived a full garbage collection, that 57304 unused objects were reclaimed by it, and that 734 kilobytes from a total allocated memory of 4096 kilobytes are available afterwards.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-g -g</code></strong></dt>
<dd><p>If you give the option <code class="code">-g</code> twice, <strong class="pkg">GAP</strong> prints a information message every time a partial or full garbage collection is performed. The message,</p>


<div class="example"><pre>
#G  PART 9405/961kb+live   7525/1324kb+dead   2541/4096kb free
</pre></div>

<p>for example, tells you that 9405 objects survived the partial garbage collection and 7525 objects were reclaimed, and that 2541 kilobytes from a total allocated memory of 4096 kilobytes are available afterwards.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-h</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to print a summary of all available options (<code class="code">-h</code> is mnemonic for "help"). <strong class="pkg">GAP</strong> exits after printing the summary, all other options are ignored.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-i </code><var class="Arg">filename</var></strong></dt>
<dd><p>changes the name of the init file from the default <code class="file">init.g</code> to <var class="Arg">filename</var>. (Usually not needed.)</p>

</dd>
<dt><strong class="Mark"> 
<code class="code">-K </code><var class="Arg">memory</var></strong></dt>
<dd><p>is like the <code class="code">-o</code> option. But while the latter actually allocates more memory if the system allows it and then prints a warning inside a break loop the <code class="code">-K</code> options tells <strong class="pkg">GAP</strong> not even to try to allocate more memory. Instead <strong class="pkg">GAP</strong> just exits with an appropriate message. The default is that this feature is switched off. You have to set it explicitly when you want to enable it.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-L </code><var class="Arg">filename</var></strong></dt>
<dd><p>The option <code class="code">-L</code> tells <strong class="pkg">GAP</strong> to load a saved workspace. See section <a href="chap3.html#X7CB282757ACB1C09"><span class="RefLink">3.3</span></a>.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-l </code><var class="Arg">path_list</var></strong></dt>
<dd><p>can be used to set or modify <strong class="pkg">GAP</strong>'s list of root directories (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). The default if no <code class="code">-l </code> option is given is the current directory <code class="file">./</code>. This option can be used several times. Depending on the <code class="code">-r</code> option a further user specific path is prepended to the list of root directories (the path in <code class="code">GAPInfo.UserGapRoot</code>).</p>

<p><var class="Arg">path_list</var> should be a list of directories separated by semicolons. No whitespace is permitted before or after a semicolon. If <var class="Arg">path_list</var> does not start or end with a semicolon, then <var class="Arg">path_list</var> replaces the existing list of root directories. If <var class="Arg">path_list</var> starts with a semicolon, then <var class="Arg">path_list</var> is appended to the existing list of root directories. If <var class="Arg">path_list</var> ends with a semicolon and does not start with one, then the new list of root directories is the concatenation of <var class="Arg">path_list</var> and the existing list of root directories. After <strong class="pkg">GAP</strong> has completed its startup procedure and displays the prompt, the list of root directories can be seen in the variable <code class="code">GAPInfo.RootPaths</code>, see <code class="func">GAPInfo</code> (<a href="chap3.html#X8354754E7935F935"><span class="RefLink">3.5-1</span></a>).</p>

<p>Usually this option is used inside a startup script to specify where <strong class="pkg">GAP</strong> is installed on the system. The <code class="code">-l</code> option can also be used by individual users to tell <strong class="pkg">GAP</strong> about privately installed modifications of the library, additional <strong class="pkg">GAP</strong> packages and so on. Section <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a> explains how several root paths can be used to do this.</p>

<p><strong class="pkg">GAP</strong> will attempt to read the file <var class="Arg">root_dir</var><code class="file">/lib/init.g</code> during startup where <var class="Arg">root_dir</var> is one of the directories in its list of root directories. If <strong class="pkg">GAP</strong> cannot find its <code class="file">init.g</code> file it will print the following warning.</p>


<div class="example"><pre>
gap: hmm, I cannot find 'lib/init.g' maybe use option '-l &lt;gaproot&gt;'?
</pre></div>

<p>It is not possible to use <strong class="pkg">GAP</strong> without the library files, so you must not ignore this warning. You should leave <strong class="pkg">GAP</strong> and start it again, specifying the correct root path using the <code class="code">-l</code> option.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-M</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> not to check for, nor to use, compiled versions of library files. This option may be repeated to toggle this behavior on and off.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-m </code><var class="Arg">memory</var></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to allocate <var class="Arg">memory</var> bytes at startup time. If the last character of <var class="Arg">memory</var> is <code class="code">k</code> or <code class="code">K</code> it is taken as kilobytes, if the last character is <code class="code">m</code> or <code class="code">M</code> <var class="Arg">memory</var> is taken as megabytes and if it is <code class="code">g</code> or <code class="code">G</code> it is taken as gigabytes.</p>

<p>This amount of memory should be large enough so that computations do not require too many garbage collections. On the other hand, if <strong class="pkg">GAP</strong> allocates more memory than is physically available, it will spend most of the time paging.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-n</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to disable the line editing and history (see <a href="chap6.html#X82234FD181899530"><span class="RefLink">6.8</span></a>).</p>

<p>You may want to do this if the command line editing is incompatible with another program that is used to run <strong class="pkg">GAP</strong>. For example if <strong class="pkg">GAP</strong> is run from inside a GNU Emacs shell window, <code class="code">-n</code> should be used since otherwise every input line will be echoed twice, once by Emacs and once by <strong class="pkg">GAP</strong>. This option does not toggle; you must use <code class="code">-f</code> to enable line editing.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-O</code></strong></dt>
<dd><p>disables loading obsolete variables (see Chapter <a href="chap77.html#X78C85ED17F00DCC1"><span class="RefLink">77</span></a>). This option is used mainly for testing purposes, for example in order to make sure that a <strong class="pkg">GAP</strong> package or one's own <strong class="pkg">GAP</strong> code does not rely on the obsolete variables.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-o </code><var class="Arg">memory</var></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to allocate at most <var class="Arg">memory</var> bytes without asking. The option argument <var class="Arg">memory</var> is specified as with the <code class="code">-m</code> option.</p>

<p>If more than this amount is required during the <strong class="pkg">GAP</strong> session, <strong class="pkg">GAP</strong> prints an error message and enters a break loop. In that case you can enter <code class="code">return;</code> which implicitly doubles the amount given with this option.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-q</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to be quiet. This means that <strong class="pkg">GAP</strong> displays neither the banner nor the prompt <code class="code">gap&gt;</code>. This is useful if you want to run <strong class="pkg">GAP</strong> as a filter with input and output redirection and want to avoid the banner and the prompts appearing in the output file. This option may be repeated to disable quiet mode; each <code class="code">-q</code> toggles quiet mode.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-R</code></strong></dt>
<dd><p>The option <code class="code">-R</code> tells <strong class="pkg">GAP</strong> not to load a saved workspace previously specified via the <code class="code">-L</code> option. This option does not toggle.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-r</code></strong></dt>
<dd><p>The option <code class="code">-r</code> tells <strong class="pkg">GAP</strong> to ignore any user specific configuration files. In particular, the user specific root directory <code class="code">GAPInfo.UserGapRoot</code> is not added to the <strong class="pkg">GAP</strong> root directories and so <code class="file">gap.ini</code> and <code class="file">gaprc</code> files that may be contained in that directory are not read, see <a href="chap3.html#X7FD66F977A3B02DF"><span class="RefLink">3.2</span></a>. Multiple <code class="code">-r</code> options toggle this behaviour.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-s </code><var class="Arg">memory</var></strong></dt>
<dd><p>With this option <strong class="pkg">GAP</strong> does not use <code class="code">sbrk</code> to get memory from the operating system. Instead it uses <code class="code">mmap</code>, <code class="code">malloc</code> or some other command for the amount given with this option to allocate space for the <code class="code">GASMAN</code> memory manager. Usually <strong class="pkg">GAP</strong> does not really use all of this memory, the options <code class="code">-m</code>, <code class="code">-o</code>, <code class="code">-K</code> still work as documented. This feature assumes that the operating system only assigns physical memory to the <strong class="pkg">GAP</strong> process when it is accessed, so that specifying a large amount of memory with <code class="code">-s</code> should not cause any performance problem. The advantage of using this option is that <strong class="pkg">GAP</strong> can work together with kernel modules which allocate a lot of memory with <code class="code">malloc</code>.</p>

<p>The option argument <var class="Arg">memory</var> is specified as with the <code class="code">-m</code> option.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-T</code></strong></dt>
<dd><p>suppresses the usual break loop behaviour of <strong class="pkg">GAP</strong>. With this option <strong class="pkg">GAP</strong> behaves as if the user <code class="keyw">quit</code> immediately from every break loop. This is intended for automated testing of <strong class="pkg">GAP</strong>. This option may be repeated to toggle this behavior on and off.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-X</code></strong></dt>
<dd><p>tells <strong class="pkg">GAP</strong> to do a consistency check of the library file and the corresponding compiled module when loading the compiled module. This option may be repeated to toggle this behavior on and off.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-x </code><var class="Arg">length</var></strong></dt>
<dd><p>With this option you can tell <strong class="pkg">GAP</strong> how long lines are. <strong class="pkg">GAP</strong> uses this value to decide when to split long lines. After starting <strong class="pkg">GAP</strong> you may use <code class="func">SizeScreen</code> (<a href="chap6.html#X8723E0A1837894F3"><span class="RefLink">6.12-1</span></a>) to alter the line length.</p>

<p>The default value is 80, unless another value can be obtained from the Operating System, which is the right value if you have a standard terminal application. If you have a larger monitor, or use a smaller font, or redirect the output to a printer, you may want to increase this value.</p>

</dd>
<dt><strong class="Mark">
<code class="code">-y </code><var class="Arg">length</var></strong></dt>
<dd><p>With this option you can tell <strong class="pkg">GAP</strong> how many lines your screen has. <strong class="pkg">GAP</strong> uses this value to decide after how many lines of on-line help it should wait. After starting <strong class="pkg">GAP</strong> you may use <code class="func">SizeScreen</code> (<a href="chap6.html#X8723E0A1837894F3"><span class="RefLink">6.12-1</span></a>) to alter the number of lines.</p>

<p>The default value is 24, unless another value can be obtained from the Operating System, which is the right value if you have a standard terminal application. If you have a larger monitor, or use a smaller font, or redirect the output to a printer, you may want to increase this value.</p>

</dd>
<dt><strong class="Mark">
<var class="Arg">filename</var> ...</strong></dt>
<dd><p>Further arguments are taken as filenames of files that are read by <strong class="pkg">GAP</strong> during startup, after the system and private init files are read, but before the first prompt is printed. The files are read in the order in which they appear on the command line. <strong class="pkg">GAP</strong> only accepts up to 14 filenames on the command line. If a file cannot be opened <strong class="pkg">GAP</strong> will print an error message and will abort.</p>

</dd>
</dl>
<p>Additional options, <code class="code">-C</code>, <code class="code">-U</code>, <code class="code">-P</code>, <code class="code">-W</code>, <code class="code">-p</code> and <code class="code">-z</code> are used internally by the <strong class="pkg">gac</strong> script (see <a href="chap76.html#X79EF67107E40A130"><span class="RefLink">76.3-9</span></a>) and/or on specific operating systems.</p>

<p><a id="X7FD66F977A3B02DF" name="X7FD66F977A3B02DF"></a></p>

<h4>3.2 <span class="Heading">The gap.ini and gaprc files</span></h4>

<p>When you start <strong class="pkg">GAP</strong>, it looks for files with the names <code class="file">gap.ini</code> and <code class="file">gaprc</code> in its root directories (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>), and reads the first <code class="file">gap.ini</code> and the first <code class="file">gaprc</code> file it finds. These files are used for certain initializations, as follows.</p>

<p>The file <code class="file">gap.ini</code> is read early in the startup process. Therefore, the parameters set in this file can influence the startup process, such as which packages are automatically loaded (see <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>)) and whether library files containing obsolete variables are read (see Chapter <a href="chap77.html#X78C85ED17F00DCC1"><span class="RefLink">77</span></a>). On the other hand, only calls to a restricted set of <strong class="pkg">GAP</strong> functions are allowed in a <code class="file">gap.ini</code> file. Usually, it should only contain calls of <code class="func">SetUserPreference</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>). This file can be generated (or updated when new releases introduce further user preferences) with the command <code class="func">WriteGapIniFile</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>). This file is read whenever <strong class="pkg">GAP</strong> is started, with or without a workspace.</p>

<p>The file <code class="file">gaprc</code> is read after the startup process, before the first input file given on the command line (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>). So the contents of this file cannot influence the startup process, but all <strong class="pkg">GAP</strong> library functions can be called in this file. When <strong class="pkg">GAP</strong> is started with a workspace then the file is read only if no <code class="file">gaprc</code> file had been read before the workspace was created. (With this setup, it is on the one hand possible that administrators provide a <strong class="pkg">GAP</strong> workspace for several users such that the user's <code class="file">gaprc</code> file is read when <strong class="pkg">GAP</strong> is started with the workspace, and on the other hand one can start <strong class="pkg">GAP</strong>, read one's <code class="file">gaprc</code> file, save a workspace, and then start from this workspace <em>without</em> reading one's <code class="file">gaprc</code> file again.)</p>

<p>Note that by default, the user specific <strong class="pkg">GAP</strong> root directory <code class="code">GAPInfo.UserGapRoot</code> is the first <strong class="pkg">GAP</strong> root directory. So you can put your <code class="file">gap.ini</code> and <code class="file">gaprc</code> files into this directory.</p>

<p>This mechanism substitutes the much less flexible reading of a users <code class="file">.gaprc</code> file in versions of <strong class="pkg">GAP</strong> up to 4.4. For compatibility this <code class="file">.gaprc</code> file is still read if the directory <code class="code">GAPInfo.UserGapRoot</code> does not exist, see <a href="chap77.html#X7F2FF72A7AD60E0C"><span class="RefLink">77.5</span></a> how to migrate your old setup.</p>

<p><a id="X87DF11C885E73583" name="X87DF11C885E73583"></a></p>

<h5>3.2-1 <span class="Heading">The gap.ini file</span></h5>

<p>The file <code class="file">gap.ini</code> is read after the declaration part of the <strong class="pkg">GAP</strong> library is read, before the declaration parts of the packages needed and suggested by <strong class="pkg">GAP</strong> are read, and before the implementation parts of <strong class="pkg">GAP</strong> and of the packages are read.</p>

<p>The file <code class="file">gap.ini</code> is expected to consist of calls to the function <code class="func">SetUserPreference</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>), see Section <code class="func">SetUserPreference</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>).</p>

<p>Since the file <code class="file">gap.ini</code> is read before the implementation part of <strong class="pkg">GAP</strong> is read, not all <strong class="pkg">GAP</strong> functions may be called in the file. Assignments of numbers, lists, and records are admissible as well as calls to basic functions such as <code class="func">Concatenation</code> (<a href="chap21.html#X840C55A77D1BB2E1"><span class="RefLink">21.20-1</span></a>) and <code class="func">JoinStringsWithSeparator</code> (<a href="chap27.html#X84624FEB825EC4B5"><span class="RefLink">27.6-17</span></a>).</p>

<p>Note that the file <code class="file">gap.ini</code> is read also when <strong class="pkg">GAP</strong> is started with a workspace.</p>

<p><a id="X84D4CF587D437C00" name="X84D4CF587D437C00"></a></p>

<h5>3.2-2 <span class="Heading">The gaprc file</span></h5>

<p>If a file <code class="file">gaprc</code> is found it is read after <strong class="pkg">GAP</strong>'s <code class="file">init.g</code>, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. (Many users may be happy with using just user preferences in the <code class="file">gap.ini</code> file (see above) for private customization.) For example, if you have a file containing functions or data that you always need, you could read this from <code class="file">gaprc</code>. Or if you find some of the names in the library too long, you could define abbreviations for those names in <code class="file">gaprc</code>. The following sample <code class="file">gaprc</code> file does both.</p>


<div class="example"><pre>
Read( "/usr/you/dat/mygroups.grp" );
Ac := Action;
AcHom := ActionHomomorphism;
RepAc := RepresentativeAction;
</pre></div>

<p>Note that only one <code class="file">gaprc</code> file is read when <strong class="pkg">GAP</strong> is started. When a workspace is created in a <strong class="pkg">GAP</strong> session after a <code class="file">gaprc</code> file has been read then no more <code class="file">gaprc</code> file will be read when <strong class="pkg">GAP</strong> is started with this workspace.</p>

<p>Also note that the file must be called <code class="file">gaprc</code>. If you use a Windows text editor, in particular if your default is not to show file suffixes, you might accidentally create a file <code class="file">gaprc.txt</code> or <code class="file">gaprc.doc</code> which GAP will not recognize.</p>

<p><a id="X7B0AD104839B6C3C" name="X7B0AD104839B6C3C"></a></p>

<h5>3.2-3 <span class="Heading">Configuring User preferences</span></h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SetUserPreference</code>( [<var class="Arg">package</var>, ]<var class="Arg">name</var>, <var class="Arg">value</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; UserPreference</code>( [<var class="Arg">package</var>, ]<var class="Arg">name</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ShowUserPreferences</code>( <var class="Arg">package1</var>, <var class="Arg">package2</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; WriteGapIniFile</code>( [<var class="Arg">dir</var>, ][<var class="Arg">ignorecurrent</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Some aspects of the behaviour of <strong class="pkg">GAP</strong> can be customized by the user via <em>user preferences</em>. Examples include the way help sections are displayed or the use of colors in the terminal.</p>

<p>User preferences are specified via a pair of strings, the first is the (case insensitive) name of a package (or <code class="code">"GAP"</code> for the core <strong class="pkg">GAP</strong> library) and the second is some arbitrary case sensitive string.</p>

<p>User preferences can be set to some <var class="Arg">value</var> with <code class="func">SetUserPreference</code>. The current value of a user preference can be found with <code class="func">UserPreference</code>. In both cases, if no package name is given the default <code class="code">"GAP"</code> is used. If a user preference is not known or not set then <code class="func">UserPreference</code> returns <code class="keyw">fail</code>.</p>

<p>The function <code class="func">ShowUserPreferences</code> with no argument shows in a pager an overview of all known user preferences together with some explanation and the current value. If one or more strings <var class="Arg">package1</var>, ... are given then only the user preferences for these packages are shown.</p>

<p>The easiest way to make use of user preferences is probably to use the function <code class="func">WriteGapIniFile</code>, usually without argument. This function creates a file <code class="file">gap.ini</code> in your user specific <strong class="pkg">GAP</strong> root directory (<code class="code">GAPInfo.UserGapRoot</code>). If such a file already exists the function will make a backup of it first. This newly created file contains descriptions of all known user preferences and also calls of <code class="func">SetUserPreference</code> for those user preferences which currently do not have their default value. You can then edit that file to customize (further) the user preferences for future <strong class="pkg">GAP</strong> sessions.</p>

<p>Should a later version of <strong class="pkg">GAP</strong> or some packages introduce new user preferences then you can call <code class="func">WriteGapIniFile</code> again since it will set the previously known user preferences to their current values.</p>

<p>Optionally, a different directory for the resulting <code class="file">gap.ini</code> file can be specified as argument <var class="Arg">dir</var> to <code class="func">WriteGapIniFile</code>. Another optional argument is the boolean value <code class="keyw">true</code>, if this is given, the settings of all user preferences in the current session are ignored.</p>

<p>Note that your <code class="file">gap.ini</code> file is read by <strong class="pkg">GAP</strong> very early during its startup process. A consequence is that the <var class="Arg">value</var> argument in a call of <code class="func">SetUserPreference</code> must be some very basic <strong class="pkg">GAP</strong> object, usually a boolean, a number, a string or a list of those. A few user preferences support more complicated settings. For example, the user preference <code class="code">"UseColorPrompt"</code> admits a record as its value whose components are available only after the <strong class="pkg">GAPDoc</strong> package has been loaded, see <code class="func">ColorPrompt</code> (<a href="chap3.html#X84F3481C8466C7FC"><span class="RefLink">3.6-1</span></a>). If you want to specify such a complicated value, then move the corresponding call of <code class="func">SetUserPreference</code> from your <code class="file">gap.ini</code> file into your <code class="file">gaprc</code> file (also in the directory <code class="code">GAPInfo.UserGapRoot</code>). This file is read much later.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetUserPreference( "Pager", "less" );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetUserPreference("PagerOptions",</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">                     [ "-f", "-r", "-a", "-i", "-M", "-j2" ] );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">UserPreference("Pager");</span>
"less"
</pre></div>

<p>The first two lines of this example will cause <strong class="pkg">GAP</strong> to use the programm <code class="code">less</code> as a pager. This is highly recommended if <code class="code">less</code> is available on your system. The last line displays the current setting.</p>

<p><a id="X7F1DF6757B248014" name="X7F1DF6757B248014"></a></p>

<h5>3.2-4 DeclareUserPreference</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DeclareUserPreference</code>( <var class="Arg">record</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function can be used (also in packages) to introduce new user preferences. It declares a user preference, determines a default value and contains documentation of the user preference. After declaration a user preference will be shown with <code class="func">ShowUserPreferences</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>) and <code class="func">WriteGapIniFile</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>).</p>

<p>When this declaration is evaluated it is checked, if this user preference is already set in the current session. If not the value of the user preference is set to its default. (Do not use <code class="keyw">fail</code> as default value since this indicated that a user preference is not set.)</p>

<p>The argument <var class="Arg">record</var> of <code class="func">DeclareUserPreference</code> must be a record with the following components.</p>


<dl>
<dt><strong class="Mark"><code class="code">name</code></strong></dt>
<dd><p>a string or a list of strings, the latter meaning several preferences which belong together,</p>

</dd>
<dt><strong class="Mark"><code class="code">description</code></strong></dt>
<dd><p>a list of strings describing the preference(s), one string for each paragraph; if several preferences are declared together then the description refers to all of them,</p>

</dd>
<dt><strong class="Mark"><code class="code">default</code></strong></dt>
<dd><p>the default value that is used, or a function without arguments that computes this default value; if several preferences are declared together then the value of this component must be the list of default values for the individual preferences.</p>

</dd>
</dl>
<p>The following components of <var class="Arg">record</var> are optional.</p>


<dl>
<dt><strong class="Mark"><code class="code">check</code></strong></dt>
<dd><p>a function that takes a value as its argument and returns either <code class="keyw">true</code> or <code class="keyw">false</code>, depending on whether the given value is admissible for this preference; if several preferences are declared together then the number of arguments of the function must equal the length of the <code class="code">name</code> list,</p>

</dd>
<dt><strong class="Mark"><code class="code">values</code></strong></dt>
<dd><p>the list of admissible values, or a function without arguments that returns this list,</p>

</dd>
<dt><strong class="Mark"><code class="code">multi</code></strong></dt>
<dd><p><code class="keyw">true</code> or <code class="keyw">false</code>, depending on whether one may choose several values from the given list or just one; needed (and useful only) if the <code class="code">values</code> component is present,</p>

</dd>
<dt><strong class="Mark"><code class="code">package</code></strong></dt>
<dd><p>the name of the <strong class="pkg">GAP</strong> package to which the preference is assigned; if the declaration happens inside a file that belongs to this package then the value of this component is computed, using <code class="code">GAPInfo.PackageCurrent</code>; otherwise, the default value for <code class="code">package</code> is <code class="code">"GAP"</code>,</p>

</dd>
<dt><strong class="Mark"><code class="code">omitFromGapIniFile</code></strong></dt>
<dd><p>if the value is <code class="keyw">true</code> then this user preference is ignored by <code class="func">WriteGapIniFile</code> (<a href="chap3.html#X7B0AD104839B6C3C"><span class="RefLink">3.2-3</span></a>).</p>

</dd>
</dl>

<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">UserPreference( "MyFavouritePrime" );</span>
fail
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DeclareUserPreference( rec(</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       name:= "MyFavouritePrime",</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       description:= [ "is not used, serves as an example" ],</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       default:= 2,</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       omitFromGapIniFile:= true ) );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">UserPreference( "MyFavouritePrime" );</span>
2
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetUserPreference( "MyFavouritePrime", 17 );</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">UserPreference( "MyFavouritePrime" );</span>
17
</pre></div>

<p><a id="X7CB282757ACB1C09" name="X7CB282757ACB1C09"></a></p>

<h4>3.3 <span class="Heading">Saving and Loading a Workspace</span></h4>

<p><strong class="pkg">GAP</strong> workspace files are binary files that contain the data of a <strong class="pkg">GAP</strong> session. One can produce a workspace file with <code class="func">SaveWorkspace</code> (<a href="chap3.html#X876544A57C73C488"><span class="RefLink">3.3-1</span></a>), and load it into a new <strong class="pkg">GAP</strong> session using the <code class="code">-L</code> command line option, see Section <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>.</p>

<p>One purpose of workspace files is of course the possibility to save a "snapshot" image of the current <strong class="pkg">GAP</strong> workspace in a file.</p>

<p>The recommended way to start <strong class="pkg">GAP</strong> is to load an existing workspace file, because this reduces the startup time of <strong class="pkg">GAP</strong> drastically. So if you have installed <strong class="pkg">GAP</strong> yourself then you should think about creating a workspace file immediately after you have started <strong class="pkg">GAP</strong>, and then using this workspace file later on, whenever you start <strong class="pkg">GAP</strong>. If your <strong class="pkg">GAP</strong> installation is shared between several users, the system administrator should think about providing such a workspace file.</p>

<p><a id="X876544A57C73C488" name="X876544A57C73C488"></a></p>

<h5>3.3-1 SaveWorkspace</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SaveWorkspace</code>( <var class="Arg">filename</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>will save a "snapshot" image of the current <strong class="pkg">GAP</strong> workspace in the file <var class="Arg">filename</var>. This image then can be loaded by another copy of <strong class="pkg">GAP</strong> which then will behave as at the point when <code class="func">SaveWorkspace</code> was called.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">a:=1;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SaveWorkspace("savefile");</span>
true
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">quit;</span>
</pre></div>

<p><code class="func">SaveWorkspace</code> can only be used at the main <code class="code">gap&gt;</code> prompt. It cannot be included in the body of a loop or function, or called from a break loop.</p>

<p><a id="X83BF07587F2CC6CD" name="X83BF07587F2CC6CD"></a></p>

<h4>3.4 <span class="Heading">Testing for the System Architecture</span></h4>

<p><a id="X7C825AF087A27884" name="X7C825AF087A27884"></a></p>

<h5>3.4-1 ARCH_IS_UNIX</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ARCH_IS_UNIX</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>tests whether <strong class="pkg">GAP</strong> is running on a UNIX system (including Mac OS X).</p>

<p><a id="X82A6893A7EC8FA72" name="X82A6893A7EC8FA72"></a></p>

<h5>3.4-2 ARCH_IS_MAC_OS_X</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ARCH_IS_MAC_OS_X</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>tests whether <strong class="pkg">GAP</strong> is running on Mac OS X. Note that on Mac OS X, also <code class="func">ARCH_IS_UNIX</code> (<a href="chap3.html#X7C825AF087A27884"><span class="RefLink">3.4-1</span></a>) will be <code class="code">true</code>.</p>

<p><a id="X7A14B659847B8627" name="X7A14B659847B8627"></a></p>

<h5>3.4-3 ARCH_IS_WINDOWS</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ARCH_IS_WINDOWS</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>tests whether <strong class="pkg">GAP</strong> is running on a Windows system.</p>

<p><a id="X7F1E823886F3681B" name="X7F1E823886F3681B"></a></p>

<h4>3.5 <span class="Heading">Global Values that Control the <strong class="pkg">GAP</strong> Session</span></h4>

<p><a id="X8354754E7935F935" name="X8354754E7935F935"></a></p>

<h5>3.5-1 GAPInfo</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; GAPInfo</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>Several global values control the <strong class="pkg">GAP</strong> session, such as the command line, the architecture, or the information about available and loaded packages. Many of these values are accessible as components of the global record <code class="func">GAPInfo</code>. Typically, these components are set and read in low level <strong class="pkg">GAP</strong> functions, so changing the values of existing components of <code class="func">GAPInfo</code> "by hand" is not recommended.</p>

<p>Important components are documented via index entries, try the input <code class="code">??GAPInfo</code> for getting an overview of these components.</p>

<p><a id="X818F2DDC863C381E" name="X818F2DDC863C381E"></a></p>

<h4>3.6 <span class="Heading">Coloring the Prompt and Input</span></h4>

<p><strong class="pkg">GAP</strong> provides hooks for functions which are called when the prompt is to be printed and when an input line is finished.</p>

<p>An example of using this feature is the following function.</p>

<p><a id="X84F3481C8466C7FC" name="X84F3481C8466C7FC"></a></p>

<h5>3.6-1 ColorPrompt</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ColorPrompt</code>( <var class="Arg">bool</var>[, <var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>With <code class="code">ColorPrompt(true);</code> <strong class="pkg">GAP</strong> changes its user interface: The prompts and the user input are displayed in different colors. Switch off the colored prompts with <code class="code">ColorPrompt(false);</code>.</p>

<p>Note that this will only work if your terminal emulation in which you run <strong class="pkg">GAP</strong> understands the so called ANSI color escape sequences –almost all terminal emulations on current UNIX/Linux (<code class="code">xterm</code>, <code class="code">rxvt</code>, <code class="code">konsole</code>, ...) systems do so.</p>

<p>The colors shown depend on the terminal configuration and cannot be forced from an application. If your terminal follows the ANSI conventions you see the standard prompt in bold blue and the break loop prompt in bold red, as well as your input in red.</p>

<p>If it works for you and you like it, put a call of <code class="code">SetUserPreference("UseColorPrompt", true);</code> in your <code class="file">gap.ini</code> file. If you want a more complicated setting as explained below then put your <code class="code">SetUserPreference("UseColorPrompt", rec( ... ) );</code> call into your <code class="file">gaprc</code> file.</p>

<p>The optional second argument <var class="Arg">optrec</var> allows one to further customize the behaviour. It must be a record from which the following components are recognized:</p>


<dl>
<dt><strong class="Mark"><code class="code">MarkupStdPrompt</code></strong></dt>
<dd><p>a string or no argument function returning a string containing the escape sequence used for the main prompt <code class="code">gap&gt; </code>.</p>

</dd>
<dt><strong class="Mark"><code class="code">MarkupContPrompt</code></strong></dt>
<dd><p>a string or no argument function returning a string containing the escape sequence used for the continuation prompt <code class="code">&gt; </code>.</p>

</dd>
<dt><strong class="Mark"><code class="code">MarkupBrkPrompt</code></strong></dt>
<dd><p>a string or no argument function returning a string containing the escape sequence used for the break prompt <code class="code">brk...&gt; </code>.</p>

</dd>
<dt><strong class="Mark"><code class="code">MarkupInput</code></strong></dt>
<dd><p>a string or no argument function returning a string containing the escape sequence used for user input.</p>

</dd>
<dt><strong class="Mark"><code class="code">TextPrompt</code></strong></dt>
<dd><p>a no argument function returning the string with the text of the prompt, but without any escape sequences. The current standard prompt is returned by <code class="code">CPROMPT()</code>. But note that changing the standard prompts makes the automatic removal of prompts from input lines impossible (see <a href="chap6.html#X866092F281910B74"><span class="RefLink">6.2</span></a>).</p>

</dd>
<dt><strong class="Mark"><code class="code">PrePrompt</code></strong></dt>
<dd><p>a function called before printing a prompt.</p>

</dd>
</dl>
<p>Here is an example.</p>


<div class="example"><pre>
LoadPackage("GAPDoc");
timeSHOWMIN := 100;
ColorPrompt(true, rec(
   # usually cyan bold, see ?TextAttr
   MarkupStdPrompt := Concatenation(TextAttr.bold, TextAttr.6),
   MarkupContPrompt := Concatenation(TextAttr.bold, TextAttr.6),
   PrePrompt := function()
     # show the 'time' automatically if at least timeSHOWMIN
     if CPROMPT() = "gap&gt; " and time &gt;= timeSHOWMIN then
       Print("Time of last command: ", time, " ms\n");
     fi;
   end)    );
</pre></div>


<div class="chlinkprevnextbot">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap2.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap4.html">[Next Chapter]</a>&nbsp;  </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>