|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 52475 (0xccfb)
Types: TextFile
Names: »lispref-17«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-17«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Creating a Synchronous Process, Prev: Functions that Create Subprocesses, Up: Processes, Next: Creating an Asynchronous Process
Creating a Synchronous Process
==============================
After a "synchronous process" is created, Emacs waits for the process
to terminate before continuing. Starting `dired' is an example of this:
it runs `ls' in a synchronous process, then modifies the output
slightly. You are not able to type a command until this is finished.
* Function: call-process PROGRAM &optional INFILE BUFFER-OR-NAME DISPLAY &rest ARGS
This function calls PROGRAM in a separate process and waits for
it to finish. It returns `nil'.
The process standard input comes from file INFILE if INFILE is
not `nil' and from `/dev/null' otherwise. The process output gets
inserted in buffer BUFFER-OR-NAME before point if the argument
names a buffer. If BUFFER-OR-NAME is `t', output is sent to the
current buffer; and if BUFFER-OR-NAME is `nil', output is
discarded.
If BUFFER-OR-NAME is 0, the output is discarded and
`call-process' returns immediately. In this case, the process is
not truly synchronous, since it can run in parallel with Emacs; but
since Emacs gets no output from it, you can think of it as that.
Emacs is essentially finished with the subprocess when the function
returns.
If DISPLAY is non-`nil', then `call-process' redisplays the
buffer as output is inserted. Otherwise the function does no
redisplay; you will see the results (put in a buffer) only if and
when Emacs redisplays that buffer.
The remaining arguments, ARGS, are strings that will be supplied
as the command line arguments for the program.
While the `call-process' function waits for PROGRAM to terminate;
if you quit by typing `C-g', the process is killed by sending it a
SIGKILL signal.
The examples below are both run with the buffer `foo' current.
(call-process "pwd" nil t)
=> nil
---------- Buffer: foo ----------
/usr/user/lewis/manual
---------- Buffer: foo ----------
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
=> nil
---------- Buffer: bar ----------
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
---------- Buffer: bar ----------
The `dired-readin' function contains a good example of the use of
`call-process':
(call-process "ls" nil buffer nil dired-listing-switches dirname)
* Function: call-process-region START END PROGRAM &optional DELETE BUFFER-OR-NAME DISPLAY &rest ARGS
This function sends the text between START to END as standard
input to a process running PROGRAM. It deletes the text sent if
DELETE is non-`nil'. You might want to do this if you are going to
insert the output back in the curent buffer.
If BUFFER-OR-NAME names a buffer, the output is inserted in that
buffer at point. If BUFFER-OR-NAME is `t', then the output is sent
to the current buffer. If BUFFER-OR-NAME is `nil', the output is
discarded.
If DISPLAY is non-`nil', then `call-process-region' redisplays
the buffer as output is inserted. Otherwise the function does no
redisplay; you will see the results (put in a buffer) only if and
when Emacs redisplays that buffer.
The remaining arguments, ARGS, are strings that are supplied as
the command line arguments for the program.
The `shell-command-on-region' function uses `call-process-region':
(call-process-region start end
shell-file-name ; Name of program.
nil ; Do not delete region.
buffer ; Send output to BUFFER.
nil ; No redisplay during output.
"-c" command) ; Arguments supplied program.
The `call-process-region' function normally waits for the process
to terminate; but if you quit (for example, by typing `C-g'), the
process is killed.
In the first example below, the `cat' utility is called with
standard input being the first five characters in buffer `foo' (the
word `input'). `cat' copies its standard input into its standard
output. This causes it to be inserted into the buffer. The
function returns `nil'.
---------- Buffer: foo ----------
input
---------- Buffer: foo ----------
(call-process-region 1 6 "cat" nil t)
=> nil
---------- Buffer: foo ----------
inputinput
---------- Buffer: foo ----------
▶1f◀
File: lispref Node: Creating an Asynchronous Process, Prev: Creating a Synchronous Process, Up: Processes, Next: Deleting Processes
Creating an Asynchronous Process
================================
After an "asynchronous process" is created by `start-process', control
returns to Emacs. The process may thereafter run at the same time as
Emacs; and it and Emacs may communicate with each other using the
functions described in following sections.
* Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS
This function creates a new process and starts a program in that
process. The process will be named NAME (modified as necessary to
be unique). The buffer BUFFER-OR-NAME is the buffer to associate
with the process. PROGRAM is the program to run.
The remaining arguments, ARGS, are strings that will be supplied
as the command line arguments for the program.
`start-process' returns the process object created.
The name given to the process is guaranteed to be unique among
processes. It will be the name supplied by the user, or the name
modified (by appending `<1>', `<2>', etc.) if necessary to make it
unique.
In the example below, the first process is started and runs
(well, sleeps) for 100 seconds. Meanwhile, the second process is
started and runs to completion, inserting the directory listing at
the end of the buffer `foo' before the first process finishes.
After the first process finishes, Emacs inserts `Process my-process
finished' at the end of the buffer.
(start-process "my-process" "foo" "sleep" "100")
=> #<process my-process>
(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
=> #<process my-process<1>>
---------- Buffer: foo ----------
total 2
lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
Process my-process<1> finished
Process my-process finished
---------- Buffer: foo ----------
* Variable: process-connection-type
This global variable controls the type of device used to
communicate with subprocesses. If it is `nil', then pipes are
used. If it is `t', then PTYS are used (or pipes if PTYS not
supported---this is determined by the C constant `HAVE_PTYS', which
must be defined when Emacs is compiled.). PTYS are usually
preferable because they allow job control (`C-c, C-z, etc.') to
work between the process and its children whereas pipes do not; the
`shell' command uses PTYS by default.
The value `process-connection-type' is used when `start-process'
is called, so to change it for just one call of `start-process',
temporarily rebind it with `let'.
(let ((process-connection-type nil)) ; use a pipe
(start-process ...))
▶1f◀
File: lispref Node: Deleting Processes, Prev: Creating an Asynchronous Process, Up: Processes, Next: Process Information
Deleting Processes
==================
* Variable: delete-exited-processes
This global variable determines when exited processes will be
deleted. If it is `nil', then they will not be deleted until
`list-processes' is run; otherwise, they will be deleted
immediately after they exit.
* Function: delete-process NAME
This function deletes the process associated with NAME. NAME may
be a process, the name of a process, a buffer, or the name of a
buffer. The subprocess is killed with a `SIGHUP' signal.
(delete-process "*shell*")
=> nil
* Function: process-kill-without-query PROCESS
This function declares that Emacs need not query the user if
PROCESS is still running when Emacs is exited. It returns `t'.
(process-kill-without-query (get-process "shell"))
=> t
▶1f◀
File: lispref Node: Process Information, Prev: Deleting Processes, Up: Processes, Next: Sending Input to Processes
Process Information
===================
Several functions return information about processes. `list-processes'
is provided for interactive use.
* Command: list-processes
This command displays a listing of all living processes. (Any
processes listed as Exited or Signaled are actually eliminated
after the listing is made.) This function returns `nil'.
* Function: process-list
This function returns a list of all processes that are still
alive.
(process-list)
=> (#<process display-time> #<process shell>)
* Function: get-process NAME
This function returns the process named NAME, or `nil' if there
is none. It is an error if NAME is not a string.
(get-process "shell")
=> #<process shell>
* Variable: mode-line-process
This buffer-local variable contains the mode line information on
process status. It is displayed immediately following the major
mode name, with no intervening space. For example, its value in
the `*shell*' buffer is `(": %s")', which allows the shell to
display its status along with the major mode as: `(Shell: run)'.
Normally this variable is `nil'.
* Function: process-command PROCESS
This function returns the command that was executed to start
PROCESS. This is a list of strings, the first string being the
program executed and the rest of the strings being the arguments
given to it.
(process-command (get-process "shell"))
=> ("/bin/csh" "-i")
* Function: process-exit-status PROCESS
This function returns the exit status of PROCESS or the signal
number that killed it. If PROCESS has not yet exited or died, the
value is 0.
* Function: process-id PROCESS
This function returns the process id of PROCESS. This is the PID
of the Unix process which PROCESS refers to.
* Function: process-mark PROCESS
This function returns the marker which indicates the end of the
last output from PROCESS into its buffer (*Note Process Buffers::).
This marker controls where additional output from the process will
be inserted. Usually, it will be at the end of the buffer.
If PROCESS does not insert its output into a buffer, then
`process-mark' returns a marker that points nowhere.
* Function: process-name PROCESS
This function returns the name of PROCESS.
* Function: process-status PROCESS-NAME
This function returns the status of PROCESS-NAME as a symbol.
PROCESS-NAME must be either a process or a string. If it is a
string, it need not name an actual process.
The possible values are:
`run'
for a process that is running.
`stop'
for a process that is stopped but continuable.
`exit'
for a process that has exited.
`signal'
for a process that has received a fatal signal.
`nil'
if PROCESS-NAME does not exist.
(process-status "shell")
=> run
(process-status "never-existed")
=> nil
x
=> #<process xx<1>>
(process-status x)
=> exit
For a network stream, `process-status' returns the symbols `open'
or `closed'. The latter means that the other side closed the
connection, or Emacs did `delete-process'.
▶1f◀
File: lispref Node: Sending Input to Processes, Prev: Process Information, Up: Processes, Next: Sending Signals to Processes
Sending Input to Processes
==========================
Asynchronous subprocesses receive input when it is sent to them by
Emacs. This is done by calling one of the functions in this section.
You must specify the process to send input to, and the input. The data
you send appears on the ``standard input'' of the subprocess.
The kernel may fail if you send more characters than it will hold in
an input buffer. If necessary, use a temporary file, and send a program
to read it.
* Function: process-send-string PROCESS-NAME STRING
This function sends PROCESS-NAME the contents of STRING as
standard input. PROCESS-NAME must be a process or the name of one.
The function returns `nil'.
(process-send-string "shell<1>" "ls\n")
=> nil
---------- Buffer: *shell* ----------
...
introduction.texinfo syntax-tables.texinfo~
introduction.texinfo~ text.texinfo
introduction.txt text.texinfo~
...
---------- Buffer: *shell* ----------
* Command: process-send-region PROCESS-NAME START END
This function sends the text in the region defined by START and
END as standard input to PROCESS-NAME, which is a process or a
process name.
It is an error unless both START and END are integers or markers
that indicate positions in the current buffer. It is unimportant
which number is larger.
* Function: process-send-eof &optional PROCESS-NAME
This function makes PROCESS-NAME see an end-of-file in its input.
The EOF comes after any text already sent to it.
If PROCESS-NAME is not supplied, or if it is `nil', then this
function send the EOF to the current buffer's process. It is an
error if the current buffer has no process.
The function returns PROCESS-NAME.
(process-send-eof "shell")
=> "shell"
▶1f◀
File: lispref Node: Sending Signals to Processes, Prev: Sending Input to Processes, Up: Processes, Next: Receiving Information from Processes
Sending Signals to Processes
============================
"Sending a signal" to a subprocess is a way of interrupting its
activities. There are several different signals, each with its own
meaning. For example, the signal `SIGINT' means that the user has typed
`C-c', or that some analogous thing has happened.
Each signal has a standard effect on the subprocess. Most signals
kill the subprocess, but some stop execution or resume execution
instead. Some programs handle certain signals and non-standard things.
The set of signals and their names is defined by the operating system;
Emacs has facilities for sending only a few of the signals that are
defined.
Emacs can send signals only to its own subprocesses. This is done
with the functions below, or automatically: killing a buffer sends a
`SIGHUP' signal to all its associated processes; killing Emacs sends a
`SIGHUP' signal to all remaining processes. (`SIGHUP' is a signal that
usually indicates that the user hung up the phone.)
Each of the signal-sending functions takes two optional arguments:
PROCESS-NAME and CURRENT-GROUP.
The argument PROCESS-NAME must be either a process, the name of one,
or `nil'. If it is `nil', the process defaults to the process
associated with the current buffer. It is an error if PROCESS-NAME does
not identify a process.
The argument CURRENT-GROUP is a flag which makes a difference when you
are running a job-control shell as an Emacs subprocess. If it is
non-`nil', then the signal is sent to the current process-group of the
terminal which Emacs uses to communicate with the subprocess. If the
process is a job-control shell, this means the shell's current subjob.
If it is `nil', the signal is sent to the process group of the immediate
subprocess of Emacs. If the subprocess is a job-control shell, this is
the shell itself.
The flag CURRENT-GROUP has no effect when a pipe is used to
communicate with the subprocess, because the operating system does not
support the distinction in the case of pipes. For the same reason,
job-control shells won't work when a pipe is used. See
`process-connection-type' in *Note Creating an Asynchronous Process::.
* Function: interrupt-process &optional PROCESS-NAME CURRENT-GROUP
This function interrupts the process PROCESS-NAME by sending the
Unix signal `SIGINT'. When you are not in Emacs, typing the
``interrupt character'' (usually `C-c' on Berkeley Unix) sends this
signal.
When the argument CURRENT-GROUP is non-`nil', you can think of this
function as ``typing `C-c''' on the terminal by which Emacs talks
to the subprocess.
* Function: kill-process &optional PROCESS-NAME CURRENT-GROUP
This function kills the process PROCESS-NAME by sending the Unix
signal `SIGKILL'. This signal kills the subprocess immediately; it
cannot be handled by the subprocess.
* Function: quit-process &optional PROCESS-NAME CURRENT-GROUP
This function sends the Unix signal `SIGQUIT' to the process
PROCESS-NAME. This signal is the one sent by the ``quit
character'' (usually `C-b' or `C-\') when you are not inside Emacs.
* Function: stop-process &optional PROCESS-NAME CURRENT-GROUP
This function stops the process PROCESS-NAME by sending the Unix
signal `SIGTSTP'. Use `continue-process' to resume its execution.
On systems with job control, the ``stop character'' (usually
`C-z') sends this signal (when you are not inside Emacs). When
CURRENT-GROUP is non-`nil', you can think of this function as
``typing `C-z''' on the terminal Emacs uses to communicate with the
subprocess.
* Function: continue-process &optional PROCESS-NAME CURRENT-GROUP
This function causes the process PROCESS to be continued by
sending the Unix signal `SIGCONT'. This presumes that PROCESS-NAME
was stopped previously.
▶1f◀
File: lispref Node: Receiving Information from Processes, Prev: Sending Signals to Processes, Up: Processes, Next: Subprocess Functions for VMS
Receiving Information from Processes
====================================
There are three ways to receive information asynchronously from a
process; two are for standard output and the third is for the process
status. It is important to note that the filter and sentinel functions
are only called when Emacs is waiting for something; they never run
while other Lisp code is running. Similarly, output is only inserted in
an associated buffer when Emacs is waiting.
You may explicitly cause Emacs to wait by calling `sit-for',
`sleep-for', or `accept-process-output'. Emacs also waits in the
command loop for the next key command.
All sentinels and filters that do regexp searching or matching should
save and restore the match data. Otherwise, a sentinel that runs during
a call to `sit-for' might clobber the match data of the program that
called `sit-for'. *Note Match Data::.
* Function: accept-process-output &optional PROCESS
This function allows pending output from any processes to be read
by Emacs. It is read into the process buffers or given to their
filter functions. If PROCESS is non-`nil' then this function does
not return until some output has been received from that process.
* Function: waiting-for-user-input-p
This function returns non-`nil' if Emacs is waiting for keyboard
input from the user, `nil' if it is not. This is intended for use
by asynchronous process output filters and sentinels.
* Menu:
* Process Filters::
* Process Buffers::
* Process Sentinels::
▶1f◀
File: lispref Node: Process Filters, Prev: Receiving Information from Processes, Up: Receiving Information from Processes, Next: Process Buffers
Process Filters
---------------
A "process filter" is a function that receives the standard output
from the associated process. If a process has a filter, then *all*
standard output from that process will be sent to the filter rather than
be inserted into a buffer or discarded.
A filter function runs onlywhile Emacs is waiting.
A filter function must accept two arguments: the associated process
and a string, which is the output. The function is then free to do
whatever it chooses to with the output.
The output to the function may come in any sized chunks. A Unix
command that produces the same output twice in a row may send it as one
string of 200 characters one time, and five strings of 40 characters the
next.
* Function: set-process-filter PROCESS FILTER
This function gives PROCESS the filter function FILTER. If
FILTER is `nil', then the process will have no filter.
(defun keep-output (process output)
(setq kept (cons output kept)))
=> keep-output
(setq kept nil)
=> nil
(set-process-filter (get-process "shell") 'keep-output)
=> keep-output
(process-send-string "shell" "ls ~/other\n")
=> nil
kept
=> ("lewis@slug[8] % "
"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
address.txt backup.psf kolstad.psf
backup.bib~ david.mss resume-Dec-86.mss~
backup.err david.psf resume-Dec.psf
backup.mss dland syllabus.mss
"
"#backups.mss# backup.mss~ kolstad.mss
")
;; Insert input in the buffer specified by `my-shell-buffer'
;; and make sure that buffer is shown in some window.
(defun my-process-filter (proc str)
(let ((cur (selected-window))
(pop-up-windows t))
(pop-to-buffer my-shell-buffer)
(goto-char (point-max))
(insert str)
(set-marker (process-mark proc) (point-max))
(select-window cur)))
* Function: process-filter PROCESS
This function returns the filter function of PROCESS, or `nil' if
has none.
▶1f◀
File: lispref Node: Process Buffers, Prev: Process Filters, Up: Receiving Information from Processes, Next: Process Sentinels
Process Buffers
---------------
The buffer that a process is associated with is where the standard
output from that process will be inserted (if the process does not have
a filter function). Output is always inserted at the `process-mark'
(*Note Process Information::), which is then updated to point to the end
of the text just inserted. Often, the `process-mark' will be at the end
of the buffer.
* Function: set-process-buffer PROCESS BUFFER
This function sets the buffer associated with PROCESS to BUFFER.
If BUFFER is `nil', then the process will not be associated with
any buffer at all.
* Function: process-buffer PROCESS
This function returns the buffer PROCESS is associated with.
(process-buffer (get-process "shell"))
=> #<buffer *shell*>
* Function: get-buffer-process BUFFER-OR-NAME
This function returns the process associated with BUFFER-OR-NAME.
If there are several processes associated with it, then one is
chosen. (Presently, the one chosen is the one most recently
created.) Normally, you should avoid having more than one process
with the same buffer.
(get-buffer-process "*shell*")
=> #<process shell>
If the process's buffer is killed, the actual child process is
killed with a `SIGHUP' signal (*Note Sending Signals to
Processes::).
▶1f◀
File: lispref Node: Process Sentinels, Prev: Process Buffers, Up: Receiving Information from Processes
Process Sentinels
-----------------
A "process sentinel" is a function that is called whenever the
associated process changes status. This includes anything that
terminates, stops, or continues the process; and the "process sentinel"
is called if the process exits on its own. The sentinel is called with
two arguments: the process for which the event occurred, and a string
describing the type of event.
The string describing the event looks like one of the following:
A sentinel is called for any signal that Emacs finds out about (anything
fatal or that stops the process). A sentinel is also called if Emacs
sends a `SIGCONT' signal to a process.
* Function: set-process-sentinel PROCESS SENTINEL
This function associates SENTINEL with PROCESS. If SENTINEL is
`nil', then the process will have no sentinel. The default
behavior when there is no sentinel is to insert a message in the
process's buffer.
(defun msg-me (process event)
(princ
(format "Process: %s had the event `%s'" process event)))
(set-process-sentinel (get-process "shell") 'msg-me)
=> msg-me
(kill-process (get-process "shell"))
=> Process: #<process shell> had the event `killed'
=> #<process shell>
* Function: process-sentinel PROCESS
This function returns the sentinel of PROCESS, or `nil' if it has
none.
▶1f◀
File: lispref Node: Subprocess Functions for VMS, Prev: Receiving Information from Processes, Up: Processes, Next: TCP
Subprocess Functions for VMS
============================
The ordinary subprocess functions do not work on VMS. Instead, these
are available.
* Function: default-subprocess-input-handler
This function is the default input handler for input from spawned
subprocesses.
* Function: send-command-to-subprocess NAME COMMAND
This function sends the string COMMAND to a VMS subprocess named
NAME.
* Function: spawn-subprocess
This function spawns an asynchronous VMS subprocess for command
processing.
* Function: stop-subprocess PROCESS-NAME
This function stops a VMS subprocess named NAME.
▶1f◀
File: lispref Node: TCP, Prev: Subprocess Functions for VMS, Up: Processes
TCP
===
This is how you can open a network connection to any program or server
that might be listening. This much like communication with a subprocess
except that the process is not a chile of Emacs and it must already
exist. The connection is represented by a process object, just like an
ordinary subprocess. You can distinguish connections from subprocesses
using `process-status'.
Input and output work as for subprocesses; `delete-process' closes the
connection.
* Function: open-network-stream NAME BUFFER HOST SERVICE
This function opens a TCP connection for a service to a host. It
returns a subprocess-object to represent the connection.
The NAME argument is the name for the `process'. It is modified
if necessary to make it unique.
The BUFFER-OR-NAME argument is the buffer to associate with the
connection. Output from the connection goes at end of the buffer,
unless you specify an output stream or filter function to handle
the output. BUFFER-OR-NAME may be also `nil', which means that the
connection is not associated with any buffer
SERVICE is name of the service desired, or an integer specifying a
port number to connect to.
▶1f◀
File: lispref Node: Operating System Interface, Prev: Processes, Up: Top, Next: Emacs Display
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.
*Note Building Emacs::, *Note Emacs Display::,
* Menu:
* When Emacs Starts Up::
* Getting out of Emacs::
* Operating System Environment::
* Terminal Input::
* Terminal Output::
* Flow Control::
* Variable: noninteractive
When Emacs is running in batch mode (without an interactive
terminal), then this variable is non-`nil'.
▶1f◀
File: lispref Node: When Emacs Starts Up, Prev: Operating System Interface, Up: Operating System Interface, Next: Getting out of Emacs
When Emacs Starts Up
====================
The order of operations performed by Emacs when it is started up (by
`startup.el') is as follows:
1. Read command line switches.
2. Load `.emacs' unless `-q' specified on command line.
3. Load `default.el' unless `inhibit-default-init' is non-`nil'.
4. Load terminal specific file.
5. Run `term-setup-hook'.
6. Run `window-setup-hook'.
7. Display copyleft information, unless `inhibit-startup-message' is
non-`nil'.
8. Process remaining command line arguments.
* Menu:
* Init File::
* Terminal-specific Initialization::
* Command Line Arguments::
* User Option: inhibit-startup-message
This global variable inhibits the initial startup messages (the
non-warranty etc.). If it is non-`nil', then the messages are not
printed. This is for use in your personal init file, once you are
familiar with the contents of the startup message.
▶1f◀
File: lispref Node: Init File, Prev: When Emacs Starts Up, Up: When Emacs Starts Up, Next: Terminal-specific Initialization
The Init File: .emacs
---------------------
When you start Emacs, it normally attempts to load the `.emacs' file
from your home directory. This file, if it exists, must contain Lisp
code. It is called your "init file". The command line switches `-q'
and `-u' can be used to tell Emacs whether to load an init file. (The
`-q' switch tells Emacs not to load your init file; and the `-u' switch
tell Emacs to load a named user's init file instead of yours.) (*Note
Entering Emacs: (emacs)Entering Emacs).
Emacs may also have a "default init file", which is the library named
`default.el'. (A Lisp library is a file containing Lisp function
definitions and other code.) Emacs finds the `default.el' file through
the standard search path for libraries. The Emacs distribution does not
have any such file; you may create one at your site for local
customizations. If the default init file exists, it is loaded whenever
you start Emacs. But your own personal init file, if any, is loaded
first; if it sets `inhibit-default-init' to a non-`nil' value, then
Emacs will not load the `default.el' file.
If you have a large amount of code in your `.emacs' file, you should
move it into another file named `SOMETHING.el', byte-compile it (*Note
Byte Compilation::), and make your `.emacs' file load the other file
using `load' (*Note Loading::).
*Note Init File Examples: (emacs)Init File Examples, for examples of
how to make various commonly desired customizations in your `.emacs'
file.
* User Option: inhibit-default-init
This global variable prevents Emacs from loading the default
initialization library file for your session of Emacs. If its
value is non-`nil', then the default library is not loaded. The
default value is `nil'.
▶1f◀
File: lispref Node: Terminal-specific Initialization, Prev: Init File, Up: When Emacs Starts Up, Next: Command Line Arguments
Terminal-specific Initialization
--------------------------------
Each terminal type can have its own Lisp library that Emacs will load
when run on that type of terminal. For a terminal type named TERMTYPE,
the library is called `term/TERMTYPE'. Emacs find the file by searching
the `load-path' directories as it does for other files and trying the
`.elc' and `.el' suffixes. Normally, terminal-specific Lisp library is
located in `emacs/lisp/term', a subdirectory of the `emacs/lisp'
directory in which most Emacs Lisp libraries are kept.
The library's name is constructed by concatenating the value of the
variable `term-file-prefix' and the terminal type.
The usual purpose of a terminal-specific library is to define the
escape sequences used by a terminal's function keys.
Function keys are handled by a two-level process. The first level is
dependent and the specific type of terminal and maps Emacs's input
sequences to the function keys that they represent. The second level is
independent of terminal type and is customized by users; function keys
are mapped into meanings at this level. The terminal-specific library
handles the first level of the process and the library `keypad.el'
handles the second level of mapping.
See the file `term/vt100.el' for an example of of a terminal-specific
library.
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 `aaa-48' and `aaa-30-rv' both use the
`term/aaa' library. If necessary, the library can evaluate `(getenv
"TERM")' to find the full name of the terminal type.
Your `.emacs' file can prevent the loading of the terminal-specific
library by setting `term-file-prefix' to `nil'. This feature is very
useful for when you experimenting with your own peculiar customizations;
but a more elegant long-term mechanism for handling your own
customizations is to include a value for `term-setup-hook' in your
`.emacs'.
If it is not `nil', Emacs calls the value of the variable
`term-setup-hook' as a function of no arguments at the end of Emacs
initialization, after Emacs has already loaded both your `.emacs' file
and any terminal-specific libraries. You can set the value of the
`term-setup-hook' variable in your `.emacs' file to override part of any
of the terminal-specific libraries and to define initializations for
terminals that do not have a library.
* Variable: term-file-prefix
If the `term-file-prefix' global variable is non-`nil', Emacs
loads your `.emacs' file and the default initialization file and
then evaluates the following expression:
(load (concat term-file-prefix (getenv"TERM")))
You may set the `term-file-prefix' variable to `nil' in your
`.emacs' file if you do not wish to load the
terminal-initialization file. (To do this, put the following in
your `.emacs' file: `(setq term-file-prefix nil)'.)
* Variable: term-setup-hook
The value of this variable is either `nil' or that of a function
that Emacs calls after loading your `.emacs' file, the default
initialization file (if any) and after loading terminal-specific
lisp code. The value of `term-setup-hook' is called with no
arguments.
The expression in `startup.el' is
(and term-setup-hook (funcall term-setup-hook))
To prevent the hook from being run twice, `term-setup-hook' is
set to `nil' after it is used.
You can use `term-setup-hook' to override the definitions made by
a terminal-specific file.
* Variable: window-setup-hook
The value of the `window-setup-hook' variable is either `nil' or
that of a function that Emacs calls after loading your `.emacs'
file, the default initialization file (if any), after loading
terminal-specific lisp code, and after calling `term-setup-hook'.
`window-setup-hook' is called with no arguments.
▶1f◀
File: lispref Node: Command Line Arguments, Prev: Terminal-specific Initialization, Up: When Emacs Starts Up
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 needed. As a practical matter,
it is best to avoid them. They exist to permit you to do several
sophisticated actions and for compatibility with other editors.
(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.)
* Function: command-line
This function parses the command line which Emacs was called
with, processes it, loads the user's `.emacs' file and displays the
initial warranty information, etc.
* Variable: command-line-processed
The value of this variable is `t' once the command line has been
processed.
* Variable: command-switch-alist
The value of this variable is an alist of user-defined
command-line switches and associated handler functions. This
variable exists so you can add elements to it.
A "command line switch" is an argument on the command line of the
form:
-SWITCH-STRING
The elements of the `command-switch-alist' look like this:
(SWITCH-STRING . HANDLER-FUNCTION)
For each element, the HANDLER-FUNCTION receives the switch name
as its sole argument.
In some cases, the command line switch is followed by an
argument. In these cases, the command-line arguments are in the
variable `command-line-args'.
The command line arguments are parsed by the `command-line-1'
function in the `startup.el' file. Also, *Note Command Line
Switches and Arguments: (emacs)Command Switches..
* Variable: command-line-args
The value of this variable is the arguments passed by the shell
to Emacs, as a list of strings.
▶1f◀
File: lispref Node: Getting out of Emacs, Prev: When Emacs Starts Up, Up: Operating System Interface, Next: Operating System Environment
Getting out of Emacs
====================
As a practical matter, in everyday use, you seldom quit Emacs---only
when you are about to log out. The rest of the time, you will work in
Emacs or in a shell inside of Emacs. If you do have to leave Emacs
temporarily, it is best to suspend Emacs rather than quit it. (*Note
Suspending Emacs::.)
* Menu:
* Killing Emacs::
* Suspending Emacs::
▶1f◀
File: lispref Node: Killing Emacs, Prev: Getting out of Emacs, Up: Getting out of Emacs, Next: Suspending Emacs
Killing Emacs
-------------
Killing Emacs means ending the execution of the Emacs job. It will
return to its superior process.
All the information in the Emacs, aside from files that are saved, is
lost when the Emacs is killed. Because killing Emacs inadvertently can
lose a lot of work, Emacs will query for confirmation before actually
terminating, if you have files that need saving or subprocesses that are
running.
* Function: kill-emacs &optional NO-QUERY
This function exits the Emacs job and kills it. If NO-QUERY is
supplied and non-`nil', then Emacs will exit directly.
Normally, if there are modified files or if there are running
processes, Emacs will ask the user whether it should *really* exit.
If Emacs is running noninteractively and NO-QUERY is an integer,
then it returns NO-QUERY as the Unix program's exit code.
(kill-emacs)
=> nil
---------- Buffer: Minibuffer ----------
1 modified buffer exists, do you really want to exit? (yes or no) yes
Subprocesses are executing; kill them and exit? (yes or no) no
---------- Buffer: Minibuffer ----------
* Variable: kill-emacs-hook
The value of the `kill-emacs-hook' variable is either `nil' or is
that of a function that Emacs calls whenever `kill-emacs' is
called. The hook is called before anything else is done by
`kill-emacs'.
▶1f◀
File: lispref Node: Suspending Emacs, Prev: Killing Emacs, Up: Getting out of Emacs
Suspending Emacs
----------------
``Suspending Emacs'' means stopping Emacs temporarily and returning
control to its superior, which is usually the shell. This allows you to
resume editing later in the same Emacs job, with the same files, the
same kill ring, the same undo history, and so on. This is very
convenient. As a practical matter, you seldom need to suspend Emacs;
you can do almost all your work inside Emacs or inside a shell inside of
Emacs.
* Function: suspend-emacs STRING
This function stops Emacs and returns to the superior process.
After suspending Emacs, you may still resume Emacs. (This is in
contrast to your situation after killing Emacs.) This function
does nothing if Emacs is running under X windows.
If STRING is non-`nil', its characters are sent to be read as
terminal input by Emacs's superior shell. The characters in STRING
will not be echoed by the superior shell; just the results will
appear.
Before suspending, Emacs examines the symbol `suspend-hook'. If
it is bound, and its value is non-`nil', then the value will be
called as a function of no arguments. Emacs won't be suspended
unless this called function returns `nil'.
After Emacs resumes, the symbol `suspend-resume-hook' will be
examined. If it is bound and non-`nil', then the value will be
called as a function of no arguments. The next redisplay after
resumption will redraw the entire screen, unless `no-redraw-on
recenter' is set (*Note Screen Attributes::).
`suspend-emacs' returns `nil'.
In the example, note that `pwd' is not echoed by the shell after
Emacs is suspended.
(suspend-emacs)
=> nil
(setq suspend-hook
(function (lambda ()
(not (y-or-n-p "Really suspend? ")))))
=> (lambda nil (not (y-or-n-p "Really suspend? ")))
(setq suspend-resume-hook
(function (lambda () (message "Resumed!"))))
=> (lambda nil (message "Resumed!"))
(suspend-emacs "pwd")
=> nil
---------- Buffer: Minibuffer ----------
Really suspend? y
---------- Parent Shell ----------
lewis@slug[23] % /user/lewis/manual
lewis@slug[24] % fg
---------- Echo Area ----------
Resumed!
* Variable: suspend-hook
The value of the `suspend-hook' variable is either `nil', or a
function to be called (with no arguments) before Emacs is suspended
with `suspend-emacs'. Emacs won't be suspended unless the called
function returns `nil'.
* Variable: suspend-resume-hook
The value of the `suspend-resume-hook' variable is either `nil'
or is called as a function after resumption of an Emacs session
that was suspended with `suspend-emacs'.
▶1f◀
File: lispref Node: Operating System Environment, Prev: Getting out of Emacs, Up: Operating System Interface, Next: Terminal Input
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 UID, and so on.
* Variable: system-type
The value of this global variable is a symbol indicating the type
of operating system Emacs is operating on. Here is a table of the
symbols for the operating systems that Emacs can run on up to
version 18.51.
system-type
=> berkeley-unix
`berkeley-unix'
Berkeley BSD 4.1, 4.2, or 4.3
`hpux'
Hewlet Packard release 5.0
`silicon-graphics-unix'
Silicon Graphics Iris 3.5 or 3.6
`rtu'
RTU 3.0, ucb universe
`unisoft-unix'
UniSoft's UniPlus 5.0 or 5.2
`usg-unix-v'
AT&T's System V.0, System V Release 2.0, 2.2, or 3
`vax-vms'
VMS VMS 4.0, 4.2, 4.4
`xenix'
SCO Xenix 386 Release 2.2
We do not wish to add new symbols to make finer distinctions unless
it is absolutely necessary!
* Function: getenv VAR
This function returns the value of the environment variable VAR,
as a string.
(getenv "USER")
=> "lewis"
lewis@slug[10] % printenv
PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
USER=lewis
TERM=ibmapa16
SHELL=/bin/csh
HOME=/user/lewis
* Function: user-login-name
This function returns the name under which the user is logged in.
This is based on the effective UID, not the real UID.
(user-login-name)
=> "lewis"
* Function: user-real-login-name
This function returns the name under which the user logged in.
This is based on the real UID, not the effective UID. This differs
from `user-login-name' only when running with the setuid bit.
* Function: user-full-name
This function returns the full name of the user.
(user-full-name)
=> "Bil Lewis"
* Function: user-real-uid
This function returns the real UID of the user.
(user-real-uid)
=> 19
* Function: user-uid
This function returns the effective UID of the user.
* Function: system-name
This function returns the name of the machine you are running
on.
(system-name)
=> "wheaties.ai.mit.edu"
* Function: current-time-string
This function returns the current time, 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 `substring' to extract pieces of it.
(current-time-string)
=> "Wed Oct 14 22:21:05 1987"
* Function: load-average
This function returns the current 1 minute, 5 minute and 15
minute load averages in a list. The values are intergers that are
100 times the system load averages. (The load averages indicate
the number of processes trying to run.)
(load-average)
=> (68 48 35)
lewis@rocky[5] % uptime
11:55am up 1 day, 19:37, 3 users, load average: 0.69, 0.48, 0.36
* Variable: default-directory
The value of this buffer-local variable is the default directory
for the current buffer. This is always a string ending with a
slash on Unix systems.
default-directory
=> "/user/lewis/manual/"
* Function: setprv PRIVILEGE-NAME &optional SETP GETPRV
This function sets or resets a VMS privilege. The first arg is
the privilege name. The second argument, SETP, is `t' or `nil',
indicating whether the privilege is to be set or reset. Its
default is `nil'. The funtion returns `t' if success, `nil' if
not.
If the third argument, GETPRV, is non-`nil', `setprv' does not
change the privilege, but returns `t' or `nil', depending upon
whether the privilege is already enabled.
▶1f◀
File: lispref Node: Terminal Input, Prev: Operating System Environment, Up: Operating System Interface, Next: Terminal Output
Terminal Input
==============
The terminal input functions and variables keep track of or manipulate
terminal input.
Also, *Note Emacs Display::, for related functions.
* Function: recent-keys
This function returns a string comprising the last 100 characters
read from terminal. These are the last 100 characters read by
Emacs, no exceptions.
(recent-keys)
=> "erminal. These are the last 100 characters read by Emacs, no
exceptions.
@example
(recent-keys)^U^X^E"
* Variable: last-input-char
This global variable is set to the last terminal input character
that was typed (as part of a command or not).
In the example below, a character is read (the character `1',
ASCII `49'). It becomes the value of `last-input-char', while
`C-e' (from the `C-x C-e' command used to evaluate this expression)
remains the value of `last-command-char'.
(progn (print (read-char))
(print last-command-char)
last-input-char)
-| 49
-| 5
=> 49
* Command: open-dribble-file FILENAME
This function opens a "dribble file" named FILENAME. When a
dribble file is open, Emacs copies all keyboard input characters to
that file. (Inserted keyboard macros are not typed on the keyboard
so they are not copied.) The function is normally called only
interactively to debug Emacs input. It returns `nil'. You close
the dribble file by calling this function with an argument of
`nil'.
(open-dribble-file "$j/dribble")
=> nil
See also the `open-termscript' function (*Note Terminal Output::).
* Function: set-input-mode INTERRUPT FLOW
This function sets the mode for reading keyboard input. If
INTERRUPT is non-null, then Emacs uses input interrupts. If it is
`nil', then it uses CBREAK mode.
If FLOW is non-`nil', then Emacs uses XON/XOFF (`C-q', `C-s')
flow control for output to terminal. This has no effect except in
CBREAK mode.
The normal setting is system dependent.
*Note Flow Control::.
* Variable: meta-flag
This global variable tells Emacs if it should treat the 0200 bit
in keyboard input as the Meta bit.
* Variable: keyboard-translate-table
This global variable defines the translate table for keyboard
input. This allows the user to redefine the keys on the keyboard
without changing any command bindings.
If `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 N, character codes N and up are untranslated.
In the example, `keyboard-translate-table' is set to a string of
128 characters. Then the characters `C-s' and `C-\' are swapped
and the characters `C-q' and `C-^' are swapped. After executing
this function, typing `C-\' behaves exactly like typing `C-s' and
vice versa. (*Note Flow Control:: for more information on this
subject.)
(defun evade-flow-control ()
"Replace ^S with ^\ and ^Q with ^^."
(interactive)
(let ((the-table (make-string 128 0)))
(let ((i 0))
(while (< i 128)
(aset the-table i i)
(setq i (1+ i))))
;; Swap ^S and ^\
(aset the-table ?\034 ?\^s)
(aset the-table ?\^s ?\034)
;; Swap ^Q and ^^
(aset the-table ?\036 ?\^q)
(aset the-table ?\^q ?\036)
(setq keyboard-translate-table the-table)))
▶1f◀