Monday, January 2, 2012

Undocumented PowerShell 2 Tail Functionality

One feature that I have often thought was missing from PowerShell is the equivalent to the *nix tail functionality, which will display lines as they are added to a log file. I have used the PowerShell Community Extensions (PSCX) Get-FileTail cmdlet, but that can be frustrating because it is not available on all the computers I use, so I wanted to find a built-in equivalent.

It turns out that there is an undocumented built-in tail function. Use the Get-Content (alias = gc) cmdlet with the undocumented -Wait parameter. Apparently, it has performance issues with large files, so you may still need to carry a copy of PSCX around with you on a USB stick, but this should suffice for most scenarios.

Below is the documentation for Get-Content for PowerShell 2.0, with no mention of the -Wait parameter.


NAME
    Get-Content
    
SYNOPSIS
    Gets the content of the item at the specified location.
    
    
SYNTAX
    Get-Content [-LiteralPath]  [-Credential ] [-Exclude ] [-Filter ] [-Force
    ] [-Include ] [-ReadCount ] [-TotalCount ] [-UseTransaction] []
    
    Get-Content [-Path]  [-Credential ] [-Exclude ] [-Filter ] [-Force] [-Inc
    lude ] [-ReadCount ] [-TotalCount ] [-UseTransaction] []
    
    
DESCRIPTION
    The Get-Content cmdlet gets the content of the item at the location specified by the path, such as the text in a fi
    le. It reads the content one line at a time and returns an object for each line.
    

PARAMETERS
    -Credential 
        Specifies a user account that has permission to perform this action. The default is the current user. 
        
        Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated 
        by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.
        
        This parameter is not supported by any providers that are installed with Windows PowerShell.
        
    -Exclude 
        Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pa
        ttern, such as "*.txt". Wildcards are permitted.
        
    -Filter 
        Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path paramet
        er. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficie
        nt than other parameters, because the provider applies them when retrieving the objects, rather than having Win
        dows PowerShell filter the objects after they are retrieved.
        
    -Force []
        Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security
        . For example, Force will override the read-only attribute or create directories to complete a file path, but i
        t will not attempt to change file permissions.
        
    -Include 
        Retrieves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path elem
        ent or pattern, such as "*.txt". Wildcards are permitted.
        
    -LiteralPath 
        Specifies the path to an item. Unlike Path, the value of LiteralPath is used exactly as it is typed. No charact
        ers are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks.
         Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
        
    -Path 
        Specifies the path to an item. Get-Content retrieves the content of the item. Wildcards are permitted. The para
        meter name ("Path" or "FilePath") is optional.
        
    -ReadCount 
        Specifies how many lines of content are sent through the pipeline at a time. The default value is 1. A value of
         0 (zero) sends all of the content at one time. 
        
        This parameter does not change the content displayed, but it does affect the time it takes to display the conte
        nt. As the value of ReadCount increases, the time it takes to return the first line increases, but the total ti
        me for the operation decreases. This can make a perceptible difference in very large items.
        
    -TotalCount 
        Specifies how many lines of content are retrieved. The default is -1 (all lines).
        
    -UseTransaction []
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress.
         For more information, see about_Transactions.
        
    
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        "get-help about_commonparameters".
    
    -------------------------- EXAMPLE 1 --------------------------
    
    C:\PS>get-content -Path C:\Chapters\chapter1.txt
    
    Description
    -----------
    This command displays the content of the Chapter1.txt file on the console. It uses the Path parameter to specify th
    e name of the item. Get-Content actually passes the content down the pipeline, but because there are no other pipel
    ine elements, the content is formatted and displayed on the console.
    
    
    
    
    -------------------------- EXAMPLE 2 --------------------------
    
    C:\PS>get-content c:\Logs\Log060912.txt -totalcount 50 | set-content sample.txt
    
    Description
    -----------
    This command gets the first 50 lines of the Log060912.txt file and stores them in the sample.txt file. The command 
    uses the Get-Content cmdlet to get the text in the file. (The name of Path parameter, which is optional, is omitted
    .) The TotalCount parameter limits the retrieval to the first 50 lines. The pipeline operator (|) sends the result 
    to Set-Content, which places it in the sample.txt file.
    
    
    
    
    -------------------------- EXAMPLE 3 --------------------------
    
    C:\PS>(get-content cmdlets.txt -totalcount 5)[-1]
    
    Description
    -----------
    This command gets the fifth line of the Cmdlets.txt text file. It uses the TotalCount parameter to get the first fi
    ve lines and then uses array notation to get the last line (indicated by "-1") of the resulting set.
    
    
    
    
REMARKS
    To see the examples, type: "get-help Get-Content -examples".
    For more information, type: "get-help Get-Content -detailed".
    For technical information, type: "get-help Get-Content -full".

0 comments:

Post a Comment