cmsfs-fuse - Mount a z/VM CMS file system

6.10 z/VM guest

Use the cmsfs-fuse command to mount the enhanced disk format (EDF) file system on a z/VM® minidisk.

In Linux®, the minidisk is represented as a DASD and the file system is mounted as a cmsfs-fuse file system. The cmsfs-fuse file system translates the record-based file system on the minidisk into Linux semantics.

Through the cmsfs-fuse file system, the files on the minidisk become available to applications on Linux. Applications can read from and write to files on minidisks. Optionally, the cmsfs-fuse file system converts text files between EBCDIC on the minidisk and ASCII within Linux.

Attention: You can inadvertently damage files and lose data when directly writing to files within the cmsfs-fuse file system. To avoid problems when you write, multiple restrictions must be observed, especially regarding linefeeds (see restrictions for write).

Tip: If you are unsure about how to safely write to a file on the cmsfs-fuse file system, copy the file to a location outside the cmsfs-fuse file system, edit the file, and then copy it back to its original location.

Use fusermount to unmount file systems that you mounted with cmsfs-fuse. See the fusermount man page for details.

Before you begin:

You need a kernel that was built with the common code option CONFIG_FUSE_FS to include FUSE support.
FUSE support must be compiled into the kernel or the fuse module must be loaded, for example, with modprobe fuse.
The FUSE library must be installed on your system. If the library is not included in your distribution, you can obtain it from sourceforge at sourceforge.net/projects/fuse.
The DASD must be online.
Depending whether you intend to read, write, or both, you must have the appropriate permissions for the device node.

cmsfs-fuse syntax

where:

-a or --ascii

treats all files on the minidisk as text files and converts them from EBCDIC to ASCII.

-t or --filetype

treats files with extensions as listed in the cmsfs-fuse configuration file as text files and converts them from EBCDIC to ASCII.

By default, the cmsfs-fuse command uses /etc/cmsfs-fuse/filetypes.conf as the configuration file. You can replace the list in this default file by creating a file .cmsfs-fuse/filetypes.conf in your home directory.

The filetypes.conf file lists one file type per line. Lines that start with a number sign (#) followed by a space are treated as comments and are ignored.

--from <code-page>

specifies the encoding of the files on the z/VM minidisk. If this option is not specified, code page CP1047 is used. Enter iconv --list to display a list of all available code pages.

--to <code-page>

specifies the encoding to which the files on the z/VM minidisk are converted in Linux. If this option is not specified, code page ISO-8859-1 is used. Enter iconv --list to display a list of all available code pages.

<mount-options>

options as available for the mount command. See the mount man page for details.

<fuse-options>

options for FUSE. The following options are supported by the cmsfs-fuse command. To use an option, it must also be supported by the version of FUSE that you have.

-d or -o debug: enables debug output (implies -f).
-f: runs the command as a foreground operation.
-o allow_other: allows access to other users.
-o allow_root: allows access to root.
-o default_permissions: enables permission checking by the kernel.
-o max_read=<n>: sets maximum size of read requests.
-o kernel_cache: caches files in the kernel.
-o [no]auto_cache: enables or disables caching based on modification times.
-o umask=<mask>: sets file permissions (octal).
-o uid=<n>: sets the file owner.
-o gid=<n>: sets the file group.
-o max_write=<n>: sets the maximum size of write requests.
-o max_readahead=<n>: sets the maximum readahead value.
-o async_read: performs reads asynchronously (default).
-o sync_read: performs reads synchronously.
-o big_writes: enables write operations with more than 4 KB.

<node>

the device node for the DASD that represents the minidisk in Linux.

<mount-point>

the mount point in the Linux file system where you want to mount the CMS file system.

-h or --help

displays help information for the command. To view the man page, enter man cmsfs-fuse.

-v or --version

displays version information for the command.

Extended attributes

You can use the following extended attributes to handle the CMS characteristics of a file:

user.record_format: specifies the format of the file. The format is F for fixed record length files and V for variable record length files. This attribute can be set only for empty files. The default file format for new files is V.
user.record_lrecl: specifies the record length of the file. This attribute can be set only for an empty fixed record length file. A valid record length is an integer in the range 1-65535.
user.file_mode: specifies the CMS file mode of the file. The file mode consists of a mode letter from A-Z and mode number from 0 - 6. The default file mode for new files is A1.

You can use the following system calls to work with extended attributes:

listxattr: to list the current values of all extended attributes.
getxattr: to read the current value of a particular extended attribute.
setxattr: to set a particular extended attribute.

You can use these system calls through the getfattr and setfattr commands. For more information, see the man pages of these commands and of the listxattr, getxattr, and setxattr system calls.

Restrictions

When you work with files in the cmsfs-fuse file system, restrictions apply for the following system calls:

write

Be aware of the following restrictions when you write to a file on the cmsfs-fuse file system:

Write location

Writing is supported only at the end of a file.

Padding

For fixed-length record files, the last record is padded to make up a full record length. The padding character is zero in binary mode and the space character in ASCII mode.

Sparse files

Sparse files are not supported. To prevent the cp tool from writing in sparse mode, specify -sparse=never.

Records and linefeeds with ASCII conversion (-a and -t)

In the ASCII representation of an EBCDIC file, a linefeed character determines the end of a record. Follow these rules about linefeed characters requirements when you write to EBCDIC files in ASCII mode:

For fixed record length files: Use linefeed characters to separate character strings of the fixed record length.
For variable record length files: Use linefeed characters to separate character strings. The character strings must not exceed the maximum record length.

The CMS file system does not support empty records. cmsfs-fuse adds a space to records that consist of a linefeed character only.

rename and creat

Uppercase file names are enforced.

truncate

Only shrinking of a file is supported. For fixed-length record files, the new file size must be a multiple of the record length.

Examples

To mount the CMS file system on the minidisk represented by the file node /dev/dasde at /mnt:
```
# cmsfs-fuse /dev/dasde /mnt
```
To mount the CMS file system on the minidisk represented by the file node /dev/dasde at /mnt and enable EBCDIC to ASCII conversion for text files with extensions as specified in ~/.cmsfs-fuse/filetypes.conf or /etc/cmsfs-fuse/filetypes.conf if the former does not exist:
```
# cmsfs-fuse -t /dev/dasde /mnt
```
To mount the CMS file system on the minidisk represented by the file node /dev/dasde at /mnt and allow root to access the mounted file system:
```
# cmsfs-fuse -o allow_root /dev/dasde /mnt
```
To unmount the CMS file system that was mounted at /mnt:
```
# fusermount -u /mnt
```
To show the record format of a file, PROFILE.EXEC, on a z/VM minidisk that is mounted on /mnt:
```
# getfattr -n user.record_format /mnt/PROFILE.EXEC
F
```
To set record length 80 for an empty fixed record format file, PROFILE.EXEC, on a z/VM minidisk that is mounted on /mnt:
```
# setfattr -n user.record_lrecl -v 80 /mnt/PROFILE.EXEC
```