4.0 SMB Requests

This section lists the "best practice" SMB requests—ones that would permit a client to exercise full CIFS functionality and optimum performance when interoperating with a server speaking the latest dialect as of this writing ("NT LM 0.12").

Note   As of this writing, no existing client restricts itself to only these requests, so no useful server can be written that supports just them. The classification is provided so that future clients will be written to permit future servers to be simpler.

4.1 Session Requests

4.1.1 NEGOTIATE: Negotiate Protocol

The Client sends a list of dialects with which it can communicate. The response is a selection of one of those dialects (numbered 0 through n) or -1 (hex FFFF) indicating that none of the dialects was acceptable. The negotiate message is binding on the virtual circuit and must be sent. One and only one negotiate message may be sent; subsequent negotiate requests will be rejected with an error response, and no action will be taken.

The protocol does not impose any particular structure to the dialect strings. Implementers of particular protocols may choose to include, for example, version numbers in the string.

If the server does not understand any of the dialect strings, or if PC NETWORK PROGRAM 1.0 is the chosen dialect, the response format is:

If the chosen dialect is greater than core up to and including LANMAN2.1, the protocol response format is:

MaxBufferSize is the size of the largest message that the client can legitimately send to the server.

If bit0 of the Flags field is set in the negotiate response, this indicates the server supports the SMB_COM_LOCK_AND_READ and SMB_COM_WRITE_AND_UNLOCK client requests.

If the SecurityMode field indicates the server is running in user mode, the client must send appropriate SMB_COM_SESSION_SETUP_ANDX requests before the server will allow the client to access resources. If the SecurityMode fields indicate the client should use challenge/response authentication, the client should use the authentication mechanism.

Clients using the "MICROSOFT NETWORKS 1.03" dialect use a different form of raw reads than documented here, and servers are better off setting RawMode in this response to 0 for such sessions.

If the negotiated dialect is "DOS LANMAN2.1" or "LANMAN2.1," then PrimaryDomain string should be included in this response.

If the negotiated dialect is NT LM 0.12, the response format is:

In addition to the definitions above, MaxBufferSize is the size of the largest message the client can legitimately send to the server. If the client is using a connectionless protocol, MaxBufferSize must be set to the smaller of the server's internal buffer size and the amount of data that can be placed in a response packet.

MaxRawSize specifies the maximum message size the server can send or receive for SMB_COM_WRITE_RAW or SMB_COM_READ_RAW.

Connectionless clients must set Sid to 0 in the SMB request header.

Capabilities allows the server to tell the client what it supports. The bit definitions are:

4.1.1.1 Errors

SUCCESS/SUCCESS
ERRSRV/ERRerror

4.1.2 SESSION_SETUP_ANDX: Session Setup

This SMB is used to further "Set up" the session normally just established via the negotiate protocol.

One primary function is to perform a "user logon" in the case where the server is in user level security mode. The Uid in the SMB header is set by the client to be the userid desired for the AccountName and validated by the AccountPassword.

If the negotiated protocol is prior to NT LM 0.12, the format of SMB_COM_SESSION_SETUP_ANDX is:

and the response is:

If the server is in "share level security mode," the account name and passwd should be ignored by the server.

If challenge/response authentication is not being used, AccountPassword should be a null terminated ASCII string with PasswordLength set to the string size including the null; the password will be case-insensitive. If challenge/response authentication is being used, then AccountPassword will be the response to the server's challenge, and PasswordLength should be set to its length.

The server validates the name and password supplied and, if valid, registers the user identifier on this session as representing the specified AccountName. The Uid field in the SMB header will then be used to validate access on subsequent SMB requests. The SMB requests where permission checks are required are those that refer to a symbolically named resource such as SMB_COM_OPEN, SMB_COM_RENAME, SMB_COM_DELETE, etc. The value of the Uid is relative to a specific client/server session, so it is possible to have the same Uid value represent two different users on two different sessions at the server.

Multiple session setup commands may be sent to register additional users on this session. If the server receives an additional SMB_COM_SESSION_SETUP_ANDX, only the Uid, AccountName, and AccountPassword fields need contain valid values (the server must ignore the other fields).

The client writes the name of its domain in PrimaryDomain if it knows what the domain name is. If the domain name is unknown, the client either encodes it as a NULL string or as a question mark.

If bit0 of Action is set, this informs the client that, although the server did not recognize the AccountName, it logged in the user as a guest. This is optional behavior by the server, and one would ordinarily expect guest privileges to be limited.

Another function of the Session Set Up protocol is to inform the server of the maximum values that will be utilized by this client. Here MaxBufferSize is the maximum message size the client can receive. Thus, although the server may support 16k buffers (as returned in the SMB_COM_NEGOTIATE response), if the client only has 4k buffers, the value of MaxBufferSize here would be 4096. The minimum allowable value for MaxBufferSize is 1024. The SMB_COM_NEGOTIATE response includes the server buffer size supported. This is the maximum SMB message size the client can send to the server. This size may be larger than the size returned to the server from the client via the SMB_COM_SESSION_SETUP_AND X protocol, which is the maximum SMB message size the server may send to the client. Thus, if the server's buffer size were 4k and the client's buffer size were only 2K, the client could send up to 4k (standard) write requests, but must only request up to 2k for (standard) read requests.

The VcNumber field specifies whether the client wants this to be the first VC or an additional VC.

The values for MaxBufferSize, MaxMpxCount, and VcNumber must be less than or equal to the maximum values supported by the server as returned in the SMB_COM_NEGOTIATE response.

If the server gets a SMB_COM_SESSION_SETUP_ANDX request with VcNumber of 0 and other VCs are still connected to that client, they will be aborted, thus freeing any resources held by the server. This condition could occur if the client was rebooted and reconnected to the server before the transport level had informed the server of the previous VC termination.

If the negotiated SMB dialect is "NT LM 0.12" and the server supports ExtendedSecurity, i.e., the CAP_EXTENDED_SECURITY flag is set in the Capabilities field of the Negotiate Response SMB, the Extended Security SessionSetup SMB format is:

The response is:

Multiple parts may be involved in the security blob exchange. In that case, the server may return an error STATUS_MORE_PROCESSING_REQUEIRED (a value of 0xC0000016) in the SMB status. The client can then repeat the SessionSetupAndX SMB with the rest of the security blob.

If the negotiated SMB dialect is "NT LM 0.12" or later and the server does not support Extended Security (i.e., the CAP_EXTENDED_SECURITY flag in the Capabilities field of the Negotiate Response SMB is not set), the format of the response SMB is unchanged, but the request is:

The client expresses its capabilities to the server encoded in the Capabilities field:

The entire message sent and received, including the optional ANDX SMB, must fit in the negotiated maximum transfer size. The following are the only valid SMB commands for AndXCommand for SMB_COM_SESSION_SETUP_ANDX.

4.1.2.1 Errors

ERRSRV/ERRerror- no NEG_PROT issued
ERRSRV/ERRbadpw- password not correct for given username
ERRSRV/ERRtoomanyuids- maximum number of users per session exceeded
ERRSRV/ERRnosupport- chaining of this request to the previous one not supported

4.1.3 LOGOFF_ANDX: User Logoff

This SMB is the inverse of SMB_COM_SESSION_SETUP_ANDX.

The user represented by Uid in the SMB header is logged off. The server closes all files currently open by this user, and invalidates any outstanding requests with this Uid.

SMB_COM_SESSION_SETUP_ANDX is the only valid AndXCommand. for this SMB.

4.1.3.1 Errors

ERRSRV/invnid- TID was invalid
ERRSRV/baduid- UID was invalid

4.1.4 TREE_CONNECT_ANDX: Tree Connect

The serving machine verifies the combination and returns an error code or an identifier. The full name is included in this request message, and the identifier identifying the connection is returned in the Tid field of the SMB header. The Tid field in the client request is ignored. The meaning of this identifier (Tid) is server-specific; the client must not associate any specific meaning to it.

If the negotiated dialect is LANMAN1.0 or later, it is a protocol violation for the client to send this message prior to a successful SMB_COM_SESSION_SETUP_ANDX, and the server ignores Password.

If the negotiated dialect is prior to LANMAN1.0 and the client has not sent a successful SMB_COM_SESSION_SETUP_ANDX request when the tree connect arrives, a user level security mode server must nevertheless validate the client's credentials as discussed earlier in this document.

Path follows UNC style syntax, that is, it is encoded as \\server\share and it indicates the name of the resource to which the client wishes to connect.

Because Password may be an authentication response, it is a variable length field with the length specified by PasswordLength. If authentication is not being used, Password should be a null terminated ASCII string with PasswordLength set to the string size including the terminating null.

The server can enforce whatever policy it desires to govern share access. Typically, if the server is paused, administrative privilege is required to connect to any share; if the server is not paused, administrative privilege is required only for administrative shares (C$, etc.). Other such policies may include valid times of day, software usage license limits, number of simultaneous server users or share users, etc.

The Service component indicates the type of resource the client intends to access. Valid values are:

If bit0 of Flags is set, the tree connection to Tid in the SMB header should be disconnected. If this tree disconnect fails, the error should be ignored.

If the negotiated dialect is earlier than DOS LANMAN2.1, the response to this SMB is:

If the negotiated is DOS LANMAN2.1 or later, the response to this SMB is:

NativeFileSystem is the name of the file system; values to be expected include FAT, NTFS, etc.

OptionalSupport bits has the encoding:

Some servers negotiate "DOS LANMAN2.1" dialect or later and still send the "downlevel" (i.e., wordcount==2) response. Valid AndX following commands are:

4.1.4.1 Errors

ERRDOS/ERRnomem
ERRDOS/ERRbadpath
ERRDOS/ERRinvdevice
ERRSRV/ERRaccess
ERRSRV/ERRbadpw
ERRSRV/ERRinvnetname

4.1.5 TREE_DISCONNECT: Tree Disconnect

This message informs the server that the client no longer wishes to access the resource connected to with a prior SMB_COM_TREE_CONNECT or SMB_COM_TREE_CONNECT_ANDX.

The resource-sharing connection identified by Tid in the SMB header is logically disconnected from the server. Tid is invalidated; it will not be recognized if used by the client for subsequent requests. All locks, open files, etc. created on behalf of Tid are released.

4.1.5.1 Errors

ERRSRV/ERRinvnid
ERRSRV/ERRbaduid

4.1.6 TRANS2_QUERY_FS_INFORMATION: Get File System Information

This transaction requests information about a file system on the server.

The file system is identified by Tid in the SMB header.

MaxDataCount in the transaction request must be large enough to accommodate the response.

The encoding of the response parameter block depends on the InformationLevel requested. Information levels whose values are greater than 0x102 are mapped to corresponding calls to NtQueryVolumeInformationFile calls by the server. The two levels below 0x102 are described below. The requested information is placed in the Data portion of the transaction response.

The following sections describe the InformationLevel dependent encoding of the data part of the transaction response.

4.1.6.1 SMB_INFO_ALLOCATION

4.1.6.2 SMB_INFO_VOLUME

4.1.6.3 SMB_QUERY_FS_VOLUME_INFO

4.1.6.4 SMB_QUERY_FS_SIZE_INFO

4.1.6.5 SMB_QUERY_FS_DEVICE_INFO

For DeviceType, note that the values 0-32767 are reserved for the exclusive use of Microsoft Corporation. The following device types are currently defined:

Some of these device types are not currently accessible over the network and may never be accessible over the network. Some may change to be accessible over the network. The values for device types that may never be accessible over the network may be redefined to be reserved at some date in the future.

Characteristics is the sum of any of the following:

4.1.6.6 SMB_QUERY_FS_ATTRIBUTE_INFO

Where FileSystemAttributes is the sum of any of the following:

4.1.6.7 Errors

ERRSRV/invnid- TID was invalid
ERRSRV/baduid- UID was invalid
ERRHRD/ERRnotready- the file system has been removed
ERRHRD/ERRdata- disk I/O error
ERRSRV/ERRaccess- user does not have the right to perform this operation
ERRSRV/ERRinvdevice- resource identified by TID is not a file system

4.1.7 ECHO: Ping the Server

This request is used to test the connection to the server, and to see if the server is still responding.

Each response echoes the data sent, though ByteCount may indicate no data If EchoCount is zero, no response is sent.

Tid in the SMB header is ignored, so this request may be sent to the server even if there are no valid tree connections to the server.

The flow for the ECHO protocol is:

4.1.7.1 Errors

ERRSRV/ERRbaduid- UID was invalid
ERRSRV/ERRnoaccess- session has not been established
ERRSRV/ERRnosupport- ECHO function is not supported

4.1.8 NT_CANCEL: Cancel Request

This SMB allows a client to cancel a request currently pending at the server.

The Sid, Uid, Pid, Tid, and Mid fields of the SMB are used to locate a pending server request from this session. If a pending request is found, it is "hurried along," which may result in success or failure of the original request. No other response is generated for this SMB.

4.2 File Requests

4.2.1 NT_CREATE_ANDX: Create or Open File

This command is used to create or open a file or a directory.

The DesiredAccess parameter is specified in Section 3.8, Access Mask Encoding.

If no value is specified, it still allows an application to query attributes without actually accessing the file.

The ExtFIleAttributes parameter specifies the file attributes and flags for the file. The parameter's value is the sum of allowed attributes and flags defined in Section 3.12 on Extended File Attribute Encoding.

The ShareAccess field specifies how this file can be shared. This parameter must be some combination of the following values:

The CreateDisposition parameter can contain one of the following values:

The ImpersonationLevel parameter can contain one or more of the following values:

The SecurityFlags parameter can have either of the following two flags set:

The response is as follows:

The following SMBs may follow SMB_COM_NT_CREATE_ANDX:

4.2.2 NT_TRANSACT_CREATE: Create or Open File with EAs or SD

This command is used to create or open a file or a directory, when EAs or an SD must be applied to the file.

See the description of NT_CREATE_ANDX for the definition of the parameters.

4.2.3 CREATE_TEMPORARY: Create Temporary File

The server creates a data file in Directory relative to Tid in the SMB header and assigns a unique name to it.

Fid is the returned handle for future file access. Filename is the name of the file that was created within the requested Directory. It is opened in compatibility mode with read/write access for the client.

Support of CreationTime by the server is optional.

4.2.4 READ_ANDX: Read Bytes

If the negotiated dialect is NT LM 0.12 or later, the client may use the 12-parameter word version of the request. This version allows specification of 64-bit file offsets.

If CAP_LARGE_READX was indicated by the server in the negotiate protocol response, the request's MaxCount field may exceed the negotiated buffer size if Fid refers to a disk file. The server may arbitrarily elect to return fewer than MaxCount bytes in response.

The following SMBs may follow SMB_COM_READ_ANDX:
SMB_COM_CLOSE

4.2.4.1 Errors

ERRDOS/ERRnoaccess
ERRDOS/ERRbadfid
ERRDOS/ERRlock
ERRDOS/ERRbadaccess
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.5 WRITE_ANDX: Write Bytes to file File or Resource

A ByteCount of 0 does not truncate the file. Rather, a zero length write merely transfers zero bytes of information to the file. A request such as SMB_COM_WRITE must be used to truncate the file.

If WriteMode has bit0 set in the request and Fid refers to a disk file, the response is not sent from the server until the data is on stable storage.

If the negotiated dialect is NT LM 0.12 or later, the 14-word format of this SMB may be used to access portions of files requiring offsets expressed as 64 bits. Otherwise, the OffsetHigh field must be omitted from the request.

The following are the valid AndXCommand values for this SMB:

4.2.5.1 Errors

ERRDOS/ERRnoaccess
ERRDOS/ERRbadfid
ERRDOS/ERRlock
ERRDOS/ERRbadaccess
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.6 LOCKING_ANDX: Lock or Unlock Byte Ranges

SMB_COM_LOCKING_ANDX allows both locking and/or unlocking of file range(s).

Locking is a simple mechanism for excluding other processes read/write access to regions of a file. The locked regions can be anywhere in the logical file. Locking beyond end-of-file is permitted. Any process using the Fid specified in this request's Fid has access to the locked bytes; other processes will be denied the locking of the same bytes.

The proper method for using locks is not to rely on being denied read or write access on any of the read/write protocols, but rather to attempt the locking protocol and proceed with the read/write only if the locks succeeded.

Locking a range of bytes will fail if any subranges or overlapping ranges are locked. In other words, if any of the specified bytes are already locked, the lock will fail.

If NumberOfUnlocks is non-zero, the Unlocks vector contains NumberOfUnlocks elements. Each element requests that a lock at Offset of Length be released. If NumberOfLocks is non-zero, the Locks vector contains NumberOfLocks elements. Each element requests the acquisition of a lock at Offset of Length.

Timeout is the maximum amount of time to wait for the byte range(s) specified to become unlocked. A timeout value of 0 indicates that the server should fail immediately if any lock range specified is locked. A timeout value of -1 indicates that the server should wait as long as it takes for each byte range specified to become unlocked so that it may be again locked by this protocol. Any other value of smb_timeout specifies the maximum number of milliseconds to wait for all lock range(s) specified to become available.

If any of the lock ranges timeout because of the area to be locked is already locked (or the lock fails), the other ranges in the protocol request that were successfully locked as a result of this protocol will be unlocked (either all requested ranges will be locked when this protocol returns to the client or none).

If LockType has the LOCKING_ANDX_SHARED_LOCK flag set, the lock is specified as a shared lock. Locks for both read and write (where LOCKING_ANDX_SHARED_LOCK is clear) should be prohibited, but other shared locks should be permitted. If shared locks cannot be supported by a server, the server should map the lock to a lock for both read and write. Closing a file with locks still in force causes the locks to be released in no defined order.

If LockType has the LOCKING_ANDX_LARGE_FILES flag set and if the negotiated protocol is NT LM 0.12 or later, then the Locks and Unlocks vectors are in the Large File LOCKING_ANDX_RANGE format. This allows specification of 64-bit offsets for very large files.

If the one and only member of the Locks vector has the LOCKING_ANDX_CANCEL_LOCK flag set in the LockType field, the client is requesting the server to cancel a previously requested, but not yet responded to, lock.

If LockType has the LOCKING_ANDX_CHANGE_LOCKTYPE flag set, the client is requesting that the server atomically change the lock type from a shared lock to an exclusive lock or vice versa. If the server cannot do this in an atomic fashion, the server must reject this request. NT and W95 servers do not support this capability.

Oplocks are described in Opportunistic Locks, Section 2.6 in this document. A client requests an oplock by setting the appropriate bit in the SMB_COM_OPEN_ANDX request when the file is being opened in a mode that is not exclusive. The server responds by setting the appropriate bit in the response SMB indicating whether or not the oplock was granted. By granting the oplock, the server tells the client the file is currently being used by only this one client process at the current time. The client can therefore safely do read ahead and write behind as well as local caching of file locks, knowing that the file will not be accessed/changed in any way by another process while the oplock is in effect. The client will be notified when another process attempts to open or modify the oplocked file.

When another user attempts to open or otherwise modify the file that a client has oplocked, the server delays the second attempt and notifies the client via an SMB_LOCKING_ANDX SMB asynchronously sent from the server to the client. This message has the LOCKING_ANDX_OPLOCK_RELEASE flag set indicating to the client that the oplock is being broken. OplockLevel indicates the type of oplock the client now owns. If OplockLevel is 0, the client possesses no oplocks on the file at all. If OplockLevel is 1, the client possesses a Level II oplock. The client is expected to flush any dirty buffers to the server, submit any file locks, and respond to the server with either an SMB_LOCKING_ANDX SMB having the LOCKING_ANDX_OPLOCK_RELEASE flag set, or with a file close if the file is no longer in use by the client. If the client sends an SMB_LOCKING_ANDX SMB with the LOCKING_ANDX_OPLOCK_RELEASE flag set and NumberOfLocks is zero, the server does not send a response. Since a close being sent to the server and break oplock notification from the server could cross on the wire, if the client gets an oplock notification on a file that it does not have open, that notification should be ignored.

Due to timing, the client could get an "oplock broken" notification in a user's data buffer as a result of this notification crossing on the wire with an SMB_COM_READ_RAW request. The client must detect this (use length of msg, "FFSMB," MID of -1 and Command of SMB_COM_LOCKING_ANDX) and honor the "oplock broken" notification as usual. The server must also note on receipt of an SMB_COM_READ_RAW request that there is an outstanding (unanswered) "oplock broken" notification to the client; it must then return a zero length response denoting failure of the read raw request. The client should (after responding to the "oplock broken" notification), use a standard read protocol to redo the read request. This allows a file to actually contain data matching an "oplock broken" notification and still be read correctly.

The entire message sent and received including the optional second protocol must fit in the negotiated maximum transfer size. The following are the only valid SMB commands for AndXCommand for SMB_COM_LOCKING_ANDX:

4.2.6.1 Errors

ERRDOS/ERRbadfile
ERRDOS/ERRbadfid
ERRDOS/ERRlock
ERRDOS/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.7 SEEK: Seek in File

The seek message is sent to set the current file pointer for Fid.

The starting point of the seek is set by Mode:

The "current position" reflects the offset plus data length specified in the previous read, write, or seek request; and the pointer set by this command will be replaced by the offset specified in the next read, write, or seek command.

The response returns the new file pointer in Offset, which is expressed as the offset from the start of the file, and may be beyond the current end of file. An attempt to seek to before the start of file sets the current file pointer to start of the file.

This request should generally be issued only by clients wishing to find the size of a file, because all read and write requests include the read or write file position as part of the SMB. This request is inappropriate for very large files, as the offsets specified are only 32 bits. A seek that results in an Offset that cannot be expressed in 32 bits returns the least significant.

4.2.7.1 Errors

ERRDOS/ERRbadfid
ERRDOS/ERRnoaccess
ERRSRV/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.8 FLUSH: Flush File

The flush SMB is sent to ensure all data and allocation information for the corresponding file has been written to stable storage. When the Fid has a value -1 (hex FFFF), the server performs a flush for all file handles associated with the client and Pid. The response is not sent until the writes are complete.

This client request is probably expensive to perform at the server, because the server's operating system is generally scheduling disk writes in a way that is optimal for the system's read and write activity integrated over the entire population of clients. This message from a client "interferes" with the server's ability to optimally schedule the disk activity; clients are discouraged from overuse of this SMB request.

4.2.8.1 Errors

ERRDOS/ERRbadfid
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.9 CLOSE: Close File

The close message is sent to invalidate a file handle for the requesting process. All locks or other resources held by the requesting process on the file should be released by the server. The requesting process can no longer use Fid for further file access requests.

If LastWriteTime is 0, the server should allow its local operating system to set the file's times. Otherwise, the server should set the time to the values requested. Failure to set the times, even if requested by the client in the request message, should not result in an error response from the server.

If Fid refers to a print spool file, the file should be spooled to the printer at this time.

4.2.9.1 Errors

ERRDOS/ERRbadfid
ERRSRV/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.10 DELETE: Delete File

The delete file message is sent to delete a data file. The appropriate Tid and additional pathname are passed. Read only files may not be deleted, the read-only attribute must be reset prior to file deletion.

Multiple files may be deleted in response to a single request, as SMB_COM_DELETE supports wildcards.

SearchAttributes indicates the attributes that the target file(s) must have. If the attribute is zero, then only normal files are deleted. If the system file or hidden attributes are specified, then the delete is inclusive—both the specified type(s) of files and normal files are deleted. Attributes are described in Section 3.11, File Attribute Encoding.

If bit0 of the Flags2 field of the SMB header is set, a pattern is passed in, and the file has a long name, then the passed pattern must match the long file name for the delete to succeed. If bit0 is clear, a pattern is passed in, and the file has a long name, then the passed pattern must match the file's short name for the deletion to succeed.

4.2.10.1 Errors

ERRDOS/ERRbadpath
ERRDOS/ERRbadfile
ERRDOS/ERRnoaccess
ERRHRD/ERRnowrite
ERRSRV/ERRaccess
ERRSRV/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.11 RENAME: Rename File

The rename file message is sent to change the name of a file.

Files OldFileName must exist and NewFileName must not. Both pathnames must be relative to the Tid specified in the request. Open files may be renamed.

Multiple files may be renamed in response to a single request, as Rename File supports wildcards in the file name (last component of the pathname).

SearchAttributes indicates the attributes that the target file(s) must have. If SearchAttributes is zero, then only normal files are renamed. If the system file or hidden attributes are specified, then the rename is inclusive—both the specified type(s) of files and normal files are renamed. The encoding of SearchAttributes is described in Section 3.11, File Attribute Encoding.

4.2.11.1 Errors

ERRDOS/ERRbadpath
ERRDOS/ERRbadfile
ERRDOS/ERRnoaccess
ERRDOS/ERRdiffdevice
ERRHRD/ERRnowrite
ERRSRV/ERRaccess
ERRSRV/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid

4.2.12 MOVE: Rename File

The source file is copied to the destination, and the source is subsequently deleted.

OldFileName is copied to NewFileName, then OldFileName is deleted. Both OldFileName and NewFileName must refer to paths on the same server. NewFileName can refer to either a file or a directory. All file components except the last must exist; directories will not be created.

NewFileName can be required to be a file or a directory by the Flags field.

The Tid in the header is associated with the source while Tid2 is associated with the destination. These fields may contain the same or differing valid values. Tid2 can be set to –1, indicating that this is to be the same Tid as in the SMB header. This allows use of the move protocol with SMB_TREE_CONNECT_ANDX.

The source path must refer to an existing file or files. Wildcards are permitted. Source files specified by wildcards are processed until an error is encountered. If an error is encountered, the expanded name of the file is returned in ErrorFileName. Wildcards are not permitted in NewFileName.

OpenFunction controls what should happen if the destination file exists. If (OpenFunction & 0x30) == 0, the operation should fail if the destination exists. If (OpenFunction & 0x30) == 0x20, the destination file should be overwritten.

4.2.12.1 Errors

ERRDOS/ERRfilexists
ERRDOS/ERRbadfile
ERRDOS/ERRnoaccess
ERRDOS/ERRnofiles
ERRDOS/ERRbadshare
ERRHRD/ERRnowrite
ERRSRV/ERRnoaccess
ERRSRV/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid
ERRSRV/ERRnosupport
ERRSRV/ERRaccess

4.2.13 COPY: Copy File

The file at SourceName is copied to TargetFileName, both of which must refer to paths on the same server.

The Tid in the header is associated with the source while Tid2 is associated with the destination. These fields may contain the same or differing valid values. Tid2 can be set to –1, indicating that this is to be the same Tid as in the SMB header. This allows use of the move protocol with SMB_TREE_CONNECT_ANDX.

The source path must refer to an existing file or files. Wildcards are permitted. Source files specified by wildcards are processed until an error is encountered. If an error is encountered, the expanded name of the file is returned in ErrorFileName. Wildcards are not permitted in TargetFileName. TargetFileName can refer to either a file or a directory.

The destination can be required to be a file or a directory by the bits in Flags. If neither bit0 nor bit1 is set, the destination may be either a file or a directory. Flags also controls the copy mode. In a binary copy for the source, the copy stops the first time an end of file (EOF) (control-Z) is encountered. In a binary copy for the target, the server must make sure that there is exactly one EOF in the target file and that it is the last character of the file.

If the destination is a file and the source contains wildcards, the destination file will either be truncated or appended to at the start of the operation, depending on bits in OpenFunction. Subsequent files will then be appended to the file.

If the negotiated dialect is LM1.2X002 or later, bit5 of Flags is used to specify a tree copy on the remote server. When this option is selected, the destination must not be an existing file, and the source mode must be binary. A request with bit5 set and either bit0 or bit3 set is therefore an error. When the tree copy mode is selected, the Count field in the server response is undefined.

4.2.13.1 Errors

ERRDOS/ERRfilexists
ERRDOS/ERRshare
ERRDOS/ERRnofids
ERRDOS/ERRbadfile
ERRDOS/ERRnoaccess
ERRDOS/ERRnofiles
ERRDOS/ERRbadshare
ERRSRV/ERRnoaccess
ERRSRV/ERRinvdevice
ERRSRV/ERRinvid
ERRSRV/ERRbaduid
ERRSRV/ERRaccess

4.2.14 TRANS2_QUERY_PATH_INFORMATION: Get File Attributes Given Path

This request is used to get information about a specific file or subdirectory.

The following InformationLevels may be requested:

The requested information is placed in the Data portion of the transaction response. For the information levels greater than 0x100, the transaction response has 1 parameter word that should be ignored by the client.

The following sections describe the InformationLevel dependent encoding of the data part of the transaction response.

4.2.14.1 SMB_INFO_STANDARD & SMB_INFO_QUERY_EA_SIZE

4.2.14.2 SMB_INFO_QUERY_EAS_FROM_LIST & SMB_INFO_QUERY_ALL_EAS

4.2.14.3 SMB_INFO_IS_NAME_VALID

This requests checks to see if the name of the file contained in the request's Data field has a valid path syntax. No parameters or data are returned on this information request. An error is returned if the syntax of the name is incorrect. Success indicates the server accepts the path syntax, but it does not ensure that the file or directory actually exists.

4.2.14.4 SMB_QUERY_FILE_BASIC_INFO

4.2.14.5 SMB_QUERY_FILE_STANDARD_INFO

4.2.14.6 SMB_QUERY_FILE_EA_INFO

4.2.14.7 SMB_QUERY_FILE_NAME_INFO

4.2.14.8 SMB_QUERY_FILE_ALL_INFO

The AccessFlags specifies the access permissions a caller has to the file and can have any suitable combination of the following values:

The Mode field specifies the mode in which the file is currently opened. The possible values may be a suitable and logical combination of the following:

The AlignmentRequirement field specifies buffer alignment required by the device and can have any one of the following values:

4.2.14.9 SMB_QUERY_FILE_ALT_NAME_INFO

4.2.14.10 SMB_QUERY_FILE_STREAM_INFO

4.2.14.11 SMB_QUERY_FILE_COMPRESSION_INFO

4.2.15 TRANS2_QUERY_FILE_INFORMATION: Get File Attributes Given FID

This request is used to get information about a specific file or subdirectory given a handle to it.

The available information levels, as well as the format of the response are identical to TRANS2_QUERY_PATH_INFORMATION.

4.2.16 TRANS2_SET_PATH_INFORMATION: Set File Attributes Given Path

This request is used to set information about a specific file or subdirectory.

The following Information Levels may be set:

The response formats are:

4.2.16.1 SMB_INFO_STANDARD & SMB_INFO_QUERY_EA_SIZE

4.2.16.2 SMB_INFO_QUERY_ALL_EAS

4.2.17 TRANS2_SET_FILE_INFORMATION: Set File Attributes Given FID

This request is used to set information about a specific file or subdirectory given a handle to the file or subdirectory.

The following InformationLevels may be set:

The two levels below 0x101 are as described in the NT_SET_PATH_INFORMATION transaction. The requested information is placed in the Data portion of the transaction response. For the information levels greater than 0x100, the transaction response has 1 parameter word that should be ignored by the client.

4.2.17.1 SMB_FILE_DISPOSITION_INFO

4.2.17.2 SMB_FILE_ALLOCATION_INFO

4.2.17.3 SMB_FILE_END_OF_FILE_INFO

4.3 Directory Requests

4.3.1 TRANS2_CREATE_DIRECTORY: Create Directory (with Optional EAs)

This requests the server to create a directory relative to Tid in the SMB header, optionally assigning extended attributes to it.

4.3.2 DELETE_DIRECTORY: Delete Directory

The delete directory message is sent to delete an empty directory. The appropriate Tid and additional pathname are passed. The directory must be empty for it to be deleted.

The directory to be deleted cannot be the root of the share specified by Tid.

4.3.3 CHECK_DIRECTORY: Check Directory

This SMB is used to verify that a path exists and is a directory. No error is returned if the given path exists and the client has read access to it. Client machines that maintain a concept of a "working directory" will find this useful to verify the validity of a "change working directory" command.

Note   The servers do not have a concept of working directory for a particular client. The client must always supply full pathnames relative to the Tid in the SMB header.

DOS clients, in particular, depend on the SMB_ERR_BAD_PATH return code if the directory is not found.

4.3.3.1 Errors

ERRDOS/ERRbadfile
ERRDOS/ERRbadpath
ERRDOS/ERRnoaccess
ERRHRD/ERRdata
ERRSRV/ERRinvid
ERRSRV/ERRbaduid
ERRSRV/ERRaccess

4.3.4 TRANS2_FIND_FIRST2: Search Directory Using Wildcards

This request allows the client to search for the file(s) that match the file specification. The search can be continued if necessary with TRANS2_FIND_NEXT2. Numerous levels of information may be obtained for the returned files; the desired level is specified in the InformationLevel field of the request.

The following sections detail the data returned for each InformationLevel. The requested information is placed in the Data portion of the transaction response.

Note   A client that does not support long names can only request SMB_INFO_STANDARD.

A four-byte resume key precedes each data item (described below) if bit 2 in the Flags field is set, i.e., if the request indicates the server should return resume keys.

4.3.4.1 SMB_INFO_STANDARD

4.3.4.2 SMB_INFO_QUERY_EA_SIZE

4.3.4.3 SMB_INFO_QUERY_EAS_FROM_LIST

This request returns the same information as SMB_INFO_QUERY_EA_SIZE, but only for files that have an extended attributes (EA) list that matches the EA information in the Data part of the request.

4.3.4.4 SMB_FIND_FILE_DIRECTORY_INFO

4.3.4.5 SMB_FIND_FILE_FULL_DIRECTORY_INFO

4.3.4.6 SMB_FIND_FILE_BOTH_DIRECTORY_INFO

4.3.4.7 SMB_FIND_FILE_NAMES_INFO

4.3.5 TRANS2_FIND_NEXT2: Resume Directory Search Using Wildcards

This request resumes a search that was begun with a previous TRANS2_FIND_FIRST2 request.

Sid is the value returned by a previous successful TRANS2_FIND_FIRST2 call. If Bit3 of Flags is set, then FileName may be the NULL string, because the search is continued from the previous TRANS2_FIND request. Otherwise, FileName must not be more than 256 characters long.

4.3.6 FIND_CLOSE2: Close Directory Search

This SMB closes a search started by the TRANS2_FIND_FIRST2 transaction request.

4.3.6.1 Errors

ERRDOS/ERRbadfid
ERRSRV/ERRinvid
ERRSRV/ERRaccess

4.3.7 NT_TRANSACT_NOTIFY_CHANGE: Request Change Notification

This command notifies the client when the directory specified by Fid is modified. It also returns the name(s) of the file(s) that changed. The command completes once the directory has been modified based on the supplied CompletionFilter. The command is a "single shot" and therefore needs to be reissued to watch for more directory changes.

A directory file must be opened before this command may be used. Once the directory is open, this command may be used to begin watching files and subdirectories in the specified directory for changes. The first time the command is issued, the MaxParameterCount field in the transact header determines the size of the buffer that will be used at the server to buffer directory change information between issuances of the notify change commands.

When a change in the CompletionFilter is made to the directory, the command completes. The names of the files that have changed since the last time the command was issued are returned to the client. The ParameterCount field of the response indicates the number of bytes that are being returned. If too many files have changed since the last time the command was issued, then zero bytes are returned, and an alternate status code is returned in the Status field of the response.

The CompletionFilter is a mask created as the sum of any of the following flags:

The response contains FILE_NOTIFY_INFORMATION structures, as defined below. The NextEntryOffset field of the structure specifies the offset, in bytes, from the start of the current entry to the next entry in the list. If this is the last entry in the list, this field is zero. Each entry in the list must be longword aligned, so NextEntryOffset must be a multiple of four.

typedef struct {
    ULONG NextEntryOffset;
    ULONG Action;
    ULONG FileNameLength;
    WCHAR FileName[1];
} FILE_NOTIFY_INFORMATION;

Where Action describes what happened to the file named FileName:

4.4 Dfs Operations

4.4.1 TRANS2_GET_DFS_REFERRAL: Retrieve Distributed File System Referral

The client sends this request to ask the server to convert RequestFilename into an alternate name for this file. This request can be sent to the server if the server response to the NEGOTIATE SMB included the CAP_DFS capability. The TID of the request must be IPC$. Bit15 of Flags2 in the SMB header must be set, indicating this is a UNICODE request.

The server response is a list of Referrals that inform the client where it should resubmit the request to obtain access to the file. PathConsumed in the response indicates to the client how many characters of RequestFilename have been consumed by the server. When the client chooses one of the referrals to use for file access, the client may need to strip the leading PathConsumed characters from the front of RequestFileName before submitting the name to the target server. Whether or not the pathname should be trimmed is indicated by the individual referral as detailed below.

Flags indicates how this referral should be treated. If bit0 is clear, any entity in the Referrals list holds the storage for RequestFileName. If bit0 is set, any entity in the Referrals list has further referral information for RequestFilename—a TRANS2_GET_DFS_REFERRAL request should be sent to an entity in the Referrals list for further resolution.

The format of an individual referral contains version and length information allowing the client to skip referrals it does not understand. MaxReferralLevel indicates to the server the latest version of referral that the client can digest. Since each referral has a uniform element, MaxReferralLevel is advisory only. Each element in Referrals has this envelope:

The following referral element versions are defined:

The CIFS protocol imposes no referral selection policy.

4.4.2 TRANS2_REPORT_DFS_INCONSISTENCY: Inform a Server about Dfs Error

As part of the Distributed Name Resolution algorithm, a Dfs client may discover a knowledge inconsistency between the referral server (i.e., the server that handed out a referral), and the storage server (i.e., the server to which the client was redirected to by the referral server). When such an inconsistency is discovered, the Dfs client optionally sends this SMB to the referral server, allowing the referral server to take corrective action.

The data part of this request contains the referral element (Version 1 format only) believed to be in error. These are encoded as described in the TRANS2_GET_DFS_REFERRAL response. If the server returns success, the client can resubmit the TRANS2_GET_DFS_REFERRAL request to this server to get a new referral. It is not mandatory for the Dfs knowledge to be automatically repaired—the client must be prepared to receive further errant referrals and must not wind up looping between this request and the TRANS2_GET_DFS_REFERRAL request.

Bit15 of Flags2 in the SMB header must be set, indicating that this is a UNICODE request.

4.5 Miscellaneous Operations

4.5.1 NT_TRANSACT_IOCTL

This command allows device and file system control functions to be transferred transparently from client to server.

4.5.2 NT_TRANSACT_QUERY_SECURITY_DESC

This command allows the client to retrieve the security descriptor on a file.

NtQuerySecurityObject() is called, requesting SecurityInformation. The result of the call is returned to the client in the Data part of the transaction response.

4.5.3 NT_TRANSACT_SET_SECURITY_DESC

This command allows the client to change the security descriptor on a file.

Data is passed directly to NtSetSecurityObject(), with SecurityInformation describing which information to set. The transaction response contains no parameters or data.