/[emacs]/emacs/lispref/functions.texi
ViewVC logotype

Diff of /emacs/lispref/functions.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.19.4.1 by miles, Fri Apr 4 06:20:41 2003 UTC revision 1.19.4.2 by miles, Tue Oct 14 23:10:11 2003 UTC
# Line 22  define them. Line 22  define them.
22  * Function Cells::        Accessing or setting the function definition  * Function Cells::        Accessing or setting the function definition
23                              of a symbol.                              of a symbol.
24  * Inline Functions::      Defining functions that the compiler will open code.  * Inline Functions::      Defining functions that the compiler will open code.
25  * Function safety::       Determining whether a function is safe to call.  * Function Safety::       Determining whether a function is safe to call.
26  * Related Topics::        Cross-references to specific Lisp primitives  * Related Topics::        Cross-references to specific Lisp primitives
27                              that have a special bearing on how functions work.                              that have a special bearing on how functions work.
28  @end menu  @end menu
# Line 57  such as @code{car} or @code{append}.  Th Line 57  such as @code{car} or @code{append}.  Th
57  considered primitives.)  considered primitives.)
58    
59  Usually the reason we implement a function as a primitive is either  Usually the reason we implement a function as a primitive is either
60  because it is fundamental, because it provides a low-level interface to  because it is fundamental, because it provides a low-level interface
61  operating system services, or because it needs to run fast.  Primitives  to operating system services, or because it needs to run fast.
62  can be modified or added only by changing the C sources and recompiling  Primitives can be modified or added only by changing the C sources and
63  the editor.  See @ref{Writing Emacs Primitives}.  recompiling the editor.  See @ref{Writing Emacs Primitives}.
64    
65  @item lambda expression  @item lambda expression
66  A @dfn{lambda expression} is a function written in Lisp.  A @dfn{lambda expression} is a function written in Lisp.
# Line 411  of one or two complete sentences that su Line 411  of one or two complete sentences that su
411  but since these spaces come before the starting double-quote, they are not part of  but since these spaces come before the starting double-quote, they are not part of
412  the string.  Some people make a practice of indenting any additional  the string.  Some people make a practice of indenting any additional
413  lines of the string so that the text lines up in the program source.  lines of the string so that the text lines up in the program source.
414  @emph{This is a mistake.}  The indentation of the following lines is  @emph{That is a mistake.}  The indentation of the following lines is
415  inside the string; what looks nice in the source code will look ugly  inside the string; what looks nice in the source code will look ugly
416  when displayed by the help commands.  when displayed by the help commands.
417    
# Line 423  practice, there is no confusion between Line 423  practice, there is no confusion between
423  documentation string; if the only body form is a string then it serves both  documentation string; if the only body form is a string then it serves both
424  as the return value and as the documentation.  as the return value and as the documentation.
425    
426      The last line of the documentation string can specify calling
427    conventions different from the actual function arguments.  Write
428    text like this:
429    
430    @example
431    (fn @var{arglist})
432    @end example
433    
434    @noindent
435    following a blank line, with no newline following it inside the
436    documentation string.  This feature is particularly useful for
437    macro definitions.
438    
439  @node Function Names  @node Function Names
440  @section Naming a Function  @section Naming a Function
441  @cindex function definition  @cindex function definition
# Line 573  purposes, it is better to use @code{fset Line 586  purposes, it is better to use @code{fset
586  records.  records.
587  @end defun  @end defun
588    
589      You cannot create a new primitive function with @code{defun} or
590    @code{defalias}, but you use them to change the function definition of
591    any symbol, even one such as @code{car} or @code{x-popup-menu} whose
592    normal definition is a primitive.  However, this is risky: for
593    instance, it is next to impossible to redefine @code{car} without
594    breaking Lisp completely.  Redefining an obscure function such as
595    @code{x-popup-menu} is less dangerous, but it still may not work as
596    you expect.  If there are calls to the primitive from C code, they
597    call the primitive's C definition directly, so changing the symbol's
598    definition will have no effect on them.
599    
600    See also @code{defsubst}, which defines a function like @code{defun}    See also @code{defsubst}, which defines a function like @code{defun}
601  and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.  and tells the Lisp compiler to open-code it.  @xref{Inline Functions}.
602    
# Line 1158  do for macros.  (@xref{Argument Evaluati Line 1182  do for macros.  (@xref{Argument Evaluati
1182  Inline functions can be used and open-coded later on in the same file,  Inline functions can be used and open-coded later on in the same file,
1183  following the definition, just like macros.  following the definition, just like macros.
1184    
1185  @node Function safety  @node Function Safety
1186  @section Determining whether a function is safe to call  @section Determining whether a function is safe to call
1187  @cindex function safety  @cindex function safety
1188  @cindex safety of functions  @cindex safety of functions
1189  @cindex virus detection  
1190  @cindex Trojan-horse detection  Some major modes such as SES (@pxref{Top,,,ses}) call functions that
1191  @cindex DDoS attacks  are stored in user files.  User files sometimes have poor
1192    pedigrees---you can get a spreadsheet from someone you've just met, or
1193  Some major modes such as SES (see @pxref{Top,,,ses}) will call  you can get one through email from someone you've never met.  So it is
1194  functions that are stored in user files.  User files sometimes have  risky to call a function whose source code is stored in a user file
1195  poor pedigrees---you can get a spreadsheet from someone you've just  until you have determined that it is safe.
 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.  
1196    
1197  @defun unsafep form &optional unsafep-vars  @defun unsafep form &optional unsafep-vars
1198  Returns nil if @var{form} is a @dfn{safe} lisp expression, or returns  Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1199  a list that describes why it might be unsafe.  The argument  returns a list that describes why it might be unsafe.  The argument
1200  @var{unsafep-vars} is a list of symbols known to have temporary  @var{unsafep-vars} is a list of symbols known to have temporary
1201  bindings at this point; it is mainly used for internal recursive  bindings at this point; it is mainly used for internal recursive
1202  calls.  The current buffer is an implicit argument, which provides a  calls.  The current buffer is an implicit argument, which provides a
# Line 1187  list of buffer-local bindings. Line 1205  list of buffer-local bindings.
1205    
1206  Being quick and simple, @code{unsafep} does a very light analysis and  Being quick and simple, @code{unsafep} does a very light analysis and
1207  rejects many Lisp expressions that are actually safe.  There are no  rejects many Lisp expressions that are actually safe.  There are no
1208  known cases where @code{unsafep} returns nil for an unsafe expression.  known cases where @code{unsafep} returns @code{nil} for an unsafe
1209  However, a ``safe'' Lisp expression can return a string with a  expression.  However, a ``safe'' Lisp expression can return a string
1210  @code{display} property, containing an associated Lisp expression to  with a @code{display} property, containing an associated Lisp
1211  be executed after the string is inserted into a buffer.  This  expression to be executed after the string is inserted into a buffer.
1212  associated expression can be a virus.  In order to be safe, you must  This associated expression can be a virus.  In order to be safe, you
1213  delete properties from all strings calculated by user code before  must delete properties from all strings calculated by user code before
1214  inserting them into buffers.  inserting them into buffers.
1215    
1216    @ignore
1217  What is a safe Lisp expression?  Basically, it's an expression that  What is a safe Lisp expression?  Basically, it's an expression that
1218  calls only built-in functions with no side effects (or only innocuous  calls only built-in functions with no side effects (or only innocuous
1219  ones).  Innocuous side effects include displaying messages and  ones).  Innocuous side effects include displaying messages and
# Line 1209  An atom or quoted thing. Line 1228  An atom or quoted thing.
1228  A call to a safe function (see below), if all its arguments are  A call to a safe function (see below), if all its arguments are
1229  safe expressions.  safe expressions.
1230  @item  @item
1231  One of the special forms [and, catch, cond, if, or, prog1, prog2,  One of the special forms @code{and}, @code{catch}, @code{cond},
1232  progn, while, unwind-protect], if all its arguments are safe.  @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1233    @code{while}, and @code{unwind-protect}], if all its arguments are
1234    safe.
1235  @item  @item
1236  A form that creates temporary bindings [condition-case, dolist,  A form that creates temporary bindings (@code{condition-case},
1237  dotimes, lambda, let, let*], if all args are safe and the symbols to  @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1238  be bound are not explicitly risky (see @pxref{File Local Variables}).  @code{let*}), if all args are safe and the symbols to be bound are not
1239    explicitly risky (see @pxref{File Local Variables}).
1240  @item  @item
1241  An assignment [add-to-list, setq, push, pop], if all args are safe and  An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1242  the symbols to be assigned are not explicitly risky and they already  @code{pop}, if all args are safe and the symbols to be assigned are
1243  have temporary or buffer-local bindings.  not explicitly risky and they already have temporary or buffer-local
1244    bindings.
1245  @item  @item
1246  One of [apply, mapc, mapcar, mapconcat] if the first argument is a  One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1247  safe explicit lambda and the other args are safe expressions.  safe explicit lambda and the other args are safe expressions.
# Line 1231  A lambda containing safe expressions. Line 1254  A lambda containing safe expressions.
1254  @item  @item
1255  A symbol on the list @code{safe-functions}, so the user says it's safe.  A symbol on the list @code{safe-functions}, so the user says it's safe.
1256  @item  @item
1257  A symbol with a non-nil @code{side-effect-free} property.  A symbol with a non-@code{nil} @code{side-effect-free} property.
1258  @item  @item
1259  A symbol with a non-nil @code{safe-function} property.  Value t  A symbol with a non-@code{nil} @code{safe-function} property.  Value t
1260  indicates a function that is safe but has innocuous side effects.  indicates a function that is safe but has innocuous side effects.
1261  Other values will someday indicate functions with classes of side  Other values will someday indicate functions with classes of side
1262  effects that are not always safe.  effects that are not always safe.
# Line 1243  The @code{side-effect-free} and @code{sa Line 1266  The @code{side-effect-free} and @code{sa
1266  provided for built-in functions and for low-level functions and macros  provided for built-in functions and for low-level functions and macros
1267  defined in @file{subr.el}.  You can assign these properties for the  defined in @file{subr.el}.  You can assign these properties for the
1268  functions you write.  functions you write.
   
1269  @end table  @end table
1270    @end ignore
   
 @c Emacs versions prior to 19 did not have inline functions.  
1271    
1272  @node Related Topics  @node Related Topics
1273  @section Other Topics Related to Functions  @section Other Topics Related to Functions
# Line 1309  See @ref{Mapping Functions}. Line 1329  See @ref{Mapping Functions}.
1329  See @ref{Key Lookup}.  See @ref{Key Lookup}.
1330  @end table  @end table
1331    
1332    @ignore
1333       arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2
1334    @end ignore

Legend:
Removed from v.1.19.4.1  
changed lines
  Added in v.1.19.4.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26