@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node System Interface
@item irix
Silicon Graphics Irix system.
+@item nacl
+Google Native Client (@acronym{NaCl}) sandboxing system.
+
@item ms-dos
Microsoft's DOS@. Emacs compiled with DJGPP for MS-DOS binds
@code{system-type} to @code{ms-dos} even when you run it on MS-Windows.
@item windows-nt
Microsoft Windows NT, 9X and later. The value of @code{system-type}
-is always @code{windows-nt}, e.g., even on Windows 7.
+is always @code{windows-nt}, e.g., even on Windows 10.
@end table
cause anything special to happen.
@end defun
+@findex timer-list
+The @code{timer-list} command lists all the currently active timers.
+There's only one command available in the buffer displayed: @kbd{c}
+(@code{timer-list-cancel}) that will cancel the timer on the line
+under point.
+
@node Idle Timers
@section Idle Timers
@cindex idle timers
@defun send-string-to-terminal string &optional terminal
This function sends @var{string} to @var{terminal} without alteration.
Control characters in @var{string} have terminal-dependent effects.
+(If you need to display non-ASCII text on the terminal, encode it
+using one of the functions described in @ref{Explicit Encoding}.)
This function operates only on text terminals. @var{terminal} may be
a terminal object, a frame, or @code{nil} for the selected frame's
terminal. In batch mode, @var{string} is sent to @code{stdout} when
calls @var{function} with no arguments, or @samp{--eval @var{form}}.
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. Similarly, input that would normally come from the
-minibuffer is read from the standard input descriptor.
-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.)
+either using @code{message}, or using @code{prin1}, etc., with
+@code{t} as the stream, goes instead to Emacs's standard descriptors
+when in batch mode: @code{message} writes to the standard error
+descriptor, while @code{prin1} and other print functions write to the
+standard output. Similarly, input that would normally come from the
+minibuffer is read from the standard input descriptor. 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.)
+
+Non-ASCII text written to the standard output or error descriptors is
+by default encoded using @code{locale-coding-system} (@pxref{Locales})
+if it is non-@code{nil}; this can be overridden by binding
+@code{coding-system-for-write} to a coding system of you choice
+(@pxref{Explicit Encoding}).
@defvar noninteractive
This variable is non-@code{nil} when Emacs is running in batch mode.
Several operating systems support watching of filesystems for changes
of files. If configured properly, Emacs links a respective library
-like @file{gfilenotify}, @file{inotify}, or @file{w32notify}
-statically. These libraries enable watching of filesystems on the
-local machine.
+like @file{inotify}, @file{kqueue}, @file{gfilenotify}, or
+@file{w32notify} statically. These libraries enable watching of
+filesystems on the local machine.
It is also possible to watch filesystems on remote machines,
@pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}
Note that the @file{w32notify} library does not report
@code{attribute-changed} events. When some file's attribute, like
permissions or modification time, has changed, this library reports a
-@code{changed} event.
+@code{changed} event. Likewise, the @file{kqueue} library does not
+report reliably file attribute changes when watching a directory.
The @code{stopped} event reports, that watching the file has been
stopped. This could be because @code{file-notify-rm-watch} was called
@group
(write-region "bla" nil "/tmp/foo")
@result{} Event (35025468 created "/tmp/.#foo")
- Event (35025468 changed "/tmp/foo") [2 times]
+ Event (35025468 changed "/tmp/foo")
Event (35025468 deleted "/tmp/.#foo")
@end group
@example
@group
(make-directory "/tmp/foo")
- @result{} nil
+ @result{} Event (35025468 created "/tmp/foo")
@end group
@group
(setq desc
(file-notify-add-watch
"/tmp/foo" '(change) 'my-notify-callback))
- @result{} 35025468
+ @result{} 11359632
@end group
@group
@group
(write-region "bla" nil "/tmp/foo/bla")
- @result{} Event (35025468 created "/tmp/foo/.#bla")
- Event (35025468 created "/tmp/foo/bla")
- Event (35025468 changed "/tmp/foo/bla")
- Event (35025468 changed "/tmp/foo/.#bla")
+ @result{} Event (11359632 created "/tmp/foo/.#bla")
+ Event (11359632 created "/tmp/foo/bla")
+ Event (11359632 changed "/tmp/foo/bla")
+ Event (11359632 deleted "/tmp/foo/.#bla")
@end group
@group
;; Deleting a file in the directory doesn't invalidate the watch.
(delete-file "/tmp/foo/bla")
- @result{} Event (35025468 deleted "/tmp/foo/bla")
+ @result{} Event (11359632 deleted "/tmp/foo/bla")
@end group
@group
(write-region "bla" nil "/tmp/foo/bla")
- @result{} Event (35025468 created "/tmp/foo/.#bla")
- Event (35025468 created "/tmp/foo/bla")
- Event (35025468 changed "/tmp/foo/bla")
- Event (35025468 changed "/tmp/foo/.#bla")
+ @result{} Event (11359632 created "/tmp/foo/.#bla")
+ Event (11359632 created "/tmp/foo/bla")
+ Event (11359632 changed "/tmp/foo/bla")
+ Event (11359632 deleted "/tmp/foo/.#bla")
@end group
@group
;; Deleting the directory invalidates the watch.
+;; Events arrive for different watch descriptors.
(delete-directory "/tmp/foo" 'recursive)
- @result{} Event (35025468 deleted "/tmp/foo/bla")
- Event (35025468 deleted "/tmp/foo")
- Event (35025468 stopped "/tmp/foo")
+ @result{} Event (35025468 deleted "/tmp/foo")
+ Event (11359632 deleted "/tmp/foo/bla")
+ Event (11359632 deleted "/tmp/foo")
+ Event (11359632 stopped "/tmp/foo")
@end group
@group
@item Authentication
Emacs has several functions that deal with passwords, e.g.,
-@code{password-read}. Although these functions do not attempt to
+@code{read-passwd}. @xref{Reading a Password}.
+Although these functions do not attempt to
broadcast passwords to the world, their implementations are not proof
against determined attackers with access to Emacs internals. For
-example, even if Elisp code attempts to scrub a password from
+example, even if Elisp code uses @code{clear-string} to scrub a password from
its memory after using it, remnants of the password may still reside
-in the garbage-collected free list.
+in the garbage-collected free list. @xref{Modifying Strings}.
@item Code injection
Emacs can send commands to many other applications, and applications
should take care that strings sent as operands of these commands are
-not misinterpreted as directives. For example, when sending a shell
+not misinterpreted as directives. For example, when using a shell
command to rename a file @var{a} to @var{b}, do not simply use the
string @code{mv @var{a} @var{b}}, because either file name might start
with @samp{-}, or might contain shell metacharacters like @samp{;}.
Although functions like @code{shell-quote-argument} can help avoid
this sort of problem, they are not panaceas; for example, on a POSIX
platform @code{shell-quote-argument} quotes shell metacharacters but
-not leading @samp{-}. @xref{Shell Arguments}.
+not leading @samp{-}. @xref{Shell Arguments}. Typically it is safer
+to use @code{call-process} than a subshell. @xref{Synchronous
+Processes}. And it is safer yet to use builtin Emacs functions; for
+example, use @code{(rename-file "@var{a}" "@var{b}" t)} instead of
+invoking @command{mv}. @xref{Changing Files}.
@item Coding systems
Emacs attempts to infer the coding systems of the files and network
-connections it accesses. If it makes a mistake, or if the other
-parties to the network connection disagree with Emacs's deductions,
+connections it accesses. @xref{Coding Systems}.
+If Emacs infers incorrectly, or if the other
+parties to the network connection disagree with Emacs's inferences,
the resulting system could be unreliable. Also, even when it infers
correctly, Emacs often can use bytes that other programs cannot. For
-example, although to Emacs the NUL (all bits zero) byte is just a
+example, although to Emacs the null byte is just a
character like any other, many other applications treat it as a string
-terminator and mishandle strings or files containing NUL bytes.
+terminator and mishandle strings or files containing null bytes.
@item Environment and configuration variables
POSIX specifies several environment variables that can affect how
@env{SHELL}, @env{TMPDIR}) need to have properly-configured values in
order to get standard behavior for any utility Emacs might invoke.
Even seemingly-benign variables like @env{TZ} may have security
-implications.
+implications. @xref{System Environment}.
Emacs has customization and other variables with similar
considerations. For example, if the variable @code{shell-file-name}
@code{(file-readable-p "foo.txt")} returns @code{t}, it could be that
@file{foo.txt} is unreadable because some other program changed the
file's permissions between the call to @code{file-readable-p} and now.
+@xref{Testing Accessibility}.
@item Resource limits
When Emacs exhausts memory or other operating system resources, its