본문 바로가기

[+] Information/[-] Reference

[Win32 Reference] CreateFile() API

CreateFile

원형

HANDLE CreateFile(LPCTSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES pSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile);

MFC 원형

해당하는 함수 없음

인수

▶lpFileName : 생성하고자 하는 파일(또는 오브젝트)의 이름을 지정한다. 오브젝트의 이름은 최대 MAX_PATH의 길이로 지정할 수 있으나 NT/2000에서 유니코드로 컴파일할 경우는 32000자까지의 길이를 사용할 수 있다. 이때 파일명은 "\\?\"로 시작되어야 한다. 파일의 경우 완전 경로를 줄 수도 있고 현재 디렉토리를 기준으로 한 상대 경로로 줄 수도 있다.

▶dwDesiredAccess : 파일에 대한 액세스 권한을 지정한다. 생성하거나 연 파일로 어떤 작업을 할 것인가에 따라 적절한 액세스 권한을 지정해야 한다. 다음 플래그 중 하나 또는 조합을 지정할 수 있는데 이 플래그들은 모든 오브젝트에 공통적으로 적용되는 일반형 권한이다.

플래그

설명

0

장치 오브젝트에 대한 쿼리 액세스만 요청한다. 이 권한으로 장치를 열 경우 실제로 장치를 액세스하지 않고도 장치의 특성을 조사할 수 있다. 예를 들어 디스켓이 없는 상태에서도 플로피 드라이브의 타입이나 용량등을 조사하는 것이 가능하다.

GENERIC_READ

읽기 위한 용도로 파일을 연다. 이 액세스 권한으로 연 파일은 읽을 수만 있으며 쓸 수는 없다.

GENERIC_WRITE

쓰기 위한 용도로 파일을 연다. 읽기와 쓰기를 동시에 하려면 GENERIC_READ | GENERIC_WRITE 플래그를 지정하면 된다.

액세스 권한은 가급적이면 최소한으로 요청하는 것이 좋다. 예를 들어 읽기만 할 용도로 파일을 연다면 GENERIC_READ 플래그만 주어야 한다. 불필요하게 읽기와 쓰기 액세스 권한을 동시에 요청할 경우 읽기 전용 파일이나 CD-ROM의 파일을 열지 못하게 된다.

이런 일반형 권한 외에 오브젝트 고유의 권한을 같이 지정하거나 아니면 일반형 권한없이 표준 권한과 고유형 권한으로 액세스 마스크를 구성할 수도 있다. 각 오브젝트의 고유한 권한에 대해서는 해당 오브젝트를 참조하기 바란다.

▶dwShareMode : 파일의 공유 모드를 지정한다. 공유 모드란 파일이 열려져 있는 상태에서 다른 프로세스가 또 이 파일을 오픈할 때 이를 허가할 것인가 아닌가를 지정한다. 만약 현재 프로세스가 파일을 쓰고 있는 상태에서 다른 프로세스가 파일을 읽을 수 없도록 하고 싶다면 공유 모드를 지정하지 않아야 한다. 다음 플래그들의 조합으로 공유 모드를 지정한다.

플래그

설명

FILE_SHARE_READ

다른 프로세스가 읽기 액세스 권한을 요청했을 때 이를 허가한다. 즉, 이 프로세스가 파일을 사용하는 동안에도 다른 프로세스가 파일을 읽을 수 있다.

FILE_SHARE_WRITE

다른 프로세스가 쓰기 액세스 권한을 요청했을 때 이를 허가한다. 즉, 이 프로세스가 파일을 사용하는 동안에도 다른 프로세스가 파일에 데이터를 쓸 수 있다.

FILE_SHARE_DELETE

NT/2000. 삭제 액세스 권한을 요청했을 때만 이를 허가한다.

▶pSecurityAttributes : 파일의 보안 속성을 지정하는 SECURITY_ATTRIBUTES 구조체의 포인터이다. 이 보안 속성에 따라 생성되는 파일의 보안 설명자가 달라지며 차일드 프로세스로 핸들을 상속할 수 있는가의 여부가 결정된다. NULL이면 핸들은 상속될 수 없으며 디폴드 보안 설명자가 할당된다. 단, 파일의 보안 설명자가 할당되기 위해서는 파일이 저장되는 디스크의 파일 시스템이 반드시 NTFS로 포맷되어 있어야 한다.

▶dwCreationDisposition : 파일을 생성할 것인지 열 것인지를 지정한다. 또한 생성하고자 하는 파일이 이미 존재하거나 또는 열고자 하는 파일이 없을 경우의 동작을 지정한다. 적절한 에러를 리턴받기 위해서는 이 플래그를 신중하게 잘 지정해 주어야 한다. 그렇지 않으면 없는 파일이 열리거나 기존 파일이 깨지는 등 프로그램이 오동작을 할 위험이 있다.

플래그

설명

CREATE_NEW

파일을 새로 만든다. 만약 이미 파일이 존재한다면 에러를 리턴한다.

CREATE_ALWAYS

항상 파일을 새로 만든다. 만약 이미 파일이 존재한다면 해당 파일을 덮어쓴다. 이는 기존 파일을 삭제하고 다시 만드는 것과 같다. 파일의 존재 여부에 상관없이 무조건 파일을 생성한다.

OPEN_EXISTING

이미 존재하는 파일을 연다. 만약 열고자 하는 파일이 없다면 이 함수는 에러를 리턴한다. 파일이 아닌 장치를 열고자 할 때는 반드시 이 플래그를 사용해야 한다.

OPEN_ALWAYS

무조건 파일을 연다. 열고자 하는 파일이 없을 경우는 직접 만든 후 이 파일을 연다. 파일이 없어도 에러를 리턴하지 않으므로 기존 파일을 열 때는 이 플래그를 사용하지 말아야 한다.

TRUNCATE_EXISTING

파일을 연 후 크기를 0으로 만든다. 즉, 기존 파일을 다시 작성하고자 할 때 이 플래그를 사용한다. 이 플래그를 사용하는 프로세스는 쓰기 액세스 권한으로 파일을 열어야 하며 파일이 없을 경우는 에러를 리턴한다.

▶dwFlagsAndAttributes : 생성할 파일의 속성 또는 기타 옵젝트이 속성을 지정한다. 파일의 속성은 다음 플래그들의 조합을 사용할 수 있다.

플래그

설명

FILE_ATTRIBUTE_ARCHIVE

기록 속성을 설정한다. 파일의 기록 속성은 백업, 리스토어 프로그램에 의해 사용되며 이 파일이 백업되어야 함을 알리는 플래그이다.

FILE_ATTRIBUTE_ENCRYPTED

파일을 암호화한다. 파일의 경우 파일의 데이터를 암호화하며 디렉토리의 경우 이후부터 생성되는 파일과 서브 디렉토리를 암호화하도록 한다. 시스템 파일에는 적용되지 않는다.

FILE_ATTRIBUTE_HIDDEN

숨김 파일로 생성한다. 숨김 파일은 통상적인 방법으로는 보이지 않으므로 목록에 나타나지 않는다.

FILE_ATTRIBUTE_NORMAL

아무런 속성도 가지지 않는 파일을 만든다. 이 이 플래그는 단독으로 사용될 때만 유효하며 다른 플래그와 함께 사용하면 해당 플래그의 속성이 설정되다.

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED

컨텐트 인덱싱 서비스에 대해 인덱스되지 않도록 한다.

FILE_ATTRIBUTE_OFFLINE

데이터가 오프라인 상태이며 즉시 사용할 수 있는 상태가 아니다. 이 속성은 윈도우즈 2000의 계층적 저장 관리자의 원격 저장소에 의해 사용되므로 응용 프로그램이 이 플래그를 직접 사용해서는 안된다.

FILE_ATTRIBUTE_READONLY

읽기 전용의 파일로 생성한다. 응용 프로그램은 이 파일의 내용을 읽을 수는 있지만 변경하거나 삭제할 수는 없다.

FILE_ATTRIBUTE_SYSTEM

시스템 파일로 생성한다. 시스템 파일은 운영체제에 의해 배타적으로 사용되는 파일이다.

FILE_ATTRIBUTE_TEMPORARY

임시 파일로 생성한다. 임시 파일은 디스크로 곧바로 입출력을 행하지 않고 가급적이면 메모리상에서 읽기와 쓰기를 수행하기 때문에 일반 파일보다 입출력 속도가 빠르다는 장점이 있다. 응용 프로그램은 임시파일을 다 사용한 후 반드시 삭제해 주어야 한다.

파일 속성과 함께 다음 플래그들도 같이 지정할 수 있다.

플래그

설명

FILE_FLAG_WRITE_THROUGH

가급적이면 캐시를 사용하지 않고 곧바로 디스크로 입출력을 행하도록 한다. 그러나 이 플래그를 지정해도 시스템이 쓰기 캐시를 사용할 수는 있되 다만 너무 늦게 버퍼를 비우지 않도록 해 준다. 기록 후 곧바로 사용해야 하는 데이터는 이 플래그를 주는 것이 좋다.

FILE_FLAG_OVERLAPPED

파일 입출력이 완전히 끝날 때까지 대기하지 않고 곧바로 리턴하는 비동기 입출력 모드로 파일을 연다. 이 모드를 사용하면 입출력 시간이 오래 걸릴 때 백그라운드로 파일을 액세스할 수 있으며 하나의 파일 핸들로 동시에 액세스가 가능하다. 이 모드로 열려진 파일을 액세스하는 함수는 OVERLAPPED 구조체를 초기화한 후 제공해여 한다.

비동기 입출력에 관한 상세한 내용은 34-1-사절을 참조하기 바란다.

FILE_FLAG_NO_BUFFERING

버퍼링이나 캐시를 하지 않으므로써 비동기 효율을 극대화한다. 이 플래그를 사용하기 위해서는 몇가지 요구 사항을 충족시켜야 한다.

FILE_FLAG_RANDOM_ACCESS

파일을 랜덤으로 액세스한다는 것을 시스템에게 알려준다. 시스템은 캐시를 최적화할 때 이 정보를 사용한다. 이 플래그는 어디까지나 시스템에 대한 힌트일 뿐이다.

FILE_FLAG_SEQUENTIAL_SCAN

파일을 순차 액세스한다는 것을 시스템에 알려준다. 시스템은 캐시 최적화에 이 정보를 사용하여 순차 액세스의 효율을 높일 수 있는 방식으로 캐시를 사용한다. 그러나 이 플래그를 지정했다고 해서 랜덤 액세스를 하지 못하는 것은 아니다. 큰 파일을 대부분 순차적으로 액세스하고 드물게 랜덤 액세스를 할 경우 이 플래그를 지정하면 효율을 높일 수 있다.

FILE_FLAG_DELETE_ON_CLOSE

이 파일에 대한 모든 핸들이 닫히면 파일을 삭제하도록 한다.

FILE_FLAG_BACKUP_SEMANTICS

NT/2000 이후. 백업, 리스토어를 위해 파일을 연다. 이 경우 시스템은 보안 체크를 무시한다.

FILE_FLAG_POSIX_SEMANTICS

파일을 POSIX 규칙대로 액세스한다. 파일명은 대소문자를 구분하며 대소문자만 다른 같은 파일명을 액세스할 수 있다. 이렇게 생성된 파일은 16비트 프로그램에서 액세스할 수 없다.

FILE_FLAG_OPEN_REPARSE_POINT

Specifying this flag inhibits the reparse behavior of NTFS reparse points. When the file is opened, a file handle is returned, whether the filter that controls the reparse point is operational or not. This flag cannot be used with the CREATE_ALWAYS flag.

FILE_FLAG_OPEN_NO_RECALL

Indicates that the file data is requested, but it should continue to reside in remote storage. It should not be transported back to local storage. This flag is intended for use by remote storage systems or the Hierarchical Storage Management system.

▶hTemplateFile : 생성될 파일의 속성을 제공할 템플릿 파일이다. 95/98은 템플릿 파일을 지원하지 않으므로 반드시 NULL이어야 한다.

리턴

생성 또는 연 파일의 핸들을 리턴한다. 실패할 경우 INVALID_HANDLE_VALUE를 리턴하는데 이 값은 NULL과는 다르므로 NULL과 비교해서는 안된다. 즉 다음과 같은 에러 처리는 잘못된 것이므로 주의하기 바란다.

hFile=CreateFile(...
if (hFile == NULL) {
에러처리
}

이 함수를 출하기 전에 파일이 이미 존재하고 있었으면 GetLastError는 ERROR_ALREADY_EXISTS를 리턴한다.

설명

이 함수는 파일을 생성하는 가장 기본적인 함수이다. 그러나 이름과는 달리 파일을 생성하는 것뿐만 아니라 기존의 파일을 열 수도 있으며 파일 외에 다음과 같은 오브젝트를 생성하거나 열 수도 있다.

파이프
메일슬롯
COM 포트 등의 통신 장치
디스크 장치
테입 드라이브
콘솔
디렉토리

이 함수로 생성한 핸들은 반드시 CloseHandle로 닫아 주어야 한다.

예제 1

다음 예제는 파일을 생성하고 파일에 텍스트를 기록한다.

LRESULT CALLBACK WndProc(HWND hWnd,UINT iMessage,WPARAM wParam,LPARAM lParam)
{
	HDC hdc;
	PAINTSTRUCT ps;
	HANDLE hFile;
	DWORD dwWritten;
	LPCTSTR str=TEXT("테스트 파일입니다");

	switch(iMessage) {
	case WM_LBUTTONDOWN:
		hFile=CreateFile("c:\\TestFile.txt",GENERIC_WRITE,0,NULL,
			CREATE_ALWAYS,FILE_ATTRIBUTE_NORMAL,NULL);
		WriteFile(hFile,str,lstrlen(str),&dwWritten,NULL);
		CloseHandle(hFile);
		return 0;
	case WM_PAINT:
		hdc=BeginPaint(hWnd, &ps);
		EndPaint(hWnd, &ps);
		return 0;
	case WM_DESTROY:
		PostQuitMessage(0);
		return 0;
	}
	return(DefWindowProc(hWnd,iMessage,wParam,lParam));
}

C드라이브의 루트 디렉토리에 TestFile.txt 파일을 쓰기 액세스 권한으로 생성하였다. CREATE_ALWAYS 플래그를 주어 파일이 있을 경우 새로 만든다. 예제를 실행한 후 TestFile.txt 를 확인해 보면 문자열이 기록되어 있을 것이다.

참고함수

ReadFile : 파일로부터 데이터를 읽는다.
WriteFile : 파일에 데이터를 기록한다.
CloseHandle : 핸들을 닫는다.

플랫폼

95이상

참조

액세스 권한에 대한 상세한 내용은 39-2-사절을 참고하기 바란다.