From patchwork Sat Apr 20 09:10:01 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Burgess X-Patchwork-Id: 88792 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id A5DE7384AB5A for ; Sat, 20 Apr 2024 09:10:55 +0000 (GMT) X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 362643858D37 for ; Sat, 20 Apr 2024 09:10:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 362643858D37 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 362643858D37 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713604222; cv=none; b=gY38ksvmugmsjOZjUPeLdYsYqBZLv4AQyY6IjK0dH2DdfVf+y+ti4JqLblQTmLFbSmMpJqDwdSLDcMMBL3UBbY7vhSC8g6HkFC5wx64C5n4E22GdHdiPVIRbC/GEr8j9WLklErVF15n02WownbWOW44NKC/vCRGLycJJ+vn7K34= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713604222; c=relaxed/simple; bh=YX6sUhOODxRnz2wIESJbT7Nd7+O87QH7R2gV877Cd1o=; h=DKIM-Signature:From:To:Subject:Date:Message-Id:MIME-Version; b=PUA8R4MnJxHqgmh0NW9MRznb7WSrOHocR6f+8detrFXlxdFGcrRLYbfgEHf2CqdUAhjiCkO3I9pfKxrZRW0B6EsNI8lwjYXrrSuVjjS15vvVnOV9XN51b0QJmpk6CDjLX5IoSa505aRz9r7pvwMiQNtojz60e798im9ATqRO7gM= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713604219; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=uBJMt6wr+fsjbDf0+oTP5jdH+qGD3rsz+jgquMFasl4=; b=A7/IpDs78tR062Xj+VvsTwzpdyJSG/c4FfTU9b7vHYLCcbFOzqiINpAXpAOmX9elX1SLL2 b2Rb3KKHMk/I5T4suS4weWjzg92qMxrz6s4W0LeAMPMqUcs6CJgyp/2vu69YVom9k1RKO5 awh93hDmx88aDCiXP/jjmQP1a4Zogys= Received: from mail-wr1-f70.google.com (mail-wr1-f70.google.com [209.85.221.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-412--43k_b8kOeem_I5ezEInEQ-1; Sat, 20 Apr 2024 05:10:18 -0400 X-MC-Unique: -43k_b8kOeem_I5ezEInEQ-1 Received: by mail-wr1-f70.google.com with SMTP id ffacd0b85a97d-343da0a889dso2225884f8f.0 for ; Sat, 20 Apr 2024 02:10:18 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713604216; x=1714209016; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=uBJMt6wr+fsjbDf0+oTP5jdH+qGD3rsz+jgquMFasl4=; b=dBrcVkAgkgQvspkpZSDQ/xfNS/do8gLSrxLwzVK4maP1s2WbL0xpaAT5jSqvcGrYEA T8WjsjtmcewLg3FYMScoEz8BSnrK8sVmgLVrPePrjOVcGhLXH/bruTo5JZbe4WWQWu8R 1eWz1M1KVgAwQYLdo2+8ebpUMD1C0NXC5TSZRqfqSbE3tR17k7x8+1H+iQnDP2GHQkWw eS44WT195G85z22Hu3C8jgzGAgOWjHGTce0tjLAyvaWVNZ0x4tHdebF+FGj9DWjw6Jx0 aDzq68nkso8e1M1PgDe/EETUg6NQRt/l8B6EcI5dYfF2eCiETwXCSvhoUMmyo0RfAmEv qdHA== X-Gm-Message-State: AOJu0YxdefDSevt+uRd+H7bN3jJmt0ebq0htF1Pk8dCqzfVGNWAtgb0Z W2TF4gxL2Iq1Iac4j1RLCq8ij2swhWUGV2oFKro/RhByZlC4tDOp1cGlMNTvjlRooBQxrza5GF/ EYcdPdjl10oyf9u4H7oP53f4C71Mj27vdVh4ZU88EGU+u/lmbSvaCMoAt6mHbRiaXKSrKh2TwmW u0udka/Mki8CePROKLQ65XHIZnpmgTgehU5Edff6qrvRM= X-Received: by 2002:adf:ef51:0:b0:349:8010:fbed with SMTP id c17-20020adfef51000000b003498010fbedmr3259623wrp.69.1713604216134; Sat, 20 Apr 2024 02:10:16 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFfuuPm99hVNlrTs3BGMrUnTF7Y6/s5tJvXklarJ1wgD3+6BKICHc6Hfs9mH94V8uw/HW6hkw== X-Received: by 2002:adf:ef51:0:b0:349:8010:fbed with SMTP id c17-20020adfef51000000b003498010fbedmr3259599wrp.69.1713604215402; Sat, 20 Apr 2024 02:10:15 -0700 (PDT) Received: from localhost (92.40.185.25.threembb.co.uk. [92.40.185.25]) by smtp.gmail.com with ESMTPSA id y16-20020a5d4710000000b0033e7de97214sm6402318wrq.40.2024.04.20.02.10.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 20 Apr 2024 02:10:15 -0700 (PDT) From: Andrew Burgess To: gdb-patches@sourceware.org Cc: Andrew Burgess , Lancelot SIX , Eli Zaretskii Subject: [PATCHv2 1/8] gdb/doc: document how filename arguments are formatted Date: Sat, 20 Apr 2024 10:10:01 +0100 Message-Id: <33ee1a27758e76ef6c0185040bdc15e2aea8b6f2.1713603415.git.aburgess@redhat.com> X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-9.6 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_ABUSEAT, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, RCVD_IN_SBL_CSS, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org In the following commits I intend to improve GDB's filename completion. However, how filenames should be completed is a little complex because GDB is not consistent with how it expects filename arguments to be formatted. This commit documents the current state of GDB when it comes to formatting filename arguments. Currently GDB will not correctly complete filenames inline with this documentation; GDB will either fail to complete, or complete incorrectly (i.e. the result of completion will not then be accepted by GDB). However, later commits in this series will fix completion. Reviewed-By: Eli Zaretskii --- gdb/doc/gdb.texinfo | 66 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 82a617e9ad3..abceb9b111b 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1752,6 +1752,7 @@ * Command Syntax:: How to give commands to @value{GDBN} * Command Settings:: How to change default behavior of commands * Completion:: Command completion +* Filename Arguments:: Filenames As Command Arguments * Command Options:: Command options * Help:: How to ask @value{GDBN} for help @end menu @@ -2123,6 +2124,56 @@ @} @end smallexample +@node Filename Arguments +@section Filenames As Command Arguments + +When passing filenames (or directory names) as arguments to a command, +if the filename argument does not include any whitespace, double +quotes, or single quotes, then for all commands the filename can be +written as a simple string, for example: + +@smallexample +(@value{GDBP}) file /path/to/some/file +@end smallexample + +If the filename does include whitespace, double quotes, or single +quotes then @value{GDBN} has two approaches for how these filenames +should be formatted, which format to use depends on which command is +being used. + +Most @value{GDBN} commands don't require, or support, quoting and +escaping. These commands treat any text after the command name, that +is not a command option (@pxref{Command Options}), as the filename, +even if the filename contains whitespace or quote characters. In the +following example the user is adding @w{@file{/path/that contains/two +spaces/}} to the auto-load safe-path (@pxref{add-auto-load-safe-path}): + +@smallexample +(@value{GDBP}) add-auto-load-safe-path /path/that contains/two spaces/ +@end smallexample + +A small number of commands require that filenames containing +whitespace or quote characters are either quoted, or have the special +characters escaped with a backslash. Commands that support this style +are marked as such in the manual, any command not marked as accepting +quoting and escaping of its filename argument, does not accept this +filename argument style. + +For example, to load the file @file{/path/with spaces/to/a file} with +the @code{file} command (@pxref{Files, ,Commands to Specify Files}), +you can escape the whitespace characters with a backslash: + +@smallexample +(@value{GDBP}) file /path/with\ spaces/to/a\ file +@end smallexample + +Alternatively the entire filename can be wrapped in quotes, in which +case no backlsashes are needed, for example: + +@smallexample +(@value{GDBP}) file "/path/with spaces/to/a file" +@end smallexample + @node Command Options @section Command options @@ -21615,6 +21666,9 @@ to run. You can change the value of this variable, for both @value{GDBN} and your program, using the @code{path} command. +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + @cindex unlinked object files @cindex patching object files You can load unlinked object @file{.o} files into @value{GDBN} using @@ -21637,6 +21691,9 @@ if necessary to locate your program. Omitting @var{filename} means to discard information on the executable file. +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + @kindex symbol-file @item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]} Read symbol table information from file @var{filename}. @env{PATH} is @@ -21660,6 +21717,9 @@ @code{symbol-file} does not repeat if you press @key{RET} again after executing it once. +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + When @value{GDBN} is configured for a particular environment, it understands debugging information in whatever format is the standard generated for that environment; you may use either a @sc{gnu} compiler, or @@ -21754,6 +21814,9 @@ @code{add-symbol-file} command any number of times; the new symbol data thus read is kept in addition to the old. +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + Changes can be reverted using the command @code{remove-symbol-file}. @cindex relocatable object files, reading symbols from @@ -21813,6 +21876,9 @@ @code{remove-symbol-file} does not repeat if you press @key{RET} after using it. +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + @kindex add-symbol-file-from-memory @cindex @code{syscall DSO} @cindex load symbols from memory