From patchwork Wed Oct 26 22:43:47 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Ahelenia_Ziemia=C5=84ska?= X-Patchwork-Id: 11465 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp520772wru; Wed, 26 Oct 2022 15:49:50 -0700 (PDT) X-Google-Smtp-Source: AMsMyM61X9byM+sbCdxHjdC41yj7kXVWb3Ow9x90tjwvdmcL6T3JgGhYr+yjOD7GL74vkpGKGVzw X-Received: by 2002:a17:906:5d04:b0:722:f46c:b891 with SMTP id g4-20020a1709065d0400b00722f46cb891mr39356173ejt.4.1666824579618; Wed, 26 Oct 2022 15:49:39 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1666824579; cv=none; d=google.com; s=arc-20160816; b=R/WNuiDm/WVUgR2K8BzoNef9pxRN1M8qzviX452wpkQjX+rH+J8zMjzkmF6UN0evPB oaYa9QhTRr6/SUu3efdeZfXnU5ekLOBWgXaLGSvtj6WZ3SGKiscRLuclQgkSXFvNexi7 eeGu76HTtb5lJfB5c19ahG/xjLcJNpvIYFBl5yxu7VdbXb2hMpuGSC45JJOSGzW8+BdW P3dSBm5WzDMOkW3DAo0gEj/MsCNUZoAgvhm2FEtvyEEX6TC75iGlNZLssR3uGSu88vkg SppZBWSznVws8Mjhxq2k+Vs7oI6/Rv1Jvqr2utc23iBXIETAQNC0/LTxKn3JKTBl3t1W cfoA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:to:user-agent:in-reply-to:content-disposition :mime-version:references:message-id:subject:cc:from:date :dkim-signature; bh=WIUxEYTuxU0XUcDUkTkuPdp+U1AXicWYDawuH2PBC5M=; b=hNMpFKY2ie22p/rbTK5dO6okcGTdE5hlbOTwkN5A5TELLDZJAVhxmpZGZHay3B983H qLIhYA1zLMRHLLODEieoZmhQL/utHRAJ4Viicsy+Aiw5wzUGULDVwrsO0T+vr+IdvjTY jcVUkAD/mnlSPcxPKFNjwb3Npxdubzuwyz5pI1GaWhvcaWtUp2F4Cl/YXvBAwaEXr6EH 3/D0n42vpzVE12smKL4SbhV7vcAvpUGge6Oxu7o3Mrkvmi4VOPG2nzyov5z1knYLCizH qUMOP0eEpHAmeShi7+vLeKf/j9Ve0gf45tudHCK6HssPMpTnMkIRtze9LSuOzWTAubTR agog== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@nabijaczleweli.xyz header.s=202205 header.b=F1q8fx42; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=nabijaczleweli.xyz Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id dt4-20020a170907728400b0079196245be8si7609628ejc.657.2022.10.26.15.49.15; Wed, 26 Oct 2022 15:49:39 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@nabijaczleweli.xyz header.s=202205 header.b=F1q8fx42; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=nabijaczleweli.xyz Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233975AbiJZWp0 (ORCPT + 99 others); Wed, 26 Oct 2022 18:45:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54772 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233835AbiJZWoI (ORCPT ); Wed, 26 Oct 2022 18:44:08 -0400 Received: from tarta.nabijaczleweli.xyz (unknown [139.28.40.42]) by lindbergh.monkeyblade.net (Postfix) with ESMTP id 94E17137297; Wed, 26 Oct 2022 15:43:49 -0700 (PDT) Received: from tarta.nabijaczleweli.xyz (unknown [192.168.1.250]) by tarta.nabijaczleweli.xyz (Postfix) with ESMTPSA id E13B645F6; Thu, 27 Oct 2022 00:43:48 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=nabijaczleweli.xyz; s=202205; t=1666824228; bh=13bJ3PGATBe6m6ipAKsYnwQ+WdgCATcYlf6DlHJtLe0=; h=Date:From:Cc:Subject:References:In-Reply-To:From; b=F1q8fx42/AZmbNHtLuFj/dM5113GxOWGW5pwkcODKYo2qaQO7gSQMR/M/DX4beNbr X0aHe5+oEsuiEsDgfniB341hoBb6jyXW5D708FGtHxBIERKIIRFM1YuNvBl1+W1RJM OBPCVq0L3g7HNykUTgotrb1VgUMXN5tB/WzWbfx9XhybzJxr7+PX14w1QSet8PfTeS 4CB8GtwZ15gZMVpQvgZuriPZYCF3176PETuL/cCvDNsqkqAim5I8uSke1+xigj2TTm KUy1c0A0TYT8UdXc/gmzwnMKa2Ub5o/qa6We43t43qRegD+K8bUXlpJcYEKOLYJ0nd nZFL/G5QNNmB8cuhF8ijHJQKpx3zWObRDKU0KSEzyV6qU3mQKyCjavVSpODyzo/n7z tocntLoA3HVEECFAyd0tZ17RfZaTimCNR2rSIeEklDtOaZfzikVOvq0E4t9AnX8+3h eY2tbWZ0952k4XZv5E6EuNRSArQljdORXL2rKYX8vgl4r2ujl1xvOUu+IpivR7TiQ8 esNyExYD6ZEXnJV3vF8LzOxzC3oyJeav9WB38/sa0yp1gGKVQixAzoqcZUE/d4dsXP u6LsPqNl2LToe/v9OUlKE7jfeu73E58qh9RCLyyArNs3H+E8hrNoaCyuJlcm0Qi0QR 3CYkiLn/PS2T80cqDgOcl7Uc= Date: Thu, 27 Oct 2022 00:43:47 +0200 From: =?utf-8?b?0L3QsNCx?= Cc: Jonathan Corbet , Federico Vaga , Alex Shi , Yanteng Si , Hu Haowen , Steven Rostedt , Kees Cook , Stefano Zacchiroli , Thorsten Leemhuis , Lukas Bulwahn , Greg Kroah-Hartman , Jiri Slaby , Wu XiangCheng , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc-tw-discuss@lists.sourceforge.net Subject: [PATCH 15/15] Documentation: bury magic-number, now devoid of content Message-ID: <83bd024a7f81492be259a531c407cb017186d745.1666822928.git.nabijaczleweli@nabijaczleweli.xyz> References: <9a453437b5c3b4b1887c1bd84455b0cc3d1c40b2.1666822928.git.nabijaczleweli@nabijaczleweli.xyz> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <9a453437b5c3b4b1887c1bd84455b0cc3d1c40b2.1666822928.git.nabijaczleweli@nabijaczleweli.xyz> User-Agent: NeoMutt/20220429 X-Spam-Status: No, score=1.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FROM_SUSPICIOUS_NTLD, MISSING_HEADERS,PDS_OTHER_BAD_TLD,PDS_RDNS_DYNAMIC_FP,RDNS_DYNAMIC, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.6 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net To: unlisted-recipients:; (no To-header on input) Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1747792250752313946?= X-GMAIL-MSGID: =?utf-8?q?1747792250752313946?= The list is now empty, and we've largely moved away from this approach, and we have better debugging instrumentation nowadays Signed-off-by: Ahelenia Ziemiańska --- Documentation/process/index.rst | 1 - Documentation/process/magic-number.rst | 71 ----------------- .../translations/it_IT/process/index.rst | 1 - .../it_IT/process/magic-number.rst | 77 ------------------- .../translations/zh_CN/process/index.rst | 1 - .../zh_CN/process/magic-number.rst | 60 --------------- .../translations/zh_TW/process/index.rst | 1 - .../zh_TW/process/magic-number.rst | 63 --------------- 8 files changed, 275 deletions(-) delete mode 100644 Documentation/process/magic-number.rst delete mode 100644 Documentation/translations/it_IT/process/magic-number.rst delete mode 100644 Documentation/translations/zh_CN/process/magic-number.rst delete mode 100644 Documentation/translations/zh_TW/process/magic-number.rst diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index d4b6217472b0..a8c0c4bffa47 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -59,7 +59,6 @@ lack of a better place. applying-patches adding-syscalls - magic-number volatile-considered-harmful botching-up-ioctls clang-format diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst deleted file mode 100644 index 5a8c2755ac9c..000000000000 --- a/Documentation/process/magic-number.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _magicnumbers: - -Linux magic numbers -=================== - -This file is a registry of magic numbers which are in use. When you -add a magic number to a structure, you should also add it to this -file, since it is best if the magic numbers used by various structures -are unique. - -It is a **very** good idea to protect kernel data structures with magic -numbers. This allows you to check at run time whether (a) a structure -has been clobbered, or (b) you've passed the wrong structure to a -routine. This last is especially useful --- particularly when you are -passing pointers to structures via a void * pointer. The tty code, -for example, does this frequently to pass driver-specific and line -discipline-specific structures back and forth. - -The way to use magic numbers is to declare them at the beginning of -the structure, like so:: - - struct tty_ldisc { - int magic; - ... - }; - -Please follow this discipline when you are adding future enhancements -to the kernel! It has saved me countless hours of debugging, -especially in the screwy cases where an array has been overrun and -structures following the array have been overwritten. Using this -discipline, these cases get detected quickly and safely. - -Changelog:: - - Theodore Ts'o - 31 Mar 94 - - The magic table is current to Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Now it should be up to date with Linux 2.1.112. Because - we are in feature freeze time it is very unlikely that - something will change before 2.2.x. The entries are - sorted by number field. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Updated the magic table to Linux 2.5.45. Right over the feature freeze, - but it is possible that some new magic numbers will sneak into the - kernel before 2.6.x yet. - - Petr Baudis - - 03 Nov 2002 - - Updated the magic table to Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Magic Name Number Structure File -===================== ================ ======================== ========================================== -===================== ================ ======================== ========================================== diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 8d4e36a07ff4..71adf53bc297 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -56,7 +56,6 @@ perché non si è trovato un posto migliore. applying-patches adding-syscalls - magic-number volatile-considered-harmful clang-format ../riscv/patch-acceptance diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst deleted file mode 100644 index 2fbc1876534a..000000000000 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. include:: ../disclaimer-ita.rst - -:Original: :ref:`Documentation/process/magic-number.rst ` -:Translator: Federico Vaga - -.. _it_magicnumbers: - -I numeri magici di Linux -======================== - -Questo documento è un registro dei numeri magici in uso. Quando -aggiungete un numero magico ad una struttura, dovreste aggiungerlo anche -a questo documento; la cosa migliore è che tutti i numeri magici usati -dalle varie strutture siano unici. - -È **davvero** un'ottima idea proteggere le strutture dati del kernel con -dei numeri magici. Questo vi permette in fase d'esecuzione di (a) verificare -se una struttura è stata malmenata, o (b) avete passato a una procedura la -struttura errata. Quest'ultimo è molto utile - particolarmente quando si passa -una struttura dati tramite un puntatore void \*. Il codice tty, per esempio, -effettua questa operazione con regolarità passando avanti e indietro le -strutture specifiche per driver e discipline. - -Per utilizzare un numero magico, dovete dichiararlo all'inizio della struttura -dati, come di seguito:: - - struct tty_ldisc { - int magic; - ... - }; - -Per favore, seguite questa direttiva quando aggiungerete migliorie al kernel! -Mi ha risparmiato un numero illimitato di ore di debug, specialmente nei casi -più ostici dove si è andati oltre la dimensione di un vettore e la struttura -dati che lo seguiva in memoria è stata sovrascritta. Seguendo questa -direttiva, questi casi vengono identificati velocemente e in sicurezza. - -Registro dei cambiamenti:: - - Theodore Ts'o - 31 Mar 94 - - La tabella magica è aggiornata a Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Ora dovrebbe essere aggiornata a Linux 2.1.112. Dato che - siamo in un momento di congelamento delle funzionalità - (*feature freeze*) è improbabile che qualcosa cambi prima - della versione 2.2.x. Le righe sono ordinate secondo il - campo numero. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Aggiornamento della tabella a Linux 2.5.45. Giusti nel congelamento - delle funzionalità ma è comunque possibile che qualche nuovo - numero magico s'intrufoli prima del kernel 2.6.x. - - Petr Baudis - - 03 Nov 2002 - - Aggiornamento della tabella magica a Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Nome magico Numero Struttura File -===================== ================ ======================== ========================================== -===================== ================ ======================== ========================================== diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index a1a35f88f4ae..300d579b3ad0 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -52,7 +52,6 @@ .. toctree:: :maxdepth: 1 - magic-number volatile-considered-harmful .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst deleted file mode 100644 index f8ec4767bc4e..000000000000 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _cn_magicnumbers: - -.. include:: ../disclaimer-zh_CN.rst - -:Original: :ref:`Documentation/process/magic-number.rst ` - -如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 -以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者:: - - 中文版维护者： 贾威威 Jia Wei Wei - 中文版翻译者： 贾威威 Jia Wei Wei - 中文版校译者： 贾威威 Jia Wei Wei - -Linux 魔术数 -============ - -这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。 - -使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。 - -使用魔术值的方法是在结构的开始处声明的，如下:: - - struct tty_ldisc { - int magic; - ... - }; - -当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，‪这些情况可以被快速地，安全地避免。 - - Theodore Ts'o - 31 Mar 94 - -给当前的Linux 2.1.55添加魔术表。 - - Michael Chastain - - 22 Sep 1997 - -现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。 - - Krzysztof G.Baranowski - - 29 Jul 1998 - -更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。 - - Petr Baudis - - 03 Nov 2002 - -更新魔术表到Linux 2.5.74。 - - Fabian Frederick - - 09 Jul 2003 - -===================== ================ ======================== ========================================== -魔术数名 数字 结构 文件 -===================== ================ ======================== ========================================== -===================== ================ ======================== ========================================== diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index c5c59b4fd595..cb3dea0b78ab 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -54,7 +54,6 @@ .. toctree:: :maxdepth: 1 - magic-number volatile-considered-harmful .. only:: subproject and html diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst deleted file mode 100644 index 0ccc60bee3d6..000000000000 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_magicnumbers: - -.. include:: ../disclaimer-zh_TW.rst - -:Original: :ref:`Documentation/process/magic-number.rst ` - -如果想評論或更新本文的內容，請直接發信到LKML。如果你使用英文交流有困難的話，也可 -以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者:: - - 中文版維護者： 賈威威 Jia Wei Wei - 中文版翻譯者： 賈威威 Jia Wei Wei - 中文版校譯者： 賈威威 Jia Wei Wei - 胡皓文 Hu Haowen - -Linux 魔術數 -============ - -這個文件是有關當前使用的魔術值註冊表。當你給一個結構添加了一個魔術值，你也應該把這個魔術值添加到這個文件，因爲我們最好把用於各種結構的魔術值統一起來。 - -使用魔術值來保護內核數據結構是一個非常好的主意。這就允許你在運行期檢查(a)一個結構是否已經被攻擊，或者(b)你已經給一個例行程序通過了一個錯誤的結構。後一種情況特別地有用---特別是當你通過一個空指針指向結構體的時候。tty源碼，例如，經常通過特定驅動使用這種方法並且反覆地排列特定方面的結構。 - -使用魔術值的方法是在結構的開始處聲明的，如下:: - - struct tty_ldisc { - int magic; - ... - }; - -當你以後給內核添加增強功能的時候，請遵守這條規則！這樣就會節省數不清的調試時間，特別是一些古怪的情況，例如，數組超出範圍並且重新寫了超出部分。遵守這個規則，‪這些情況可以被快速地，安全地避免。 - - Theodore Ts'o - 31 Mar 94 - -給當前的Linux 2.1.55添加魔術表。 - - Michael Chastain - - 22 Sep 1997 - -現在應該最新的Linux 2.1.112.因爲在特性凍結期間，不能在2.2.x前改變任何東西。這些條目被數域所排序。 - - Krzysztof G.Baranowski - - 29 Jul 1998 - -更新魔術表到Linux 2.5.45。剛好越過特性凍結，但是有可能還會有一些新的魔術值在2.6.x之前融入到內核中。 - - Petr Baudis - - 03 Nov 2002 - -更新魔術表到Linux 2.5.74。 - - Fabian Frederick - - 09 Jul 2003 - -===================== ================ ======================== ========================================== -魔術數名 數字 結構 文件 -===================== ================ ======================== ========================================== -===================== ================ ======================== ==========================================