GNU bug report logs - #79932
[PATCH] ; * src/.gdbinit: Document xfmt, a user-defined function.

Previous Next

To reply to this bug, email your comments to 79932 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] ; * src/.gdbinit: Document xfmt, a user-defined function.
Date: Mon, 01 Dec 2025 22:52:19 +0000

[Message part 1 (text/plain, inline)]

This patch adds user documentation for xfmt, accessible as
(gdb) help xfmt
in GDB.

(Adding Daniel as the author of this, for any comments or suggestions)


Eli, there are also other functions which are missing docs, but their meaning is
less clear to me.  If this is explained I can write a patch.
I am looking to document what we have in .gdbinit before adding any
potential helper functions as part of my prototype C/Lisp hybrid debugging.

What do these do?
xprintstr
xgetptr
xgetint
xgetsym

[0001-src-.gdbinit-Document-xfmt-a-user-defined-function.patch (text/x-diff, attachment)]

Message #8 received at 79932 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 79932 <at> debbugs.gnu.org, dancol <at> dancol.org
Subject: Re: bug#79932: [PATCH] ;
 * src/.gdbinit: Document xfmt, a user-defined function.
Date: Thu, 04 Dec 2025 14:38:31 +0200

> Cc: Daniel Colascione <dancol <at> dancol.org>, Eli Zaretskii <eliz <at> gnu.org>
> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Date: Mon, 01 Dec 2025 22:52:19 +0000
> 
> This patch adds user documentation for xfmt, accessible as
> (gdb) help xfmt
> in GDB.
> 
> (Adding Daniel as the author of this, for any comments or suggestions)

Thanks, see my comments below.

> Eli, there are also other functions which are missing docs, but their meaning is
> less clear to me.  If this is explained I can write a patch.
> I am looking to document what we have in .gdbinit before adding any
> potential helper functions as part of my prototype C/Lisp hybrid debugging.
> 
> What do these do?
> xprintstr
> xgetptr
> xgetint
> xgetsym

They are helper commands that are not very useful on their own.  (The
rule of thumb is: if a command is called from several other commands,
it's a helper command.)  I don't think they need to be documented.

> +document xfmt
> +Format $ and print it as a string.
> +Calls into Lisp, then prints within GDB.

I'd say "Format the argument Lisp value using %S as format, and print it."

I'd also add "Works only when an inferior emacs is executing.", as
that is important.

Message #11 received at 79932 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79932 <at> debbugs.gnu.org, dancol <at> dancol.org
Subject: Re: bug#79932: [PATCH] ; * src/.gdbinit: Document xfmt, a
 user-defined function.
Date: Fri, 05 Dec 2025 22:50:57 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Eli, there are also other functions which are missing docs, but their meaning is
>> less clear to me.  If this is explained I can write a patch.
>> I am looking to document what we have in .gdbinit before adding any
>> potential helper functions as part of my prototype C/Lisp hybrid debugging.
>> 
>> What do these do?
>> xprintstr
>> xgetptr
>> xgetint
>> xgetsym
>
> They are helper commands that are not very useful on their own.  (The
> rule of thumb is: if a command is called from several other commands,
> it's a helper command.)  I don't think they need to be documented.

Understood for a user-facing commands.

But here's an idea for another patch - why not describe these helper
commands in a comment for developers, to use for other new commands?
If so please explain their purpose and I might be able to prototype
another patch.


>> +document xfmt
>> +Format $ and print it as a string.
>> +Calls into Lisp, then prints within GDB.
>
> I'd say "Format the argument Lisp value using %S as format, and print it."
>
> I'd also add "Works only when an inferior emacs is executing.", as
> that is important.

OK, revised patch attached for merging.

Presumably, as it's documentation, merging to the emacs-30 branch, or possibly master.

[0001-src-.gdbinit-Document-xfmt-a-user-defined-function.patch (text/x-diff, attachment)]

Message #14 received at 79932 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 79932 <at> debbugs.gnu.org, dancol <at> dancol.org
Subject: Re: bug#79932: [PATCH] ; * src/.gdbinit: Document xfmt, a
 user-defined function.
Date: Sat, 06 Dec 2025 11:33:18 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 79932 <at> debbugs.gnu.org,  dancol <at> dancol.org
> Date: Fri, 05 Dec 2025 22:50:57 +0000
> 
> >> What do these do?
> >> xprintstr
> >> xgetptr
> >> xgetint
> >> xgetsym
> >
> > They are helper commands that are not very useful on their own.  (The
> > rule of thumb is: if a command is called from several other commands,
> > it's a helper command.)  I don't think they need to be documented.
> 
> Understood for a user-facing commands.
> 
> But here's an idea for another patch - why not describe these helper
> commands in a comment for developers, to use for other new commands?
> If so please explain their purpose and I might be able to prototype
> another patch.

Fine by me, see below.

> >> +document xfmt
> >> +Format $ and print it as a string.
> >> +Calls into Lisp, then prints within GDB.
> >
> > I'd say "Format the argument Lisp value using %S as format, and print it."
> >
> > I'd also add "Works only when an inferior emacs is executing.", as
> > that is important.
> 
> OK, revised patch attached for merging.
> 
> Presumably, as it's documentation, merging to the emacs-30 branch, or possibly master.

I installed on master, thanks.

As for the other commands you asked about:

  xprintstr -- helper command to print the text of a Lisp string given
  	       as argument.  Stores the pointer to the C string data
  	       in $data and its length in characters (excluding the
  	       terminating null) in $strsize.  Prints "0" for empty
  	       strings and strings longer than 1000 characters.
  xgetptr -- helper command to get the pointer to the C struct that
  	     holds the data of a Lisp object given as argument, by
  	     removing the GC and type-tag bits.  Stores the result in $ptr.
  xgetint -- helper command to extract the C integer value of a Lisp
  	     fixnum given as argument.  Stores the result in $int.
  xgetsym -- helper command to get the pointer to 'struct Lisp_Symbol'
  	     corresponding to the Lisp object given as argument.
  	     Stores the result in $ptr.

Message #17 received at 79932 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79932 <at> debbugs.gnu.org
Subject: Document Helper functions Re: bug#79932: [PATCH] ; * src/.gdbinit:
 Document xfmt, a user-defined function.
Date: Sat, 06 Dec 2025 23:21:51 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> As for the other commands you asked about:
>
>   xprintstr -- helper command to print the text of a Lisp string given
>   	       as argument.  Stores the pointer to the C string data
>   	       in $data and its length in characters (excluding the
>   	       terminating null) in $strsize.  Prints "0" for empty
>   	       strings and strings longer than 1000 characters.
>   xgetptr -- helper command to get the pointer to the C struct that
>   	     holds the data of a Lisp object given as argument, by
>   	     removing the GC and type-tag bits.  Stores the result in $ptr.
>   xgetint -- helper command to extract the C integer value of a Lisp
>   	     fixnum given as argument.  Stores the result in $int.
>   xgetsym -- helper command to get the pointer to 'struct Lisp_Symbol'
>   	     corresponding to the Lisp object given as argument.
>   	     Stores the result in $ptr.

Here is a patch incorporating your text (with comment formatting).

I also realised I didn't ask about another missing helper function.
xgettype

I find the GDB script unclear, so if you supply an explanation I can
incorporate also.

[0001-src-.gdbinit-Improve-comments-of-.gdbinit-helper-fun.patch (text/x-diff, attachment)]

Message #20 received at 79932 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 79932 <at> debbugs.gnu.org
Subject: Re: Document Helper functions Re: bug#79932: [PATCH] ; * src/.gdbinit:
 Document xfmt, a user-defined function.
Date: Sun, 07 Dec 2025 07:53:18 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 79932 <at> debbugs.gnu.org
> Date: Sat, 06 Dec 2025 23:21:51 +0000
> 
> Here is a patch incorporating your text (with comment formatting).

Thanks.

> I also realised I didn't ask about another missing helper function.
> xgettype

xgettype produces the type of a Lisp_Object, as a value from the
'Lisp_Type' enumeration, and stores it in $type.

> I find the GDB script unclear, so if you supply an explanation I can
> incorporate also.

Most of the complexity in .gdbinit has to do with the Emacs C code and
how Lisp is implemented on the C level, not with GDB scripting.

Message #23 received at 79932 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79932 <at> debbugs.gnu.org
Subject: Re: Document Helper functions Re: bug#79932: [PATCH] ; *
 src/.gdbinit: Document xfmt, a user-defined function.
Date: Sun, 07 Dec 2025 22:06:23 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Jeremy Bryant <jb <at> jeremybryant.net>
>> Cc: 79932 <at> debbugs.gnu.org
>> Date: Sat, 06 Dec 2025 23:21:51 +0000
>> 
>> Here is a patch incorporating your text (with comment formatting).
>
> Thanks.
>
>> I also realised I didn't ask about another missing helper function.
>> xgettype
>
> xgettype produces the type of a Lisp_Object, as a value from the
> 'Lisp_Type' enumeration, and stores it in $type.

OK, additional comment added to the previous patch.
Would you like to merge?

>
>> I find the GDB script unclear, so if you supply an explanation I can
>> incorporate also.
>
> Most of the complexity in .gdbinit has to do with the Emacs C code and
> how Lisp is implemented on the C level, not with GDB scripting.

OK, I'll learn that.

[0001-src-.gdbinit-Improve-comments-of-.gdbinit-helper-fun.patch (text/x-diff, attachment)]

Message #28 received at 79932-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 79932-done <at> debbugs.gnu.org
Subject: Re: Document Helper functions Re: bug#79932: [PATCH] ; *
 src/.gdbinit: Document xfmt, a user-defined function.
Date: Mon, 08 Dec 2025 16:12:44 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 79932 <at> debbugs.gnu.org
> Date: Sun, 07 Dec 2025 22:06:23 +0000
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > xgettype produces the type of a Lisp_Object, as a value from the
> > 'Lisp_Type' enumeration, and stores it in $type.
> 
> OK, additional comment added to the previous patch.
> Would you like to merge?

Done, thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.