CreateSemaphoreA 函式（winbase.h）

發行項
11/20/2024

建立或開啟具名或未命名的號誌物件。

若要指定物件的存取遮罩，請使用 createSemaphoreEx 函式。

語法

HANDLE CreateSemaphoreA(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCSTR                lpName
);

參數

[in, optional] lpSemaphoreAttributes

SECURITY_ATTRIBUTES 結構的指標。如果此參數 NULL，則子進程無法繼承句柄。

lpSecurityDescriptor 結構的成員會指定新旗號的安全性描述元。如果此參數 NULL，則旗號會取得預設的安全性描述元。信號的預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。

[in] lInitialCount

信號物件的初始計數。這個值必須大於或等於零，且小於或等於 lMaximumCount 。旗號的狀態會在計數大於零時發出訊號，且當其為零時則為非信號。每當等候函式釋放等候號誌的線程時，計數就會減少一個。呼叫 ReleaseSemaphore 函式，就會增加指定的數量。

[in] lMaximumCount

信號物件的最大計數。此值必須大於零。

[in, optional] lpName

號誌物件的名稱。名稱限制為 MAX_PATH 個字元。名稱比較區分大小寫。

如果 lpName 符合現有具名號誌物件的名稱，則此函式會要求 SEMAPHORE_ALL_ACCESS 訪問許可權。在此情況下，lInitialCount 和 lMaximumCount 參數會被忽略，因為它們已經由建立程序設定。如果 lpSemaphoreAttributes 參數不是 NULL，它會判斷是否可以繼承句柄，但忽略其安全性描述元成員。

如果 lpNameNULL，則會建立沒有名稱的旗號物件。

如果 lpName 符合現有事件、mutex、可等候定時器、作業或檔案對應物件的名稱，則函式會失敗，而且 getLastError 函式會傳回 ERROR_INVALID_HANDLE。這是因為這些對象共用相同的命名空間。

名稱可以有「Global」或「Local」前置詞，以明確在全域或會話命名空間中建立物件。名稱的其餘部分可以包含反斜杠字元（\）以外的任何字元。如需詳細資訊，請參閱 Kernel Object Namespaces。使用終端機服務會話實作快速使用者切換。核心物件名稱必須遵循終端機服務概述的指導方針，應用程式才能支援多個使用者。

物件可以在私人命名空間中建立。如需詳細資訊，請參閱物件命名空間。

傳回值

如果函式成功，傳回值就是信號物件的句柄。如果具名旗號物件存在於函數調用之前，函式會傳回現有物件的句柄，GetLastError 會傳回 ERROR_ALREADY_EXISTS。

如果函式失敗，則傳回值 NULL。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

CreateSemaphore 傳回的句柄具有 SEMAPHORE_ALL_ACCESS 訪問許可權;它可以用於任何需要信號物件的句柄的函式中，前提是呼叫端已獲得存取權。如果旗號是從服務或模擬不同用戶的線程建立的，您可以在建立旗標時將安全性描述元套用至旗號，或藉由變更其預設 DACL 來變更建立程式的預設安全性描述元。如需詳細資訊，請參閱 Synchronization Object Security and Access Rights。

旗號物件的狀態會在計數大於零時發出訊號，而且當計數等於零時，則表示非信號。 lInitialCount 參數會指定初始計數。計數永遠不能小於零或大於 lMaximumCount 參數中指定的值。

呼叫行程的任何線程都可以在呼叫其中一個等候函式時指定信號物件句柄，。當指定物件的狀態發出訊號時，單一物件等候函式會傳回。當任一物件或發出所有指定物件的訊號時，可以指示多物件等候函式傳回。當等候函式傳回時，等候線程會釋放以繼續執行。每次線程完成等候號誌物件時，旗號物件的計數都會遞減一。線程完成時，它會呼叫 releaseSemaphore 函式，以遞增號誌物件的計數。

多個進程可以有相同號誌物件的句柄，讓對象能夠進行進程間同步處理。下列物件共享機制可供使用：

如果 createSemaphore 的 lpSemaphoreAttributes 參數已啟用 CreateSemaphore 繼承，CreateProcess 函式所建立的子進程可以繼承旗號物件的句柄。
進程可以在呼叫 DuplicateHandle 函式中指定信號物件句柄，以建立另一個進程可以使用的重複句柄。
進程可以在呼叫 [OpenSemaphore]（/windows/win32/api/synchapi/nf-synchapi-opensemaphorew）或 CreateSemaphorew 中指定信號對象的名稱。

使用 CloseHandle 函式來關閉句柄。系統會在進程終止時自動關閉句柄。當最後一個句柄關閉時，旗號對象會終結。

例子

如需使用 CreateSemaphore的範例，請參閱使用信號物件。

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	winbase.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll