共用方式為


createSemaphoreA 函式 (winbase.h)

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

若要指定物件的存取遮罩,請使用 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 存取權限。 在此情況下, 會忽略 lInitialCountlMaximumCount 參數,因為它們已經由建立程式設定。 如果 lpSemaphoreAttributes 參數不是 Null,它會判斷是否可以繼承控制碼,但其安全性描述元成員會被忽略。

如果 lpNameNull,則會建立旗號物件,而不需名稱。

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

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

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

傳回值

如果函式成功,則傳回值是旗號物件的控制碼。 如果具名旗號物件存在於函式呼叫之前,函式會傳回現有物件的控制碼,而 GetLastError 會傳回 ERROR_ALREADY_EXISTS

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

備註

CreateSemaphore 傳回的控制碼具有 SEMAPHORE_ALL_ACCESS 存取權限;它可用於任何需要旗號物件的控制碼的函式中,前提是呼叫端已獲得存取權。 如果從服務或模擬不同使用者的執行緒建立旗號,您可以在建立旗標時將安全性描述元套用至旗號,或變更建立程式的預設安全性描述元,方法是變更其預設 DACL。 如需詳細資訊,請參閱 同步處理物件安全性和存取權限

當旗號物件的計數大於零,且當計數等於零時,會發出訊號。 lInitialCount參數會指定初始計數。 計數不能小於零或大於 lMaximumCount 參數中指定的值。

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

多個進程可以有相同旗號物件的控制碼,讓物件能夠用於進程間同步處理。 下列物件共用機制可供使用:

  • 如果CreateSemaphore 啟用繼承的 lpSemaphoreAttributes參數,CreateProcess函式所建立的子進程可以繼承旗號物件的控制碼。
  • 進程可以在對 DuplicateHandle 函式的呼叫中指定旗號物件控制碼,以建立可由另一個進程使用的重複控制碼。
  • 進程可以在呼叫 [OpenSemaphore] (/windows/win32/api/synchapi/nf-synchapi/nf-synchapi-openemaphorew) 或 CreateSemaphorew 中指定旗號物件的名稱。
使用 CloseHandle 函式 關閉控制碼。 系統會在進程終止時自動關閉控制碼。 當最後一個控制碼關閉時,旗號物件就會終結。

範例

如需使用 CreateSemaphore 的範例,請參閱 使用旗標物件

規格需求

   
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winbase.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CloseHandle

CreateProcess

CreateSemaphoreEx

DuplicateHandle

物件名稱

OpenSemaphore

ReleaseSemaphore

SECURITY_ATTRIBUTES

旗號物件

同步處理函式