2.2.2.2.1 Symbolic Link Error Response

The Symbolic Link Error Response is used to indicate that a symbolic link was encountered on create; it describes the target path that the client MUST use if it requires to follow the symbolic link. This structure is contained in the ErrorData section of the SMB2 ERROR Response (section 2.2.2). This structure MUST NOT be returned in an SMB2 ERROR Response unless the Status code in the header of that response is set to STATUS_STOPPED_ON_SYMLINK.<5> The structure has the following format.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

SymLinkLength

SymLinkErrorTag

ReparseTag

ReparseDataLength

UnparsedPathLength

SubstituteNameOffset

SubstituteNameLength

PrintNameOffset

PrintNameLength

Flags

PathBuffer (variable)

...

SymLinkLength (4 bytes): The length, in bytes, of the response including the variable-length portion and excluding SymLinkLength.

SymLinkErrorTag (4 bytes): The server MUST set this field to 0x4C4D5953.

ReparseTag (4 bytes): The type of link encountered. The server MUST set this field to 0xA000000C.

ReparseDataLength (2 bytes): The length, in bytes, of the variable-length portion of the symbolic link error response plus the size of the static portion, not including SymLinkLength, SymLinkErrorTag, ReparseTag, ReparseDataLength, and UnparsedPathLength. The server MUST set this to the size of PathBuffer[], in bytes, plus 12. (12 is the size of SubstituteNameOffset, SubstituteNameLength, PrintNameOffset, PrintNameLength, and Flags.)

UnparsedPathLength (2 bytes): The length, in bytes, of the unparsed portion of the path. The unparsed portion is the remaining part of the path after the symbolic link. See section 2.2.2.2.1.1 for examples.

SubstituteNameOffset (2 bytes): The offset, in bytes, from the beginning of the PathBuffer field, at which the substitute name is located. The substitute name is the name the client MUST use to access this file if it requires to follow the symbolic link.

SubstituteNameLength (2 bytes): The length, in bytes, of the substitute name string. If there is a terminating null character at the end of the string, it is not included in the SubstituteNameLength count. This value MUST be greater than or equal to 0.

PrintNameOffset (2 bytes): The offset, in bytes, from the beginning of the PathBuffer field, at which the print name is located. The print name is the user-friendly name the client MUST return to the application if it requests the name of the symbolic link target.

PrintNameLength (2 bytes): The length, in bytes, of the print name string. If there is a terminating null character at the end of the string, it is not included in the PrintNameLength count. This value MUST be greater than or equal to 0.

Flags (4 bytes): A 32-bit bit field that specifies whether the substitute is an absolute target path name or a path name relative to the directory containing the symbolic link.

This field contains one of the values in the table below.

Value

Meaning

0x00000000

The substitute name is an absolute target path name.

SYMLINK_FLAG_RELATIVE

0x00000001

When this Flags value is set, the substitute name is a path name relative to the directory containing the symbolic link.

PathBuffer (variable): A buffer that contains the Unicode strings for the substitute name and the print name, as described by SubstituteNameOffset, SubstituteNameLength, PrintNameOffset, and PrintNameLength. The substitute name string MUST be a Unicode path to the target of the symbolic link. The print name string MUST be a Unicode string, suitable for display to a user, that also identifies the target of the symbolic link.

  • For an absolute target that is on a remote machine, the server MUST return the path in the format "\??\UNC\server\share\..." where server is replaced by the target server name, share is replaced by the target share name, and ... is replaced by the remainder of the path to the target.

  • The server SHOULD NOT return symbolic link information with an absolute target that is a local resource, because local evaluation will vary based on client operating system (OS).<6>

  • For a relative target, the server MUST return a path that does not start with "\". The path MUST be evaluated, by the calling application, relative to the directory containing the symbolic link. The path can contain either "." to refer to the current directory or ".." to refer to the parent directory, and could contain multiple elements.

For more information on absolute and relative targets, see Handling the Symbolic Link Error Response (section 2.2.2.2.1.1).