3

I tried to use GDB to debug Emacs.
More specifically, I want to observe the behavior of a function written in C.

vertical-motion is a built-in function in ‘C source code’.

However, the name of a C function cannot contain a - (i.e., minus sign).
So GDB will complain when I type break vertical-motion.

I noticed that this function is defined by DEFUN (C macro?), which is weird to me:

DEFUN ("vertical-motion", Fvertical_motion, Svertical_motion, 1, 3, 0,
       doc: /* ... */)
  (Lisp_Object lines, Lisp_Object window, Lisp_Object cur_col)
{ ... }

What is a built-in function's C name?
(including those NOT defined by DEFUN if they exist)

1
  • "C macro?" --- Or Emacs maintainers wrote a pre-processor specifically for Emacs C source code? (That may not be the point. I'm just mentioning it.)
    – shynur
    Mar 29, 2023 at 9:19

2 Answers 2

2

The C function name is Fvertical_motion.

DEFUN is a macro defined in lisp.h. It is used to define C functions which are also visible as lisp functions.

/* Define a built-in function for calling from Lisp.
 `lname' should be the name to give the function in Lisp,
    as a null-terminated C string.
 `fnname' should be the name of the function in C.
    By convention, it starts with F.
 `sname' should be the name for the C constant structure
    that records information on this function for internal use.
    By convention, it should be the same as `fnname' but with S instead of F.
    It's too bad that C macros can't compute this from `fnname'.
 `minargs' should be a number, the minimum number of arguments allowed.
 `maxargs' should be a number, the maximum number of arguments allowed,
    or else MANY or UNEVALLED.
    MANY means there are &rest arguments.  Here we pass a vector
        of evaluated arguments in the form of an integer
        number-of-arguments followed by the address of a vector of
        Lisp_Objects which contains the argument values.  (We also use
        this convention when calling a subr with more than 8 parameters.)
    UNEVALLED means pass the list of unevaluated arguments
 `intspec' says how interactive arguments are to be fetched.
    If the string starts with a `(', `intspec' is evaluated and the resulting
    list is the list of arguments.
    If it's a string that doesn't start with `(', the value should follow
    the one of the doc string for `interactive'.
    A null string means call interactively with no arguments.
 `doc' is documentation for the user.  */

/* This version of DEFUN declares a function prototype with the right
   arguments, so we can catch errors with maxargs at compile-time.  */
#define DEFUN(lname, fnname, sname, minargs, maxargs, intspec, doc) \
...

If you search the C code for Fvertical_motion you will also find many direct calls to that name.

5
  • 1
    But there is a doc: /* ... */ in the DEFUN form. Can C macro process comments?
    – shynur
    Mar 29, 2023 at 10:19
  • 1
    I think that lib-src/make-docfile.c is responsible for extracting those docstring comments. (That's as far as I've ever looked into it, though, and I've only done so just now :)
    – phils
    Mar 29, 2023 at 10:57
  • So the technique here is something like what I mentioned in my another comment?
    – shynur
    Mar 29, 2023 at 11:43
  • 1
    Yes - make-docfile is invoked by a Makefile with all the source files (and more) of Emacs as arguments . It gets all the doc strings that it finds into etc/DOC. The file is read in at Emacs initialization and then describe-function calls documentation to fetch the doc string (which is stored as just an index (a number) in the function). I think this is correct, but caveat emptor.
    – NickD
    Mar 29, 2023 at 15:08
  • The C comment for fname of DEFUN in src/lisp.h may be a little incomplete. In general, it starts with the letter F and uses underscore(s). This is natural, in line with C conventions, but ... for rigor. My answer is an addendum to yours.
    – shynur
    Mar 30, 2023 at 2:36
3

Provide a reference (from the manual) for @phils's answer;
Supplement the conversion convention for the name of the function.

E.7 Writing Emacs Primitives:

Here is a template for them:

DEFUN (lname, fname, sname, min, max, interactive, doc)

lname : This is the name of the Lisp symbol to define as the function name; ...

fname : This is the C function name for this function. This is the name that is used in C code for calling the function. The name is, by convention, ‘F’ prepended to the Lisp name, with all dashes (‘-’) in the Lisp name changed to underscores.


As for the docstrings in the comments, although they may not be relevant, I just make a note here of one point of interest:

The others have placeholders beginning with ‘SKIP’, which are ignored by the function that parses the DOC file.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.