Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
KICONVTOOL(8)		  BSD System Manager's Manual		 KICONVTOOL(8)

     kiconvtool	-- load	kernel iconv charset tables

     kiconvtool	[-hvmd]	[-l local ...] [-f foreign ...]	[-p pair ...]

     On	FreeBSD, it's possible to allow	unprivileged users to mount file sys-
     tems without using	su or sudo. This can be	enabled	with vfs.usermount
     sysctl. However, if file name conversion is used when mounting a file
     system, in	most cases mount will fail with	e.g. `mount_msdosfs: ms-
     dosfs_iconv: Operation not	permitted' error. This is caused by the	fact
     that mount	needs to load character	set tables into	kernel for file	name
     conversion	to work, but this operation can't be allowed to	unprivileged
     users because it's	possible to waste lots of kernel memory	filling	it
     with many charset tables, which may lead to DoS.

     kiconvtool	utility	allows you to preload specific charset tables into
     kernel, so	you can	allow unprivileged users to mount file systems with
     file name conversion, but still control amount of memory taken by conver-
     sion tables.

     The options are as	follows:

     -h		Display	short help.

     -v		Turn on	verbose	output.

     -m		Display	amount of memory used by tables	already	loaded into
		kernel.	This is	similar	to `vmstat -m |	grep iconv_data'.

     -d		Display	list of	currently loaded charset conversion tables.

     -l	charset
		Specify	local charset(s). Usually locale(s) of user(s) who
		will mount file	systems.

     -f	charset
		Specify	foreign	charset(s). These are charset(s) used inside
		file systems to	store file names. Note that you	don't need to
		specify	UTF-16BE as it's always	assumed.

     -p	pair	Specify	charset	pair(s). Each pair consists of local charset
		and foreign charset, separated by colon.

     To	load needed charset conversion tables, you should specify one or more
     local-foreign charset pairs. You can do it	in two ways:

	   +o   Explicitly specify needed pairs with -p flag. For example:

		     kiconvtool	-p KOI8-R:CP866	KOI8-R:CP1251

	   +o   Specify all required local charsets with	-l flag	and all	re-
	       quired foreign charsets with -f flag. For example:

		     kiconvtool	-l KOI8-R -f CP866 CP1251

     You can combine those two ways (first, pairs are formed from all possible
     combinations of provided local/foreign charsets, then explicitly defined
     pairs are added).

     To	know which character sets you need for your media, first mount it un-
     der root user, then use the following command:

	   kiconvtool -d

     to	get list of charset tables loaded after	your mounts. Note, that	for
     each charset pair (LOCAL, FOREIGN), there will be two conversions (LOCAL
     ->	FOREIGN	and FOREIGN -> LOCAL).

     Don't forget, that	you need iconv library and iconv support for specific
     file system(s) to either be compiled into kernel or loaded	as modules.
     Thus, for msdosfs you either need


     in	your /boot/loader.conf or

	   options   LIBICONV
	   options   MSDOSFS_ICONV

     in	your kernel config. Alternatively, rc.d	script provided	with kicon-
     vtool can load required modules for you (see below).

     1)	My locale is ru_RU.KOI8-R, and I want to mount FAT32 with Russian file
     names from	my USB flash drive with	the following command:

	   mount_msdosfs -L ru_RU.KOI8-R -D CP866 /dev/da0s1 ~/mnt/flash

     In	my case, msdosfs uses both CP866 for 8.3 legacy	file names and
     UTF-16BE for Win95	long names. So to be able to execute the mount command
     above as unprivileged user, I need	to run this as root first (note	that
     UTF-16BE doesn't need to be specified):

	   kiconvtool -l KOI8-R	-f CP866

     2)	The same thing,	but for	mounting CD-ROM. I want	to run this as a user:

	   mount_cd9660	-C KOI8-R /dev/acd0 ~/mnt/cdrom

     ISO9660 only uses UTF-16BE	internally, so I only need to specify local

	   kiconvtool -l KOI8-R

     You only need to call kiconvtool once to load charset tables - after
     that, mounting will work until reboot.  For convenience, you can use rcNG
     script provided with kiconvtool to	load charset conversion	tables on sys-
     tem startup.  Just	add the	following lines	to /etc/rc.conf:

	   # enable kiconv script

	   # specify local/foreign encodings (all 4 ways demonstrated here load	the same set):
	   kiconv_local_charsets="KOI8-R UTF-8"
	   # or
	   kiconv_charset_pairs="UTF-8:CP866 KOI8-R:CP866"
	   # or	(you may specify kiconvtool flags directly)
	   kiconv_flags="-l KOI8-R UTF-8 -f CP866"
	   # or
	   kiconv_flags="-p UTF-8:CP866	KOI8-R:CP866"

	   # script also offers	a convenient way to load required kernel iconv modules
	   kiconv_fstypes="msdosfs cd9660"

     mount_cd9660(8), mount_msdosfs(8),	mount_smbfs(8),	mount_udf(8),

     Dmitry Marakasov <>

     The main bug is not in kiconvtool itself, but in kernel iconv implementa-
     tion: charset names are case sensitive. So	if you're using	KOI8-R for
     mounting, you should use KOI8-R (not koi8-r or Koi8-R) in kiconvtool as
     well. The best idea is to use uppercase charset names everywhere.

FreeBSD				 May 08, 2018			       FreeBSD


Want to link to this manual page? Use this URL:

home | help