Winsock API 函數參考手冊 (二)：I/O 與進階控制函數

前言：Winsock 1.1 規範函數分類

本文承接系列文件，依據 1993 年 Winsock 1.1 規範，整理 輸入輸出、Socket 選項控制、位址轉換、多工監控 等核心 API，包含 30 個 BSD 標準函數與 16 個 Windows 擴充函數。以下為第 11-20 號函數詳細說明。

函數詳細規格

(11) inet_ntoa — 網路位址轉點分十進位字串

char FAR * PASCAL FAR inet_ntoa(struct in_addr in);

• 參數：in - IPv4 位址結構 (32-bit)
• 回傳：成功指向 "a.b.c.d" 靜態緩衝區指標；失敗傳回 NULL
• 備註：非執行緒安全，多執行緒環境建議改用 InetNtop

(12) ioctlsocket — Socket 模式控制

int PASCAL FAR ioctlsocket(SOCKET s, long cmd, u_long FAR *argp);

• 命令：
  • FIONBIO：啟用/停用非阻塞模式 (*argp=1/0)
  • FIONREAD：取得可立即讀取資料量 (bytes)
  • SIOCATMARK：檢查 OOB 資料是否已讀完 (暫未實作)
• 回傳：0 成功；SOCKET_ERROR 失敗

(13) listen — 設定監聽佇列

int PASCAL FAR listen(SOCKET s, int backlog);

• 參數：backlog - 未完成連線佇列最大長度 (系統限制最大 5，最小 1)
• 用途：將 Stream Socket 置於被動開啟狀態，等待 accept

(14) ntohl / (15) ntohs — 網路位序轉主機位序

u_long PASCAL FAR ntohl(u_long netlong);   // 32-bit
u_short PASCAL FAR ntohs(u_short netshort); // 16-bit

• 網路序為 Big-Endian，主機序視 CPU 架構而定 (x86 為 Little-Endian)
• 跨平台資料交換必須配對使用 htonl/ntohl, htons/ntohs

(16) recv — 接收連線導向資料

int PASCAL FAR recv(SOCKET s, char FAR *buf, int len, int flags);

• 適用：Stream Socket 或已連線 Datagram Socket
• 行為：阻塞直到有資料或連線關閉；回傳實際接收位元組數 (0 表對端關閉)
• Flags：MSG_PEEK (窺視不移除)、MSG_OOB (讀取緊急資料，暫未實作)

(17) recvfrom — 接收資料並取得來源位址

int PASCAL FAR recvfrom(SOCKET s, char FAR *buf, int len, int flags,
                        struct sockaddr FAR *from, int FAR *fromlen);

• 適用：無連線 Datagram Socket (UDP) 為主；Stream Socket 行為同 recv，from/fromlen 被忽略
• 注意：緩衝區小於封包大小時，多餘資料遺失並回報錯誤

(18) select — 多工 I/O 就緒檢查

int PASCAL FAR select(int nfds, fd_set FAR *readfds, fd_set FAR *writefds,
                      fd_set FAR *exceptfds, const struct timeval FAR *timeout);

• 參數：nfds 在 Windows 忽略；timeout=NULL 表永久阻塞
• 回傳：就緒 Socket 總數；0 表逾時；SOCKET_ERROR 失敗
• 用途：單執行緒同時監控多個 Socket 讀/寫/例外狀態

(19) send — 連線導向傳送

int PASCAL FAR send(SOCKET s, const char FAR *buf, int len, int flags);

• 行為：將資料複製至發送緩衝區；若緩衝區滿則阻塞 (非阻塞模式下傳回 WSAEWOULDBLOCK)
• 重要：回傳成功不代表資料已抵達對端，僅表示已進入協定堆疊發送佇列
• Flags：MSG_DONTROUTE (暫未實作)、MSG_OOB

(20) sendto — 指定目的位址傳送

int PASCAL FAR sendto(SOCKET s, const char FAR *buf, int len, int flags,
                      const struct sockaddr FAR *to, int tolen);

• 適用：Datagram Socket (指定目標)；Stream Socket 行為同 send (忽略 to/tolen)
• 同 send：非阻塞模式下緩衝區滿會立即失敗

下一篇預告

下集將涵蓋 setsockopt, shutdown, socket, gethostbyaddr, gethostbyname, gethostname, getprotobyname, getprotobynumber, getservbyname, getservbyport 等 Socket 建立、關閉、名稱解析與服務查詢函數。