CreateFileMapping(A)

CreateFileMapping(A)

지정된 파일에 대한 파일 매핑 오브젝트를 작성 또는 오픈합니다.

HANDLE CreateFileMappingA(
    HANDLE  hFile,            // 파일 핸들
    PSECURITY_ATTRIBUTES psa, // 시큐러티 지정
    DWORD   fdwProtect,       // 파일 데이터 보호 속성
    DWORD   dwMaxSizeHigh,    // 사이즈의 상위32비트
    DWORD   dwMaxSizeLow,     // 사이즈의 하위32비트
    PCTSTR  pszName           // 오브젝트의 이름
);

KERNEL32.DLL

인수

hFile

매핑 오브젝트를 작성하기 위한 파일의 핸들을 지정합니다.이것은 CreateFile함수등에 의해서 취득되는 것입니다.이 파일 핸들은,fdwProtect그리고 지정되는 보호 속성과 모순되지 않는 액세스권을 가지고 있지 않으면 안됩니다.매핑 하는 파일이 배타 액세스로 오픈되고 있는 것이 추천 됩니다(필수가 아닙니다).

-1 (INVALID_HANDLE_VALUE) (을)를 지정하면, 파일 시스템상에서 이름을 붙일 수 있었던 파일은 아니고 operating system의 페이징 파일에 의해서 지지를 받은, 지정 사이즈의 파일 매핑 오브젝트를 작성합니다.이 경우에는,dwMaxSizeHigh및dwMaxSizeLow파라미터에 오브젝트 사이즈를 지정하지 않으면 안됩니다.매핑 오브젝트는 복제나 계승이나 이름을 개입시켜 공유할 수 있습니다.파일 매핑 오브젝트내의 페이지의 내용은 초기 상태로 제로가 되어 있습니다.

psa

돌려주어지는 핸들을 child process에 계승할지를 결정한다 SECURITY_ATTRIBUTES구조체에의 포인터를 지정합니다.psa파라미터에0 (NULL) (을)를 지정하면 핸들은 계승되지 않습니다.

SECURITY_ATTRIBUTES구조체의lpSecurityDescriptor멤버는, 새로운 파일 매핑 오브젝트에 대한 시큐러티 기술자를 지정합니다.psa파라미터에0 (NULL) (을)를 지정하면, 파일 매핑 오브젝트는 디폴트의 시큐러티 기술자가 취득합니다.

fdwProtect

파일이 매핑 되었을 때에 파이르뷰에 요구하는 보호를 지정합니다.이하의 값의 어느쪽이든을 지정할 수 있습니다.

0x00000002 (PAGE_READONLY)

위탁된 페이지 영역에의 읽어내 전용 액세스를 줍니다.위탁 영역에의 기입 혹은 코드 실행을 실시하려고 하면 액세스 위반이 발생합니다.hFile파라미터로 지정된 파일은GENERIC_READ액세스권을 가지고 있지 않으면 안됩니다.

0x00000004 (PAGE_READWRITE)

위탁된 페이지 영역에의 읽어내·기입 액세스를 취득합니다.hFile파라미터로 지정된 파일은GENERIC_READ및GENERIC_WRITE액세스권을 가지고 있지 않으면 안됩니다.

0x00000008 (PAGE_WRITECOPY)

위탁된 페이지 영역에의 카피 온 라이트 액세스를 줍니다.hFile파라미터로 지정된 파일은GENERIC_READ및GENERIC_WRITE액세스권을 가지고 있지 않으면 안됩니다.

게다가 상기의 페이지 보호 속성에 가세하고, 이하의 섹션 속성치를 조합해 지정할 수 있습니다.

0x1000000 (SEC_IMAGE)

섹션의 파일 매핑에 대해서 지정된 파일은 실행 가능 이미지 파일입니다.매핑 정보 및 파일 보호 속성은 이미지 파일로부터 취득되기 위해, 다른 속성을SEC_IMAGE(와)과 함께 지정할 수 없습니다.

Windows 95/98/Me： 이 플래그는 서포트되지 않습니다.

0x4000000 (SEC_RESERVE)

섹션의 전페이지를 예약합니다.물리 스토리지의 확보는 실시하지 않습니다.예약된 페이지 영역은, 그 영역이 해방될 때까지, 다른 메모리 확보 조작에 의해서 사용될 것은 없습니다.다음에VirtualAlloc함수를 호출해 예약 페이지를 위탁할 수 있습니다.이 속성은,hFile파라미터가INVALID_HANDLE_VALUE인 경우에게만 유효합니다.

0x8000000 (SEC_COMMIT)

섹션의 전페이지에 대해서, 메모리내 혹은 디스크상 페이징 파일내의 물리 스토리지를 확보합니다.이것은 디폴트의 설정입니다.

0x10000000 (SEC_NOCACHE)

섹션의 전페이지를 캐쉬 불가로 설정합니다.이 속성은, 여러 가지의 락 구조체가 메모리내에 놓여지도록(듯이) 해, 프로세서내의 캐시 기억 장치에 놓여지지 않게 하기 위해서 이용됩니다.80x86머신 및MIPS머신상에서는, 이러한 구조체에 대해서 캐쉬를 사용해도, 하드웨어가 캐쉬의 일관성을 유지하려고 할 때에 있어서의 퍼포먼스 저하 밖에 일으키지 않습니다.몇개의 디바이스 드라이버는 프로그램이 물리 메모리에 제대로 써지도록(듯이) 비캐쉬의 데이터를 요구합니다.SEC_NOCACHE(을)를 지정하려면 ,SEC_RESERVE또는SEC_COMMIT의 언젠가를 함께 지정할 필요가 있습니다.

Windows 95/98/Me： 이 플래그는 서포트되지 않습니다.

dwMaxSizeHigh

파일 매핑 오브젝트의 최대 사이즈의 상위32비트를 지정합니다.

Windows 95/98/Me： 이 파라미터는 무시됩니다.

dwMaxSizeLow

파일 매핑 오브젝트의 최대 사이즈의 하위32비트를 지정합니다.

dwMaxSizeHigh파라미터 및dwMaxSizeLow파라미터에 함께0(을)를 지정하면, 파일 매핑 오브젝트의 최대 사이즈는hFile파라미터로 지정된 파일의 현재의 사이즈와 같게 됩니다.

이 방법으로 사이즈가 제로의 파일을 매핑 하려고 하면, 함수는 실패해 확장 에러 코드ERROR_FILE_INVALID(을)를 돌려줍니다.어플리케이션은 사이즈가 제로의 파일을 체크하고, 그러한 파일을 제외해야 합니다.

pszName

파일 매핑 오브젝트의 이름을 나타내는 문자열에의 포인터를 지정합니다.

지정된 이름이 기존의 이름 다해 매핑 오브젝트의 이름과 일치하면, 함수는 매핑 오브젝트에의 액세스를fdwProtect그리고 지정되는 보호 속성으로 요구합니다.

이 파라미터에0 (NULL) (을)를 지정하면, 이름을 가지지 않는 매핑 오브젝트가 작성됩니다.

지정된 이름이 기존의 이벤트, semaphore, 뮤텍스, 웨이타브르타이마, 작업 오브젝트의 이름과 일치하면, 함수는 실패해 확장 에러 코드ERROR_INVALID_HANDLE(을)를 돌려줍니다.이것은, 이러한 오브젝트가 같은 이름 공간을 공유하고 있기 위해서 일어납니다.

터미널 서비스： 이름은“Global\”또는“Local\”프레픽스를 붙이고, 명시적으로 글로벌 이름 공간 또는 세션 이름 공간에 오브젝트를 작성할 수 있습니다.이름의 나머지의 부분에는, backslash 문자(\) 이외의 모든 문자를 사용할 수 있습니다.

Windows XP Home： 고속의 유저 변환이 터미널 서비스 세션에 의해 제공되고 있습니다.최초의 로그 온 유저가 세션0(을)를 사용해, 다음의 유저가 세션1(을)를 사용해,…되고 있습니다.어플리케이션이 복수 유저를 서포트할 수 있도록(듯이), 커넬 오브젝트의 이름은 터미널 서비스에 관해서 기술되고 있는 가이드 라인에 따르지 않으면 안됩니다.

Windows 2000： 터미널 서비스가 실행되어 있지 않은 경우, “Global\” 및“Local\”프레픽스는 무시됩니다.이름의 나머지의 부분에는, backslash 문자(\) 이외의 모든 문자를 사용할 수 있습니다.

Windows 95/98/Me： 이름에는 backslash 문자(\) 이외의 모든 문자를 사용할 수 있습니다.공문자열(“”)도 유효한 오브젝트명으로서 다루어집니다.

반환값

성공하면, 작성된 매핑 오브젝트의 핸들이 돌아갑니다.벌써 존재하는 오브젝트의 핸들이 돌려주어졌을 경우, 함수는 기존의 오브젝트의 핸들을 돌려주어, 직후에 불려 갔다 GetLastError함수는183 (ERROR_ALREADY_EXISTS) (을)를 돌려줍니다.이 때, 파일 매핑 오브젝트의 사이즈는 지정된 것에는 안되어에, 기존의 오브젝트의 사이즈대로 됩니다.

실패하면 0 (NULL) 하지만 돌아갑니다.확장 에러 정보를 취득하려면 , GetLastError함수를 사용합니다.

해설

파일 매핑 오브젝트를 작성한 다음에, 파일 사이즈를 파일 매핑 오브젝트의 사이즈 이상으로 확장 해서는 안됩니다.사이즈 확장을 실시하면, 파일의 내용 전체를 공유에 이용할 수 없게 됩니다.

디스크상의 파일 그 자체의 사이즈보다 큰 사이즈를 파일 매핑 오브젝트에 대해서 지정하면, 디스크상의 파일이 지정된 파일 매핑 오브젝트의 사이즈와 일치하도록(듯이) 확장됩니다.파일 사이즈를 확장시킬 수 없는 경우에는, 파일 매핑 오브젝트의 작성은 실패해, 확장 에러 코드ERROR_DISK_FULL(을)를 돌려줍니다.

CreateFileMapping함수가 돌려준 핸들은, 새로운 파일 매핑 오브젝트에 대한 전액세스권을 가집니다.이 핸들은, 파일 매핑 오브젝트의 핸들을 필요로 하는 함수로 사용할 수 있습니다.프로세스의 작성, 핸들의 복제, 혹은 오브젝트의 이름을 개입시키고, 파일 매핑 오브젝트를 공유할 수 있습니다.

Windows Me/98/95: 파일 매핑 오브젝트를 작성하는데 사용된 파일 핸들을, ReadFile함수나 WriteFile함수등의 파일I/O함수의 호출로 사용 해서는 안됩니다.일반적으로,CreateFileMapping함수의 호출로 사용된 파일 핸들은, 파일 매핑 오브젝트가 클로우즈 될 때까지 사용 해서는 안됩니다.

파일 매핑 오브젝트를 작성해도, 파이르뷰의 매핑은 행해지지 않습니다. MapViewOfFile함수 또는MapViewOfFileEx함수에 의해, 파일의 뷰가 프로세스의 address 공간에 매핑 됩니다.

단일의 파일 매핑 오브젝트로부터 생성된 파이르뷰는, 임의의 시점에서의 정합성을 가집니다.즉, 그러한 뷰의 내용이 어떤 시점에 동일하다라고 하는 것이 보증됩니다.복수의 프로세스가 같은 파일 매핑 오브젝트에 대한 핸들을 가지고 있는 경우, 그러한 프로세스는, 파이르뷰를 매핑 했을 때에 정합성이 있는 뷰를 참조할 수 있습니다.

다만, 리모트 파일에 관해서는 예외입니다.CreateFileMapping함수를 리모트 파일에 대해서 사용할 수 있습니다만, 그 정합성은 유지되지 않습니다.예를 들면,2개의 컴퓨터가 같은 파일을 써 가능하고 매핑 해, 양쪽 모두가 동시에 같은 페이지를 고쳐 쓰면, 각각의 컴퓨터에서는, 자신이 고쳐 쓴 페이지 내용 밖에 참조되지 않습니다.데이터가 디스크상에서 갱신될 때에 이것들은 통합되지 않습니다.

매핑 된 파일과 ReadFile함수나 WriteFile함수등의 파일I/O함수에 의해 액세스 되는 파일과의 사이에는, 정합성이 보증되지 않습니다.

오브젝트를 완전하게 클로우즈 하려면 , UnmapViewOfFile함수를 호출해 파일 매핑 오브젝트의 모든 매핑 되고 있는 뷰를 매핑 해제해, CloseHandle함수를 호출해 오브젝트의 핸들을 클로우즈 하지 않으면 안됩니다.이러한 함수를 호출하는 순서는 중시되지 않습니다.파일 매핑 오브젝트의 뷰는 내부에서 오픈된 오브젝트 핸들을 보관 유지하고 있어, 오픈 떠날 수 있어 모든 핸들이 클로우즈 되지 않는 한 파일 매핑 오브젝트는 클로우즈 되지 않기 때문에, UnmapViewOfFile함수의 호출은 필수입니다.

터미널 서비스의 세션은, 공유 메모리브록크를 사용하고, 그러한 세션으로 생성된 프로세스간에 데이터를 전송 할 수 있습니다.이 경우에는, 이하의 조건이 동시에 존재하는 상황하에서는 공유 메모리를 사용할 수 없다고 하는 것에 유의해 둘 필요가 있습니다.

• 공유 메모리브록크를 사용하고 있는 모든 프로세스가1개의 섹션으로 작성된 것이 아닌 경우.
• 모든 세션이 같은 유저 로그 온 증명서를 공유하고 있는 경우

액세스 위반을 막으려면 , 구조화 예외 처리를 사용해 메모리맙핑 된 뷰에의 기입이나 독해를 하고 있는 코드를 보호합니다.

대응 정보

Windows 95 이후 / Windows NT 3.1 이후