Documentation ¶
Index ¶
- Constants
- Variables
- func CreateJournal(handle syscall.Handle, maxSize, allocDelta uint64) (err error)
- func DeleteJournal(handle syscall.Handle) (err error)
- func EnumData(handle syscall.Handle, opts RawEnumOptions, buffer []byte) (length uint32, err error)
- func MarkHandle(handle syscall.Handle) (err error)
- func ReadJournal(handle syscall.Handle, opts RawReadOptions, buffer []byte) (length uint32, err error)
- type Cache
- type Cursor
- func (c *Cursor) Close()
- func (c *Cursor) End(buffer []byte)
- func (c *Cursor) Next(buffer []byte) (records []Record, err error)
- func (c *Cursor) Read(p []byte) (n int, err error)
- func (c *Cursor) Seek(offset int64, whence int) (usn int64, err error)
- func (c *Cursor) Stats() (total, filtered Stats)
- func (c *Cursor) USN() USN
- type Enumerator
- type Filer
- type Filter
- type Iter
- type Journal
- func (j *Journal) Cache(filter Filter, low, high USN) (*Cache, error)
- func (j *Journal) Close()
- func (j *Journal) Create(maxSize, allocDelta uint64) error
- func (j *Journal) Cursor(processor Processor, reasonMask Reason, filter Filter, filer Filer) (*Cursor, error)
- func (j *Journal) MFT() *MFT
- func (j *Journal) Monitor() *Monitor
- func (j *Journal) Query() (data RawJournalData, err error)
- type MFT
- type Monitor
- type Processor
- type RawEnumOptions
- type RawJournalData
- type RawReadOptions
- type RawRecordHeader
- type RawRecordV1
- type RawRecordV2
- type RawRecordV3
- type RawRecordV4
- type Reason
- type ReasonFormat
- type Record
- type RecordExtent
- type Stats
- type USN
Constants ¶
const ( // MinimumPollingInterval is the minimum amount of time that a monitor will // wait between change journal read requests. MinimumPollingInterval = time.Millisecond // DefaultPollingInterval is the suggested amount of time that a monitor // should wait between change journal read requests. DefaultPollingInterval = time.Second )
const ( // Min is the smallest valid update sequence number. Min = USN(0) // Max is the largest valid update sequence number. Max = USN(^uint64(0) >> 1) )
const ( // MaxRecordSize is the maximum record size that will be parsed. It is // an arbitrary number that should be sufficiently large to accept any valid // change journal record. MaxRecordSize = 12288 )
Variables ¶
var ( // ErrNegativeUSN is returned when seeking to a negative update sequence // number. ErrNegativeUSN = errors.New("the requested operation would result in a negative update sequence number") // ErrInvalidWhence is returned when an invalid or unsupported whence value is // supplied to a Seek function. ErrInvalidWhence = errors.New("invalid whence value") // ErrInsufficientBuffer is returned when a record cannot be read because the // buffer is too small to receive its data. ErrInsufficientBuffer = errors.New("unable to read record data due to insufficient buffer size") )
var ( // ErrClosed is returned when a monitor is already closed. ErrClosed = errors.New("monitor already closed") // ErrRunning is returned when an attempt is made to start an already // running monitor. ErrRunning = errors.New("the monitor has already been started") // ErrStopped is returned when an attempt is made to stop a monitor that isn't // running. ErrStopped = errors.New("the monitor has already been stopped") )
var ( // ErrTruncatedRecord is returned when the data buffer containing a // record appears to have been truncated. ErrTruncatedRecord = errors.New("USN record data was truncated") // ErrRecordLengthZero is returned when a record specifies a length of // zero. ErrRecordLengthZero = errors.New("USN record length is zero (possible data corruption)") // ErrRecordLengthTooSmall is returned when a record specifies a length // that is too small to hold the record data. ErrRecordLengthTooSmall = errors.New("USN record length is too small (possible data corruption)") // ErrRecordLengthExceedsMax is returned when a record specifies a length // that exceeds MaxRecordSize. ErrRecordLengthExceedsMax = errors.New("USN record length exceeds maximum (possible data corruption)") // ErrFileNameExceedsBoundary is returned when a record specifies a file // name data range that exceeds the boundaries of the record. ErrFileNameExceedsBoundary = errors.New("USN record file name data exceeds the record boundary") )
var ErrNotFound = errors.New("not found")
ErrNotFound is returned by cache.Filer when a record cannot be found.
var ReasonFormatBasic = ReasonFormat{ ReasonDataOverwrite: "DataOverwrite", ReasonDataExtend: "DataExtend", ReasonDataTruncation: "DataTruncation", ReasonNamedDataOverwrite: "NamedDataOverwrite", ReasonNamedDataExtend: "NamedDataExtend", ReasonNamedDataTruncation: "NamedDataTruncation", ReasonFileCreate: "FileCreate", ReasonFileDelete: "FileDelete", ReasonEAChange: "EAChange", ReasonSecurityChange: "SecurityChange", ReasonRenameOldName: "RenameOldName", ReasonRenameNewName: "RenameNewName", ReasonRename: "Rename", ReasonIndexableChange: "IndexableChange", ReasonBasicInfoChange: "BasicInfoChange", ReasonHardLinkChange: "HardLinkChange", ReasonCompressionChange: "CompressionChange", ReasonEncryptionChange: "EncryptionChange", ReasonObjectIDChange: "ObjectIDChange", ReasonReparsePointChange: "ReparsePointChange", ReasonStreamChange: "StreamChange", ReasonTransactedChange: "TransactedChange", ReasonIntegrityChange: "IntegrityChange", ReasonClose: "Close", }
ReasonFormatBasic maps basic reason strings to reason codes.
var ReasonFormatConstant = ReasonFormat{ ReasonDataOverwrite: "USN_REASON_DATA_OVERWRITE", ReasonDataExtend: "USN_REASON_DATA_EXTEND", ReasonDataTruncation: "USN_REASON_DATA_TRUNCATION", ReasonNamedDataOverwrite: "USN_REASON_NAMED_DATA_OVERWRITE", ReasonNamedDataExtend: "USN_REASON_NAMED_DATA_EXTEND", ReasonNamedDataTruncation: "USN_REASON_NAMED_DATA_TRUNCATION", ReasonFileCreate: "USN_REASON_FILE_CREATE", ReasonFileDelete: "USN_REASON_FILE_DELETE", ReasonEAChange: "USN_REASON_EA_CHANGE", ReasonSecurityChange: "USN_REASON_SECURITY_CHANGE", ReasonRenameOldName: "USN_REASON_RENAME_OLD_NAME", ReasonRenameNewName: "USN_REASON_RENAME_NEW_NAME", ReasonIndexableChange: "USN_REASON_INDEXABLE_CHANGE", ReasonBasicInfoChange: "USN_REASON_BASIC_INFO_CHANGE", ReasonHardLinkChange: "USN_REASON_HARD_LINK_CHANGE", ReasonCompressionChange: "USN_REASON_COMPRESSION_CHANGE", ReasonEncryptionChange: "USN_REASON_ENCRYPTION_CHANGE", ReasonObjectIDChange: "USN_REASON_OBJECT_ID_CHANGE", ReasonReparsePointChange: "USN_REASON_REPARSE_POINT_CHANGE", ReasonStreamChange: "USN_REASON_STREAM_CHANGE", ReasonTransactedChange: "USN_REASON_TRANSACTED_CHANGE", ReasonIntegrityChange: "USN_REASON_INTEGRITY_CHANGE", ReasonClose: "USN_REASON_CLOSE", }
ReasonFormatConstant maps the official C-style constant strings to reason codes.
var ReasonFormatShort = ReasonFormat{ ReasonDataOverwrite: "Overwrite", ReasonDataExtend: "Extend", ReasonDataTruncation: "Truncation", ReasonNamedDataOverwrite: "NamedDataOverwrite", ReasonNamedDataExtend: "NamedDataExtend", ReasonNamedDataTruncation: "NamedDataTruncation", ReasonFileCreate: "Create", ReasonFileDelete: "Delete", ReasonEAChange: "EAChange", ReasonSecurityChange: "SecurityChange", ReasonRenameOldName: "RenameOldName", ReasonRenameNewName: "RenameNewName", ReasonRename: "Rename", ReasonIndexableChange: "IndexableChange", ReasonBasicInfoChange: "BasicInfoChange", ReasonHardLinkChange: "HardLinkChange", ReasonCompressionChange: "CompressionChange", ReasonEncryptionChange: "EncryptionChange", ReasonObjectIDChange: "ObjectIDChange", ReasonReparsePointChange: "ReparsePointChange", ReasonStreamChange: "StreamChange", ReasonTransactedChange: "TransactedChange", ReasonIntegrityChange: "IntegrityChange", ReasonClose: "Close", }
ReasonFormatShort maps short reason strings to reason codes.
Functions ¶
func CreateJournal ¶
CreateJournal will create a change journal on the file system volume represented by the provided handle and the parameters maximum journal size and allocation delta. If the parameters are zero, the journal will be created with defaults
func DeleteJournal ¶
DeleteJournal will delete a change journal on the file system volume represented by the provided handle.
func EnumData ¶
EnumData will enumerate change journal data on the file system volume represented by the provided handle.
func MarkHandle ¶
MarkHandle will add file change information about a specified file and to the files metadata and to the USN change journal of the file system volume on which the file resides.
func ReadJournal ¶
func ReadJournal(handle syscall.Handle, opts RawReadOptions, buffer []byte) (length uint32, err error)
ReadJournal retrieves change journal data from the USN journal.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is a usn change journal cache.
func (*Cache) ReadFrom ¶
ReadFrom reads records from iter and inserts them into mft. It returns when the iterator returns an error or io.EOF.
TODO: Add context?
func (*Cache) Records ¶
Records returns a slice of all records in the cache. The order of the returned records is unspecified.
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
Cursor provides a more idiomatic means of reading USN change journal data through an io.ReadSeeker interface.
TODO: Attempt to merge Enumerator and Cursor into one type.
func NewCursor ¶
func NewCursor(path string, reasonMask Reason, processor Processor, filter Filter, filer Filer) (cursor *Cursor, err error)
NewCursor returns a USN change journal cursor for the volume described by path. Only records matching the provided reason mask will be returned.
If filer is non-nil, it will be used to return records with a populated path field.
TODO: Make processors, filters and filers fulfill a CursorOption interface, then accept a variadic set of options.
func NewCursorWithHandle ¶
func NewCursorWithHandle(handle *hsync.Handle, processor Processor, reasonMask Reason, filter Filter, filer Filer) (*Cursor, error)
NewCursorWithHandle returns a USN Journal cursor for the volume with the given handle.
When the cursor is closed its associated handle will also be closed. When providing an existing handle that will be used elsewhere be sure to clone it first.
func (*Cursor) Close ¶
func (c *Cursor) Close()
Close releases any resources consumed by the journal.
func (*Cursor) End ¶
End causes the cursor to read forward until there are no more records left to be read. The cursor's statistics will be updated to reflect the ro
func (*Cursor) Next ¶
Next returns a slice of records from the journal. It returns all unread records that are available that can fit within the given buffer.
If there are no more unread records err will be io.EOF.
func (*Cursor) Read ¶
Read fills the given buffer with data from the underlying USN journal if any is present. The first 8 bytes of the returned data contain a 64 bit USN value.
Read does not apply the cursor's filter. To retrieve filtered records call Next instead.
If no more data is currently available, io.EOF will be returned.
type Enumerator ¶
type Enumerator struct {
// contains filtered or unexported fields
}
Enumerator reads records from a master file table.
TODO: Attempt to merge Enumerator and Cursor into one type.
func NewEnumerator ¶
func NewEnumerator(path string, filter Filter, low, high USN) (enumerator *Enumerator, err error)
NewEnumerator returns a master file table enumerator for the volume described by path.
func NewEnumeratorWithHandle ¶
func NewEnumeratorWithHandle(handle *hsync.Handle, filter Filter, low, high USN) (*Enumerator, error)
NewEnumeratorWithHandle returns a master file table enumerator for the volume with the given handle.
When the enumerator is closed its associated handle will also be closed. When providing an existing handle that will be used elsewhere be sure to clone it first.
func (*Enumerator) Close ¶
func (e *Enumerator) Close()
Close releases any resources consumed by the enumerator.
func (*Enumerator) Next ¶
func (e *Enumerator) Next(buffer []byte) (records []Record, err error)
Next returns a slice of records from the master file table. It returns all unread records that are available that can fit within the given buffer.
If there are no more unread records err will be io.EOF.
func (*Enumerator) Read ¶
func (e *Enumerator) Read(p []byte) (n int, err error)
Read fills the given buffer with data from the master file table. The first 8 bytes of the returned data contain a 64 bit file reference number or update sequence number.
If no more data is available, io.EOF will be returned.
type Filter ¶
Filter is capable of filtering USN change journal records. It returns true when a record should be included in a set and false when it should not.
type Journal ¶
type Journal struct {
// contains filtered or unexported fields
}
Journal provides access to USN journal information and records.
func NewJournal ¶
NewJournal returns a USN Journal accessor for the volume with the given path.
func NewJournalWithHandle ¶
NewJournalWithHandle returns a USN Journal accessor for the volume with the given handle.
When the journal is closed its associated handle will also be closed. When providing an existing handle that will be used elsewhere be sure to clone it first.
NewJournal does not force the creation of a change journal when one does not already exist on the volume. To bring a new journal into existence call Journal.Create().
func (*Journal) Cache ¶
Cache builds up a cache of MFT records matching the given filter with USN values between low and high, inclusive.
func (*Journal) Close ¶
func (j *Journal) Close()
Close releases any resources consumed by the journal.
func (*Journal) Create ¶
Create creates a new USN journal using the parameters for max size and allocation delta. Pass zero parameters to create a journal with defaults.
func (*Journal) Cursor ¶
func (j *Journal) Cursor(processor Processor, reasonMask Reason, filter Filter, filer Filer) (*Cursor, error)
Cursor returns a new cursor for the journal.
If filer is non-nil, it will be used to return records with a populated path field.
func (*Journal) Query ¶
func (j *Journal) Query() (data RawJournalData, err error)
Query returns information about the current condition of the change journal.
type MFT ¶
type MFT struct {
// contains filtered or unexported fields
}
MFT provides access to the master file table.
func NewMFTWithHandle ¶
NewMFTWithHandle returns a master file table accessor for the volume with the given handle.
When the journal is closed its associated handle will also be closed. When providing an existing handle that will be used elsewhere be sure to clone it first.
func (*MFT) Enumerate ¶
func (mft *MFT) Enumerate(filter Filter, low, high USN) (*Enumerator, error)
Enumerate returns a new enumerator for the master file table. It will return records with update sequence numbers between low and high, inclusive.
To enumerate all records within the MFT, provide Min and Max as values.
type Monitor ¶
type Monitor struct {
// contains filtered or unexported fields
}
Monitor facilitates monitoring of USN journals.
func NewMonitor ¶
NewMonitor returns a USN change journal monitor for the volume described by path.
func NewMonitorWithHandle ¶
NewMonitorWithHandle returns a USN journal monitor for the volume with the given handle. The returned monitor will be inactive until it has been started by a call to Run().
When the monitor is closed its associated handle will also be closed. When providing an existing handle that will be used elsewhere be sure to clone it first.
It is the caller's responsibility to close the monitor when finished with it.
func (*Monitor) Close ¶
Close releases any resources consumed by the monitor. All active listeners will be closed and the monitor will stop observing the journal.
Once a monitor has been closed it cannot be used.
func (*Monitor) Listen ¶
Listen returns a channel on which USN journal updates will be broadcast. The channel will be closed when the monitor is closed or when unlisten is called for the returned channel.
func (*Monitor) Run ¶
func (m *Monitor) Run(start USN, interval time.Duration, reasonMask Reason, processor Processor, filter Filter, filer Filer) <-chan error
Run will cause the monitor to start observing its USN journal. Reads will start from the given update sequence number and will continue until the monitor is stopped or closed.
Records retrieved from the journal will be broadcast to all registered listeners.
The monitor will start reading records from the update sequence number specified by start. If start is zero the monitor will read from the beginning of the journal.
When the monitor stops, the returned channel is closed. If the monitor has already been started, or stops due to an error, the error will be sent to the channel.
type Processor ¶
type Processor func(Record)
A Processor is capable of processing USN change journal records.
type RawEnumOptions ¶
type RawEnumOptions struct { // Version 0 Fields StartFileReferenceNumber int64 // Can be a file reference number or USN Low USN High USN // Version 1 Fields MinMajorVersion uint16 MaxMajorVersion uint16 }
RawEnumOptions are used to specify parameters when enumerating the master file table.
type RawJournalData ¶
type RawJournalData struct { // Version 0 Fields JournalID uint64 FirstUSN USN NextUSN USN LowestValidUSN USN MaxUSN USN MaximumSize uint64 AllocationDelta uint64 // Version 1 Fields MinSupportedMajorVersion uint16 MaxSupportedMajorVersion uint16 // Version 2 Fields Flags uint32 RangeTrackChunkSize uint64 RangeTrackFileSizeThreshold int64 }
RawJournalData contains the raw output of USN journal information.
func QueryJournal ¶
func QueryJournal(handle syscall.Handle) (data RawJournalData, err error)
QueryJournal retrieves information about the change journal affiliated with the given volume handle.
type RawReadOptions ¶
type RawReadOptions struct { // Version 0 Fields StartUSN USN ReasonMask Reason ReturnOnlyOnClose uint32 Timeout int64 BytesToWaitFor uint64 JournalID uint64 // Version 1 Fields MinMajorVersion uint16 MaxMajorVersion uint16 }
RawReadOptions are used to specify parameters when reading from the USN journal.
type RawRecordHeader ¶
RawRecordHeader represents the raw form of the common USN journal record header.
type RawRecordV1 ¶
type RawRecordV1 struct { RawRecordHeader FileReferenceNumber int64 ParentFileReferenceNumber int64 USN USN TimeStamp windows.Filetime }
RawRecordV1 represents the raw form of a version 1 change journal record.
type RawRecordV2 ¶
type RawRecordV2 struct { RawRecordHeader FileReferenceNumber int64 ParentFileReferenceNumber int64 USN USN TimeStamp windows.Filetime Reason Reason SourceInfo usnsource.Info SecurityID uint32 FileAttributes fileattr.Value FileNameLength uint16 FileNameOffset uint16 // contains filtered or unexported fields }
RawRecordV2 represents the raw form of a version 2 change journal record.
type RawRecordV3 ¶
type RawRecordV3 struct { RawRecordHeader FileReferenceNumber [16]byte ParentFileReferenceNumber [16]byte USN USN TimeStamp windows.Filetime Reason Reason SourceInfo usnsource.Info SecurityID uint32 FileAttributes fileattr.Value FileNameLength uint16 FileNameOffset uint16 // contains filtered or unexported fields }
RawRecordV3 represents the raw form of a version 3 change journal record.
type RawRecordV4 ¶
type RawRecordV4 struct { RawRecordHeader FileReferenceNumber [16]byte ParentFileReferenceNumber [16]byte USN USN Reason Reason SourceInfo usnsource.Info RemainingExtents uint32 NumberOfExtents uint16 ExtentSize uint16 // contains filtered or unexported fields }
RawRecordV4 represents the raw form of a version 4 change journal record.
type Reason ¶
type Reason uint32
Reason describes a kind of USN record, that is the reason for which it was recorded. A record may have been created for more than one reason.
const ( ReasonDataOverwrite Reason = 0x00000001 // USN_REASON_DATA_OVERWRITE ReasonDataExtend Reason = 0x00000002 // USN_REASON_DATA_EXTEND ReasonDataTruncation Reason = 0x00000004 // USN_REASON_DATA_TRUNCATION ReasonNamedDataOverwrite Reason = 0x00000010 // USN_REASON_NAMED_DATA_OVERWRITE ReasonNamedDataExtend Reason = 0x00000020 // USN_REASON_NAMED_DATA_EXTEND ReasonNamedDataTruncation Reason = 0x00000040 // USN_REASON_NAMED_DATA_TRUNCATION ReasonFileCreate Reason = 0x00000100 // USN_REASON_FILE_CREATE ReasonFileDelete Reason = 0x00000200 // USN_REASON_FILE_DELETE ReasonEAChange Reason = 0x00000400 // USN_REASON_EA_CHANGE ReasonSecurityChange Reason = 0x00000800 // USN_REASON_SECURITY_CHANGE ReasonRenameOldName Reason = 0x00001000 // USN_REASON_RENAME_OLD_NAME ReasonRenameNewName Reason = 0x00002000 // USN_REASON_RENAME_NEW_NAME ReasonRename Reason = ReasonRenameOldName | ReasonRenameNewName ReasonIndexableChange Reason = 0x00004000 // USN_REASON_INDEXABLE_CHANGE ReasonBasicInfoChange Reason = 0x00008000 // USN_REASON_BASIC_INFO_CHANGE ReasonHardLinkChange Reason = 0x00010000 // USN_REASON_HARD_LINK_CHANGE ReasonCompressionChange Reason = 0x00020000 // USN_REASON_COMPRESSION_CHANGE ReasonEncryptionChange Reason = 0x00040000 // USN_REASON_ENCRYPTION_CHANGE ReasonObjectIDChange Reason = 0x00080000 // USN_REASON_OBJECT_ID_CHANGE ReasonReparsePointChange Reason = 0x00100000 // USN_REASON_REPARSE_POINT_CHANGE ReasonStreamChange Reason = 0x00200000 // USN_REASON_STREAM_CHANGE ReasonTransactedChange Reason = 0x00400000 // USN_REASON_TRANSACTED_CHANGE ReasonIntegrityChange Reason = 0x00800000 // USN_REASON_INTEGRITY_CHANGE ReasonClose Reason = 0x80000000 // USN_REASON_CLOSE ReasonAny Reason = 0xffffffff )
USN Journal Reason Codes
func ParseReason ¶
ParseReason interprets the given string as one or more reason codes and returns a uint32 representing their combined bitmask.
func (Reason) Join ¶
func (r Reason) Join(sep string, format ReasonFormat) string
Join returns a string representation of the reason code using the given separator and reason format.
type ReasonFormat ¶
ReasonFormat describes a format for reason names
type Record ¶
type Record struct { RecordLength uint32 MajorVersion uint16 MinorVersion uint16 FileReferenceNumber fileref.ID ParentFileReferenceNumber fileref.ID USN USN TimeStamp time.Time Reason Reason SourceInfo usnsource.Info SecurityID uint32 // This always seems to be zero, and is probably useless FileAttributes fileattr.Value FileName string Path string }
Record represents a change journal record.
func (*Record) UnmarshalBinary ¶
UnmarshalBinary attempts to parse a single record from the given data.
type RecordExtent ¶
RecordExtent represents a change journal record extent.