package fs

import "github.com/Microsoft/go-winio/internal/fs"

This package contains Win32 filesystem functionality.

Index

Constants 

const NullHandle windows.Handle = 0

Functions

func CreateFile 

func CreateFile(name string, access AccessMask, mode FileShareMode, sa *windows.SecurityAttributes, createmode FileCreationDisposition, attrs FileFlagOrAttribute, templatefile windows.Handle) (handle windows.Handle, err error)

func GetFinalPathNameByHandle 

func GetFinalPathNameByHandle(h windows.Handle, flags GetFinalPathFlag) (string, error)

getFinalPathNameByHandle facilitates calling the Windows API GetFinalPathNameByHandle with the given handle and flags. It transparently takes care of creating a buffer of the correct size for the call.

https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfinalpathnamebyhandlew

Types

type AccessMask 

type AccessMask = windows.ACCESS_MASK

AccessMask defines standard, specific, and generic rights.

Used with CreateFile and NtCreateFile (and co.). 

Bitmask:
 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+---------------+---------------+-------------------------------+
|G|G|G|G|Resvd|A| StandardRights|         SpecificRights        |
|R|W|E|A|     |S|               |                               |
+-+-------------+---------------+-------------------------------+

GR     Generic Read
GW     Generic Write
GE     Generic Exectue
GA     Generic All
Resvd  Reserved
AS     Access Security System

https://learn.microsoft.com/en-us/windows/win32/secauthz/access-mask

https://learn.microsoft.com/en-us/windows/win32/secauthz/generic-access-rights

https://learn.microsoft.com/en-us/windows/win32/fileio/file-access-rights-constants 

const (
	// Not actually any.
	//
	// For CreateFile: "query certain metadata such as file, directory, or device attributes without accessing that file or device"
	// https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew#parameters
	FILE_ANY_ACCESS AccessMask = 0

	GENERIC_READ           AccessMask = 0x8000_0000
	GENERIC_WRITE          AccessMask = 0x4000_0000
	GENERIC_EXECUTE        AccessMask = 0x2000_0000
	GENERIC_ALL            AccessMask = 0x1000_0000
	ACCESS_SYSTEM_SECURITY AccessMask = 0x0100_0000

	FILE_READ_DATA      AccessMask = (0x0001) // file & pipe
	FILE_LIST_DIRECTORY AccessMask = (0x0001) // directory

	FILE_WRITE_DATA AccessMask = (0x0002) // file & pipe
	FILE_ADD_FILE   AccessMask = (0x0002) // directory

	FILE_APPEND_DATA          AccessMask = (0x0004) // file
	FILE_ADD_SUBDIRECTORY     AccessMask = (0x0004) // directory
	FILE_CREATE_PIPE_INSTANCE AccessMask = (0x0004) // named pipe

	FILE_READ_EA         AccessMask = (0x0008) // file & directory
	FILE_READ_PROPERTIES AccessMask = FILE_READ_EA

	FILE_WRITE_EA         AccessMask = (0x0010) // file & directory
	FILE_WRITE_PROPERTIES AccessMask = FILE_WRITE_EA

	FILE_EXECUTE  AccessMask = (0x0020) // file
	FILE_TRAVERSE AccessMask = (0x0020) // directory

	FILE_DELETE_CHILD AccessMask = (0x0040) // directory

	FILE_READ_ATTRIBUTES AccessMask = (0x0080) // all

	FILE_WRITE_ATTRIBUTES AccessMask = (0x0100) // all

	FILE_ALL_ACCESS      AccessMask = (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0x1FF)
	FILE_GENERIC_READ    AccessMask = (STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE)
	FILE_GENERIC_WRITE   AccessMask = (STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE)
	FILE_GENERIC_EXECUTE AccessMask = (STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE)

	SPECIFIC_RIGHTS_ALL AccessMask = 0x0000FFFF

	DELETE       AccessMask = 0x0001_0000
	READ_CONTROL AccessMask = 0x0002_0000
	WRITE_DAC    AccessMask = 0x0004_0000
	WRITE_OWNER  AccessMask = 0x0008_0000
	SYNCHRONIZE  AccessMask = 0x0010_0000

	STANDARD_RIGHTS_REQUIRED AccessMask = 0x000F_0000

	STANDARD_RIGHTS_READ    AccessMask = READ_CONTROL
	STANDARD_RIGHTS_WRITE   AccessMask = READ_CONTROL
	STANDARD_RIGHTS_EXECUTE AccessMask = READ_CONTROL

	STANDARD_RIGHTS_ALL AccessMask = 0x001F_0000
)

type FileCreationDisposition 

type FileCreationDisposition uint32
const (
	CREATE_NEW        FileCreationDisposition = 0x01
	CREATE_ALWAYS     FileCreationDisposition = 0x02
	OPEN_EXISTING     FileCreationDisposition = 0x03
	OPEN_ALWAYS       FileCreationDisposition = 0x04
	TRUNCATE_EXISTING FileCreationDisposition = 0x05
)

type FileFlagOrAttribute 

type FileFlagOrAttribute uint32

CreateFile and co. take flags or attributes together as one parameter. Define alias until we can use generics to allow both

https://learn.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants 

const (
	FILE_FLAG_WRITE_THROUGH       FileFlagOrAttribute = 0x8000_0000
	FILE_FLAG_OVERLAPPED          FileFlagOrAttribute = 0x4000_0000
	FILE_FLAG_NO_BUFFERING        FileFlagOrAttribute = 0x2000_0000
	FILE_FLAG_RANDOM_ACCESS       FileFlagOrAttribute = 0x1000_0000
	FILE_FLAG_SEQUENTIAL_SCAN     FileFlagOrAttribute = 0x0800_0000
	FILE_FLAG_DELETE_ON_CLOSE     FileFlagOrAttribute = 0x0400_0000
	FILE_FLAG_BACKUP_SEMANTICS    FileFlagOrAttribute = 0x0200_0000
	FILE_FLAG_POSIX_SEMANTICS     FileFlagOrAttribute = 0x0100_0000
	FILE_FLAG_OPEN_REPARSE_POINT  FileFlagOrAttribute = 0x0020_0000
	FILE_FLAG_OPEN_NO_RECALL      FileFlagOrAttribute = 0x0010_0000
	FILE_FLAG_FIRST_PIPE_INSTANCE FileFlagOrAttribute = 0x0008_0000
)

type FileSQSFlag 

type FileSQSFlag = FileFlagOrAttribute
const (
	SECURITY_ANONYMOUS      FileSQSFlag = FileSQSFlag(SecurityAnonymous << 16)
	SECURITY_IDENTIFICATION FileSQSFlag = FileSQSFlag(SecurityIdentification << 16)
	SECURITY_IMPERSONATION  FileSQSFlag = FileSQSFlag(SecurityImpersonation << 16)
	SECURITY_DELEGATION     FileSQSFlag = FileSQSFlag(SecurityDelegation << 16)

	SECURITY_SQOS_PRESENT     FileSQSFlag = 0x0010_0000
	SECURITY_VALID_SQOS_FLAGS FileSQSFlag = 0x001F_0000
)

type FileShareMode 

type FileShareMode uint32
const (
	FILE_SHARE_NONE        FileShareMode = 0x00
	FILE_SHARE_READ        FileShareMode = 0x01
	FILE_SHARE_WRITE       FileShareMode = 0x02
	FILE_SHARE_DELETE      FileShareMode = 0x04
	FILE_SHARE_VALID_FLAGS FileShareMode = 0x07
)

type GetFinalPathFlag 

type GetFinalPathFlag uint32

GetFinalPathNameByHandle flags

https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfinalpathnamebyhandlew#parameters 

const (
	GetFinalPathDefaultFlag GetFinalPathFlag = 0x0

	FILE_NAME_NORMALIZED GetFinalPathFlag = 0x0
	FILE_NAME_OPENED     GetFinalPathFlag = 0x8

	VOLUME_NAME_DOS  GetFinalPathFlag = 0x0
	VOLUME_NAME_GUID GetFinalPathFlag = 0x1
	VOLUME_NAME_NT   GetFinalPathFlag = 0x2
	VOLUME_NAME_NONE GetFinalPathFlag = 0x4
)

type NTCreateOptions 

type NTCreateOptions uint32

NtCreate* functions take a dedicated CreateOptions parameter.

https://learn.microsoft.com/en-us/windows/win32/api/Winternl/nf-winternl-ntcreatefile

https://learn.microsoft.com/en-us/windows/win32/devnotes/nt-create-named-pipe-file 

const (
	FILE_DIRECTORY_FILE            NTCreateOptions = 0x0000_0001
	FILE_WRITE_THROUGH             NTCreateOptions = 0x0000_0002
	FILE_SEQUENTIAL_ONLY           NTCreateOptions = 0x0000_0004
	FILE_NO_INTERMEDIATE_BUFFERING NTCreateOptions = 0x0000_0008

	FILE_SYNCHRONOUS_IO_ALERT    NTCreateOptions = 0x0000_0010
	FILE_SYNCHRONOUS_IO_NONALERT NTCreateOptions = 0x0000_0020
	FILE_NON_DIRECTORY_FILE      NTCreateOptions = 0x0000_0040
	FILE_CREATE_TREE_CONNECTION  NTCreateOptions = 0x0000_0080

	FILE_COMPLETE_IF_OPLOCKED NTCreateOptions = 0x0000_0100
	FILE_NO_EA_KNOWLEDGE      NTCreateOptions = 0x0000_0200
	FILE_DISABLE_TUNNELING    NTCreateOptions = 0x0000_0400
	FILE_RANDOM_ACCESS        NTCreateOptions = 0x0000_0800

	FILE_DELETE_ON_CLOSE        NTCreateOptions = 0x0000_1000
	FILE_OPEN_BY_FILE_ID        NTCreateOptions = 0x0000_2000
	FILE_OPEN_FOR_BACKUP_INTENT NTCreateOptions = 0x0000_4000
	FILE_NO_COMPRESSION         NTCreateOptions = 0x0000_8000
)

type NTFileCreationDisposition 

type NTFileCreationDisposition uint32

Create disposition values for NtCreate* 

const (
	FILE_SUPERSEDE           NTFileCreationDisposition = 0x00
	FILE_OPEN                NTFileCreationDisposition = 0x01
	FILE_CREATE              NTFileCreationDisposition = 0x02
	FILE_OPEN_IF             NTFileCreationDisposition = 0x03
	FILE_OVERWRITE           NTFileCreationDisposition = 0x04
	FILE_OVERWRITE_IF        NTFileCreationDisposition = 0x05
	FILE_MAXIMUM_DISPOSITION NTFileCreationDisposition = 0x05
)

type SecurityImpersonationLevel 

type SecurityImpersonationLevel int32 // C default enums underlying type is `int`, which is Go `int32`

https://learn.microsoft.com/en-us/windows/win32/api/winnt/ne-winnt-security_impersonation_level 

const (
	SecurityAnonymous      SecurityImpersonationLevel = 0
	SecurityIdentification SecurityImpersonationLevel = 1
	SecurityImpersonation  SecurityImpersonationLevel = 2
	SecurityDelegation     SecurityImpersonationLevel = 3
)

Impersonation levels

Source Files

doc.go fs.go security.go zsyscall_windows.go

Version
v0.6.2 (latest)
Published
Apr 9, 2024
Platform
windows/amd64
Imports
4 packages
Last checked
23 hours ago –

Tools for package owners.