QFileDevice Class
QFileDevice 클래스는 열린 파일에서 읽고 쓰기 위한 인터페이스를 제공합니다. 더 보기...
Header: | #include <QFileDevice> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
상속합니다: | QIODevice |
상속 대상 |
- 상속된 멤버를 포함한 모든 멤버 목록
- QFileDevice는 입력/출력 및 네트워킹의 일부입니다.
참고: 이 클래스의 모든 함수는 재상속됩니다.
공용 유형
enum | FileError { NoError, ReadError, WriteError, FatalError, ResourceError, …, CopyError } |
enum | FileHandleFlag { AutoCloseHandle, DontCloseHandle } |
flags | FileHandleFlags |
enum | FileTime { FileAccessTime, FileBirthTime, FileMetadataChangeTime, FileModificationTime } |
enum | MemoryMapFlag { NoOptions, MapPrivateOption } |
flags | MemoryMapFlags |
enum | Permission { ReadOwner, WriteOwner, ExeOwner, ReadUser, WriteUser, …, ExeOther } |
flags | Permissions |
공용 함수
virtual | ~QFileDevice() |
QFileDevice::FileError | error() const |
virtual QString | fileName() const |
QDateTime | fileTime(QFileDevice::FileTime time) const |
bool | flush() |
int | handle() const |
uchar * | map(qint64 offset, qint64 size, QFileDevice::MemoryMapFlags flags = NoOptions) |
virtual QFileDevice::Permissions | permissions() const |
virtual bool | resize(qint64 sz) |
bool | setFileTime(const QDateTime &newDate, QFileDevice::FileTime fileTime) |
virtual bool | setPermissions(QFileDevice::Permissions permissions) |
bool | unmap(uchar *address) |
void | unsetError() |
재구현된 공용 함수
virtual bool | atEnd() const override |
virtual void | close() override |
virtual bool | isSequential() const override |
virtual qint64 | pos() const override |
virtual bool | seek(qint64 pos) override |
virtual qint64 | size() const override |
재구현된 보호 함수
virtual qint64 | readData(char *data, qint64 len) override |
virtual qint64 | readLineData(char *data, qint64 maxlen) override |
virtual qint64 | writeData(const char *data, qint64 len) override |
매크로
(since 6.8) | QT_NO_USE_NODISCARD_FILE_OPEN |
(since 6.8) | QT_USE_NODISCARD_FILE_OPEN |
상세 설명
QFileDevice는 텍스트 및 바이너리 파일과 리소스를 읽고 쓸 수 있는 입출력 장치의 베이스 클래스입니다. QFile 는 주요 기능을 제공하며, QFileDevice는 QFile 또는 QSaveFile 에서 연 파일에서 수행할 수 있는 모든 작업을 제공하여 QSaveFile 과 같은 다른 파일 장치와 기능을 공유하기 위한 베이스 클래스 역할을 합니다.
멤버 유형 문서
enum QFileDevice::FileError
이 열거형은 error() 함수에서 반환할 수 있는 오류를 설명합니다.
Constant | 값 | 설명 |
---|---|---|
QFileDevice::NoError | 0 | 오류가 발생하지 않았습니다. |
QFileDevice::ReadError | 1 | 파일에서 읽을 때 오류가 발생했습니다. |
QFileDevice::WriteError | 2 | 파일에 쓰는 동안 오류가 발생했습니다. |
QFileDevice::FatalError | 3 | 치명적인 오류가 발생했습니다. |
QFileDevice::ResourceError | 4 | 리소스 부족(예: 열려 있는 파일이 너무 많거나 메모리 부족 등) |
QFileDevice::OpenError | 5 | 파일을 열 수 없습니다. |
QFileDevice::AbortError | 6 | 작업이 중단되었습니다. |
QFileDevice::TimeOutError | 7 | 시간 초과가 발생했습니다. |
QFileDevice::UnspecifiedError | 8 | 지정되지 않은 오류가 발생했습니다. |
QFileDevice::RemoveError | 9 | 파일을 제거할 수 없습니다. |
QFileDevice::RenameError | 10 | 파일 이름을 바꿀 수 없습니다. |
QFileDevice::PositionError | 11 | 파일 내 위치를 변경할 수 없습니다. |
QFileDevice::ResizeError | 12 | 파일 크기를 조정할 수 없습니다. |
QFileDevice::PermissionsError | 13 | 파일에 액세스할 수 없습니다. |
QFileDevice::CopyError | 14 | 파일을 복사할 수 없습니다. |
열거형 QFileDevice::FileHandleFlag
플래그 QFileDevice::FileHandleFlags
이 열거형은 파일을 열 때 일반 QIODevice 에는 적용되지 않고 파일에만 적용되는 추가 옵션을 지정하는 데 사용됩니다.
상수 | 값 | 설명 |
---|---|---|
QFileDevice::AutoCloseHandle | 0x0001 | open()에 전달된 파일 핸들은 close()에 의해 닫혀야 하며, 기본 동작은 닫기만 하면 파일을 플러시하고 애플리케이션이 파일 핸들을 닫는 것입니다. 이름으로 파일을 열 때, 이 플래그는 무시됩니다. Qt는 항상 파일 핸들을 소유하고 있으므로 반드시 닫아야 합니다. |
QFileDevice::DontCloseHandle | 0 | 명시적으로 닫지 않으면 QFile 객체가 소멸될 때 기본 파일 핸들은 열린 상태로 유지됩니다. |
FileHandleFlags 유형은 QFlags<FileHandleFlag>에 대한 typedef입니다. 이 유형은 FileHandleFlag 값의 OR 조합을 저장합니다.
enum QFileDevice::FileTime
이 열거형은 fileTime() 및 setFileTime() 함수에서 사용됩니다.
상수 | 값 | 설명 |
---|---|---|
QFileDevice::FileAccessTime | 0 | 가장 최근에 파일에 액세스한 시간(예: 읽기 또는 쓰기)입니다. |
QFileDevice::FileBirthTime | 1 | 파일이 생성된 시기(UNIX에서는 지원되지 않을 수 있음). |
QFileDevice::FileMetadataChangeTime | 2 | 파일의 메타데이터가 마지막으로 변경된 시기. |
QFileDevice::FileModificationTime | 3 | 파일이 가장 최근에 수정된 시기. |
setFileTime(), fileTime() 및 QFileInfo::fileTime()도 참조하세요 .
열거형 QFileDevice::MemoryMapFlag
플래그 QFileDevice::MemoryMapFlags
이 열거형은 map() 함수에서 사용할 수 있는 특수 옵션을 설명합니다.
상수 | 값 | 설명 |
---|---|---|
QFileDevice::NoOptions | 0 | 옵션이 없습니다. |
QFileDevice::MapPrivateOption | 0x0001 | 매핑된 메모리는 비공개 메모리가 되므로 다른 프로세스에 수정 내용이 표시되지 않으며 디스크에 기록되지 않습니다. 메모리가 매핑 해제되면 이러한 수정 사항은 모두 손실됩니다. 매핑이 생성된 후 파일에 대한 수정 사항이 매핑된 메모리를 통해 표시되는지 여부는 지정되지 않았습니다. 이 열거형 값은 Qt 5.4에 도입되었습니다. |
MemoryMapFlags 형은 QFlags<MemoryMapFlag>에 대한 typedef입니다. MemoryMapFlag 값의 OR 조합을 저장합니다.
열거형 QFileDevice::Permission
플래그 QFileDevice::Permissions
이 열거형은 permission() 함수에서 파일의 권한과 소유권을 보고하는 데 사용됩니다. 이 값은 여러 권한 및 소유권 값을 테스트하기 위해 OR로 결합될 수 있습니다.
상수 | 값 | 설명 |
---|---|---|
QFileDevice::ReadOwner | 0x4000 | 파일 소유자가 파일을 읽을 수 있습니다. |
QFileDevice::WriteOwner | 0x2000 | 파일 소유자가 파일을 쓸 수 있습니다. |
QFileDevice::ExeOwner | 0x1000 | 파일 소유자가 파일을 실행할 수 있습니다. |
QFileDevice::ReadUser | 0x0400 | 사용자가 파일을 읽을 수 있습니다. |
QFileDevice::WriteUser | 0x0200 | 사용자가 파일을 쓸 수 있습니다. |
QFileDevice::ExeUser | 0x0100 | 사용자가 파일을 실행할 수 있습니다. |
QFileDevice::ReadGroup | 0x0040 | 그룹이 파일을 읽을 수 있습니다. |
QFileDevice::WriteGroup | 0x0020 | 그룹이 파일을 쓸 수 있습니다. |
QFileDevice::ExeGroup | 0x0010 | 그룹이 파일을 실행할 수 있습니다. |
QFileDevice::ReadOther | 0x0004 | 다른 사용자가 파일을 읽을 수 있습니다. |
QFileDevice::WriteOther | 0x0002 | 다른 사람이 파일을 쓸 수 있습니다. |
QFileDevice::ExeOther | 0x0001 | 다른 사람이 파일을 실행할 수 있습니다. |
경고: Qt가 지원하는 플랫폼의 차이로 인해 ReadUser, WriteUser 및 ExeUser의 의미는 플랫폼에 따라 다릅니다: 유닉스에서는 파일 소유자의 권한이 반환되고 윈도우에서는 현재 사용자의 권한이 반환됩니다. 이 동작은 향후 Qt 버전에서 변경될 수 있습니다.
참고: NTFS 파일 시스템에서는 성능상의 이유로 소유권 및 권한 확인이 기본적으로 비활성화되어 있습니다. 활성화하려면 다음 줄을 추가하세요:
extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;
그런 다음 qt_ntfs_permission_lookup
을 1씩 늘리거나 줄여서 권한 확인을 켜고 끕니다.
qt_ntfs_permission_lookup++; // turn checking on qt_ntfs_permission_lookup--; // turn it off again
참고: 이 변수는 원자가 아닌 전역 변수이므로 메인 스레드 이외의 스레드가 시작되기 전이나 메인 스레드 이외의 모든 스레드가 종료된 후에만 qt_ntfs_permission_lookup
을 증가시키거나 감소시키는 것이 안전합니다.
참고: Qt 6.6부터 qt_ntfs_permission_lookup
변수는 더 이상 사용되지 않습니다. 다음 대안을 사용하세요.
안전하고 쉽게 권한 검사를 관리하는 방법은 RAII 클래스 QNtfsPermissionCheckGuard
를 사용하는 것입니다.
void complexFunction() { QNtfsPermissionCheckGuard permissionGuard; // check is enabled // do complex things here that need permission check enabled } // as the guard goes out of scope the check is disabled
보다 세분화된 제어가 필요한 경우 다음 함수를 사용하여 권한을 대신 관리할 수 있습니다:
qAreNtfsPermissionChecksEnabled(); // 상태 확인qEnableNtfsPermissionChecks(); // turn checking on qDisableNtfsPermissionChecks(); // turn it off again
Permissions 유형은 QFlags<Permission>에 대한 타입 정의입니다. Permission 값의 OR 조합을 저장합니다.
멤버 함수 문서
[virtual noexcept]
QFileDevice::~QFileDevice()
파일 장치를 삭제하고 필요한 경우 닫습니다.
[override virtual]
bool QFileDevice::atEnd() const
재구현합니다: QIODevice::atEnd() const.
파일의 끝에 도달하면 true
를 반환하고, 그렇지 않으면 false를 반환합니다.
Unix의 일반 빈 파일(예: /proc
)의 경우 이 함수는 파일 시스템이 해당 파일의 크기가 0이라고 보고하므로 true
을 반환합니다. 따라서 이러한 파일에서 데이터를 읽을 때는 atEnd()에 의존하지 말고 더 이상 데이터를 읽을 수 없을 때까지 read()를 호출해야 합니다.
[override virtual]
void QFileDevice::close()
다시 구현합니다: QIODevice::close().
QFileDevice::flush()를 호출하고 파일을 닫습니다. 플러시로 인한 에러는 무시됩니다.
QIODevice::close()도 참조하세요 .
QFileDevice::FileError QFileDevice::error() const
파일 오류 상태를 반환합니다.
I/O 장치 상태는 오류 코드를 반환합니다. 예를 들어 open()가 false
을 반환하거나 읽기/쓰기 작업에서 -1을 반환하는 경우 이 함수를 호출하여 작업 실패의 원인을 찾을 수 있습니다.
unsetError()도 참조하세요 .
[virtual]
QString QFileDevice::fileName() const
파일 이름을 반환합니다. QFileDevice 의 기본 구현은 널 문자열을 반환합니다.
QDateTime QFileDevice::fileTime(QFileDevice::FileTime time) const
time 에 지정된 파일 시간을 반환합니다. 시간을 확인할 수 없으면 QDateTime()(잘못된 날짜 시간)을 반환합니다.
setFileTime(), FileTime, 및 QDateTime::isValid()도 참조하세요 .
bool QFileDevice::flush()
버퍼링된 모든 데이터를 파일로 푸시합니다. 성공하면 true
을 반환하고, 그렇지 않으면 false
을 반환합니다.
int QFileDevice::handle() const
파일의 파일 핸들을 반환합니다.
작은 양의 정수로, fdopen()
및 fcntl()
과 같은 C 라이브러리 함수와 함께 사용하기에 적합합니다. 소켓에 파일 기술자를 사용하는 시스템(예: 윈도우가 아닌 유닉스 시스템)에서는 QSocketNotifier 와 함께 핸들을 사용할 수도 있습니다.
파일이 열려 있지 않거나 오류가 있는 경우 handle()는 -1을 반환합니다.
QSocketNotifier 를참조하세요 .
[override virtual]
bool QFileDevice::isSequential() const
재구현합니다: QIODevice::isSequential() const.
파일을 순차적으로만 조작할 수 있으면 true
를 반환하고, 그렇지 않으면 false
를 반환합니다.
대부분의 파일은 랜덤 액세스를 지원하지만 일부 특수 파일은 지원하지 않을 수 있습니다.
QIODevice::isSequential()도 참조하세요 .
uchar *QFileDevice::map(qint64 offset, qint64 size, QFileDevice::MemoryMapFlags flags = NoOptions)
size 바이트의 파일을 offset 에서 시작하는 메모리에 매핑합니다. 매핑이 성공하려면 파일이 열려 있어야 하지만 메모리가 매핑된 후에는 파일이 열려 있을 필요는 없습니다. QFile 가 삭제되거나 이 개체로 새 파일을 열면 매핑이 해제되지 않은 모든 맵은 자동으로 매핑이 해제됩니다.
매핑은 파일과 동일한 열기 모드(읽기 및/또는 쓰기)를 갖지만 MapPrivateOption 을 사용하는 경우를 제외하고는 매핑된 메모리에 항상 쓸 수 있습니다.
모든 매핑 옵션은 flags 을 통해 전달할 수 있습니다.
메모리에 대한 포인터를 반환하거나 오류가 있는 경우 nullptr
을 반환합니다.
unmap()도 참조하세요 .
[virtual]
QFileDevice::Permissions QFileDevice::permissions() const
파일에 대한 QFile::Permission의 전체 OR 결합 조합을 반환합니다.
setPermissions()도 참조하세요 .
[override virtual]
qint64 QFileDevice::pos() const
재구현합니다: QIODevice::pos() const.
[override virtual protected]
qint64 QFileDevice::readData(char *data, qint64 len)
다시 구현합니다: QIODevice::readData(문자 *데이터, qint64 maxSize).
[override virtual protected]
qint64 QFileDevice::readLineData(char *data, qint64 maxlen)
다시 구현합니다: QIODevice::readLineData(문자 *데이터, qint64 maxSize).
[virtual]
bool QFileDevice::resize(qint64 sz)
파일 크기(바이트 단위)를 설정합니다 sz. 크기 조정에 성공하면 true
을 반환하고, 그렇지 않으면 false 를 반환합니다. sz 이 현재 파일보다 크면 새 바이트가 0으로 설정되고 sz 이 작으면 파일이 단순히 잘립니다.
경고: 파일이 존재하지 않으면 이 함수가 실패할 수 있습니다.
size()도 참조하세요 .
[override virtual]
bool QFileDevice::seek(qint64 pos)
다시 구현합니다: QIODevice::seek(qint64 pos).
랜덤 액세스 장치의 경우 이 함수는 현재 위치를 pos 로 설정하고 성공하면 참을 반환하고 오류가 발생하면 거짓을 반환합니다. 순차적 장치의 경우 기본 동작은 아무것도 하지 않고 false를 반환하는 것입니다.
파일 끝 너머에서 찾기: 위치가 파일 끝을 넘어서는 경우 seek()는 즉시 파일을 확장하지 않습니다. 이 위치에서 쓰기가 수행되면 파일이 확장됩니다. 이전 파일 끝과 새로 쓰여진 데이터 사이의 파일 내용은 미정의이며 플랫폼과 파일 시스템에 따라 다릅니다.
bool QFileDevice::setFileTime(const QDateTime &newDate, QFileDevice::FileTime fileTime)
fileTime 에 지정된 파일 시간을 newDate 으로 설정하고 성공하면 참을 반환하고 그렇지 않으면 거짓을 반환합니다.
참고: 이 함수를 사용하려면 파일이 열려 있어야 합니다.
fileTime() 및 FileTime도 참조하세요 .
[virtual]
bool QFileDevice::setPermissions(QFileDevice::Permissions permissions)
파일에 대한 권한을 지정된 permissions 로 설정합니다. 성공하면 true
, 권한을 수정할 수 없으면 false
을 반환합니다.
경고: 이 함수는 ACL을 조작하지 않으므로 효과가 제한될 수 있습니다.
permissions()도 참조하세요 .
[override virtual]
qint64 QFileDevice::size() const
재구현합니다: QIODevice::size() const.
파일의 크기를 반환합니다.
Unix의 일반 빈 파일(예: /proc
)의 경우 이 함수는 0을 반환하며, 이러한 파일의 내용은 read()을 호출하면 요청에 따라 생성됩니다.
bool QFileDevice::unmap(uchar *address)
메모리 매핑을 해제합니다 address.
매핑 해제에 성공하면 true
을 반환하고, 그렇지 않으면 false 를 반환합니다.
map()도 참조하세요 .
void QFileDevice::unsetError()
파일의 오류를 QFileDevice::NoError 로 설정합니다.
error()도 참조하세요 .
[override virtual protected]
qint64 QFileDevice::writeData(const char *data, qint64 len)
재구현합니다: QIODevice::writeData(const char *data, qint64 maxSize).
매크로 문서
파일 관련 I/O 클래스(예: QFile, QSaveFile, QTemporaryFile)에는 동작하는 파일을 여는 open()
메서드가 있습니다. 파일에 데이터를 읽거나 쓰기 전에 open()
호출의 반환값을 확인하는 것이 중요합니다.
이러한 이유로 Qt 6.8부터는 open()
의 일부 오버로드에 [[nodiscard]]
어트리뷰트가 표시되었습니다. 이 변경으로 인해 기존 코드베이스에서 경고가 발생할 수 있으므로 사용자 코드에서 특정 매크로를 정의하여 해당 속성을 적용하지 않도록 옵트인 또는 옵트아웃할 수 있습니다:
QT_USE_NODISCARD_FILE_OPEN
매크로가 정의된 경우open()
의 과부하가[[nodiscard]]
로 표시됩니다.QT_NO_USE_NODISCARD_FILE_OPEN
매크로가 정의된 경우open()
의 오버로드는[[nodiscard]]
로 표시되지 않습니다.- 두 매크로가 모두 정의되지 않은 경우, Qt 6.9까지의 기본값은 어트리뷰트를 갖지 않는 것입니다. Qt 6.10부터는 이 속성이 자동으로 적용됩니다.
- 두 매크로가 모두 정의되어 있으면 프로그램이 잘못 형성된 것입니다.
이 기능은 Qt 6.8에서 도입되었습니다.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.