8.4 Name Mangling and Case

Back in the days of DOS and Windows 3.1, every filename was limited to eight uppercase characters, followed by a dot, and three more uppercase characters . This was known as the 8.3 format and was a huge nuisance. Windows 95/98/Me, Windows NT/2000/XP, and Unix have since relaxed this problem by allowing longer, sometimes case-sensitive, filenames. Table 8-4 shows the current naming state of several popular operating systems.

Table 8-4. Operating system filename limitations

Operating system	File-naming rules
DOS 6.22 or below	Eight characters followed by a dot followed by a three-letter extension (8.3 format); case-insensitive
Windows 3.1 for Workgroups	Eight characters followed by a dot followed by a three-letter extension (8.3 format); case-insensitive
Windows 95/98/Me	255 characters; case-insensitive but case- preserving
Windows NT/2000/XP	255 characters; case-insensitive but case-preserving
Unix	255 characters; case-sensitive

Samba still has to remain backward-compatible with network clients that store files in just the 8.3 format, such as Windows for Workgroups. If a user creates a file on a share called antidisestablishmentarianism.txt , a Windows for Workgroups client cannot tell it apart from another file in the same directory called antidisease.txt . Like Windows 95/98/Me and Windows NT/2000/XP, Samba has to employ a special method for translating a long filename to an 8.3 filename in such a way that similar filenames will not cause collisions. This is called name mangling , and Samba deals with this in a manner that is similar, but not identical to, Windows 95 and its successors.

8.4.1 The Samba Mangling Operation

Here is how Samba mangles a long filename into an 8.3 filename:

If the original filename does not begin with a dot, the first five characters before the dot (if there is one) are converted to uppercase. These characters are used as the first five characters of the 8.3 mangled filename.
If the original filename begins with a dot, the dot is removed and then the previous step is performed on what is left.
These characters are immediately followed by a special mangling character: by default, a tilde (~), although Samba allows you to change this character.
The base of the long filename before the last period is hashed into a two-character code; parts of the name after the last dot can be used if necessary. This two-character code is appended to the filename after the mangling character.
The first three characters after the last dot (if there is one) of the original filename are converted to uppercase and appended onto the mangled name as the extension. If the original filename began with a dot, three underscores ( _ _ _ ) are used as the extension instead.

Here are some examples:

 virtuosity.dat                       VIRTU~F1.DAT .htaccess                            HTACC~U0._ _ _ hello.java                           HELLO~1F.JAV team.config.txt                      TEAMC~04.TXT antidisestablishmentarianism.txt     ANTID~E3.TXT antidisease.txt                      ANTID~9K.TXT

Using these rules will allow Windows for Workgroups to differentiate the two files on behalf of the poor individual who is forced to see the network through the eyes of that operating system. Note that the same long filename should always hash to the same mangled name with Samba; this doesn't always happen with Windows. The downside of this approach is that there can still be collisions; however, the chances are greatly reduced.

You generally want to use the mangling configuration options with only the oldest clients. We recommend doing this without disrupting other clients by adding an include directive to the smb.conf file:

 [global]     include = /usr/local/samba/lib/smb.conf.%a

This resolves to smb.conf.WfWg when a Windows for Workgroups client attaches. Now you can create a file /usr/local/samba/lib/smb.conf.WfWg , which might contain these options:

 [global]     case sensitive = no     default case = upper     preserve case = no     short preserve case = no     mangle case = yes     mangled names= yes

If you are not using Windows for Workgroups, you probably do not need to change any of these options from their defaults.

8.4.1.1 Representing and resolving filenames with Samba

Another item that we should point out is that there is a difference between how an operating system represents a file and how it resolves it. For example, you have likely run across a file on a Windows system called README.TXT . The file can be represented by the operating system entirely in uppercase letters . However, if you open an MS-DOS command prompt and enter the command:

 C:\>  notepad readme.txt

the all-caps file is loaded into the editing program, even though you typed the name in lowercase letters.

This is because the Windows 95/98/Me and Windows NT/2000/XP families of operating systems resolve filenames in a case-insensitive manner, even though the files are represented in a case-sensitive manner. Unix-based operating systems, on the other hand, always resolve files in a case-sensitive manner; if you try to edit README.TXT with the command:

 $  vi readme.txt

you will likely be editing the empty buffer of a new file.

Here is how Samba handles case: if the preserve case is set to yes , Samba will always use the case provided by the operating system for representing (not resolving) filenames. If it is set to no , it will use the case specified by the default case option. The same is true for short preserve case . If this option is set to yes , Samba will use the default case of the operating system for representing 8.3 filenames; otherwise , it will use the case specified by the default case option. Finally, Samba will always resolve filenames in its shares based on the value of the case sensitive option.

8.4.2 Mangling Options

Samba allows more refined instructions on how it should perform name mangling, including those controlling the case sensitivity, the character inserted to form a mangled name, and the ability to map filenames manually from one format to another. These options are shown in Table 8-5.

Table 8-5. Name-mangling options

Option	Parameters	Function	Default	Scope
`case sensitive` `(casesignames)`	Boolean	If `yes` , treats filenames as case-sensitive (Windows doesn't).	`no`	Share
`default case`	string ( `upper` or `lower` )	Case to assume as default (used only when preserve case is `no` ).	Lower	Share
`preserve case`	Boolean	If `yes` , keep the case the client supplied (i.e., do not convert to `default` `case` ).	`yes`	Share
`short preserve case`	Boolean	If `yes` , preserve case of 8.3-format names that the client provides.	`yes`	Share
`mangled names`	Boolean	Mangles long names into 8.3 DOS format.	`yes`	Share
`mangle case`	Boolean	Mangle a name if it is mixed case.	`no`	Share
`mangling char`	string (single character)	Gives mangling character.	`~`	Share
`mangled stack`	numeric	Number of mangled names to keep on the local mangling stack.	`50`	Global
`mangled map`	string (list of patterns)	Allows mapping of filenames from one format into another.	None	Share

8.4.2.1 case sensitive

This share-level option, which has the obtuse synonym casesignames , specifies whether Samba should preserve case when resolving filenames in a specific share. The default value for this option is no , which is how Windows handles file resolution. If clients are using an operating system that takes advantage of case-sensitive filenames, you can set this configuration option to yes as shown here:

 [accounting]     case sensitive = yes

Otherwise, we recommend that you leave this option set to its default.

8.4.2.2 default case

The default case option is used with preserve case . This specifies the default case (upper or lower) Samba uses to create a file on one of its shares on behalf of a client. The default case is lower , which means that newly created files will have lowercase names. If you need to, you can override this global option by specifying the following:

 [global]     default case = upper

If you specify this value, the names of newly created files are translated into uppercase and cannot be overridden in a program. We recommend that you use the default value unless you are dealing with a Windows for Workgroups or other 8.3 client, in which case it should be upper .

8.4.2.3 preserve case

This option specifies whether a file created by Samba on behalf of the client is created with the case provided by the client operating system or the case specified by the earlier default case configuration option. The default value is yes , which uses the case provided by the client operating system. If it is set to no , the value of the default case option (upper or lower) is used.

Note that this option does not handle 8.3 file requests sent from the client ”see the upcoming short preserve case option. You might want to set this option to yes , for example, if applications that create files on the Samba server demand the file be all uppercase. If instead you want Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, yes .

8.4.2.4 short preserve case

This option specifies whether an 8.3 filename created by Samba on behalf of the client is created with the default case of the client operating system or the case specified by the default case configuration option. The default value is yes , which uses the case provided by the client operating system. You can let Samba choose the case through the default case option by setting it as follows :

 [global]     short preserve case = no

If you want to force Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, yes .

8.4.2.5 mangled names

This share-level option specifies whether Samba will mangle filenames for 8.3 clients. If the option is set to no , Samba will not mangle the names, and (depending on the client) they will either be invisible or appear truncated to those using 8.3 operating systems. The default value is yes . You can override it per share as follows:

 [data]     mangled names = no

8.4.2.6 mangle case

This option tells Samba whether it should mangle filenames that are not composed entirely of the case specified using the default case configuration option. The default for this option is no . If you set it to yes , you should be sure that all clients can handle the mangled filenames that result. You can override it per share as follows:

 [data]     mangle case = yes

We recommend that you leave this option alone unless you have a well-justified need to change it.

8.4.2.7 mangling char

This share-level option specifies the mangling character used when Samba mangles filenames into the 8.3 format. The default character used is a tilde (~). You can reset it to whatever character you wish. For instance:

 [data]     mangling char = #

8.4.2.8 mangled stack

Samba maintains a local stack of recently mangled 8.3 filenames; this stack can be used to reverse-map mangled filenames back to their original state. This is often needed by applications that create and save a file, close it, and need to modify it later. The default number of long filename/mangled filename pairs stored on this stack is 50. However, if you want to cut down on the amount of processor time used to mangle filenames, you can increase the size of the stack to whatever you wish, at the expense of memory and slightly slower file access:

 [global]     mangled stack = 100

8.4.2.9 mangled map

If the default behavior of name mangling is not sufficient, you can give Samba further instructions on how to behave using the mangled map option. This option allows you to specify mapping patterns that can be used in place of name mangling performed by Samba. For example:

 [data]     mangled map =(*.database *.db) (*.class *.cls)

Here, Samba is instructed to search each encountered file for characters that match the first pattern specified in the parenthesis and convert them to the modified second pattern in the parenthesis for display on an 8.3 client. This is useful in the event that name mangling converts the filename incorrectly or converts it to a format that the client cannot understand readily. Patterns are separated by whitespaces.