comparison lispref/functions.texi @ 51701:080a8041fef7

(Defining Functions): Explain about redefining primitives. (Function Safety): Renamed. Minor changes. Comment out the detailed criteria for what is safe.

51700:8e56fb9cfe82

* Mapping Functions::     Applying a function to each element of a list, etc.
* Anonymous Functions::   Lambda expressions are functions with no names.
* Function Cells::        Accessing or setting the function definition
                            of a symbol.
* Inline Functions::	  Defining functions that the compiler will open code.
* Function safety::       Determining whether a function is safe to call.
* Related Topics::        Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.
@end menu

@node What Is a Function

such as @code{car} or @code{append}.  These functions are also called
@dfn{built-in} functions or @dfn{subrs}.  (Special forms are also
considered primitives.)

Usually the reason we implement a function as a primitive is either
because it is fundamental, because it provides a low-level interface to
operating system services, or because it needs to run fast.  Primitives
can be modified or added only by changing the C sources and recompiling
the editor.  See @ref{Writing Emacs Primitives}.

@item lambda expression
A @dfn{lambda expression} is a function written in Lisp.
These are described in the following section.
@ifnottex

By contrast, in programs that manipulate function definitions for other
purposes, it is better to use @code{fset}, which does not keep such
records.
@end defun

  See also @code{defsubst}, which defines a function like @code{defun}
and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.

@node Calling Functions
@section Calling Functions

do for macros.  (@xref{Argument Evaluation}.)

Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.

@node Function safety
@section Determining whether a function is safe to call
@cindex function safety
@cindex safety of functions
@cindex virus detection
@cindex Trojan-horse detection
@cindex DDoS attacks

Some major modes such as SES (see @pxref{Top,,,ses}) will call
functions that are stored in user files.  User files sometimes have
poor pedigrees---you can get a spreadsheet from someone you've just
met, or you can get one through email from someone you've never met.
Such files can contain viruses and other Trojan horses that could
corrupt your operating system environment, delete your files, or even
turn your computer into a DDoS zombie!  To avoid this terrible fate,
you should not call a function whose source code is stored in a user
file until you have determined that it is safe.

@defun unsafep form &optional unsafep-vars
Returns nil if @var{form} is a @dfn{safe} lisp expression, or returns
a list that describes why it might be unsafe.  The argument
@var{unsafep-vars} is a list of symbols known to have temporary
bindings at this point; it is mainly used for internal recursive
calls.  The current buffer is an implicit argument, which provides a
list of buffer-local bindings.
@end defun

Being quick and simple, @code{unsafep} does a very light analysis and
rejects many Lisp expressions that are actually safe.  There are no
known cases where @code{unsafep} returns nil for an unsafe expression.
However, a ``safe'' Lisp expression can return a string with a
@code{display} property, containing an associated Lisp expression to
be executed after the string is inserted into a buffer.  This
associated expression can be a virus.  In order to be safe, you must
delete properties from all strings calculated by user code before
inserting them into buffers.

What is a safe Lisp expression?  Basically, it's an expression that
calls only built-in functions with no side effects (or only innocuous
ones).  Innocuous side effects include displaying messages and
altering non-risky buffer-local variables (but not global variables).

An atom or quoted thing.
@item
A call to a safe function (see below), if all its arguments are
safe expressions.
@item
One of the special forms [and, catch, cond, if, or, prog1, prog2,
progn, while, unwind-protect], if all its arguments are safe.
@item
A form that creates temporary bindings [condition-case, dolist,
dotimes, lambda, let, let*], if all args are safe and the symbols to
be bound are not explicitly risky (see @pxref{File Local Variables}).
@item
An assignment [add-to-list, setq, push, pop], if all args are safe and
the symbols to be assigned are not explicitly risky and they already
have temporary or buffer-local bindings.
@item
One of [apply, mapc, mapcar, mapconcat] if the first argument is a
safe explicit lambda and the other args are safe expressions.
@end itemize

@item
A lambda containing safe expressions.
@item
A symbol on the list @code{safe-functions}, so the user says it's safe.
@item
A symbol with a non-nil @code{side-effect-free} property.
@item
A symbol with a non-nil @code{safe-function} property.  Value t
indicates a function that is safe but has innocuous side effects.
Other values will someday indicate functions with classes of side
effects that are not always safe.
@end itemize

The @code{side-effect-free} and @code{safe-function} properties are
provided for built-in functions and for low-level functions and macros
defined in @file{subr.el}.  You can assign these properties for the
functions you write.

@end table


@c Emacs versions prior to 19 did not have inline functions.

@node Related Topics
@section Other Topics Related to Functions

  Here is a table of several functions that do things related to

51701:080a8041fef7

* Mapping Functions::     Applying a function to each element of a list, etc.
* Anonymous Functions::   Lambda expressions are functions with no names.
* Function Cells::        Accessing or setting the function definition
                            of a symbol.
* Inline Functions::	  Defining functions that the compiler will open code.
* Function Safety::       Determining whether a function is safe to call.
* Related Topics::        Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.
@end menu

@node What Is a Function

such as @code{car} or @code{append}.  These functions are also called
@dfn{built-in} functions or @dfn{subrs}.  (Special forms are also
considered primitives.)

Usually the reason we implement a function as a primitive is either
because it is fundamental, because it provides a low-level interface
to operating system services, or because it needs to run fast.
Primitives can be modified or added only by changing the C sources and
recompiling the editor.  See @ref{Writing Emacs Primitives}.

@item lambda expression
A @dfn{lambda expression} is a function written in Lisp.
These are described in the following section.
@ifnottex

By contrast, in programs that manipulate function definitions for other
purposes, it is better to use @code{fset}, which does not keep such
records.
@end defun

  You cannot create a new primitive function with @code{defun} or
@code{defalias}, but you use them to change the function definition of
any symbol, even one such as @code{car} or @code{x-popup-menu} whose
normal definition is a primitive.  However, this is risky: for
instance, it is next to impossible to redefine @code{car} without
breaking Lisp completely.  Redefining an obscure function such as
@code{x-popup-menu} is less dangerous, but it still may not work as
you expect.  If there are calls to the primitive from C code, they
call the primitive's C definition directly, so changing the symbol's
definition will have no effect on them.

  See also @code{defsubst}, which defines a function like @code{defun}
and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.

@node Calling Functions
@section Calling Functions

do for macros.  (@xref{Argument Evaluation}.)

Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.

@node Function Safety
@section Determining whether a function is safe to call
@cindex function safety
@cindex safety of functions

Some major modes such as SES (@pxref{Top,,,ses}) call functions that
are stored in user files.  User files sometimes have poor
pedigrees---you can get a spreadsheet from someone you've just met, or
you can get one through email from someone you've never met.  So it is
risky to call a function whose source code is stored in a user file
until you have determined that it is safe.

@defun unsafep form &optional unsafep-vars
Returns @code{nil} if @var{form} is a @dfn{safe} lisp expression, or
returns a list that describes why it might be unsafe.  The argument
@var{unsafep-vars} is a list of symbols known to have temporary
bindings at this point; it is mainly used for internal recursive
calls.  The current buffer is an implicit argument, which provides a
list of buffer-local bindings.
@end defun

Being quick and simple, @code{unsafep} does a very light analysis and
rejects many Lisp expressions that are actually safe.  There are no
known cases where @code{unsafep} returns @code{nil} for an unsafe
expression.  However, a ``safe'' Lisp expression can return a string
with a @code{display} property, containing an associated Lisp
expression to be executed after the string is inserted into a buffer.
This associated expression can be a virus.  In order to be safe, you
must delete properties from all strings calculated by user code before
inserting them into buffers.

@ignore
What is a safe Lisp expression?  Basically, it's an expression that
calls only built-in functions with no side effects (or only innocuous
ones).  Innocuous side effects include displaying messages and
altering non-risky buffer-local variables (but not global variables).

An atom or quoted thing.
@item
A call to a safe function (see below), if all its arguments are
safe expressions.
@item
One of the special forms @code{and}, @code{catch}, @code{cond},
@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
@code{while}, and @code{unwind-protect}], if all its arguments are
safe.
@item
A form that creates temporary bindings (@code{condition-case},
@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
@code{let*}), if all args are safe and the symbols to be bound are not
explicitly risky (see @pxref{File Local Variables}).
@item
An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
@code{pop}, if all args are safe and the symbols to be assigned are
not explicitly risky and they already have temporary or buffer-local
bindings.
@item
One of [apply, mapc, mapcar, mapconcat] if the first argument is a
safe explicit lambda and the other args are safe expressions.
@end itemize

@item
A lambda containing safe expressions.
@item
A symbol on the list @code{safe-functions}, so the user says it's safe.
@item
A symbol with a non-@code{nil} @code{side-effect-free} property.
@item
A symbol with a non-@code{nil} @code{safe-function} property.  Value t
indicates a function that is safe but has innocuous side effects.
Other values will someday indicate functions with classes of side
effects that are not always safe.
@end itemize

The @code{side-effect-free} and @code{safe-function} properties are
provided for built-in functions and for low-level functions and macros
defined in @file{subr.el}.  You can assign these properties for the
functions you write.
@end table
@end ignore

@node Related Topics
@section Other Topics Related to Functions

  Here is a table of several functions that do things related to