Dosya oluşturma ve açma

CreateFile işlevi yeni bir dosya oluşturabilir veya var olan bir dosyayı açabilir. Dosya adını, oluşturma yönergelerini ve diğer öznitelikleri belirtmelisiniz. Bir uygulama yeni bir dosya oluşturduğunda, işletim sistemi bunu belirtilen dizine ekler.

Doğru dosya API'sini seçme

Scenario	Önerilen API	Notlar
C/C++ dilinde basit dosya okuma/yazma	fopen / fread / fwrite (CRT) veya C++ std::ifstream/std::ofstream	Taşınabilir, arabelleği otomatik olarak işler. Çoğu uygulama düzeyi dosya G/Ç için yeterli.
Dosya yolu işleme ve numaralandırma	C++17 std::filesystem	Taşınabilir, modern C++. Dizin geçişi, yol işlemleri ve temel dosya meta verileri için kullanın.
Çakışan (zaman uyumsuz) G/Ç	CreateFile ile FILE_FLAG_OVERLAPPED	G/Ç tamamlama bağlantı noktaları, yüksek performanslı sunucular ve engelleyici olmayan dosya işlemleri için gereklidir.
Ayrıntılı paylaşım veya kilitleme	dwShareMode ile CreateFile	Yalnızca CreateFile, işlemler arasındaki eşzamanlı dosya erişimi üzerinde denetim sağlar.
Bellek eşlemeli dosyalar	CreateFile + CreateFileMapping	Paylaşılan bellek, büyük dosya rastgele erişimi ve işlemler arası iletişim için gereklidir.
Cihazlar, borular, posta yuvaları veya konsollar	CreateFile	CRT ve standart kitaplık API'leri bu Win32 nesne türlerini desteklemez.
.NET yönetilen uygulamalar	System.IO.File / System.IO.FileStream	.NET kodu için tercih edilir. CreateFile’ı arka planda kullanır, ancak istisna tabanlı hata işleme ve async/await sağlar.

Important

Hata işleme: Her zaman CreateFile değerinin dönüş değerini denetleyin. Hata durumunda döndürür INVALID_HANDLE_VALUE (değil NULL). Çağrı belirli bir hata kodunu alamadıktan hemen sonra GetLastError'ı çağırın. Yaygın hatalar arasında ERROR_FILE_NOT_FOUND, ERROR_ACCESS_DENIEDve ERROR_SHARING_VIOLATIONbulunur.

Note

Yaygın tuzak — dwShareMode: dwShareMode'un0 (özel erişim) olarak ayarlanması güvenlidir, ancak başka bir işlemde dosya zaten açıksa neden ERROR_SHARING_VIOLATION olabilir. Diğer işlemlerin eşzamanlı olarak okuyabileceği günlük dosyaları veya dosyalar için kullanın FILE_SHARE_READ. Koordinasyon mekanizmanız olmadığı sürece kaçının FILE_SHARE_WRITE ; eş zamanlı koordinasyonsuz yazma işlemleri dosya içeriğini bozabilir.

Uygulamanızdaki dosyalarla çalışma

İşletim sistemi, CreateFile kullanılarak açılan veya oluşturulan her dosyaya tanıtıcı olarak adlandırılan benzersiz bir tanımlayıcı atar. Bir uygulama bu tanıtıcıyı dosyayı okuma, yazma ve açıklama işlevleriyle kullanabilir. Bu tanıtıcıya yapılan tüm referanslar kapatılana kadar geçerlidir. Bir uygulama başlatıldığında, eğer tanıtıcılar devralınabilir olarak oluşturulmuşsa, uygulamayı başlatan işlemden tüm açık tanıtıcıları devralır.

Bir uygulama, dosyaya erişmek için tanıtıcıyı kullanmaya çalışmadan önce CreateFile tarafından döndürülen tanıtıcının değerini denetlemelidir. Hata oluşursa tanıtıcı değeri INVALID_HANDLE_VALUE olur ve uygulama genişletilmiş hata bilgileri için GetLastError işlevini kullanabilir.

Bir uygulama CreateFile kullandığında, dosyadan okuma, dosyaya yazma, hem okuma hem yazma veya hiçbirini yapma niyetini belirtmek için dwDesiredAccess parametresini kullanmalıdır. Bu, erişim moduistemek olarak bilinir. Uygulamanın ayrıca, oluşturma düzeni olarak bilinen, dosya zaten varsa hangi işlemin yapılacağını belirtmek için dwCreationDisposition parametresini kullanması gerekir. Örneğin, bir uygulama, CreateFile fonksiyonunu çağırabilir ve dwCreationDisposition parametresi, aynı isimli bir dosya mevcut olsa bile her zaman yeni bir dosya oluşturacak şekilde CREATE_ALWAYS olarak ayarlanabilir, böylece mevcut dosyanın üzerine yazılır. Bunun başarılı olup olmadığı, önceki dosyanın öznitelikleri ve güvenlik ayarları gibi faktörlere bağlıdır (daha fazla bilgi için aşağıdaki bölümlere bakın).

Bir uygulama, dosyayı okumak, yazmak, her ikisi veya hiçbiri için paylaşmak isteyip istemediğini belirtmek için CreateFile'ı da kullanır. Bu, paylaşım moduolarak bilinir. Paylaşılmayan açık bir dosya (dwShareMode sıfır olarak ayarlanır) tanıtıcısı kapatılana kadar, onu açan uygulama veya başka bir uygulama tarafından yeniden açılamaz. Buna özel erişim de denir.

Bir işlem paylaşım modunda açılmış bir dosyayı açmaya çalışmak için CreateFile'ı kullandığında (dwShareMode geçerli bir sıfır olmayan değere ayarlanır), sistem istenen erişim ve paylaşım modlarını dosya açıldığında belirtilenlerle karşılaştırır. Önceki çağrıda belirtilen modlarla çakişen bir erişim veya paylaşım modu belirtirseniz CreateFile başarısız olur.

Aşağıdaki tabloda, çeşitli erişim modlarını ve paylaşım modlarını (sırasıyla dwDesiredAccess, dwShareMode) kullanarak CreateFile'a yapılan iki çağrının geçerli birleşimleri gösterilmektedir. CreateFile çağrılarının hangi sırada yapıldığı önemli değildir. Ancak, her dosya tanıtıcısındaki sonraki tüm dosya G/Ç işlemleri, söz konusu dosya tanıtıcısıyla ilişkili geçerli erişim ve paylaşım modları tarafından kısıtlanmaya devam eder.

CreateFile'a ilk çağrı	CreateFile için geçerli ikinci çağrılar
GENERIC_READ, FILE_SHARE_READ	- GENERIC_READ, FILE_SHARE_READ - GENERIC_READ, FILE_SHARE_READFILE_SHARE_WRITE
GENERIC_READ, FILE_SHARE_WRITE	- GENERIC_WRITE, FILE_SHARE_READ - GENERIC_WRITE, FILE_SHARE_READFILE_SHARE_WRITE
GENEL_OKUMA, DOSYA_PAYLAŞIM_OKUMA, DOSYA_PAYLAŞIM_YAZMA	- GENERIC_READ, FILE_SHARE_READ - GENERIC_READ, FILE_SHARE_READ, FILE_SHARE_WRITE - GENERIC_WRITE, FILE_SHARE_READ - GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE - GENERIC_READGENERIC_WRITE,FILE_SHARE_READ - GENERIC_READGENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE
GENERIC_WRITE, FILE_SHARE_READ	- GENERIC_READ, FILE_SHARE_WRITE - GENERIC_READ, FILE_SHARE_READ, FILE_SHARE_WRITE
GENERIC_WRITE, FILE_SHARE_WRITE	- GENERIC_WRITE (Genel Yazma Yetkisi), FILE_SHARE_WRITE (Dosya Paylaşımı Yazma Yetkisi) - GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE
GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE	- GENERIC_READ, FILE_SHARE_WRITE - GENERIC_READ, FILE_SHARE_READ, FILE_SHARE_WRITE - GENERIC_WRITE (Genel Yazma Yetkisi), FILE_SHARE_WRITE (Dosya Paylaşımı Yazma Yetkisi) - GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE - GENERIC_READ, GENERIC_WRITE, FILE_SHARE_WRITE - GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE
GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ	- GENERIC_READ, FILE_SHARE_READ, FILE_SHARE_WRITE
GENERIC_READ, GENERIC_WRITE, FILE_SHARE_WRITE	- GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE
GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE	- GENERIC_READ, FILE_SHARE_READ, FILE_SHARE_WRITE - GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE - GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE

Standart dosya özniteliklerine ek olarak, createfile öğesinin dördüncü parametresi olarak bir SECURITY_ATTRIBUTES yapısına işaretçi ekleyerek güvenlik özniteliklerini de belirtebilirsiniz. Ancak, bunun herhangi bir etkiye sahip olması için temel dosya sisteminin güvenliği desteklemesi gerekir (örneğin, NTFS dosya sistemi bunu destekler, ancak çeşitli FAT dosya sistemleri desteklemez). Güvenlik öznitelikleri hakkında daha fazla bilgi için bkz. erişim denetimi.

Yeni dosya oluşturan bir uygulama şablon dosyasına isteğe bağlı bir tanıtıcı sağlayabilir. Bu tanıtıcıdan CreateFile , yeni dosyanın oluşturulması için dosya özniteliklerini ve genişletilmiş öznitelikleri alır.

CreateFile Senaryoları

CreateFile işlevini kullanarak bir dosyaya erişim başlatmaya yönelik çeşitli temel senaryolar vardır. Bunlar şu şekilde özetlenir:

• Bu ada sahip bir dosya henüz mevcut olmadığında yeni bir dosya oluşturma.
• Aynı ada sahip bir dosya zaten mevcut olsa bile yeni bir dosya oluşturma, verilerini temizleyerek ve boş olarak başlatma.
• Var olan bir dosyayı yalnızca mevcutsa ve bozulmamış olması koşuluyla açma.
• Var olan bir dosyayı yalnızca varsa açma, boş olacak şekilde kesme.
• Bir dosyayı her zaman açma işlemi: Varsa as-is açılır, yoksa yeni bir dosya oluşturulur.

Bu senaryolar, dwCreationDisposition parametresinin düzgün kullanımıyla denetlenmektedir. Aşağıda, bu senaryoların bu parametrenin değerleriyle nasıl eşlendiğinde ve kullanıldıklarında ne olduğuyla ilgili bir döküm yer almaktadır.

Bu ada sahip bir dosya henüz mevcut olmadığında (dwCreationDispositionCREATE_NEW, CREATE_ALWAYS veya OPEN_ALWAYS) yeni bir dosya oluştururken veya açarken CreateFile işlevi aşağıdaki eylemleri gerçekleştirir:

• dwFlagsAndAttributes tarafından belirtilen dosya özniteliklerini ve bayraklarını FILE_ATTRIBUTE_ARCHIVEile birleştirir.
• Dosya uzunluğunu sıfır olarak ayarlar.
• hTemplateFile parametresi belirtilirse şablon dosyası tarafından sağlanan genişletilmiş öznitelikleri yeni dosyaya kopyalar (bu, daha önce belirtilen tüm FILE_ATTRIBUTE_* bayraklarını geçersiz kılar).
• Sağlanmışsa, bInheritHandle üyesi tarafından belirtilen devralma bayrağını ve lpSecurityAttributes parametresinin (SECURITY_ATTRIBUTES yapısı) lpSecurityDescriptor üyesi tarafından belirtilen güvenlik tanımlayıcısını ayarlar.

Aynı ada sahip bir dosya zaten mevcut olsa bile (dwCreationDispositionCREATE_ALWAYS olarak ayarlanmış) yeni bir dosya oluştururken CreateFile işlevi aşağıdaki eylemleri gerçekleştirir:

• Yazma erişimi için geçerli dosya özniteliklerini ve güvenlik ayarlarını denetler, reddedilirse başarısız olur.
• dwFlagsAndAttributes tarafından belirtilen dosya özniteliklerini ve bayraklarını FILE_ATTRIBUTE_ARCHIVE ve var olan dosya öznitelikleriyle birleştirir.
• Dosya uzunluğunu sıfır olarak ayarlar (başka bir ifadeyle, dosyadaki veriler artık kullanılamaz ve dosya boş olur).
• hTemplateFile parametresi belirtilirse şablon dosyası tarafından sağlanan genişletilmiş öznitelikleri yeni dosyaya kopyalar (bu, daha önce belirtilen tüm FILE_ATTRIBUTE_* bayraklarını geçersiz kılar).
• Sağlanırsa lpSecurityAttributes parametresinin (SECURITY_ATTRIBUTES yapısı) bInheritHandle üyesi tarafından belirtilen devralma bayrağını ayarlar, ancak SECURITY_ATTRIBUTES yapısının lpSecurityDescriptor üyesini yoksayar.
• Aksi takdirde başarılı olursa (yani CreateFile geçerli bir tanıtıcı döndürürse), GetLastError çağrısı kodu ERROR_ALREADY_EXISTS verir; bu, mevcut dosya yerine "yeni" (boş) bir dosya oluşturmayı amaçladıysanız, bu kullanım örneğinde aslında gerçek bir hata değildir.

Mevcut bir dosyayı açarken (dwCreationDispositionOPEN_EXISTING, OPEN_ALWAYS veya TRUNCATE_EXISTING) CreateFile işlevi aşağıdaki eylemleri gerçekleştirir:

• İstenen erişim için geçerli dosya özniteliklerini ve güvenlik ayarlarını denetler, reddedilirse başarısız olur.
• dwFlagsAndAttributes tarafından belirtilen dosya bayraklarını (FILE_FLAG_*) var olan dosya öznitelikleriyle birleştirir ve dwFlagsAndAttributestarafından belirtilen tüm dosya özniteliklerini (FILE_ATTRIBUTE_*) yoksayar.
• Dosya uzunluğunu yalnızca dwCreationDispositionTRUNCATE_EXISTINGolarak ayarlanırsa sıfır olarak ayarlar; aksi takdirde geçerli dosya uzunluğu korunur ve dosya as-isaçılır.
• hTemplateFile parametresini yoksayar.
• Sağlanırsa lpSecurityAttributes parametresinin (SECURITY_ATTRIBUTES yapısı) bInheritHandle üyesi tarafından belirtilen devralma bayrağını ayarlar, ancak SECURITY_ATTRIBUTES yapısının lpSecurityDescriptor üyesini yoksayar.

Dosya Öznitelikleri ve Dizinleri

Dosya öznitelikleri, bir dosya veya dizinle ilişkilendirilmiş meta verilerin bir parçasıdır ve bunların her biri kendi amacına ve nasıl ayarlanıp değiştirilebileceğine ilişkin kurallara sahiptir. Bu özniteliklerden bazıları yalnızca dosyalara, bazıları ise yalnızca dizinlere uygulanır. Örneğin, FILE_ATTRIBUTE_DIRECTORY özniteliği yalnızca dizinler için geçerlidir: Disk üzerindeki bir nesnenin dizin olup olmadığını belirlemek için dosya sistemi tarafından kullanılır, ancak var olan bir dosya sistemi nesnesi için değiştirilemez.

Bazı dosya öznitelikleri bir dizin için ayarlanabilir, ancak yalnızca bu dizinde oluşturulan ve varsayılan öznitelikler olarak davranan dosyalar için anlamlıdır. Örneğin, FILE_ATTRIBUTE_COMPRESSED bir dizin nesnesi üzerinde ayarlanabilir, ancak dizin nesnesinin kendisi gerçek veri içermediğinden, gerçekten sıkıştırılmaz; ancak, bu öznitelikle işaretlenmiş dizinler dosya sistemine bu dizine eklenen tüm yeni dosyaları sıkıştırmasını söyler. Bir dizinde ayarlanabilen ve bu dizine eklenen yeni dosyalar için de ayarlanacak tüm dosya öznitelikleri,devralınan özniteliği olarak adlandırılır.

CreateFile işlevi, bir dosya oluşturulduğunda belirli dosya özniteliklerini ayarlamak için bir parametre sağlar. Genel olarak, bu öznitelikler bir uygulamanın dosya oluşturma zamanında kullanması en yaygın olan özniteliklerdir, ancak CreateFileiçin tüm olası dosya öznitelikleri kullanılamaz. Bazı dosya öznitelikleri, dosya zaten var olduktan sonra SetFileAttributes, DeviceIoControl veya DecryptFile gibi diğer işlevlerin kullanılmasını gerektirir. FILE_ATTRIBUTE_DIRECTORY durumunda CreateDirectory işlevi oluşturma zamanında gereklidir çünkü CreateFile dizin oluşturamaz. FILE_ATTRIBUTE_REPARSE_POINT ve FILE_ATTRIBUTE_SPARSE_FILE, özel işleme gerektiren ve DeviceIoControlgerektiren dosya öznitelikleridir. Daha fazla bilgi için bkz . SetFileAttributes.

Daha önce belirtildiği gibi, dosya özniteliği devralma, dosyanın bulunacağı dizin özniteliklerinden okunan dosya öznitelikleriyle bir dosya oluşturulduğunda gerçekleşir. Aşağıdaki tabloda bu devralınan öznitelikler ve Bunların CreateFile özellikleriyle ilişkisi özetlenmiştir.

Dizin öznitelik durumu	Yeni dosyalar için CreateFile devralma geçersiz kılma özelliği
FILE_ATTRIBUTE_COMPRESSED ayarlanmıştır.	Kontrol yok. Temizlemek için DeviceIoControl kullanın.
FILE_ATTRIBUTE_COMPRESSED ayarlanmadı.	Kontrol yok. Ayarlamak için DeviceIoControl kullanın.
FILE_ATTRIBUTE_ENCRYPTED ayarlayın.	Kontrol yok. DecryptFile kullanın.
FILE_ATTRIBUTE_ENCRYPTED ayarlanmadı.	CreateFile kullanılarak ayarlanabilir.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED olarak ayarlayın.	Kontrol yok. Temizlemek için SetFileAttributes kullanın.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED ayarlanmadı.	Kontrol yok. Ayarlamak için SetFileAttributes kullanın.

İlgili içerik

Erişim Denetimi

CreateFile

DeviceIoControl (CihazIoKontrolü)

Dosya Öznitelik Sabitleri

Dosya Sıkıştırma ve Çözme

Dosya Şifrelemesi

Dosya Yönetimi İşlevleri

Tutamaklar ve Nesneler

Devralma İşleme

Bir Dosyayı Okuma veya Yazma için Açma

SetFileAttributes