From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.remote-ip=209.85.216.42 ARC-Seal: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; cv=none; t=1793964982; b=b+mbautJ1xqYzB6kMMnXN3HwGtaFeQZsumI5u2UEf0aXeHer7240vO0Hj+Y/NrGUnQ3d 5N+jy4yd8dKsFm4wJ2icsU6zXL3O0vpIBLoS1hYu2zhOH5BK9zFWllKXr7GSKFJ6zQ+Gc xiavSRV3UOIlKx6+xVoghts3cIWNZbB+f8w4LnYu1zqAh0lun1ZTF/WPEYLNA7iA4eTWI VSaxCXiCvjKaXbBJreUvdshihcpoBoXeJq0qxEO7gbIb/MYxMCaLdtMJHTzVIha0tvvD7 ID3sxOre3PgCPY/gxsSAu/OFaw9q93O1Ig50yrSgU1LFj0MuMtw0PyMmz+fyQkj//3Q== ARC-Message-Signature: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; c=relaxed/relaxed; t=1793964982; h=DMARC-Filter:Received:DKIM-Signature:X-Google-DKIM-Signature: X-Forwarded-Encrypted:X-Gm-Message-State:X-Gm-Gg:X-Received:Received: From:To:Cc:Subject:Date:Message-ID:X-Mailer:In-Reply-To:References: MIME-Version:Content-Type:Content-Transfer-Encoding; bh=ZYxQSy8dLCKYWceK3MqyY+vv/0VurjYeK94bOEbIJSA=; b=Tr9EBbxiy3bi0wo/cNJWOjN2kc9LcR39qmZTCkK9qE9FFw1xnpmP1f9d4IWCObEN2qwn GypAc3JzAnXk5BTIco/Kl7VwvxVycoETRTq9h+T4TigulgvY+YtFKg9wvTF9f1ArYVCkc V2teS+Mg3WPJBgh3GBT/Y4X57QKneo7IrMyO1BUFixNJ2HLU6hExUz4wOSIMVHQPFDi11 NJ0VdsUEKAIOGYrD05X4raFlk8FWJ52A9t2/iGAy/plFItfDl710yDYBKZAPcAGEtZzdB XUCzfrNfQDp9ImTYXT088S/kB1YSDtjgnNP5ItotiYbv3r7yLIsD/iZGtMxKOjmv4lw== ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20260707 header.b=z1KmrsWR; arc=none smtp.remote-ip=209.85.216.42 Received: from mail-pj1-f42.google.com (mail-pj1-f42.google.com [209.85.216.42]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DE59460A2619 for ; Fri, 6 Nov 2026 11:36:21 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.2 smtp.subspace.kernel.org DE59460A2619 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key, unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20260707 header.b=z1KmrsWR Received: by mail-pj1-f42.google.com with SMTP id 98e67ed59e1d1-3afc7b51abfso32684a91.2 for ; Fri, 06 Nov 2026 03:36:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20260707; t=1793964981; x=1794569781; darn=vger.kernel.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:from:to:cc:subject :date:message-id:reply-to:content-type; bh=ZYxQSy8dLCKYWceK3MqyY+vv/0VurjYeK94bOEbIJSA=; b=z1KmrsWR68iGrKH9Z6PUvX0OBHp6HuhLHN3M9EBO/NTyq9Gd2LhHTjHnGVbTSr/xbN 8GmrCedRFKAwsGczEzrug5Z6FHWLEIFaK2IwZ6TAZadzBYtYx/FJmJN6orQ/xOQtL7PH Spe81/e/NEQqOsMLSXSV3Eii91kC5b9Fa2z2hCZTj7nDFTFCSMtspjfe3nF+vs82j7Xm 4oQcjip8ywvJj+TrCnv/jT24shqUnO/LLpne7lFZcrdyjJQ5A3eYo8XAe/MWSuAWvAG5 bROYTg7SBnEN9ZDeWBW1k2niXennJI1FMs6zw8ttGhi2084UHtjPjO463ejt9FsOn6mB aQ2Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1793964981; x=1794569781; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=ZYxQSy8dLCKYWceK3MqyY+vv/0VurjYeK94bOEbIJSA=; b=pHgZ32OPVdj5qiJWg0AmLbFc+mjnjDGkA5qTN82uuk2YqI4tRnB7/J6CCAOfLqn4TD LvkLqWqHHjR9CdxmtK56gP9fH5QV9erqVFsUDGWxX0xSQaxZybsO4DG80WMZhvRjzt78 Enk60UOZDxZwTP+g4EfF4aSunhZFbMqQFinNue4DmoMwQl8sfQxYPr+PldaY5hbi/WLe SL2Un+tj/o7pTrzH8vA/IN+wB2PaHvkXIYbdE9E9oiVBgeEU+2VhvoxzHNaGoQF53VTI Jq/A/3LaHny7UDfPEyynGDp1BM2tfSvhlAnEyyGIFfUuzeLUBW1ImtZIyJsa3gFngRsO xoAA== X-Forwarded-Encrypted: i=1; AL+hErFdr0uJcZj9bCBjT/BzccQ42lvrfYxR9XX16oRpc7hBOWA8mljaFcIu1+Eq4wXGn4KQ2shQ0ulaTc0=@vger.kernel.org X-Gm-Message-State: APuU4Z+fkRGPVru94MlIsXK72lPBOefUtMLtXTJtM3KtS1SRil48LMkz UTo1gxZ2BHml2EWtvcNsXey05l+C/t1LltLlxTyYrBEWNk4pW8fHE53b8eKBng== X-Gm-Gg: AYBFou3hfAJTDIpbndBan/gkOtTwC3mRQfqSJILr3N9TPl+TZYNMsfOkZh36x6644Q4 p4I4c2vEeGGAoYdau+iMqI12L18hTNWXFGsOoJtqkofalc2kecm8YUH++TgAyUS2wUhoHxpps28 fvVRdnFmdoFxgAQjnpQ+mSzUQ/exiLuVU5NXjUqdbEPdfw95ybQ4ORkg2nwR0yczTExZVXn2Ea5 pssrDAV/4sDij/UoLpc0V8h3CG9c8MzOcorWU+jcwGlsh0ApKK2XcvNhQ2g9o1Q0BzsLgj7dRP2 1Uf4dSxgaDQeFzFLNyoQqK3kY0Qc0dSYrPzRM+cWNDkdfjb/jDKhNpqhGXw/Noaf5Dop/T00cGS bmzJh1skUfOWfbl8kmaEIo9FgtulKp7TKloOLxAIjSkWwH1n7PzKfKmIzv/OC+hYMGpQBy7rLxk I1QI0DNgKl7piWuoU8mCyifz6LrsjEg5zPDWWFASlu8v0pBP5UX1lbK4J/L9w3+9ZrLVRcd5ebj clMK3URvpczlBgp4BnCIsBszXJTBM+3cLwncy77SqsVY3KO+Wi31+7I5RwdtRbDNgILxrxlYskR QHCDAfBbgEmZpOVcUuM7dW2mGe7a2l02ktSqV07ghuMYuJmmiYdNgYv74azha+wceyQdlyqnD+x hhIi8pzbKhzH1cB7SeDUgVoN7 X-Received: by 2002:a17:90b:388d:b0:3a8:9db2:a59 with SMTP id 98e67ed59e1d1-3b0db013fbamr3325222a91.0.1793964981081; Fri, 06 Nov 2026 03:36:21 -0800 (PST) Received: from chenyou.ncku.edu.tw ([140.116.19.13]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-3b0b32b6507sm8343173a91.16.2026.11.06.03.36.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Nov 2026 03:36:19 -0800 (PST) From: Chen-Yu Yeh To: Alex Shi , Jonathan Corbet Cc: Weijie Yuan , Dongliang Mu , Yanteng Si , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen-Yu Yeh Subject: [PATCH 07/13] docs/zh_TW: process: add deprecated.rst translation Date: Fri, 6 Nov 2026 19:35:38 +0800 Message-ID: <20261106113545.708896-8-chenyou910331@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20261106113545.708896-1-chenyou910331@gmail.com> References: <20261106113545.708896-1-chenyou910331@gmail.com> X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translate Documentation/process/deprecated.rst into Traditional Chinese from the current English text, including the kmalloc_obj() family section and the rewritten strncpy() section that lists its replacements. There is no zh_CN translation of this file to consult. The note in the allocator section links to the "Zero-length and one-element arrays" section by its HTML anchor; since the translated heading no longer produces that anchor, add an explicit zero-length-and-one-element-arrays target before the section. List the new file in the toctree of process/index.rst, under "Other material" as in the English index, and drop it from the TODOList. update to commit 079a028d6327 ("string: Remove strncpy() from the kernel") Signed-off-by: Chen-Yu Yeh --- .../translations/zh_TW/process/deprecated.rst | 363 ++++++++++++++++++ .../translations/zh_TW/process/index.rst | 6 +- 2 files changed, 368 insertions(+), 1 deletion(-) create mode 100644 Documentation/translations/zh_TW/process/deprecated.rst diff --git a/Documentation/translations/zh_TW/process/deprecated.rst b/Documentation/translations/zh_TW/process/deprecated.rst new file mode 100644 index 000000000000..7a5e42a12041 --- /dev/null +++ b/Documentation/translations/zh_TW/process/deprecated.rst @@ -0,0 +1,363 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/process/deprecated.rst + +.. _tw_deprecated: + +====================================== +已棄用的介面、語言特性、屬性與慣例 +====================================== + +在理想的世界裡，我們可以在單一開發週期內，把某個已棄用 API 的所有使用處 +都轉換成新的 API，並完全移除舊的 API。然而，由於核心的規模、維護者的層級 +架構以及時程等因素，這類轉換並不總是能一次完成。這表示在移除舊用法的同時， +新的用法可能會偷偷混進核心，只會讓移除該 API 的工作量越來越大。為了讓開發者 +了解哪些東西已被棄用以及原因，我們建立了這份清單；當有人提議把已棄用的東西 +納入核心時，可以引用這份清單。 + +__deprecated +------------ +雖然這個屬性確實會在視覺上把介面標示為已棄用，但它 `在建置時已不再產生警告 +`_， +因為核心的長期目標之一是在建置時不產生任何警告，而且實際上也沒有人在著手 +移除這些已棄用的介面。雖然在標頭檔中使用 `__deprecated` 來標註舊的 API +是不錯的做法，但這並不是完整的解決方案。這類介面必須從核心中完全移除， +或者加入這份檔案，以勸阻其他人未來再使用它們。 + +BUG() 和 BUG_ON() +----------------- +請改用 WARN() 和 WARN_ON()，並盡可能妥善地處理這種「不可能發生」的錯誤 +狀況。雖然 BUG() 系列 API 最初是設計成「不可能發生的情況」的斷言，並「安全 +地」終止核心執行緒，但事實證明它們的風險實在太高。（例如：「鎖需要以什麼 +順序釋放？各種狀態都已經恢復了嗎？」）使用 BUG() 經常會讓系統變得不穩定或 +完全崩潰，使得除錯甚至取得可用的當機報告都變得不可能。Linus 對此有 `非常強烈 +`_ +的 `看法 +`_。 + +請注意，WARN() 系列只應該用於「預期不會執行到」的情況。如果要對「可能執行 +到但不希望發生」的情況發出警告，請使用 pr_warn() 系列函式。系統擁有者可能 +設定了 *panic_on_warn* sysctl，以確保系統在遇到「不可能執行到」的狀況時不會 +繼續執行。（例如，請參考 `這個 +`_ +之類的 commit。） + +在配置函式的參數中直接進行算術運算 +---------------------------------- +動態的大小計算（尤其是乘法）不應該在記憶體配置函式（或類似函式）的參數中 +進行，因為有溢位的風險。這可能導致數值繞回（wrap around），使實際配置的 +空間比呼叫者預期的還小。使用這些配置出來的空間，可能導致堆積（heap）記憶體 +的線性溢位以及其他異常行為。（一個例外是字面常數值，此時編譯器可以在可能 +溢位時發出警告。不過在這些情況下，比較好的做法仍然是依照下面的建議重構程式 +碼，以避免直接進行算術運算。） + +例如，不要像這樣使用 ``count * size`` 作為參數:: + + foo = kmalloc(count * size, GFP_KERNEL); + +而應該使用配置函式的雙因子形式:: + + foo = kmalloc_array(count, size, GFP_KERNEL); + +具體來說，kmalloc() 可以換成 kmalloc_array()，kzalloc() 可以換成 +kcalloc()。 + +如果沒有可用的雙因子形式，就應該使用溢位時會飽和（saturate-on-overflow）的 +輔助函式:: + + bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL); + +另一個應避免的常見情況，是計算尾端帶有其他結構陣列的結構大小，例如:: + + header = kzalloc(sizeof(*header) + count * sizeof(*header->item), + GFP_KERNEL); + +請改用輔助函式:: + + header = kzalloc(struct_size(header, item, count), GFP_KERNEL); + +.. note:: 如果你在尾端陣列成員為零長度陣列或單元素陣列的結構上使用 + struct_size()，請重構這類陣列的用法，改用 `彈性陣列成員 + <#zero-length-and-one-element-arrays>`_。 + +其他計算請組合使用 size_mul()、size_add() 和 size_sub() 輔助函式。例如 +以下這種情況:: + + foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); + +請改用輔助函式:: + + foo = krealloc(size_add(current_size, + size_mul(chunk_size, + size_sub(count, 3))), GFP_KERNEL); + +更多細節請參考 array3_size() 和 flex_array_size()，以及相關的 +check_mul_overflow()、check_add_overflow()、check_sub_overflow() 和 +check_shl_overflow() 系列函式。 + +simple_strtol()、simple_strtoll()、simple_strtoul()、simple_strtoull() +---------------------------------------------------------------------- +simple_strtol()、simple_strtoll()、simple_strtoul() 和 simple_strtoull() +函式會刻意忽略溢位，這可能讓呼叫者得到預期之外的結果。對應的 kstrtol()、 +kstrtoll()、kstrtoul() 和 kstrtoull() 函式通常是正確的替代品，但請注意， +它們要求字串必須以 NUL 或換行字元結尾。 + +strcpy() +-------- +strcpy() 不會對目的緩衝區做任何邊界檢查。這可能導致超出緩衝區結尾的線性溢位， +進而造成各種異常行為。雖然 `CONFIG_FORTIFY_SOURCE=y` 和各種編譯器旗標有助於 +降低使用這個函式的風險，但沒有任何好理由再新增這個函式的用法。安全的替代品 +是 strscpy()，但凡是用到 strcpy() 回傳值的地方都必須小心處理，因為 strscpy() +回傳的不是指向目的緩衝區的指標，而是複製的非 NUL 位元組數（截斷時則回傳負的 +errno）。 + +strncpy() +--------- +strncpy() 已經從核心中移除。所有原本的呼叫者都已改用更安全的替代函式。 + +strncpy() 不保證目的緩衝區會以 NUL 結尾，因而導致線性讀取溢位和其他異常行為。 +它也會無條件地以 NUL 填補目的緩衝區，對只使用以 NUL 結尾字串的呼叫者來說， +這是不必要的效能損失。由於它具有多種不同的行為，從這個 API 很難判斷作者進行 +複製時的真正意圖。 + +strncpy() 的替代函式如下： + +- strscpy()：目的緩衝區必須以 NUL 結尾時使用。 +- strscpy_pad()：目的緩衝區必須以 NUL 結尾並以零填補時使用（例如跨越權限 + 邊界的結構）。 +- memtostr()：來源是不以 NUL 結尾的固定寬度資料、目的緩衝區需以 NUL 結尾時 + 使用（來源需加上 `__nonstring` 屬性）。 +- memtostr_pad()：同上，但另外以零填補。 +- strtomem()：目的是不以 NUL 結尾的固定寬度緩衝區時使用，目的緩衝區需加上 + `__nonstring` 屬性。 +- strtomem_pad()：目的緩衝區不以 NUL 結尾且也需要以零填補時使用。 +- memcpy_and_pad()：從可能沒有結尾字元的來源進行有界複製，且目的緩衝區大小 + 是執行期數值時使用。 + +strlcpy() +--------- +strlcpy() 會先讀取整個來源緩衝區（因為它的回傳值應該與 strlen() 的回傳值 +相同）。這次讀取可能會超出目的緩衝區的大小限制。這既沒有效率，而且當來源 +字串不以 NUL 結尾時，還可能導致線性讀取溢位。安全的替代品是 strscpy()，但 +凡是用到 strlcpy() 回傳值的地方都必須小心處理，因為 strscpy() 在截斷時會 +回傳負的 errno 值。 + +%p 格式指定符 +------------- +傳統上，在格式字串中使用 "%p" 經常會造成位址在 dmesg、proc、sysfs 等處外洩 +的漏洞。為了避免這些漏洞被利用，核心中所有 "%p" 的用法現在都會印出雜湊值， +使其無法用於定址。不應該在核心中新增 "%p" 的用法。對於程式碼（text）位址， +使用 "%pS" 可能比較好，因為它會改為印出更有用的符號名稱。至於幾乎其他所有 +情況，就乾脆不要加入 "%p"。 + +轉述 Linus 目前的 `指導原則 `_： + +- 如果雜湊過的 "%p" 值沒有意義，請先問問自己指標本身是否重要。也許應該把它 + 整個移除？ +- 如果你真的認為真實的指標值很重要，那麼為什麼某些系統狀態或使用者權限等級 + 會被視為「特殊」？如果你認為自己能（在註解和 commit 日誌中）提出足以經得起 + Linus 檢驗的理由，也許可以使用 "%px"，同時確保權限設定合理。 + +如果你在除錯時遇到 "%p" 雜湊造成的問題，可以暫時以除錯旗標 +"`no_hash_pointers +`_" +開機。 + +可變長度陣列（VLA） +------------------- +使用堆疊上的 VLA 所產生的機器碼，比靜態大小的堆疊陣列差得多。雖然這些不容 +忽視的 `效能問題 `_ 已足以成為 +消除 VLA 的理由，但它們同時也是安全風險。堆疊陣列的動態成長可能超出堆疊區段 +中剩餘的記憶體。這可能導致當機，可能覆寫堆疊尾端的敏感內容（在沒有啟用 +`CONFIG_THREAD_INFO_IN_TASK=y` 建置時），或覆寫與堆疊相鄰的記憶體（在沒有 +啟用 `CONFIG_VMAP_STACK=y` 建置時）。 + +隱式的 switch case 貫穿（fall-through） +--------------------------------------- +C 語言允許在某個 case 結尾缺少 "break" 敘述時，貫穿到下一個 case。然而這會 +讓程式碼產生歧義，因為缺少 break 究竟是刻意的還是 bug，並不總是那麼清楚。 +例如，光看程式碼並無法明顯看出 `STATE_ONE` 是否刻意設計成貫穿到 +`STATE_TWO`:: + + switch (value) { + case STATE_ONE: + do_something(); + case STATE_TWO: + do_other(); + break; + default: + WARN("unknown state"); + } + +由於已經出現過一長串 `因缺少 "break" 敘述而造成的缺陷 +`_，我們不再允許隱式貫穿。 +為了標示刻意的貫穿情況，我們採用了一個名為 "fallthrough" 的偽關鍵字巨集， +它會展開成 gcc 的擴充語法 `__attribute__((__fallthrough__)) +`_。 +（等到 C17/C18 的 `[[fallthrough]]` 語法普遍獲得 C 編譯器、靜態分析器和 +IDE 支援時，我們就可以改用該語法來實作這個巨集偽關鍵字。） + +所有 switch/case 區塊都必須以下列其中之一結尾： + +* break; +* fallthrough; +* continue; +* goto