Source

emacs / lispref / os.texi

   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
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
@node System Interface, Display, Processes, Top
@chapter Operating System Interface

  This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output,
and flow control.

  @xref{Building Emacs}, for related information.  See also
@ref{Display}, for additional operating system status information
pertaining to the terminal and the screen.

@menu
* Starting Up::         Customizing Emacs start-up processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day::		Getting the current time.
* Time Conversion::     Converting a time from numeric form to a string, or
                          to calendrical data (or vice versa).
* Timers::		Setting a timer to call a function at a certain time.
* Terminal Input::      Recording terminal input for debugging.
* Terminal Output::     Recording terminal output for debugging.
* Special Keysyms::     Defining system-specific key symbols for X windows.
* Flow Control::        How to turn output flow control on or off.
* Batch Mode::          Running Emacs without terminal interaction.
@end menu

@node Starting Up
@section Starting Up Emacs

  This section describes what Emacs does when it is started, and how you
can customize these actions.

@menu
* Start-up Summary::        Sequence of actions Emacs performs at start-up.
* Init File::               Details on reading the init file (@file{.emacs}).
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command Line Arguments::  How command line arguments are processed,
                              and how you can customize them.
@end menu

@node Start-up Summary
@subsection Summary: Sequence of Actions at Start Up
@cindex initialization
@cindex start up of Emacs
@cindex @file{startup.el}

   The order of operations performed (in @file{startup.el}) by Emacs when
it is started up is as follows:

@enumerate
@item
It loads the initialization library for the window system, if you are
using a window system.  This library's name is
@file{term/@var{windowsystem}-win.el}.

@item
It processes the initial options.  (Some of them are handled
even earlier than this.)

@item
It initializes the X window frame and faces, if appropriate.

@item
It runs the normal hook @code{before-init-hook}.

@item
It loads the library @file{site-start}, unless the option
@samp{-no-site-file} was specified.  The library's file name is usually
@file{site-start.el}.
@cindex @file{site-start.el}

@item 
It loads the file @file{~/.emacs} unless @samp{-q} was specified on
the command line.  (This is not done in @samp{-batch} mode.)  The @samp{-u}
option can specify the user name whose home directory should be used
instead of @file{~}.

@item 
It loads the library @file{default} unless @code{inhibit-default-init}
is non-@code{nil}.  (This is not done in @samp{-batch} mode or if
@samp{-q} was specified on the command line.)  The library's file name
is usually @file{default.el}.
@cindex @file{default.el}

@item
It runs the normal hook @code{after-init-hook}.

@item
It sets the major mode according to @code{initial-major-mode}, provided
the buffer @samp{*scratch*} is still current and still in Fundamental
mode.

@item 
It loads the terminal-specific Lisp file, if any, except when in batch
mode or using a window system.

@item
It displays the initial echo area message, unless you have suppressed
that with @code{inhibit-startup-echo-area-message}.

@item 
It processes the action arguments from the command line.

@item 
It runs @code{term-setup-hook}.

@item
It calls @code{frame-notice-user-settings}, which modifies the
parameters of the selected frame according to whatever the init files
specify.

@item 
It runs @code{window-setup-hook}.  @xref{Window Systems}.

@item 
It displays copyleft, nonwarranty, and basic use information, provided
there were no remaining command line arguments (a few steps above) and
the value of @code{inhibit-startup-message} is @code{nil}.
@end enumerate

@defopt inhibit-startup-message
This variable inhibits the initial startup messages (the nonwarranty,
etc.).  If it is non-@code{nil}, then the messages are not printed.

This variable exists so you can set it in your personal init file, once
you are familiar with the contents of the startup message.  Do not set
this variable in the init file of a new user, or in a way that affects
more than one user, because that would prevent new users from receiving
the information they are supposed to see.
@end defopt

@defopt inhibit-startup-echo-area-message
This variable controls the display of the startup echo area message.
You can suppress the startup echo area message by adding text with this
form to your @file{.emacs} file:

@example
(setq inhibit-startup-echo-area-message
      "@var{your-login-name}")
@end example

Simply setting @code{inhibit-startup-echo-area-message} to your login
name is not sufficient to inhibit the message; Emacs explicitly checks
whether @file{.emacs} contains an expression as shown above.  Your login
name must appear in the expression as a Lisp string constant.

This way, you can easily inhibit the message for yourself if you wish,
but thoughtless copying of your @file{.emacs} file will not inhibit the
message for someone else.
@end defopt

@node Init File
@subsection The Init File: @file{.emacs}
@cindex init file
@cindex @file{.emacs}

  When you start Emacs, it normally attempts to load the file
@file{.emacs} from your home directory.  This file, if it exists, must
contain Lisp code.  It is called your @dfn{init file}.  The command line
switches @samp{-q} and @samp{-u} affect the use of the init file;
@samp{-q} says not to load an init file, and @samp{-u} says to load a
specified user's init file instead of yours.  @xref{Entering Emacs,,,
emacs, The GNU Emacs Manual}.

@cindex default init file
  A site may have a @dfn{default init file}, which is the library named
@file{default.el}.  Emacs finds the @file{default.el} file through the
standard search path for libraries (@pxref{How Programs Do Loading}).
The Emacs distribution does not come with this file; sites may provide
one for local customizations.  If the default init file exists, it is
loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
specified.  But your own personal init file, if any, is loaded first; if
it sets @code{inhibit-default-init} to a non-@code{nil} value, then
Emacs does not subsequently load the @file{default.el} file.

  Another file for site-customization is @file{site-start.el}.  Emacs
loads this @emph{before} the user's init file.  You can inhibit the
loading of this file with the option @samp{-no-site-file}.

@defvar site-run-file
This variable specifies the site-customization file to load
before the user's init file.  Its normal value is @code{"site-start"}.
@end defvar

  If there is a great deal of code in your @file{.emacs} file, you
should move it into another file named @file{@var{something}.el},
byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
file load the other file using @code{load} (@pxref{Loading}).

  @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
examples of how to make various commonly desired customizations in your
@file{.emacs} file.

@defopt inhibit-default-init
This variable prevents Emacs from loading the default initialization
library file for your session of Emacs.  If its value is non-@code{nil},
then the default library is not loaded.  The default value is
@code{nil}.
@end defopt

@defvar before-init-hook
@defvarx after-init-hook
These two normal hooks are run just before, and just after, loading of
the user's init file, @file{default.el}, and/or @file{site-start.el}.
@end defvar

@node Terminal-Specific
@subsection Terminal-Specific Initialization
@cindex terminal-specific initialization

  Each terminal type can have its own Lisp library that Emacs loads when
run on that type of terminal.  For a terminal type named @var{termtype},
the library is called @file{term/@var{termtype}}.  Emacs finds the file
by searching the @code{load-path} directories as it does for other
files, and trying the @samp{.elc} and @samp{.el} suffixes.  Normally,
terminal-specific Lisp library is located in @file{emacs/lisp/term}, a
subdirectory of the @file{emacs/lisp} directory in which most Emacs Lisp
libraries are kept.@refill

  The library's name is constructed by concatenating the value of the
variable @code{term-file-prefix} and the terminal type.  Normally,
@code{term-file-prefix} has the value @code{"term/"}; changing this
is not recommended.

  The usual function of a terminal-specific library is to enable special
keys to send sequences that Emacs can recognize.  It may also need to
set or add to @code{function-key-map} if the Termcap entry does not
specify all the terminal's function keys.  @xref{Terminal Input}.

@cindex Termcap
  When the name of the terminal type contains a hyphen, only the part of
the name before the first hyphen is significant in choosing the library
name.  Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
the @file{term/aaa} library.  If necessary, the library can evaluate
@code{(getenv "TERM")} to find the full name of the terminal
type.@refill

  Your @file{.emacs} file can prevent the loading of the
terminal-specific library by setting the variable
@code{term-file-prefix} to @code{nil}.  This feature is useful when
experimenting with your own peculiar customizations.

  You can also arrange to override some of the actions of the
terminal-specific library by setting the variable
@code{term-setup-hook}.  This is a normal hook which Emacs runs using
@code{run-hooks} at the end of Emacs initialization, after loading both
your @file{.emacs} file and any terminal-specific libraries.  You can
use this variable to define initializations for terminals that do not
have their own libraries.  @xref{Hooks}.

@defvar term-file-prefix
@cindex @code{TERM} environment variable
If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
a terminal-specific initialization file as follows:

@example
(load (concat term-file-prefix (getenv "TERM")))
@end example

@noindent
You may set the @code{term-file-prefix} variable to @code{nil} in your
@file{.emacs} file if you do not wish to load the
terminal-initialization file.  To do this, put the following in
your @file{.emacs} file: @code{(setq term-file-prefix nil)}.
@end defvar

@defvar term-setup-hook 
This variable is a normal hook that Emacs runs after loading your
@file{.emacs} file, the default initialization file (if any) and the
terminal-specific Lisp file.

You can use @code{term-setup-hook} to override the definitions made by a
terminal-specific file.
@end defvar

  See @code{window-setup-hook} in @ref{Window Systems}, for a related
feature.

@node Command Line Arguments
@subsection Command Line Arguments
@cindex command line arguments

  You can use command line arguments to request various actions when you
start Emacs.  Since you do not need to start Emacs more than once per
day, and will often leave your Emacs session running longer than that,
command line arguments are hardly ever used.  As a practical matter, it
is best to avoid making the habit of using them, since this habit would
encourage you to kill and restart Emacs unnecessarily often.  These
options exist for two reasons: to be compatible with other editors (for
invocation by other programs) and to enable shell scripts to run
specific Lisp programs.

  This section describes how Emacs processes command line arguments,
and how you can customize them.

@ignore
  (Note that some other editors require you to start afresh each time
you want to edit a file.  With this kind of editor, you will probably
specify the file as a command line argument.  The recommended way to
use GNU Emacs is to start it only once, just after you log in, and do
all your editing in the same Emacs process.  Each time you want to edit
a different file, you visit it with the existing Emacs, which eventually
comes to have many files in it ready for editing.  Usually you do not
kill the Emacs until you are about to log out.)
@end ignore

@defun command-line
This function parses the command line that Emacs was called with,
processes it, loads the user's @file{.emacs} file and displays the
startup messages.
@end defun

@defvar command-line-processed
The value of this variable is @code{t} once the command line has been
processed.

If you redump Emacs by calling @code{dump-emacs}, you may wish to set
this variable to @code{nil} first in order to cause the new dumped Emacs
to process its new command line arguments.
@end defvar

@defvar command-switch-alist
@cindex switches on command line
@cindex options on command line
@cindex command line options
The value of this variable is an alist of user-defined command-line
options and associated handler functions.  This variable exists so you
can add elements to it.

A @dfn{command line option} is an argument on the command line of the
form:

@example
-@var{option}
@end example

The elements of the @code{command-switch-alist} look like this: 

@example
(@var{option} . @var{handler-function})
@end example

The @var{handler-function} is called to handle @var{option} and receives
the option name as its sole argument.

In some cases, the option is followed in the command line by an
argument.  In these cases, the @var{handler-function} can find all the
remaining command-line arguments in the variable
@code{command-line-args-left}.  (The entire list of command-line
arguments is in @code{command-line-args}.)

The command line arguments are parsed by the @code{command-line-1}
function in the @file{startup.el} file.  See also @ref{Command
Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
Manual}.
@end defvar

@defvar command-line-args
The value of this variable is the list of command line arguments passed
to Emacs.
@end defvar

@defvar command-line-functions
This variable's value is a list of functions for handling an
unrecognized command-line argument.  Each time the next argument to be
processed has no special meaning, the functions in this list are called,
in order of appearance, until one of them returns a non-@code{nil}
value.

These functions are called with no arguments.  They can access the
command-line argument under consideration through the variable
@code{argi}.  The remaining arguments (not including the current one)
are in the variable @code{command-line-args-left}.

When a function recognizes and processes the argument in @code{argi}, it
should return a non-@code{nil} value to say it has dealt with that
argument.  If it has also dealt with some of the following arguments, it
can indicate that by deleting them from @code{command-line-args-left}.

If all of these functions return @code{nil}, then the argument is used
as a file name to visit.
@end defvar

@node Getting Out
@section Getting Out of Emacs
@cindex exiting Emacs

  There are two ways to get out of Emacs: you can kill the Emacs job,
which exits permanently, or you can suspend it, which permits you to
reenter the Emacs process later.  As a practical matter, you seldom kill
Emacs---only when you are about to log out.  Suspending is much more
common.

@menu
* Killing Emacs::        Exiting Emacs irreversibly.
* Suspending Emacs::     Exiting Emacs reversibly.
@end menu

@node Killing Emacs
@comment  node-name,  next,  previous,  up
@subsection Killing Emacs
@cindex killing Emacs

  Killing Emacs means ending the execution of the Emacs process.  The
parent process normally resumes control.  The low-level primitive for
killing Emacs is @code{kill-emacs}.

@defun kill-emacs &optional exit-data
This function exits the Emacs process and kills it.

If @var{exit-data} is an integer, then it is used as the exit status
of the Emacs process.  (This is useful primarily in batch operation; see
@ref{Batch Mode}.)

If @var{exit-data} is a string, its contents are stuffed into the
terminal input buffer so that the shell (or whatever program next reads
input) can read them.
@end defun

  All the information in the Emacs process, aside from files that have
been saved, is lost when the Emacs is killed.  Because killing Emacs
inadvertently can lose a lot of work, Emacs queries for confirmation
before actually terminating if you have buffers that need saving or
subprocesses that are running.  This is done in the function
@code{save-buffers-kill-emacs}.

@defvar kill-emacs-query-functions
After asking the standard questions, @code{save-buffers-kill-emacs}
calls the functions in the list @code{kill-buffer-query-functions}, in
order of appearance, with no arguments.  These functions can ask for
additional confirmation from the user.  If any of them returns
non-@code{nil}, Emacs is not killed.
@end defvar

@defvar kill-emacs-hook
This variable is a normal hook; once @code{save-buffers-kill-emacs} is
finished with all file saving and confirmation, it runs the functions in
this hook.
@end defvar

@node Suspending Emacs
@subsection Suspending Emacs
@cindex suspending Emacs

  @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
control to its superior process, which is usually the shell.  This
allows you to resume editing later in the same Emacs process, with the
same buffers, the same kill ring, the same undo history, and so on.  To
resume Emacs, use the appropriate command in the parent shell---most
likely @code{fg}.

  Some operating systems do not support suspension of jobs; on these
systems, ``suspension'' actually creates a new shell temporarily as a
subprocess of Emacs.  Then you would exit the shell to return to Emacs.

  Suspension is not useful with window systems such as X, because the
Emacs job may not have a parent that can resume it again, and in any
case you can give input to some other job such as a shell merely by
moving to a different window.  Therefore, suspending is not allowed
when Emacs is an X client.

@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
If and when the superior process resumes Emacs, @code{suspend-emacs}
returns @code{nil} to its caller in Lisp.

If @var{string} is non-@code{nil}, its characters are sent to be read
as terminal input by Emacs's superior shell.  The characters in
@var{string} are not echoed by the superior shell; only the results
appear.

Before suspending, @code{suspend-emacs} runs the normal hook
@code{suspend-hook}.  In Emacs version 18, @code{suspend-hook} was not a
normal hook; its value was a single function, and if its value was
non-@code{nil}, then @code{suspend-emacs} returned immediately without
actually suspending anything.

After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
@code{suspend-resume-hook}.  @xref{Hooks}.

The next redisplay after resumption will redraw the entire screen,
unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
(@pxref{Refresh Screen}).

In the following example, note that @samp{pwd} is not echoed after
Emacs is suspended.  But it is read and executed by the shell.

@smallexample
@group
(suspend-emacs)
     @result{} nil
@end group

@group
(add-hook 'suspend-hook
          (function (lambda ()
                      (or (y-or-n-p
                            "Really suspend? ")
                          (error "Suspend cancelled")))))
     @result{} (lambda nil
          (or (y-or-n-p "Really suspend? ")
              (error "Suspend cancelled")))
@end group
@group
(add-hook 'suspend-resume-hook
          (function (lambda () (message "Resumed!"))))
     @result{} (lambda nil (message "Resumed!"))
@end group
@group
(suspend-emacs "pwd")
     @result{} nil
@end group
@group
---------- Buffer: Minibuffer ----------
Really suspend? @kbd{y}
---------- Buffer: Minibuffer ----------
@end group

@group
---------- Parent Shell ----------
lewis@@slug[23] % /user/lewis/manual
lewis@@slug[24] % fg
@end group

@group
---------- Echo Area ----------
Resumed!
@end group
@end smallexample
@end defun

@defvar suspend-hook
This variable is a normal hook run before suspending.
@end defvar

@defvar suspend-resume-hook
This variable is a normal hook run after suspending.
@end defvar

@node System Environment
@section Operating System Environment
@cindex operating system environment

  Emacs provides access to variables in the operating system environment
through various functions.  These variables include the name of the
system, the user's @sc{uid}, and so on.

@defvar system-type
The value of this variable is a symbol indicating the type of operating
system Emacs is operating on.  Here is a table of the possible values:

@table @code
@item aix-v3
AIX.

@item berkeley-unix
Berkeley BSD.

@item dgux
Data General DGUX operating system.

@item gnu
A GNU system (using the GNU kernel, which consists of the HURD and Mach).

@item gnu/linux
A variant GNU system using the Linux kernel.

@item hpux
Hewlett-Packard HPUX operating system.

@item irix
Silicon Graphics Irix system.

@item ms-dos
Microsoft MS-DOS ``operating system.''

@item next-mach
NeXT Mach-based system.

@item rtu
Masscomp RTU, UCB universe.

@item unisoft-unix
UniSoft UniPlus.

@item usg-unix-v
AT&T System V.

@item vax-vms
VAX VMS.

@item windows-nt
Microsoft windows NT.

@item xenix
SCO Xenix 386.
@end table

We do not wish to add new symbols to make finer distinctions unless it
is absolutely necessary!  In fact, we hope to eliminate some of these
alternatives in the future.  We recommend using
@code{system-configuration} to distinguish between different operating
systems.
@end defvar

@defvar system-configuration
This variable holds the three-part configuration name for the
hardware/software configuration of your system, as a string.  The
convenient way to test parts of this string is with @code{string-match}.
@end defvar

@defun system-name
This function returns the name of the machine you are running on.
@example
(system-name)
     @result{} "prep.ai.mit.edu"
@end example
@end defun

@vindex system-name
  The symbol @code{system-name} is a variable as well as a function.  In
fact, the function returns whatever value the variable
@code{system-name} currently holds.  Thus, you can set the variable
@code{system-name} in case Emacs is confused about the name of your
system.  The variable is also useful for constructing frame titles
(@pxref{Frame Titles}).

@defvar mail-host-address
If this variable is non-@code{nil}, it is used instead of
@code{system-name} for purposes of generating email addresses.  For
example, it is used when constructing the default value of
@code{user-mail-address}.  @xref{User Identification}.  (Since this is
done when Emacs starts up, the value actually used is the one saved when
Emacs was dumped.  @xref{Building Emacs}.)
@end defvar

@defun getenv var
@cindex environment variable access
This function returns the value of the environment variable @var{var},
as a string.  Within Emacs, the environment variable values are kept in
the Lisp variable @code{process-environment}.

@example
@group
(getenv "USER")
     @result{} "lewis"
@end group

@group
lewis@@slug[10] % printenv
PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
USER=lewis
@end group
@group
TERM=ibmapa16
SHELL=/bin/csh
HOME=/user/lewis
@end group
@end example
@end defun

@c Emacs 19 feature
@deffn Command setenv variable value
This command sets the value of the environment variable named
@var{variable} to @var{value}.  Both arguments should be strings.  This
function works by modifying @code{process-environment}; binding that
variable with @code{let} is also reasonable practice.
@end deffn

@defvar process-environment
This variable is a list of strings, each describing one environment
variable.  The functions @code{getenv} and @code{setenv} work by means
of this variable.

@smallexample
@group
process-environment
@result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
    "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
    "USER=lewis" 
@end group
@group
    "TERM=ibmapa16" 
    "SHELL=/bin/csh"
    "HOME=/user/lewis")
@end group
@end smallexample
@end defvar

@defvar path-separator
This variable holds a string which says which character separates
directories in a search path (as found in an environment variable).  Its
value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
and Windows NT.
@end defvar

@defvar invocation-name
This variable holds the program name under which Emacs was invoked.  The
value is a string, and does not include a directory name.
@end defvar

@defvar invocation-directory
This variable holds the directory from which the Emacs executable was
invoked, or perhaps @code{nil} if that directory cannot be determined.
@end defvar

@defvar installation-directory
If non-@code{nil}, this is a directory within which to look for the
@file{lib-src} and @file{etc} subdirectories.  This is non-@code{nil}
when Emacs can't find those directories in their standard installed
locations, but can find them in a directory related somehow to the one
containing the Emacs executable.
@end defvar

@defun load-average
This function returns the current 1-minute, 5-minute and 15-minute
load averages in a list.  The values are integers that are 100 times
the system load averages.  (The load averages indicate the number of
processes trying to run.)

@example
@group
(load-average)
     @result{} (169 48 36)
@end group

@group
lewis@@rocky[5] % uptime
 11:55am  up 1 day, 19:37,  3 users,
 load average: 1.69, 0.48, 0.36
@end group
@end example
@end defun

@defun emacs-pid
This function returns the process @sc{id} of the Emacs process.
@end defun

@defun setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege.  (It does not exist on
Unix.)  The first arg is the privilege name, as a string.  The second
argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the
privilege is to be turned on or off.  Its default is @code{nil}.  The
function returns @code{t} if successful, @code{nil} otherwise.

  If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
does not change the privilege, but returns @code{t} or @code{nil}
indicating whether the privilege is currently enabled.
@end defun

@node User Identification
@section User Identification

@defvar user-mail-address
This holds the nominal email address of the user who is using Emacs.
Emacs normally sets this variable to a default value after reading your
init files, but not if you have already set it.  So you can set the
variable to some other value in your @file{~/.emacs} file if you do not
want to use the default value.
@end defvar

@defun user-login-name &optional uid
If you don't specify @var{uid}, this function returns the name under
which the user is logged in.  If the environment variable @code{LOGNAME}
is set, that value is used.  Otherwise, if the environment variable
@code{USER} is set, that value is used.  Otherwise, the value is based
on the effective @sc{uid}, not the real @sc{uid}.

If you specify @var{uid}, the value is the user name that corresponds
to @var{uid} (which should be an integer).

@example
@group
(user-login-name)
     @result{} "lewis"
@end group
@end example
@end defun

@defun user-real-login-name
This function returns the user name corresponding to Emacs's real
@sc{uid}.  This ignores the effective @sc{uid} and ignores the
environment variables @code{LOGNAME} and @code{USER}.
@end defun

@defun user-full-name
This function returns the full name of the user.

@example
@group
(user-full-name)
     @result{} "Bil Lewis"
@end group
@end example
@end defun

@vindex user-full-name
@vindex user-real-login-name
@vindex user-login-name
  The symbols @code{user-login-name}, @code{user-real-login-name} and
@code{user-full-name} are variables as well as functions.  The functions
return the same values that the variables hold.  These variables allow
you to ``fake out'' Emacs by telling the functions what to return.  The
variables are also useful for constructing frame titles (@pxref{Frame
Titles}).

@defun user-real-uid
This function returns the real @sc{uid} of the user.

@example
@group
(user-real-uid)
     @result{} 19
@end group
@end example
@end defun

@defun user-uid
This function returns the effective @sc{uid} of the user.  
@end defun

@node Time of Day
@section Time of Day

  This section explains how to determine the current time and the time
zone.

@defun current-time-string &optional time-value
This function returns the current time and date as a humanly-readable
string.  The format of the string is unvarying; the number of characters
used for each part is always the same, so you can reliably use
@code{substring} to extract pieces of it.  It is wise to count the
characters from the beginning of the string rather than from the end, as
additional information may be added at the end.

@c Emacs 19 feature
The argument @var{time-value}, if given, specifies a time to format
instead of the current time.  The argument should be a list whose first
two elements are integers.  Thus, you can use times obtained from
@code{current-time} (see below) and from @code{file-attributes}
(@pxref{File Attributes}).

@example
@group
(current-time-string)
     @result{} "Wed Oct 14 22:21:05 1987"
@end group
@end example
@end defun

@c Emacs 19 feature
@defun current-time
This function returns the system's time value as a list of three
integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
@var{high} and @var{low} combine to give the number of seconds since
0:00 January 1, 1970, which is
@ifinfo
@var{high} * 2**16 + @var{low}.
@end ifinfo
@tex
$high*2^{16}+low$.
@end tex

The third element, @var{microsec}, gives the microseconds since the
start of the current second (or 0 for systems that return time only on
the resolution of a second).

The first two elements can be compared with file time values such as you
get with the function @code{file-attributes}.  @xref{File Attributes}.
@end defun

@c Emacs 19 feature
@defun current-time-zone &optional time-value
This function returns a list describing the time zone that the user is
in.

The value has the form @code{(@var{offset} @var{name})}.  Here
@var{offset} is an integer giving the number of seconds ahead of UTC
(east of Greenwich).  A negative value means west of Greenwich.  The
second element, @var{name} is a string giving the name of the time
zone.  Both elements change when daylight savings time begins or ends;
if the user has specified a time zone that does not use a seasonal time
adjustment, then the value is constant through time.

If the operating system doesn't supply all the information necessary to
compute the value, both elements of the list are @code{nil}.

The argument @var{time-value}, if given, specifies a time to analyze
instead of the current time.  The argument should be a cons cell
containing two integers, or a list whose first two elements are
integers.  Thus, you can use times obtained from @code{current-time}
(see above) and from @code{file-attributes} (@pxref{File Attributes}).
@end defun

@node Time Conversion
@section Time Conversion

  These functions convert time values (lists of two or three integers)
to strings or to calendrical information.  There is also a function to
convert calendrical information to a time value.  You can get time
values from the functions @code{current-time} (@pxref{Time of Day}) and
@code{file-attributes} (@pxref{File Attributes}).

Many operating systems are limited to time values that contain 32 bits
of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, some
operating systems have larger time values, and can represent times far
in the past or future.

Time conversion functions always use the Gregorian calendar, even for
dates before the Gregorian calendar was introduced.  Year numbers count
the number of years since the year 1 B.C., and do not skip zero as
traditional Gregorian years do; for example, the year number -37
represents the Gregorian year 38 B.C@.

@defun format-time-string format-string time
This function converts @var{time} to a string according to
@var{format-string}.  The argument @var{format-string} may contain
@samp{%}-sequences which say to substitute parts of the time.  Here is a
table of what the @samp{%}-sequences mean:

@table @samp
@item %a
This stands for the abbreviated name of the day of week.
@item %A
This stands for the full name of the day of week.
@item %b
This stands for the abbreviated name of the month.
@item %B
This stands for the full name of the month.
@item %c
This is a synonym for @samp{%x %X}.
@item %C
This has a locale-specific meaning.  In the default locale (named C), it
is equivalent to @samp{%A, %B %e, %Y}.
@item %d
This stands for the day of month, zero-padded.
@item %D
This is a synonym for @samp{%m/%d/%y}.
@item %e
This stands for the day of month, blank-padded.
@item %h
This is a synonym for @samp{%b}.
@item %H
This stands for the hour (00-23).
@item %I
This stands for the hour (00-12).
@item %j
This stands for the day of the year (001-366).
@item %k
This stands for the hour (0-23), blank padded.
@item %l
This stands for the hour (1-12), blank padded.
@item %m
This stands for the month (01-12).
@item %M
This stands for the minute (00-59).
@item %n
This stands for a newline.
@item %p
This stands for @samp{AM} or @samp{PM}, as appropriate.
@item %r
This is a synonym for @samp{%I:%M:%S %p}.
@item %R
This is a synonym for @samp{%H:%M}.
@item %S
This stands for the seconds (00-60).
@item %t
This stands for a tab character.
@item %T
This is a synonym for @samp{%H:%M:%S}.
@item %U
This stands for the week of the year (01-52), assuming that weeks
start on Sunday.
@item %w
This stands for the numeric day of week (0-6).  Sunday is day 0.
@item %W
This stands for the week of the year (01-52), assuming that weeks
start on Monday.
@item %x
This has a locale-specific meaning.  In the default locale (named C), it
is equivalent to @samp{%D}.
@item %X
This has a locale-specific meaning.  In the default locale (named C), it
is equivalent to @samp{%T}.
@item %y
This stands for the year without century (00-99).
@item %Y
This stands for the year with century.
@item %Z
This stands for the time zone abbreviation.
@end table
@end defun

@defun decode-time time
This function converts a time value into calendrical information.  The
return value is a list of nine elements, as follows:

@example
(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
@end example

Here is what the elements mean:

@table @var
@item sec
The number of seconds past the minute, as an integer between 0 and 59.
@item minute
The number of minutes past the hour, as an integer between 0 and 59.
@item hour
The hour of the day, as an integer between 0 and 23.
@item day
The day of the month, as an integer between 1 and 31.
@item month
The month of the year, as an integer between 1 and 12.
@item year
The year, an integer typically greater than 1900.
@item dow
The day of week, as an integer between 0 and 6, where 0 stands for
Sunday.
@item dst
@code{t} if daylight savings time is effect, otherwise @code{nil}.
@item zone
An integer indicating the time zone, as the number of seconds east of
Greenwich.
@end table

Note that Common Lisp has different meanings for @var{dow} and
@var{zone}.
@end defun

@defun encode-time seconds minutes hour day month year &optional @dots{}zone
This function is the inverse of @code{decode-time}.  It converts seven
items of calendrical data into a time value.  For the meanings of the
arguments, see the table above under @code{decode-time}.

Year numbers less than 100 are treated just like other year numbers.  If
you want them to stand for years above 1900, you must alter them yourself
before you call @code{encode-time}.

The optional argument @var{zone} defaults to the current time zone and
its daylight savings time rules.  If specified, it can be either a list
(as you would get from @code{current-time-zone}) or an integer (as you
would get from @code{decode-time}).  The specified zone is used without
any further alteration for daylight savings time.

If you pass more than seven arguments to @code{encode-time}, the first
six are used as @var{seconds} through @var{year}, the last argument is
used as @var{zone}, and the arguments in between are ignored.  This
feature makes it possible to use the elements of a list returned by
@code{decode-time} as the arguments to @code{encode-time}, like this:

@example
(apply 'encode-time (decode-time @dots{}))
@end example
@end defun

@node Timers
@section Timers for Delayed Execution
@cindex timer

  You can set up a @dfn{timer} to call a function at a specified future time or
after a certain length of idleness.

  Emacs cannot run a timer at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
namely, while waiting or inside certain primitive functions such as
@code{sit-for} or @code{read-char} which @emph{can} wait.  Therefore, a
timer's execution may be delayed if Emacs is busy.  However, the time of
execution is very precise if Emacs is idle.

@defun run-at-time time repeat function &rest args
This function arranges to call @var{function} with arguments @var{args}
at time @var{time}.  The argument @var{function} is a function to call
later, and @var{args} are the arguments to give it when it is called.
The time @var{time} is specified as a string.

Absolute times may be specified in a variety of formats; The form
@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
@var{month}/@var{day}/@var{year}}, where all fields are numbers, works;
the format that @code{current-time-string} returns is also allowed.

To specify a relative time, use numbers followed by units.
For example:

@table @samp
@item 1 min
denotes 1 minute from now.
@item 1 min 5 sec
denotes 65 seconds from now.
@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
denotes exactly 103 months, 123 days, and 10862 seconds from now.
@end table

If @var{time} is a number (integer or floating point), that specifies a
relative time measured in seconds.

The argument @var{repeat} specifies how often to repeat the call.  If
@var{repeat} is @code{nil}, there are no repetitions; @var{function} is
called just once, at @var{time}.  If @var{repeat} is a number, it
specifies a repetition period measured in seconds.  In any case,
@var{repeat} has no effect on when @emph{first} call takes
place---@var{time} alone specifies that.

The function @code{run-at-time} returns a timer value that identifies
the particular scheduled future action.  You can use this value to call
@code{cancel-timer} (see below).
@end defun

@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
Execute @var{body}, but give up after @var{seconds} seconds.  If
@var{body} finishes before the time is up, @code{with-timeout} returns
the value of the last form in @var{body}.  If, however, the execution of
@var{body} is cut short by the timeout, then @code{with-timeout}
executes all the @var{timeout-forms} and returns the value of the last
of them.

This macro works by set a timer to run after @var{seconds} seconds.  If
@var{body} finishes before that time, it cancels the timer.  If the
timer actually runs, it terminates execution of @var{body}, then
executes @var{timeout-forms}.

Since timers can run within a Lisp program only when the program calls a
primitive that can wait, @code{with-timeout} cannot stop executing
@var{body} while it is in the midst of a computation---only when it
calls one of those primitives.  So use @code{with-timeout} only with a
@var{body} that waits for input, not one that does a long computation.
@end defmac

  The function @code{y-or-n-p-with-timeout} provides a simple way to use
a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
Queries}.

@defun run-with-idle-timer secs repeat function &rest args
Set up a timer which runs when Emacs has been idle for @var{secs}
seconds.  The value of @var{secs} may be an integer or a floating point
number.

If @var{repeat} is @code{nil}, the timer runs just once, the first time
Emacs remains idle for a long enough time.  More often @var{repeat} is
non-@code{nil}, which means to run the timer @emph{each time} Emacs
remains idle for @var{secs} seconds.

The function @code{run-with-idle-timer} returns a timer value which you
can use in calling @code{cancel-timer} (see below).
@end defun

@cindex idleness
  Emacs becomes ``idle'' when it starts waiting for user input, and it
remains idle until the user provides some input.  If a timer is set for
five seconds of idleness, it runs approximately five seconds after Emacs
first became idle.  Even if its @var{repeat} is true, this timer will
not run again as long as Emacs remains idle, because the duration of
idleness will continue to increase and will not go down to five seconds
again.

  Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess.  But these interludes during idleness
have little effect on idle timers.  An idle timer set for 600 seconds
will run when ten minutes have elapsed since the last user command was
finished, even if subprocess output has been accepted thousands of times
within those ten minutes, even if there have been garbage collections
and autosaves.

  When the user supplies input, Emacs becomes non-idle while executing the
input.  Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.

@defun cancel-timer timer
Cancel the requested action for @var{timer}, which should be a value
previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
This cancels the effect of that call to @code{run-at-time}; the arrival
of the specified time will not cause anything special to happen.
@end defun

@node Terminal Input
@section Terminal Input
@cindex terminal input

  This section describes functions and variables for recording or
manipulating terminal input.  See @ref{Display}, for related
functions.

@menu
* Input Modes::		Options for how input is processed.
* Translating Input::   Low level conversion of some characters or events
			  into others.
* Recording Input::	Saving histories of recent or all input events.
@end menu

@node Input Modes
@subsection Input Modes
@cindex input modes
@cindex terminal input modes

@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input.  If
@var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
@code{nil}, then it uses @sc{cbreak} mode.  When Emacs communicates
directly with X, it ignores this argument and uses interrupts if that is
the way it knows how to communicate.

If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
@kbd{C-s}) flow control for output to the terminal.  This has no effect except
in @sc{cbreak} mode.  @xref{Flow Control}.

The default setting is system dependent.  Some systems always use
@sc{cbreak} mode regardless of what is specified.

@c Emacs 19 feature
The argument @var{meta} controls support for input character codes
above 127.  If @var{meta} is @code{t}, Emacs converts characters with
the 8th bit set into Meta characters.  If @var{meta} is @code{nil},
Emacs disregards the 8th bit; this is necessary when the terminal uses
it as a parity bit.  If @var{meta} is neither @code{t} nor @code{nil},
Emacs uses all 8 bits of input unchanged.  This is good for terminals
using European 8-bit character sets.

@c Emacs 19 feature
If @var{quit-char} is non-@code{nil}, it specifies the character to
use for quitting.  Normally this character is @kbd{C-g}.
@xref{Quitting}.
@end defun

The @code{current-input-mode} function returns the input mode settings
Emacs is currently using.

@c Emacs 19 feature
@defun current-input-mode
This function returns current mode for reading keyboard input.  It
returns a list, corresponding to the arguments of @code{set-input-mode},
of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
which:
@table @var
@item interrupt
is non-@code{nil} when Emacs is using interrupt-driven input.  If
@code{nil}, Emacs is using @sc{cbreak} mode.
@item flow
is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
flow control for output to the terminal.  This value has no effect
unless @var{interrupt} is non-@code{nil}.
@item meta
is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
input character; any other value means Emacs uses all eight bits as the
basic character code.
@item quit
is the character Emacs currently uses for quitting, usually @kbd{C-g}.
@end table
@end defun

@node Translating Input
@subsection Translating Input Events
@cindex translating input events

  This section describes features for translating input events into
other input events before they become part of key sequences.  These
features apply to each event in the order they are described here: each
event is first modified according to @code{extra-keyboard-modifiers},
then translated through @code{keyboard-translate-table} (if applicable).
If it is being read as part of a key sequence, it is then added to the
sequece being read; then subsequences containing it are checked first
with @code{function-key-map} and then with @code{key-translation-map}.

@c Emacs 19 feature
@defvar extra-keyboard-modifiers
This variable lets Lisp programs ``press'' the modifier keys on the
keyboard.  The value is a bit mask:

@table @asis
@item 1
The @key{SHIFT} key.
@item 2
The @key{LOCK} key.
@item 4
The @key{CTL} key.
@item 8
The @key{META} key.
@end table

Each time the user types a keyboard key, it is altered as if the
modifier keys specified in the bit mask were held down.

When using X windows, the program can ``press'' any of the modifier
keys in this way.  Otherwise, only the @key{CTL} and @key{META} keys can
be virtually pressed.
@end defvar

@defvar keyboard-translate-table
This variable is the translate table for keyboard characters.  It lets
you reshuffle the keys on the keyboard without changing any command
bindings.  Its value must be a string or @code{nil}.

If @code{keyboard-translate-table} is a string, then each character read
from the keyboard is looked up in this string and the character in the
string is used instead.  If the string is of length @var{n}, character codes
@var{n} and up are untranslated.

In the example below, we set @code{keyboard-translate-table} to a
string of 128 characters.  Then we fill it in to swap the characters
@kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.
Subsequently, typing @kbd{C-\} has all the usual effects of typing
@kbd{C-s}, and vice versa.  (@xref{Flow Control} for more information on
this subject.)

@cindex flow control example
@example
@group
(defun evade-flow-control ()
  "Replace C-s with C-\ and C-q with C-^."
  (interactive)
@end group
@group
  (let ((the-table (make-string 128 0)))
    (let ((i 0))
      (while (< i 128)
        (aset the-table i i)
        (setq i (1+ i))))
@end group
    ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
    (aset the-table ?\034 ?\^s)
    (aset the-table ?\^s ?\034)
@group
    ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
    (aset the-table ?\036 ?\^q)
    (aset the-table ?\^q ?\036)
    (setq keyboard-translate-table the-table)))
@end group
@end example

Note that this translation is the first thing that happens to a
character after it is read from the terminal.  Record-keeping features
such as @code{recent-keys} and dribble files record the characters after
translation.
@end defvar

@defun keyboard-translate from to
This function modifies @code{keyboard-translate-table} to translate
character code @var{from} into character code @var{to}.  It creates
or enlarges the translate table if necessary.
@end defun

  The remaining translation features translate subsequences of key
sequences being read.  They are implemented in @code{read-key-sequence}
and have no effect on @code{read-char}.

@defvar function-key-map
This variable holds a keymap that describes the character sequences
sent by function keys on an ordinary character terminal.  This keymap
uses the same data structure as other keymaps, but is used differently: it
specifies translations to make while reading event sequences.

If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
key sequence, it is replaced with the events in @var{v}.

For example, VT100 terminals send @kbd{@key{ESC} O P} when the
keypad PF1 key is pressed.  Therefore, we want Emacs to translate
that sequence of events into the single event @code{pf1}.  We accomplish
this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
@code{function-key-map}, when using a VT100.

Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
@key{ESC} O P}; later the function @code{read-key-sequence} translates
this back into @kbd{C-c @key{PF1}}, which it returns as the vector
@code{[?\C-c pf1]}.

Entries in @code{function-key-map} are ignored if they conflict with
bindings made in the minor mode, local, or global keymaps.  The intent
is that the character sequences that function keys send should not have
command bindings in their own right.

The value of @code{function-key-map} is usually set up automatically
according to the terminal's Terminfo or Termcap entry, but sometimes
those need help from terminal-specific Lisp files.  Emacs comes with
terminal-specific files for many common terminals; their main purpose is
to make entries in @code{function-key-map} beyond those that can be
deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.

Emacs versions 18 and earlier used totally different means of detecting
the character sequences that represent function keys.
@end defvar

@defvar key-translation-map
This variable is another keymap used just like @code{function-key-map}
to translate input events into other events.  It differs from
@code{function-key-map} in two ways:

@itemize @bullet
@item
@code{key-translation-map} goes to work after @code{function-key-map} is
finished; it receives the results of translation by
@code{function-key-map}.

@item
@code{key-translation-map} overrides actual key bindings.  For example,
if @kbd{C-x f} has a binding in @code{key-translation-map}, that
translation takes effect even though @kbd{C-x f} also has a key binding
in the global map.
@end itemize

The intent of @code{key-translation-map} is for users to map one
character set to another, including ordinary characters normally bound
to @code{self-insert-command}.
@end defvar

@cindex key translation function
You can use @code{function-key-map} or @code{key-translation-map} for
more than simple aliases, by using a function, instead of a key
sequence, as the ``translation'' of a key.  Then this function is called
to compute the translation of that key.

The key translation function receives one argument, which is the prompt
that was specified in @code{read-key-sequence}---or @code{nil} if the
key sequence is being read by the editor command loop.  In most cases
you can ignore the prompt value.

If the function reads input itself, it can have the effect of altering
the event that follows.  For example, here's how to define @kbd{C-c h}
to turn the character that follows into a Hyper character:

@example
@group
(defun hyperify (prompt)
  (let ((e (read-event)))
    (vector (if (numberp e)
                (logior (lsh 1 20) e)
              (if (memq 'hyper (event-modifiers e))
                  e
                (add-event-modifier "H-" e))))))

(defun add-event-modifier (string e)
  (let ((symbol (if (symbolp e) e (car e))))
    (setq symbol (intern (concat string
                                 (symbol-name symbol))))
@end group
@group
    (if (symbolp e)
        symbol
      (cons symbol (cdr e)))))

(define-key function-key-map "\C-ch" 'hyperify)
@end group
@end example

@pindex iso-transl
@cindex Latin-1 character set (input)
@cindex ISO Latin-1 characters (input)
The @file{iso-transl} library uses this feature to provide a way of
inputting non-ASCII Latin-1 characters.

@node Recording Input
@subsection Recording Input

@defun recent-keys
This function returns a vector containing the last 100 input events
from the keyboard or mouse.  All input events are included, whether or
not they were used as parts of key sequences.  Thus, you always get the
last 100 inputs, not counting keyboard macros.  (Events from keyboard
macros are excluded because they are less interesting for debugging; it
should be enough to see the events that invoked the macros.)
@end defun

@deffn Command open-dribble-file  filename
@cindex dribble file
This function opens a @dfn{dribble file} named @var{filename}.  When a
dribble file is open, each input event from the keyboard or mouse (but
not those from keyboard macros) is written in that file.  A
non-character event is expressed using its printed representation
surrounded by @samp{<@dots{}>}.

You close the dribble file by calling this function with an argument
of @code{nil}.

This function is normally used to record the input necessary to
trigger an Emacs bug, for the sake of a bug report.

@example
@group
(open-dribble-file "~/dribble")
     @result{} nil
@end group
@end example
@end deffn

  See also the @code{open-termscript} function (@pxref{Terminal Output}).

@node Terminal Output
@section Terminal Output
@cindex terminal output

  The terminal output functions send output to the terminal or keep
track of output sent to the terminal.  The variable @code{baud-rate}
tells you what Emacs thinks is the output speed of the terminal.

@defvar baud-rate
This variable's value is the output speed of the terminal, as far as
Emacs knows.  Setting this variable does not change the speed of actual
data transmission, but the value is used for calculations such as
padding.  It also affects decisions about whether to scroll part of the
screen or repaint---even when using a window system.  (We designed it
this way despite the fact that a window system has no true ``output
speed'', to give you a way to tune these decisions.)

The value is measured in baud.
@end defvar

  If you are running across a network, and different parts of the
network work at different baud rates, the value returned by Emacs may be
different from the value used by your local terminal.  Some network
protocols communicate the local terminal speed to the remote machine, so
that Emacs and other programs can get the proper value, but others do
not.  If Emacs has the wrong value, it makes decisions that are less
than optimal.  To fix the problem, set @code{baud-rate}.

@defun baud-rate
This function returns the value of the variable @code{baud-rate}.  In
Emacs versions 18 and earlier, this was the only way to find out the
terminal speed.
@end defun

@defun send-string-to-terminal string
This function sends @var{string} to the terminal without alteration.
Control characters in @var{string} have terminal-dependent effects.

One use of this function is to define function keys on terminals that
have downloadable function key definitions.  For example, this is how on
certain terminals to define function key 4 to move forward four
characters (by transmitting the characters @kbd{C-u C-f} to the
computer):

@example
@group
(send-string-to-terminal "\eF4\^U\^F")
     @result{} nil
@end group
@end example
@end defun

@deffn Command open-termscript filename
@cindex termscript file
This function is used to open a @dfn{termscript file} that will record
all the characters sent by Emacs to the terminal.  It returns
@code{nil}.  Termscript files are useful for investigating problems
where Emacs garbles the screen, problems that are due to incorrect
Termcap entries or to undesirable settings of terminal options more
often than to actual Emacs bugs.  Once you are certain which characters
were actually output, you can determine reliably whether they correspond
to the Termcap specifications in use.

See also @code{open-dribble-file} in @ref{Terminal Input}.

@example
@group
(open-termscript "../junk/termscript")
     @result{} nil
@end group
@end example
@end deffn

@node Special Keysyms
@section System-Specific X11 Keysyms

To define system-specific X11 keysyms, set the variable
@code{system-key-alist}.

@defvar system-key-alist
This variable's value should be an alist with one element for each
system-specific keysym.  An element has this form: @code{(@var{code}
. @var{symbol})}, where @var{code} is the numeric keysym code (not
including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
name for the function key.

For example @code{(168 . mute-acute)} defines a system-specific key used
by HP X servers whose numeric code is (1 << 28) + 168.

It is not a problem if the alist defines keysyms for other X servers, as
long as they don't conflict with the ones used by the X server actually
in use.

The variable is always local to the current X terminal and cannot be
buffer-local.  @xref{Multiple Displays}.
@end defvar

@node Flow Control
@section Flow Control
@cindex flow control characters

  This section attempts to answer the question ``Why does Emacs choose
to use flow-control characters in its command character set?''  For a
second view on this issue, read the comments on flow control in the
@file{emacs/INSTALL} file from the distribution; for help with Termcap
entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.

@cindex @kbd{C-s}
@cindex @kbd{C-q}
  At one time, most terminals did not need flow control, and none used
@code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
Emacs, for economy of keystrokes and portability, used nearly all the
@sc{ASCII} control characters, with mnemonic meanings when possible;
thus, @kbd{C-s} for search and @kbd{C-q} for quote.

  Later, some terminals were introduced which required these characters
for flow control.  They were not very good terminals for full-screen
editing, so Emacs maintainers did not pay attention.  In later years,
flow control with @kbd{C-s} and @kbd{C-q} became widespread among
terminals, but by this time it was usually an option.  And the majority
of users, who can turn flow control off, were unwilling to switch to
less mnemonic key bindings for the sake of flow control.

  So which usage is ``right'', Emacs's or that of some terminal and
concentrator manufacturers?  This question has no simple answer.

  One reason why we are reluctant to cater to the problems caused by
@kbd{C-s} and @kbd{C-q} is that they are gratuitous.  There are other
techniques (albeit less common in practice) for flow control that
preserve transparency of the character stream.  Note also that their use
for flow control is not an official standard.  Interestingly, on the
model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
and @kbd{C-q} were sent by the computer to turn the punch on and off!

  As X servers and other window systems replace character-only
terminals, this problem is gradually being cured.  For the mean time,
Emacs provides a convenient way of enabling flow control if you want it:
call the function @code{enable-flow-control}.

@defun enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
@end defun

You can use the function @code{enable-flow-control-on} in your
@file{.emacs} file to enable flow control automatically on certain
terminal types.

@defun enable-flow-control-on &rest termtypes
This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
if the terminal type is one of @var{termtypes}.  For example:

@smallexample
(enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
@end smallexample
@end defun

  Here is how @code{enable-flow-control} does its job:

@enumerate
@item
@cindex @sc{cbreak}
It sets @sc{cbreak} mode for terminal input, and tells the operating
system to handle flow control, with @code{(set-input-mode nil t)}.

@item
It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
@kbd{C-^} into @kbd{C-s} and @kbd{C-q}.  Except at its very
lowest level, Emacs never knows that the characters typed were anything
but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
and @kbd{C-^} even when they are input for other commands.
@xref{Translating Input}.
@end enumerate

If the terminal is the source of the flow control characters, then once
you enable kernel flow control handling, you probably can make do with
less padding than normal for that terminal.  You can reduce the amount
of padding by customizing the Termcap entry.  You can also reduce it by
setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
speed when calculating the padding needed.  @xref{Terminal Output}.

@node Batch Mode
@section Batch Mode
@cindex batch mode
@cindex noninteractive use

  The command line option @samp{-batch} causes Emacs to run
noninteractively.  In this mode, Emacs does not read commands from the
terminal, it does not alter the terminal modes, and it does not expect
to be outputting to an erasable screen.  The idea is that you specify
Lisp programs to run; when they are finished, Emacs should exit.  The
way to specify the programs to run is with @samp{-l @var{file}}, which
loads the library named @var{file}, and @samp{-f @var{function}}, which
calls @var{function} with no arguments.

  Any Lisp program output that would normally go to the echo area,
either using @code{message} or using @code{prin1}, etc., with @code{t}
as the stream, goes instead to Emacs's standard error descriptor when
in batch mode.  Thus, Emacs behaves much like a noninteractive
application program.  (The echo area output that Emacs itself normally
generates, such as command echoing, is suppressed entirely.)

@defvar noninteractive
This variable is non-@code{nil} when Emacs is running in batch mode.
@end defvar
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.