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)

shynur
  • 4,065
  • 1
  • 3
  • 23
  • "*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 '23 at 09:19

2 Answers2

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.

shynur
  • 4,065
  • 1
  • 3
  • 23
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.

phils
  • 48,657
  • 3
  • 76
  • 115
  • 1
    But there is a `doc: /* ... */` in the `DEFUN` form. Can C macro process comments? – shynur Mar 29 '23 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 '23 at 10:57
  • So the technique here is something like what I mentioned in my [another comment](https://emacs.stackexchange.com/questions/76542/the-name-of-function-defined-in-c/76543?noredirect=1#comment126743_76542)? – shynur Mar 29 '23 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 '23 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](https://emacs.stackexchange.com/questions/76542/76563#76563) is an addendum to yours. – shynur Mar 30 '23 at 02:36