WriteFile

WriteFile

파일에 데이터를 씁니다.파일 포인터의 현재 위치가, 기입의 개시 위치가 됩니다.동기 기입 조작에서는, 기입이 종료하면, 파일 핸들이 오버랩 속성 지정으로 작성되어 있지 않은 한, 파일 포인터의 위치는 쓴 바이트 수 만큼 진행됩니다.비동기 기입 조작에서는, 어플리케이션측에서 파일 포인터를 조정할 필요가 있습니다.

BOOL WriteFile(
    HANDLE   hFile,                  // 파일 핸들
    LPCVOID  pBuffer,                // 버퍼 주소
    DWORD    nNumberOfBytesToWrite,  // 사이즈
    LPDWORD  pNumberOfBytesWritten,  // 실제의 사이즈를 격납하는 변수
    LPOVERLAPPED  pOverlapped        // OVERLAPPED구조체
);

KERNEL32.DLL

인수

hFile

독해처의 파일의 핸들을 지정합니다.파일 핸들은 CreateFile 함수로 취득할 수 있습니다.이 핸들은, GENERIC_WRITE 액세스를 가지고 있지 않으면 안됩니다.

Windows NT/2000/XP： CreateFile 함수로 FILE_FLAG_OVERLAPPED 플래그를 지정해 오픈된 모든 종류의 핸들, 또는, socket 함수 혹은 accept 함수로부터 돌려주어진 소켓 핸들을, 비동기 기입 조작으로 hFile 파라미터로 지정할 수 있습니다.

Windows 95/98/Me： CreateFile 함수로 FILE_FLAG_OVERLAPPED 플래그를 지정해 오픈된 커뮤니케이션 자원의 핸들, 또는, socket 함수 혹은 accept 함수로부터 돌려주어진 소켓 핸들을, 비동기 기입 조작으로 hFile 파라미터로 지정할 수 있습니다.메일 슬롯이나 이름 파이프, 디스크 파일로부터의 비동기 기입 조작을 행할 수 없습니다.

pBuffer

쓰는 데이터가 들어간 버퍼의 주소를 지정합니다.

nNumberOfBytesToWrite

쓰는 바이트 수를 지정합니다.

0 (을)를 지정하면, NULL 의 기입 조작이다고 해석되어 타임 스탬프가 변경됩니다.(데이터는 변경되지 않습니다.)

네트워크를 개입시킨 이름 파이프에의 써 조작에서는, 65535 이하를 지정하지 않으면 안됩니다.

pNumberOfBytesWritten

실제로 써진 바이트 수를 격납하기 위한 변수의 주소를 지정합니다.

Windows NT/2000/XP： pOverlapped 파라미터에 유효한 주소를 지정했을 경우는 0 (NULL) (을)를 지정할 수 있습니다.비동기 기입 조작의 경우는, GetOverlappedResult 함수를 호출하는 것으로 써진 바이트 수를 취득할 수 있습니다. hFile 파라미터가 I/O 완료 포토와 관련지을 수 있고 있는 경우는, GetQueuedCompletionStatus 함수를 호출하는 것으로 써진 바이트수를 취득할 수 있습니다.

Windows 95/98/Me： 이 파라미터에 0 (NULL) (을)를 지정할 수 없습니다.

pOverlapped

유효한 OVERLAPPED 구조체의 주소 또는 0 (NULL) (을)를 지정합니다.

hFile 파라미터의 핸들이 FILE_FLAG_OVERLAPPED 플래그를 가지지 않을 때, 한편, 이 파라미터에 0 (NULL) (을)를 지정했을 때는, 파일 포인터의 현재 위치로부터 파일이 동기적으로 써집니다.기입이 완료하면, 제어가 돌아갑니다.

hFile 파라미터의 핸들이 FILE_FLAG_OVERLAPPED 플래그를 가질 때, 한편, 이 파라미터로 유효한 OVERLAPPED 구조체의 주소를 지정했을 때는, OVERLAPPED 구조체로 지정된 오프셋으로부터 파일이 비동기적으로 써집니다.제어는 곧바로 돌아갑니다만, 기입이 완료하고 있다고는 할 수 없습니다.기입이 종료하고 있지 않는 경우는, WriteFile 함수는 실패해, GetLastError 함수는 997 (ERROR_IO_PENDING) (을)를 돌려줍니다.그 후, 기입이 완료하면, OVERLAPPED 구조체로 지정한 이벤트가 시그널 상태가 됩니다.

Windows NT/2000/XP： hFile 파라미터의 핸들이 FILE_FLAG_OVERLAPPED 플래그를 가지지 않을 때, 한편, 이 파라미터로 유효한 OVERLAPPED 구조체의 주소를 지정했을 때는, OVERLAPPED 구조체로 지정한 오프셋으로부터 파일이 동기적으로 써집니다.기입이 완료하면, 제어가 돌아갑니다.

Windows 95/98/Me： 파일, 디스크, 파이프, 메일 슬롯에의 조작을 행하는 경우, 이 파라미터는 0 (NULL) (이)가 아니면 안됩니다. 0 (NULL) 이외의 값을 지정하면 호출은 실패합니다.다만, 시리얼 포트 및 패러렐 포토의 비동기 입출력은 서포트됩니다.

반환값

성공하면 0 이외의 값이 돌아갑니다.

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

해설

다른 프로세스에 의해서 락 되고 있는 영역에 쓰려고 하면, 이 함수는 실패합니다.

기입 조작이 종료하지 않는 한, pBuffer 파라미터로 지정된 버퍼의 내용을 변경 해서는 안됩니다.

미처리의 비동기 I/O 하지만 대량으로 남아 있을 때, WriteFile 함수가 실패해 GetLastError 함수가 1784 (ERROR_INVALID_USER_BUFFER) 또는 8 (ERROR_NOT_ENOUGH_MEMORY) (을)를 돌려주는 일이 있습니다.

대응 정보

Windows 95 이후 / Windows NT 3.1 이후