Windows CreateFile Possible Error Codes

Question

I'm playing around with abstracting Windows, Linux, and Mac File IO calls into macros (to avoid C runtime, so no fopen, fclose, etc...). I've actually got quite a bit working but I've run into a stumbling block.

I'm trying to boil down all of the possible errors that could be thrown by each of these platforms into a subset of common ones: Not Found, Exists, Invalid Access, etc.

Linux is obviously well document, Mac even has the most common ones, but Windows does not specify which errors are thrown for its native File I/O functions. We obviously need to use GetLastError(), but I could not find a reference to what the possible values would be.

How about this?

I'm writing a Windows application and using the CreatFile() API. I'd like to handle any errors as gracefully as I can, and perhaps recover from said error instead of telling the user "Crap! Can't do that." But the MSDN docs don't list the possible error codes that could be generated.

Does anyone have a reference to the possible error codes that Windows File functions may generate, specifically (for now) CreateFile()?

Answer 1

Windows supports installable file systems. Microsoft cannot possibly predict what kind of errors a 3rd party file system driver is going to generate so does not make any attempt to promise a strict sub-set of possible error codes.

So yes, you really do have to use GetLastError(). The FormatMessage() function is available to generate a readable string for the error code. In general, the user will get a decent error message that helps him diagnose the root cause. It isn't quite specific enough to tell that an earthquake in Chile severed an undersea communication cable but it will certainly help him to start looking at networking problems for example. You can use the CRT wrappers as well, but with the inevitable loss of specificity. That might be a service call that you have to handle instead of the user's IT staff.

Answer 2

to avoid C runtime

You're reinventing the wheel. C runtime was created so people could write platform-independent programs that (theorietcally) would compile anywhere, as long as you aren't using something platform-specific. Right now, you're doing the same thing.

I'd advise to stop doing that and either use standard C file function, or cross-platform framework that support several platform. You could use either Boost or Qt 4.

Regarding your question

Does anyone have a reference to the possible error codes that Windows File functions may generate,

WinAPI documentation is available on MSDN and you should read it.
CreateFile
GetLastError
SystemErrorCodes

Does anyone have a reference to the possible error codes that Windows File functions may generate

Because CreateFile doesn't only deal with "files" (it also works with directories, pipes, physical devices, etc), you should assume that it can generate any operating system code that exists. According to msdn, there are 16000 codes total. Moral of the story: if you want to generate human-readable message, use FormatMessage. If documentation doesn't list possible error codes (for CreateFile), it automatically means, that CreateFile can produce any error code that exists.

Answer 3

As SigTerm stated, there's no definitive list of system error codes associated with CreateFile. Your best bet is searching for the keyword "ERROR" in the CreateFileA/CreateFileW documentation.

Otherwise, there's always web search engine. A quick DuckDuckGo search of "CreateFile" and "Error" reveals a slew of errors and error codes

You should also consult Microsoft's lengthy lists of System Error Codes and Win32 Error Codes.

Excerpts from CreateFileA/CreateFileW Documentation

param: dwShareMode

You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. CreateFile would fail and the GetLastError function would return ERROR_SHARING_VIOLATION (32).

param: dwCreationDisposition

CREATE_ALWAYS

If the specified file exists and is writable, the function overwrites the file, the function succeeds, and last-error code is set to ERROR_ALREADY_EXISTS (183).

CREATE_NEW

If the specified file exists, the function fails and the last-error code is set to ERROR_FILE_EXISTS (80).

OPEN_ALWAYS

If the specified file exists, the function succeeds and the last-error code is set to ERROR_ALREADY_EXISTS (183).

OPEN_EXISTING

If the specified file or device does not exist, the function fails and the last-error code is set to ERROR_FILE_NOT_FOUND (2).

TRUNCATE_EXISTING

If the specified file does not exist, the function fails and the last-error code is set to ERROR_FILE_NOT_FOUND (2).

Files

If you call CreateFile on a file that is pending deletion as a result of a previous call to DeleteFile, the function fails. The operating system delays file deletion until all handles to the file are closed. GetLastError returns ERROR_ACCESS_DENIED.

If CREATE_ALWAYS and FILE_ATTRIBUTE_NORMAL are specified, CreateFile fails and sets the last error to ERROR_ACCESS_DENIED if the file exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_SYSTEM attribute. To avoid the error, specify the same attributes as the existing file.

When an application creates a file across a network, it is better to use GENERIC_READ | GENERIC_WRITE for dwDesiredAccess than to use GENERIC_WRITE alone. The resulting code is faster, because the redirector can use the cache manager and send fewer SMBs with more data. This combination also avoids an issue where writing to a file across a network can occasionally return ERROR_ACCESS_DENIED.

Consoles

If lpFileName is indeterminate "CON" and dwDesiredAccess is GENERIC_READ | GENERIC_WRITE, CreateFile fails; GetLastError returns ERROR_FILE_NOT_FOUND.

• "CON" and GENERIC_READ implies a console handle for input.
• "CON" and "GENERIC_WRITE` implies a console handle for output.

Pipes

If the CreateNamedPipe function was not successfully called on the server prior to this operation, a pipe will not exist and CreateFile will fail with ERROR_FILE_NOT_FOUND.

If there is at least one active pipe instance but there are no available listener pipes on the server, which means all pipe instances are currently connected, CreateFile fails with ERROR_PIPE_BUSY.

Various errors from across the internet

• ERROR_INVALID_FUNCTION (1)
• ERROR_FILE_NOT_FOUND (2)
• ERROR_PATH_NOT_FOUND (3)
• ERROR_ACCESS_DENIED (5)
• ERROR_GEN_FAILURE (31) - A device attached to the system is not functioning. This can also occur when working with network devices e.g. virtual network adapters
• ERROR_SHARING_VIOLATION (32) - The process cannot access the file because it is being used by another process.
• ERROR_INVALID_PARAMETER (87) - "An application must meet certain requirements when working with files that are opened with FILE_FLAG_NO_BUFFERING: File access must begin at byte offsets within a file that are integer multiples of the volume sector size. File access must be for numbers of bytes that are integer multiples of the volume sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, 1536, or 2048 bytes, but not of 335, 981, or 7171 bytes. Buffer addresses for read and write operations should be sector aligned, which means aligned on addresses in memory that are integer multiples of the volume sector size. Depending on the disk, this requirement may not be enforced."
• ERROR_CALL_NOT_IMPLEMENTED (120) - using P/Invoke and calling to coredll.dll for Windows Pocket PC
• ERROR_INVALID_NAME (123)
• ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION (181)
• ERROR_FILE_TOO_LARGE (223)
• ERROR_CONNECTION_COUNT_LIMIT (1238)
• ERROR_MUTUAL_AUTH_FAILED (1397) - network auth e.g. serial COM port over Bluetooth
• ERROR_NO_SYSTEM_RESOURCES (1450) - e.g. working with Serial Ports