3.2.4.6 Application Requests to Create or Overwrite a File

To create or overwrite a file on a remote share, the application provides the following:

• The Client.TreeConnect representing the share within which to create the file.

• The pathname of the file being created, relative to Client.TreeConnect.ShareName.

• The Client.Session representing the security context of the user opening the file.

• The requested access mode (read, write, and so on).

• An optional Boolean indicating whether the attributes and time stamps of the file are to be returned in the response.

• An optional Boolean indicating whether the total length of the file's extended attributes is to be returned in the response.

• The share access for the created file.

• The create disposition for the open.

• An optional set of create options for the open.

• An optional list of extended attributes.

• An optional list of search attributes.

• The request for an exclusive or batch OpLock, if any.

• A Boolean indicating whether or not the file attribute data is to be returned in the response.

• A Boolean indicating whether or not the parent directory of the target is to be opened.

• An optional requested level of impersonation.

• The security flags.

• An optional allocation size.

• An optional timeout value.

• An optional security descriptor.

• The print file mode Boolean.

To create the file, the client MUST issue one of the following command requests:

• SMB_COM_CREATE (section 2.2.4.4) (deprecated)

  The client MUST construct an SMB_COM_CREATE Request (section 2.2.4.4.1) message as defined in section 2.2.4.4. This command provides basic Create semantics.

• SMB_COM_CREATE_TEMPORARY (section 2.2.4.15) (obsolescent)

  This command is used to create a temporary file on the server. The client MUST construct an SMB_COM_CREATE_TEMPORARY Request (section 2.2.4.15.1) message.

• SMB_COM_CREATE_NEW (section 2.2.4.16) (deprecated)

  This command is used to create a new file and MUST fail if the specified file already exists. The client MUST construct an SMB_COM_CREATE_NEW Request (section 2.2.4.16.1) message as defined in section 2.2.4.16.

• SMB_COM_OPEN_PRINT_FILE (section 2.2.4.67)

  This command is used to create a new print spool file. The application provides opaque printer-specific control data that is to be included as the first part of the spool file. The client MUST construct an SMB_COM_OPEN_PRINT_FILE Request (section 2.2.4.67.1) message as defined in 2.2.4.67.

• SMB_COM_OPEN_ANDX (section 2.2.4.41) (deprecated)

  The client MUST construct an SMB_COM_OPEN_ANDX Request (section 2.2.4.41.1) message as defined in section 2.2.4.41. If the application-provided Boolean value indicates the file attribute data to be returned in the response, the client MUST set REQ_ATTRIB flag in the SMB_Parameters.Flags field. In addition to basic Create semantics, SMB_COM_OPEN_ANDX provides:

  • AndX chaining.

  • The ability to set the file attributes when the file is created.

  • The ability to set the creation time of the file.

  • The disposition action to take based on the existence of the target file.

• TRANS2_OPEN2 (section 2.2.6.1)

  The client MUST construct an SMB_COM_TRANSACTION2 (section 2.2.4.46) transaction request, as defined in section 2.2.4.46, to transport the TRANS2_OPEN2 transaction request. The client MUST construct a TRANS2_OPEN2 Request (section 2.2.6.1.1) as defined in section 2.2.6.1. If the application-provided Boolean value indicates the file attribute data to be returned in the response, the client MUST set REQ_ATTRIB flag in the SMB_Parameters.Flags field. In addition to basic Create semantics, TRANS2_OPEN2 provides:

  • The ability to set extended attribute (EA) name/value pairs.

  • The ability to set or reset the creation time of the file.

  • The ability to specify an initial allocation for newly created or overwritten files.

  • The disposition action to take based on the existence of the target file.

• NT_TRANSACT_CREATE (section 2.2.7.1)

  The client MUST construct an SMB_COM_NT_TRANSACT (section 2.2.4.62) transaction request, as defined in section 2.2.4.62 to transport the NT_TRANSACT_CREATE transaction request. The client MUST construct an NT_TRANSACT_CREATE Request (section 2.2.7.1.1) as defined in section 2.2.7.1. In addition to basic Open semantics, NT_TRANSACT_CREATE provides:

  • The ability to specify a path relative to a subdirectory within the share indicated by the TID.

  • The ability to specify an initial allocation for newly opened or overwritten files.

  • The disposition action to take based on the existence of the target file.

• SMB_COM_NT_CREATE_ANDX (section 2.2.4.64)

  The client MUST construct an SMB_COM_NT_CREATE_ANDX Request (section 2.2.4.64.1) message as defined in section 2.2.4.64. In addition to basic Open semantics, SMB_COM_NT_CREATE_ANDX provides:

  • AndX chaining.

  • The ability to create a directory.

  • The ability to specify a path relative to a subdirectory within the share indicated by the TID.

  • The ability to specify an initial allocation for newly opened or overwritten files.

  • The disposition action to take based on the existence of the target file.

    The SMB_COM_NT_CREATE_ANDX is the most comprehensive (and, therefore, the most complex) of the Create commands.

When opening a named pipe, the SMB_COM_NT_CREATE_ANDX command requires that the FileName field MUST contain only the relative name of the pipe; that is, the "\PIPE\" prefix MUST NOT be present. This is in contrast with other commands, such as SMB_COM_OPEN_ANDX and TRANS2_OPEN2, which require that the "\PIPE\" prefix be present in the path name.

Any of the commands or subcommands listed in this section can be used to create a file. Directories can also be created. Most of these commands provide the option to open or overwrite a file if it already exists. For SMB_COM_OPEN_ANDX (section 2.2.4.41) and TRANS2_OPEN2 (section 2.2.6.1) commands, the client MUST construct the AccessMode field of the request by translating the input parameters as specified in section 3.2.4.5.

In early dialects of the SMB Protocol the Open and Create operations were somewhat separate. In CIFS, there is considerable overlap between the set of commands used to open an existing file, the commands used to overwrite an existing file, and those used to create a new file.

The request MUST be sent to the server as described in section 3.2.4.1.