LocalAlloc 함수(winbase.h)

아티클
08/27/2023

힙에서 지정된 바이트 수를 할당합니다.

참고 로컬 함수는 오버헤드가 더 크고 다른 메모리 관리 함수보다 적은 기능을 제공합니다. 설명서에서 로컬 함수를 사용해야 한다고 명시하지 않는 한 새 애플리케이션은 힙 함수를 사용해야 합니다. 자세한 내용은 전역 및 로컬 함수를 참조하세요.

구문

DECLSPEC_ALLOCATOR HLOCAL LocalAlloc(
  [in] UINT   uFlags,
  [in] SIZE_T uBytes
);

매개 변수

[in] uFlags

메모리 할당 특성입니다. 기본값은 LMEM_FIXED 값입니다. 이 매개 변수는 특별히 언급된 호환되지 않는 조합을 제외하고 다음 값 중 하나 이상이 될 수 있습니다.

값	의미
LHND 0x0042	LMEM_MOVEABLE 및 LMEM_ZEROINIT 결합합니다.
LMEM_FIXED 0x0000	고정 메모리를 할당합니다. 반환 값은 메모리 개체에 대한 포인터입니다.
LMEM_MOVEABLE 0x0002	이동 가능한 메모리를 할당합니다. 메모리 블록은 실제 메모리에서 이동되지 않지만 기본 힙 내에서 이동할 수 있습니다. 반환 값은 메모리 개체에 대한 핸들입니다. 핸들을 포인터로 변환하려면 LocalLock 함수를 사용합니다. 이 값은 LMEM_FIXED 결합할 수 없습니다.
LMEM_ZEROINIT 0x0040	메모리 콘텐츠를 0으로 초기화합니다.
LPTR 0x0040	LMEM_FIXED 및 LMEM_ZEROINIT 결합합니다.
NONZEROLHND	LMEM_MOVEABLE 동일합니다.
NONZEROLPTR	LMEM_FIXED 동일합니다.

다음 값은 사용되지 않지만 16비트 Windows와의 호환성을 위해 제공됩니다. 무시됩니다.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

할당할 바이트 수입니다. 이 매개 변수가 0이고 uFlags 매개 변수가 LMEM_MOVEABLE 지정하는 경우 함수는 삭제된 것으로 표시된 메모리 개체에 대한 핸들을 반환합니다.

반환 값

함수가 성공하면 반환 값은 새로 할당된 메모리 개체에 대한 핸들입니다.

함수가 실패하면 반환 값은 NULL입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

Windows 메모리 관리는 별도의 로컬 힙 및 전역 힙을 제공하지 않습니다. 따라서 LocalAlloc 및 GlobalAlloc 함수는 기본적으로 동일합니다.

movable-memory flags LHND, LMEM_MOVABLE 및 NONZEROLHND 는 불필요한 오버헤드를 추가하고 잠금을 안전하게 사용해야 합니다. 설명서에서 사용해야 한다고 구체적으로 명시하지 않는 한 피해야 합니다.

설명서에서 로컬 함수를 사용해야 한다고 구체적으로 명시하지 않는 한 새 애플리케이션은 힙 함수를 사용해야 합니다. 예를 들어 일부 Windows 함수는 LocalFree를 사용하여 해제해야 하는 메모리를 할당합니다.

힙에 요청을 충족할 수 있는 충분한 여유 공간이 없으면 LocalAlloc 에서 NULL을 반환합니다. NULL은 오류를 나타내는 데 사용되므로 가상 주소 0은 할당되지 않습니다. 따라서 NULL 포인터의 사용을 쉽게 감지할 수 있습니다.

LocalAlloc 함수가 성공하면 요청된 양 이상을 할당합니다. 할당된 금액이 요청된 금액보다 크면 프로세스에서 전체 금액을 사용할 수 있습니다. 할당된 실제 바이트 수를 확인하려면 LocalSize 함수를 사용합니다.

메모리를 해제하려면 LocalFree 함수를 사용합니다. GlobalFree를 사용하여 LocalAlloc에 할당된 메모리를 해제하는 것은 안전하지 않습니다.

예제

다음 코드에서는 LocalAlloc 및 LocalFree를 간단하게 사용하는 방법을 보여줍니다.

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _cdecl _tmain()
{
    LPTSTR pszBuf=NULL;

    pszBuf = (LPTSTR)LocalAlloc(
              LPTR,
              MAX_PATH*sizeof(TCHAR));

    // Handle error condition
    if( pszBuf == NULL )
    {
       _tprintf(TEXT("LocalAlloc failed (%d)\n"), GetLastError());
       return;
    }

    //see how much memory was allocated
    _tprintf(TEXT("LocalAlloc allocated %d bytes\n"), LocalSize(pszBuf));

    // Use the memory allocated

    // Free the memory when finished with it
    LocalFree(pszBuf);
}

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winbase.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll