R getNativeSymbolInfo 獲取一個或多個本機 (C/Fortran) 符號的說明

說明

這會查找並返回一個或多個動態加載或‘exported’內置本機符號的說明。對於每個名稱，它返回有關符號名稱、它所在的庫的信息，以及它期望的參數數量(如果有)以及應該通過哪個接口調用它的信息(即 .Call 、 .C 、 .Fortran 或 .External )。此外，它還返回符號的地址，並且可以將其傳遞給其他 C 例程。具體來說，這提供了一種在不同動態加載的包庫之間顯式共享符號的方法。此外，它還提供了一種查詢符號解析位置的方法，並有助於診斷與動態解析相關的奇怪行為。

用法

getNativeSymbolInfo(name, PACKAGE, unlist = TRUE,
                    withRegistrationInfo = FALSE)

參數

name	本地符號的名稱。
PACKAGE	一個可選參數，指定要限製對該符號的搜索的 DLL。如果這是"base"，我們在R本身可執行。
unlist	一個邏輯值，控製使用單個符號名稱調用函數時如何返回結果。如果unlist 是TRUE 並且name 中的符號名稱數量為1，則返回NativeSymbolInfo 對象。如果是 FALSE ，則返回 NativeSymbolInfo 對象的列表。如果 name 中傳遞的符號數量超過 1，則忽略此設置。為了與此函數的早期版本兼容，默認為 TRUE 。
withRegistrationInfo	一個邏輯值，指示是否、ifTRUE，返回注冊信息R關於符號及其參數類型(如果此類信息可用)，或者如果FALSE僅返回符號的地址。

細節

這使用與所有本機接口( .Call 等)中使用的相同機製來解析符號。如果該符號已由包含該符號的 DLL 顯式注冊，則將返回有關參數數量和調用該符號的接口的信息。否則，返回通用的本機符號對象。

值

通常，NativeSymbolInfo 元素的列表，其元素可以通過調用中的name 的元素進行索引。每個 NativeSymbolInfo 對象都是一個包含以下元素的列表：

name	符號的名稱，由 name 參數給出。
address	如果 withRegistrationInfo 是 FALSE ，則這是符號的本機內存地址，可用於調用例程，並可與其他符號地址進行比較。這是一個外部指針對象，屬於 NativeSymbol 類。如果withRegistrationInfo 是TRUE 並且注冊信息可用於該符號，則這是類RegisteredNativeSymbol 的對象，並且是對可以訪問例程指針和注冊信息的內部數據類型的引用。這也可以用於調用 .Call 、 .C 、 .Fortran 和 .External 。
dll	包含 3 個元素的列表： 名字 庫名稱的縮寫形式，可用作不同本機接口函數中 PACKAGE 參數的值。 小路 DLL 的完全限定名稱。 動態查找 一個邏輯值，指示在該庫中查找符號時是否使用動態解析，或者隻能找到已注冊的例程。

如果例程是由動態加載庫顯式注冊的，則列表包含第四個字段

numParameters

調用此例程時應傳遞的參數數量。

此外，該列表還將有一個附加類，即 CRoutine 、 CallRoutine 、 FortranRoutine 或 ExternalRoutine ，對應於應通過其調用的 R 接口。

如果未找到任何符號，則會引發錯誤。

如果 name 僅包含一個符號名稱，並且 unlist 是 TRUE ，則返回單個 NativeSymbolInfo 而不是包含該一個元素的列表。

注意

的第三個元素NativeSymbolInfo對象被重命名為package到dll在R版本 3.6.0，為了與名稱保持一致NativeSymbolInfo返回的對象getDLLRegisteredRoutines().

注意

訪問此反射信息的一個動機是能夠將本機例程作為 C 中的函數指針傳遞給 C 例程。這使我們能夠處理本機例程並R以類似的方式起作用，例如當傳遞一個R函數到 C 代碼，在計算的不同點對該函數進行回調(例如，nls)。此外，我們可以隻解析一次符號，並避免重複解析或使用內部緩存。

作者

Duncan Temple Lang

參考

For information about registering native routines, see “In Search of C/C++ & FORTRAN Routines”, R-News, volume 1, number 3, 2001, p20-23 (https://www.r-project.org/doc/Rnews/Rnews_2001-3.pdf).

也可以看看

getDLLRegisteredRoutines、is.loaded、.C、.Fortran、.External、.Call、dyn.load。