1需要直接呼叫系統 API 的情況：
2├── 取得主機名稱（gethostname）
3├── 取得使用者 ID（getuid, geteuid）
4├── 系統時間操作（time, gettimeofday）
5├── 檔案系統操作（sync, fsync）
6├── 記憶體資訊（sysinfo - Linux 限定）
7└── 其他未封裝的 POSIX/Windows API

 1# system_api.py
 2"""
 3使用 ctypes 呼叫系統 API 的範例模組。
 4
 5跨平台支援 Linux、macOS 和 Windows。
 6"""
 7
 8import ctypes
 9import ctypes.util
10import sys
11from typing import Optional
12
13def load_libc() -> ctypes.CDLL:
14    """
15    跨平台載入 C 函式庫。
16
17    Returns:
18        ctypes.CDLL: 載入的 C 函式庫物件
19
20    Raises:
21        OSError: 無法載入 C 函式庫
22    """
23    if sys.platform == 'win32':
24        # Windows 使用 msvcrt
25        return ctypes.CDLL('msvcrt')
26    else:
27        # Unix-like 系統使用 find_library
28        libc_name = ctypes.util.find_library('c')
29        if libc_name is None:
30            # 嘗試常見路徑
31            if sys.platform == 'darwin':
32                libc_name = 'libc.dylib'
33            else:
34                libc_name = 'libc.so.6'
35        return ctypes.CDLL(libc_name)
36
37# 全域 libc 實例
38_libc: Optional[ctypes.CDLL] = None
39
40def get_libc() -> ctypes.CDLL:
41    """取得 libc 的單例實例。"""
42    global _libc
43    if _libc is None:
44        _libc = load_libc()
45    return _libc

 1import ctypes
 2import socket
 3
 4def gethostname_ctypes(max_len: int = 256) -> str:
 5    """
 6    使用 ctypes 呼叫 gethostname() 取得主機名稱。
 7
 8    Args:
 9        max_len: 主機名稱緩衝區大小
10
11    Returns:
12        主機名稱字串
13
14    Raises:
15        OSError: 系統呼叫失敗
16    """
17    libc = get_libc()
18
19    # int gethostname(char *name, size_t len)
20    libc.gethostname.argtypes = [ctypes.c_char_p, ctypes.c_size_t]
21    libc.gethostname.restype = ctypes.c_int
22
23    # 建立緩衝區
24    buffer = ctypes.create_string_buffer(max_len)
25
26    # 呼叫系統函式
27    result = libc.gethostname(buffer, max_len)
28
29    if result != 0:
30        raise OSError(f"gethostname failed with code {result}")
31
32    return buffer.value.decode('utf-8')
33
34# 比較 ctypes 與 Python 標準庫
35if __name__ == "__main__":
36    print(f"ctypes gethostname: {gethostname_ctypes()}")
37    print(f"socket.gethostname: {socket.gethostname()}")

 1import ctypes
 2import os
 3
 4def getpid_ctypes() -> int:
 5    """
 6    使用 ctypes 呼叫 getpid() 取得當前 process ID。
 7
 8    Returns:
 9        當前 process 的 PID
10    """
11    libc = get_libc()
12
13    # pid_t getpid(void)
14    libc.getpid.argtypes = []
15    libc.getpid.restype = ctypes.c_int
16
17    return libc.getpid()
18
19def getppid_ctypes() -> int:
20    """
21    使用 ctypes 呼叫 getppid() 取得父 process ID。
22
23    Returns:
24        父 process 的 PID
25    """
26    libc = get_libc()
27
28    # pid_t getppid(void)
29    libc.getppid.argtypes = []
30    libc.getppid.restype = ctypes.c_int
31
32    return libc.getppid()
33
34# 驗證結果
35if __name__ == "__main__":
36    print(f"ctypes getpid: {getpid_ctypes()}")
37    print(f"os.getpid: {os.getpid()}")
38    print(f"ctypes getppid: {getppid_ctypes()}")
39    print(f"os.getppid: {os.getppid()}")

 1import ctypes
 2import time as time_module
 3
 4def time_ctypes() -> int:
 5    """
 6    使用 ctypes 呼叫 time() 取得 Unix 時間戳記。
 7
 8    Returns:
 9        當前 Unix 時間戳記（秒）
10    """
11    libc = get_libc()
12
13    # time_t time(time_t *tloc)
14    libc.time.argtypes = [ctypes.c_void_p]
15    libc.time.restype = ctypes.c_long
16
17    # 傳入 NULL，直接取得回傳值
18    return libc.time(None)
19
20# timeval 結構體（用於 gettimeofday）
21class Timeval(ctypes.Structure):
22    """
23    struct timeval {
24        time_t      tv_sec;   // 秒
25        suseconds_t tv_usec;  // 微秒
26    };
27    """
28    _fields_ = [
29        ("tv_sec", ctypes.c_long),
30        ("tv_usec", ctypes.c_long),
31    ]
32
33def gettimeofday_ctypes() -> tuple[int, int]:
34    """
35    使用 ctypes 呼叫 gettimeofday() 取得高精度時間。
36
37    Returns:
38        (秒, 微秒) 的 tuple
39
40    Note:
41        gettimeofday 在 POSIX.1-2008 中已標記為過時，
42        建議使用 clock_gettime。此處僅作為教學範例。
43    """
44    import sys
45    if sys.platform == 'win32':
46        raise NotImplementedError("gettimeofday not available on Windows")
47
48    libc = get_libc()
49
50    # int gettimeofday(struct timeval *tv, struct timezone *tz)
51    libc.gettimeofday.argtypes = [
52        ctypes.POINTER(Timeval),
53        ctypes.c_void_p  # timezone 已過時，傳 NULL
54    ]
55    libc.gettimeofday.restype = ctypes.c_int
56
57    tv = Timeval()
58    result = libc.gettimeofday(ctypes.byref(tv), None)
59
60    if result != 0:
61        raise OSError(f"gettimeofday failed with code {result}")
62
63    return (tv.tv_sec, tv.tv_usec)
64
65# 驗證結果
66if __name__ == "__main__":
67    print(f"ctypes time: {time_ctypes()}")
68    print(f"time.time: {int(time_module.time())}")
69
70    import sys
71    if sys.platform != 'win32':
72        sec, usec = gettimeofday_ctypes()
73        print(f"gettimeofday: {sec}.{usec:06d}")

 1import ctypes
 2import os
 3import sys
 4
 5def get_user_ids() -> dict:
 6    """
 7    取得當前 process 的使用者和群組 ID。
 8
 9    Returns:
10        包含 uid, euid, gid, egid 的字典
11
12    Note:
13        僅支援 Unix-like 系統。
14    """
15    if sys.platform == 'win32':
16        raise NotImplementedError("User IDs not applicable on Windows")
17
18    libc = get_libc()
19
20    # 設定函式簽名
21    # uid_t getuid(void)
22    libc.getuid.argtypes = []
23    libc.getuid.restype = ctypes.c_uint
24
25    # uid_t geteuid(void)
26    libc.geteuid.argtypes = []
27    libc.geteuid.restype = ctypes.c_uint
28
29    # gid_t getgid(void)
30    libc.getgid.argtypes = []
31    libc.getgid.restype = ctypes.c_uint
32
33    # gid_t getegid(void)
34    libc.getegid.argtypes = []
35    libc.getegid.restype = ctypes.c_uint
36
37    return {
38        'uid': libc.getuid(),
39        'euid': libc.geteuid(),
40        'gid': libc.getgid(),
41        'egid': libc.getegid(),
42    }
43
44# 驗證結果
45if __name__ == "__main__":
46    if sys.platform != 'win32':
47        ids = get_user_ids()
48        print(f"ctypes: uid={ids['uid']}, euid={ids['euid']}, "
49              f"gid={ids['gid']}, egid={ids['egid']}")
50        print(f"os: uid={os.getuid()}, euid={os.geteuid()}, "
51              f"gid={os.getgid()}, egid={os.getegid()}")

 1import ctypes
 2import sys
 3
 4def gethostname_windows(max_len: int = 256) -> str:
 5    """
 6    Windows 版本的 gethostname。
 7
 8    使用 kernel32.GetComputerNameA。
 9    """
10    if sys.platform != 'win32':
11        raise NotImplementedError("This function is Windows-only")
12
13    kernel32 = ctypes.windll.kernel32
14
15    # BOOL GetComputerNameA(LPSTR lpBuffer, LPDWORD nSize)
16    buffer = ctypes.create_string_buffer(max_len)
17    size = ctypes.c_ulong(max_len)
18
19    result = kernel32.GetComputerNameA(buffer, ctypes.byref(size))
20
21    if not result:
22        raise OSError(f"GetComputerNameA failed")
23
24    return buffer.value.decode('utf-8')
25
26def getpid_windows() -> int:
27    """
28    Windows 版本的 getpid。
29
30    使用 kernel32.GetCurrentProcessId。
31    """
32    if sys.platform != 'win32':
33        raise NotImplementedError("This function is Windows-only")
34
35    kernel32 = ctypes.windll.kernel32
36
37    # DWORD GetCurrentProcessId(void)
38    kernel32.GetCurrentProcessId.argtypes = []
39    kernel32.GetCurrentProcessId.restype = ctypes.c_ulong
40
41    return kernel32.GetCurrentProcessId()

 1import sys
 2
 3def get_hostname() -> str:
 4    """跨平台取得主機名稱。"""
 5    if sys.platform == 'win32':
 6        return gethostname_windows()
 7    else:
 8        return gethostname_ctypes()
 9
10def get_process_id() -> int:
11    """跨平台取得 process ID。"""
12    if sys.platform == 'win32':
13        return getpid_windows()
14    else:
15        return getpid_ctypes()

 1import ctypes
 2import errno
 3
 4def safe_gethostname(max_len: int = 256) -> str:
 5    """
 6    安全版本的 gethostname，包含完整的錯誤處理。
 7    """
 8    libc = get_libc()
 9
10    # 設定函式簽名
11    libc.gethostname.argtypes = [ctypes.c_char_p, ctypes.c_size_t]
12    libc.gethostname.restype = ctypes.c_int
13
14    # 驗證參數
15    if max_len <= 0:
16        raise ValueError("max_len must be positive")
17
18    if max_len > 1024:
19        raise ValueError("max_len too large (max 1024)")
20
21    # 建立緩衝區
22    buffer = ctypes.create_string_buffer(max_len)
23
24    # 呼叫系統函式
25    result = libc.gethostname(buffer, max_len)
26
27    if result != 0:
28        # 取得錯誤碼
29        err = ctypes.get_errno()
30        if err == errno.ENAMETOOLONG:
31            raise OSError(errno.ENAMETOOLONG,
32                         "Hostname too long for buffer")
33        elif err == errno.EFAULT:
34            raise OSError(errno.EFAULT,
35                         "Invalid buffer address")
36        else:
37            raise OSError(err, f"gethostname failed: {errno.errorcode.get(err, 'Unknown')}")
38
39    # 解碼並處理可能的編碼錯誤
40    try:
41        return buffer.value.decode('utf-8')
42    except UnicodeDecodeError:
43        return buffer.value.decode('latin-1')

 1"""
 2使用 ctypes 時的安全性注意事項：
 3
 41. 緩衝區溢位
 5   - 永遠確保緩衝區大小足夠
 6   - 使用 create_string_buffer() 而非直接操作指標
 7
 82. 型別安全
 9   - 務必設定 argtypes 和 restype
10   - 錯誤的型別可能導致程式崩潰或安全漏洞
11
123. 記憶體管理
13   - ctypes 物件由 Python GC 管理
14   - 小心回呼函式的生命週期
15
164. 輸入驗證
17   - 永遠驗證使用者輸入
18   - 不要直接將未驗證的資料傳給 C 函式
19"""
20
21def secure_strlen(s: str) -> int:
22    """
23    安全的 strlen 範例，包含輸入驗證。
24    """
25    # 輸入驗證
26    if not isinstance(s, str):
27        raise TypeError("Expected str, got {type(s).__name__}")
28
29    # 限制長度避免 DoS
30    MAX_LENGTH = 10_000_000  # 10 MB
31    if len(s) > MAX_LENGTH:
32        raise ValueError(f"String too long (max {MAX_LENGTH} bytes)")
33
34    libc = get_libc()
35    libc.strlen.argtypes = [ctypes.c_char_p]
36    libc.strlen.restype = ctypes.c_size_t
37
38    # 轉換為 bytes
39    encoded = s.encode('utf-8')
40
41    return libc.strlen(encoded)

 1import ctypes
 2import errno
 3
 4def get_errno_message(err: int) -> str:
 5    """取得錯誤碼對應的訊息。"""
 6    libc = get_libc()
 7
 8    # char *strerror(int errnum)
 9    libc.strerror.argtypes = [ctypes.c_int]
10    libc.strerror.restype = ctypes.c_char_p
11
12    result = libc.strerror(err)
13    if result:
14        return result.decode('utf-8')
15    return f"Unknown error {err}"
16
17# 使用範例
18if __name__ == "__main__":
19    print(f"ENOENT ({errno.ENOENT}): {get_errno_message(errno.ENOENT)}")
20    print(f"EACCES ({errno.EACCES}): {get_errno_message(errno.EACCES)}")
21    print(f"EINVAL ({errno.EINVAL}): {get_errno_message(errno.EINVAL)}")

 1import subprocess
 2import time
 3import statistics
 4from typing import Callable
 5
 6def benchmark(func: Callable, iterations: int = 1000) -> dict:
 7    """執行效能測試並回傳統計資料。"""
 8    times = []
 9
10    # 暖機
11    for _ in range(10):
12        func()
13
14    # 實際測試
15    for _ in range(iterations):
16        start = time.perf_counter()
17        func()
18        end = time.perf_counter()
19        times.append(end - start)
20
21    return {
22        'mean': statistics.mean(times) * 1_000_000,  # 轉換為微秒
23        'stdev': statistics.stdev(times) * 1_000_000,
24        'min': min(times) * 1_000_000,
25        'max': max(times) * 1_000_000,
26    }
27
28# 方法 1：ctypes
29def hostname_ctypes():
30    return gethostname_ctypes()
31
32# 方法 2：subprocess
33def hostname_subprocess():
34    result = subprocess.run(
35        ['hostname'],
36        capture_output=True,
37        text=True
38    )
39    return result.stdout.strip()
40
41# 方法 3：Python 標準庫
42def hostname_stdlib():
43    import socket
44    return socket.gethostname()
45
46# 執行測試
47if __name__ == "__main__":
48    print("=" * 60)
49    print("取得主機名稱效能比較")
50    print("=" * 60)
51
52    methods = [
53        ("ctypes", hostname_ctypes),
54        ("subprocess", hostname_subprocess),
55        ("socket (stdlib)", hostname_stdlib),
56    ]
57
58    for name, func in methods:
59        result = benchmark(func)
60        print(f"\n{name}:")
61        print(f"  平均: {result['mean']:.2f} us")
62        print(f"  標準差: {result['stdev']:.2f} us")
63        print(f"  最小: {result['min']:.2f} us")
64        print(f"  最大: {result['max']:.2f} us")

 1============================================================
 2取得主機名稱效能比較
 3============================================================
 4
 5ctypes:
 6  平均: 1.52 us
 7  標準差: 0.31 us
 8  最小: 1.21 us
 9  最大: 8.45 us
10
11subprocess:
12  平均: 4523.67 us
13  標準差: 892.34 us
14  最小: 3128.45 us
15  最大: 12456.78 us
16
17socket (stdlib):
18  平均: 0.89 us
19  標準差: 0.18 us
20  最小: 0.72 us
21  最大: 4.23 us

 1適合使用 ctypes 的情況：
 2├── Python 標準庫沒有對應功能
 3├── 需要呼叫特定平台的 API
 4├── 效能是關鍵考量
 5├── 需要與 C 函式庫整合
 6└── 希望避免編譯步驟（相比 Cython）
 7
 8不建議使用 ctypes 的情況：
 9├── 標準庫已有對應功能
10├── 大量複雜的 C 介面（考慮 cffi 或 Cython）
11├── 需要頻繁傳遞大量資料（考慮 NumPy）
12└── 團隊不熟悉 C 語言

 1"""
 2ctypes 呼叫系統 API 的最佳實踐：
 3
 41. 封裝成模組
 5   - 將 ctypes 呼叫封裝在獨立模組中
 6   - 提供清晰的 Python API
 7
 82. 完整的型別宣告
 9   - 永遠設定 argtypes 和 restype
10   - 使用適當的 ctypes 型別
11
123. 錯誤處理
13   - 檢查回傳值
14   - 處理 errno
15   - 提供有意義的錯誤訊息
16
174. 跨平台支援
18   - 使用 ctypes.util.find_library()
19   - 提供平台特定的實作
20   - 考慮使用 Python 標準庫作為 fallback
21
225. 文件與測試
23   - 記錄 C 函式的原型
24   - 與 Python 標準庫比較結果
25   - 包含效能測試
26"""

 1# getenv 範例框架
 2def getenv_ctypes(name: str) -> Optional[str]:
 3    """使用 ctypes 取得環境變數。"""
 4    libc = get_libc()
 5
 6    # char *getenv(const char *name)
 7    libc.getenv.argtypes = [ctypes.c_char_p]
 8    libc.getenv.restype = ctypes.c_char_p
 9
10    result = libc.getenv(name.encode('utf-8'))
11    # 完成實作...