{"id":2499,"date":"2013-12-01T00:01:00","date_gmt":"2013-12-01T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/12\/01\/weekend-scripter-determine-process-that-locks-a-file\/"},"modified":"2013-12-01T00:01:00","modified_gmt":"2013-12-01T00:01:00","slug":"weekend-scripter-determine-process-that-locks-a-file","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/weekend-scripter-determine-process-that-locks-a-file\/","title":{"rendered":"Weekend Scripter: Determine Process that Locks a File"},"content":{"rendered":"

Summary<\/strong>: Guest blogger, Adam Driscoll, talks about using Windows PowerShell to determine which process is locking a file.\nMicrosoft Scripting Guy, Ed Wilson, is here. Today we have a guest blogger, Adam Driscoll…\nIt’s quite common to run into the issue where a process is locking a particular file. Attempting to delete or open the file can result in an error message when another process has exclusive access to the file. Unfortunately, Windows PowerShell nor the .NET Framework expose a simple way of determining which process is locking the file. Determine which process is locking the file requires quite a few steps to interrogate the system. This can be accomplished by using a set of Windows API calls and Platform Invoke (PInvoke) functionality. In this post, we’ll take a tour of what it takes to identify the process that is locking a file.\nThe first step is to understand how Windows manages files and other objects. When opening a file in Windows, the kernel provides a handle to the calling process to identify the opened file. A handle is a kernel-level identifier to an open file or other Windows object. There are handles for all types of Windows objects, including files, events, and mutexes.\nTo view the open handles on the system, we need to utilize the NtQuerySystemInformation<\/strong> function. This function is largely undocumented, and it requires some intimate knowledge to use correctly. The first step is to call several Win32 functions and structures that we will need for this operation. This can be accomplished by using the Add-Type <\/strong>cmdlet. The functions involved include:<\/p>\n

NtQuerySystemInformation<\/a>: Amongst other things, can query the handles open on the system.<\/p>\n

NtQueryObject<\/a>: Queries additional information about a handle.<\/p>\n

OpenProcess<\/a>: Allows us to get more information about the process that owns the handle.<\/p>\n

DuplicateHandle<\/a>: Creates a copy of a handle in the current process (for example, ISE) so we can perform additional operations on it.<\/p>\n

QueryDosDevice<\/a>: Converts a logical drive (such as drive C) into the DOS device identifier.<\/p>\n

SystemHandleEntry<\/strong>: Describes the memory structure of handle information that is returned by NtQuerySystemInformation<\/strong>.\nFor more information about the signatures that are required to use these functions, refer to PInvoke.net<\/a>.\nNow we need to define the PInvoke<\/strong> functions. This has been eliminated in this document for brevity, but it is included in the script posted in the Script Center Repository: Find-LockingProcess<\/a>.\nThe next step is to query the handles that are currently open on the system. The following snippet, which is part of a larger function, queries the open handles on the system. We pass 16 into the NtQuerySystemInformation<\/strong> function to signify that we want it to return open handles. We then pass in IntPtr<\/strong>, which will hold the information return by the system.\nThe IntPtr<\/strong> object is used to hold the address of a chunk of memory that has been provided or allocated to us. The first time we fall through the while<\/strong> loop, it returns the size of the data that we need and then we allocate it by using the AllocHGlobal<\/strong> function. This returns a segment of memory large enough to hold the data.\nThe IntPtr<\/strong> object points to the beginning of that segment of memory. The next time we cycle through the loop, we have enough memory available to store all the handle data and NtQuerySystemInformation<\/strong> fills our memory segment with that data.<\/p>\n

        while ($true)<\/p>\n

        {<\/p>\n

            $ptr = [System.Runtime.InteropServices.Marshal]::AllocHGlobal($length)<\/p>\n

            $wantedLength = 0<\/p>\n

                 $SystemHandleInformation = 16<\/p>\n

            $result = [NtDll]::NtQuerySystemInformation($SystemHandleInformation, $ptr, $length, [ref] $wantedLength)<\/p>\n

            if ($result -eq [NT_STATUS]::STATUS_INFO_LENGTH_MISMATCH)<\/p>\n

            {<\/p>\n

                $length = [Math]::Max($length, $wantedLength)<\/p>\n

                [System.Runtime.InteropServices.Marshal]::FreeHGlobal($ptr)<\/p>\n

                $ptr = [IntPtr]::Zero<\/p>\n

            }<\/p>\n

            elseif ($result -eq [NT_STATUS]::STATUS_SUCCESS)<\/p>\n

                 {<\/p>\n

                break<\/p>\n

                 }<\/p>\n

            else<\/p>\n

                 {<\/p>\n

                throw (New-Object System.ComponentModel.Win32Exception)<\/p>\n

                 }<\/p>\n

        }\nFrom here, we can convert the handle information into a .NET structure that can be used easily in Windows PowerShell—much like any other object. We need to loop numerous times because we have multiple SystemHandleEntry<\/strong> structures to create—one for each open handle. We actually create the structures by using the Marshal.PtrToStructure<\/strong> method in the .NET Framework.\nYou may have noticed that we are incrementing an offset by using the size of the SystemHandleEntry<\/strong>. This is because we have a big blob of data, and we need to move sequentially down it to get each SystemHandleEntry<\/strong>. You can think of this as a big row of Lego blocks. We know the size of one block and instruct the PtrToStructure<\/strong> method to where the beginning of the each block is. It breaks that block off and returns it as a SystemHandleEntry<\/strong>.\nNote that I am evaluating whether the ObjectTypeNumber<\/strong> is 31. This is the file object type number for Windows 8. Other operating systems have different identifying numbers. To reduce the size of this post, I’ve eliminated the logic to determine that number, but it is possible to do so dynamically.<\/p>\n

$offset = [IntPtr]::Size<\/p>\n

$size = [System.Runtime.InteropServices.Marshal]::SizeOf([SystemHandleEntry])<\/p>\n

for ($i = 0; $i -lt $handleCount; $i++)<\/p>\n

{<\/p>\n

[SystemHandleEntry]$FileHandle = [System.Runtime.InteropServices.Marshal]::PtrToStructure([IntPtr]([long]$ptr + $offset), [SystemHandleEntry])<\/p>\n

 <\/p>\n

if ($FileHandle.ObjectTypeNumber -eq 31)<\/p>\n

{<\/p>\n

$FileHandle | ConvertTo-HandleHashTable<\/p>\n

}<\/p>\n

$offset += $size<\/p>\n

}\nWe have also defined a ConvertTo-HandleHashTable<\/strong> function. The purpose of this function is to convert the handle information into a useful hash table that will contain the path to the file and a System.Diagnostics.Process object. This is much more useful than the memory addresses and process IDs that currently populate the SystemHandleEntry<\/strong> structures that we just created.\nInside this function, we need to duplicate the handle returned by NtQuerySystemInformation<\/strong>. If we do not create a copy of the handle, we’ll be unable to query additional information about it. We use OpenProcess<\/strong> to get a handle to the process that owns the original handle. This is necessary for the DuplicateHandle<\/strong> function. The DuplicateHandle<\/strong> function is what provides us with a malleable handle inside our process.<\/p>\n

$sourceProcessHandle = [IntPtr]::Zero<\/p>\n

$handleDuplicate = [IntPtr]::Zero<\/p>\n

$currentProcessHandle = (Get-Process -Id $Pid).Handle<\/p>\n

$sourceProcessHandle = [Kernel32]::OpenProcess(0x40, $true, $HandleEntry.OwnerProcessId)<\/p>\n

 <\/p>\n

if (-not [Kernel32]::DuplicateHandle($sourceProcessHandle,<\/p>\n

  [IntPtr]$HandleEntry.Handle,<\/p>\n

  $currentProcessHandle,<\/p>\n

  [ref]$handleDuplicate,<\/p>\n

  0,<\/p>\n

  $false,<\/p>\n

  2))<\/p>\n

{<\/p>\n

     return<\/p>\n

}\nNext, we use the NtQueryObject<\/strong> function to get additional information about the handle. We use the duplicate handle because we will not have the proper rights on the original handle. In this case, we are calling NtQueryObject<\/strong> with the ObjectNameInformation<\/strong> flag. This tells NtQueryObject<\/strong> that we want the name of the handle. In regards to a file handle, this is the path to the file.<\/p>\n

$length = 0<\/p>\n

[NtDll]::NtQueryObject($handleDuplicate,  <\/p>\n

                       [OBJECT_INFORMATION_CLASS]::ObjectNameInformation,<\/p>\n

                       [IntPtr]::Zero,<\/p>\n

                       0,<\/p>\n

                       [ref]$length) | Out-Null<\/p>\n

$ptr = [IntPtr]::Zero<\/p>\n

 <\/p>\n

$ptr = [System.Runtime.InteropServices.Marshal]::AllocHGlobal($length)<\/p>\n

if ([NtDll]::NtQueryObject($handleDuplicate,<\/p>\n

                           [OBJECT_INFORMATION_CLASS]::ObjectNameInformation,<\/p>\n

                           $ptr,<\/p>\n

                           $length,<\/p>\n

                           [ref]$length) -ne [NT_STATUS]::STATUS_SUCCESS)<\/p>\n

{<\/p>\n

     return<\/p>\n

}\nWhen we have the name as an IntPtr<\/strong> object, we need to convert it into a .NET string. To do this, we use the Marshal.PtrToStringUni<\/strong> method. It converts a memory address into a useable .NET string.<\/p>\n

$Path = [System.Runtime.InteropServices.Marshal]::PtrToStringUni([IntPtr]([long]$ptr+ 2 * [IntPtr]::Size))\nFinally, we create a new PSCustomObject<\/strong> that contains the path to the file and the Process<\/strong> object that owns the handle in question. You can see that we are using a ConvertTo-RegularFileName<\/strong> function. This is due to the fact that the name returned by NtQueryObject<\/strong> will be in the DOS-style format. This format looks similar to: DeviceHarddiskVolume1myfile.txt.\nPerforming a comparison on a path like this would likely fail later. The result of ConvertTo-RegularFileName<\/strong> will instead be in this format: C:MyFile.txt.\n                        [PSCustomObject]@{\n                                    Path=(ConvertTo-RegularFileName $Path);\n                                    Process=(Get-Process -Id $HandleEntry.OwnerProcessId);\n                        }\nThe ConvertTo-RegularFileName<\/strong> function uses the QueryDosDevice<\/strong> function to convert a logical drive (such as drive C) into a DOS style drive (for example, DeviceHarddiskVolume1). We use Environment::GetLogicalDrives<\/strong> to return all the drives on the current machine. Then we convert them to DOS style and fix up the raw path that is returned by NtQueryObject<\/strong>.<\/p>\n

foreach ($logicalDrive in [Environment]::GetLogicalDrives())<\/p>\n

{<\/p>\n

       $targetPath = New-Object System.Text.StringBuilder 256<\/p>\n

if ([Kernel32]::QueryDosDevice($logicalDrive.Substring(0, 2), $targetPath, 256) -eq 0)<\/p>\n

{<\/p>\n

       return $targetPath<\/p>\n

 }<\/p>\n

        $targetPathString = $targetPath.ToString()<\/p>\n

        if ($RawFileName.StartsWith($targetPathString))<\/p>\n

        {<\/p>\n

            $RawFileName = $RawFileName.Replace($targetPathString,           <\/p>\n

                                                $logicalDrive.Substring(0, 2))<\/p>\n

            break<\/p>\n

        }<\/p>\n

}<\/p>\n

$RawFileName\nThis all comes together in the most useful of the functions, Find-LockingProcess<\/strong>. This advanced function accepts a file info object (as returned by Get-ChildItem<\/strong>), or a raw path, and it finds handles that are open for that path. When it finds the handle, it returns the Process<\/strong> object for the locking file.<\/p>\n

function Find-LockingProcess<\/p>\n

{<\/p>\n

            [CmdletBinding()]<\/p>\n

            param(<\/p>\n

            [Parameter(ValueFromPipeline=$true,ParameterSetName=”Pipeline”,Mandatory)]<\/p>\n

            [System.IO.FileInfo]$InputObject,<\/p>\n

            [Parameter(ValueFromPipeline=$true,ParameterSetName=”Path”,Mandatory)]<\/p>\n

            [String]$Path<\/p>\n

            )<\/p>\n

 <\/p>\n

            Begin {<\/p>\n

            $Handles = Get-FileHandle<\/p>\n

            }<\/p>\n

 <\/p>\n

            Process<\/p>\n

            {<\/p>\n

                        if ($InputObject)<\/p>\n

                        {<\/p>\n

                                    $Handles | Where-Object { $_.Path -eq $InputObject.FullName } | Select-Object -ExpandProperty Process<\/p>\n

                        }<\/p>\n

 <\/p>\n

                        if ($Path)<\/p>\n

                        {<\/p>\n

                                    $Handles| Where-Object { $_.Path -contains $Path } | Select-Object -ExpandProperty Process<\/p>\n

                        }<\/p>\n

            }<\/p>\n

}\nTo use this function, we could then specify a full file path. We will get output that references all the processes that have a handle open to the file. It’s worth noting that not all the process may be locking the file, but only a process that currently has a handle can be locking it. In the following example, Steam<\/strong> is locking the file and devenv<\/strong> is not.<\/p>\n

Find-LockingProcess -Path “E:Program Files (x86)Steamsteam.log”<\/p>\n

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName                                                                                                                                 <\/p>\n

——-  ——    —–      —– —–   ——     — ———–                                                                                                                                 <\/p>\n

    685      85   218692      37356   536   116.84   4420 Steam                                                                                                                                        <\/p>\n

  73285     248   279136     366676   887   550.61   3344 devenv                                                                                                                                       <\/p>\n

  74622     249   267796     359196   904   550.68   3344 devenv                                                                                                                                    <\/p>\n

  75959     246   282880     369672   881   550.76   3344 devenv                                                                                                                                   <\/p>\n

  88123     247   307540     389004   897   551.17   3344 devenv   \nThe full script can be found in the Script Center Repository: Find-LockingProcess<\/a>. You will likely need to run your Windows PowerShell host as an administrator to successfully execute this script.\n~Adam\nThank you, Adam, for taking your time to share with our readers.\nI invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.\nEd Wilson, Microsoft Scripting Guy<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Guest blogger, Adam Driscoll, talks about using Windows PowerShell to determine which process is locking a file. Microsoft Scripting Guy, Ed Wilson, is here. Today we have a guest blogger, Adam Driscoll… It’s quite common to run into the issue where a process is locking a particular file. Attempting to delete or open the […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[334,56,31,87,3,61,45],"class_list":["post-2499","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-adam-driscoll","tag-guest-blogger","tag-operating-system","tag-processes","tag-scripting-guy","tag-weekend-scripter","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Guest blogger, Adam Driscoll, talks about using Windows PowerShell to determine which process is locking a file. Microsoft Scripting Guy, Ed Wilson, is here. Today we have a guest blogger, Adam Driscoll… It’s quite common to run into the issue where a process is locking a particular file. Attempting to delete or open the […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/2499","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=2499"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/2499\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=2499"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=2499"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=2499"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}