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

FreeBSD Manual Pages

  
 
  

home | help
LIBINOTIFY(3)		    Library Functions Manual		 LIBINOTIFY(3)

NAME
       libinotify,     inotify_init,	 inotify_init1,	    inotify_add_watch,
       inotify_rm_watch,	 libinotify_set_param,		inotify_event,
       libinotify_direct_readv,				libinotify_free_iovec,
       libinotify_direct_close,	-- monitor file	system events

SYNOPSIS
       #include	<sys/inotify.h>

       int
       inotify_init();

       int
       inotify_init1(int flags);

       int
       inotify_add_watch(int fd, const char *pathname, uint32_t	mask);

       int
       inotify_rm_watch(int fd,	int wd);

       int
       libinotify_set_param(int	fd, int	param, intptr_t	value);

       int
       libinotify_direct_readv(int  fd,	 struct	 iovec	**events,  int	 size,
	   int no_block);

       void
       libinotify_free_iovec(struct iovec *events);

       int
       libinotify_direct_close(int fd);

DESCRIPTION
       The  inotify_init() and inotify_init1() functions create	an inotify in-
       stance and  returns  a  file  descriptor	 referring  to	the  instance.
       inotify_init1()	function  is  similar to inotify_init()	except that it
       takes additional	flags parameter	whose values can be:

       IN_NONBLOCK	  Set I_NONBLOCK file status flag on the inotify  file
			  descriptor.

       IN_CLOSEXEC	  Set  FD_CLOEXEC flag on the new file descriptor. See
			  O_CLOEXEC flag in open(2)

       IN_DIRECT	  libinotify-specific flag that	 enables  direct  mode
			  (see below)

       The  function  returns the file descritor to the	inotify	handle if suc-
       cessful otherwise return	-1. Possible errorno values are	-

       EINVAL		  Invalid flag value passed.

       EMFILE		  System wide limit of inotify instances reached.

       ENFILE		  System limit on total	number of fd's reached.

       ENOMEM		  Insufficient kernel memory.

       inotify_add_watch() function adds news watch to the  inotify  instance.
       List  of	 possible  masks  are  described below.	If the watch for given
       filename	already	exists,	it it updated with the new mask	value  passed.
       The  function  returns an integer called	watch descriptor if successful
       otherwise -1.

       Possible	values for errorno are -

       EACCES		  Permission for read access is	denied for given file.

       EBADF		  Invalid file descriptor.

       EFAULT		  Pathname points outside process's allocated  address
			  space.

       EINVAL		  Invalid event	mask passed.

       ENOENT		  A component of path that must	exist does not exist.

       ENOMEM		  Insufficient kernel memory available.

       ENOSPC		  User	limit  on  total number	of inotify watches has
			  crossed or kernel failed to allocate	a  needed  re-
			  source.

       inotify_rm_watch()  function  removes  watch  wd	 from the instance de-
       scribed by file descriptor fd.  The function returns zero on sucess and
       -1 on error. Possible errorno values are	-

       EBADF		  Invalid file descriptor fd.

       EINVAL		  Invalid watch	descriptor wd.

       libinotify_set_param()  Libinotify  specific.  Replacement  for	 Linux
       procfs  interface.  Set inotify parameter for the instance described by
       file descriptor fd.  fd value of	-1 is used for setting of global para-
       meters. Possible	param values are -

       IN_SOCKBUFSIZE	  Size of communication	socket buffer in bytes.	Should
			  match	read(2)	buffer size for	libinotify event  con-
			  sumers.  Lower values	can cause partial event	reads.
			  Bigger  values is just a wasting of memory.  Default
			  value	is arbitrary, has been acquired	from code sam-
			  ple in linux inotify(7) man page  and	 seems	to  be
			  very	common	among  the  inotify  clients.  Default
			  value	4096 (exported as IN_DEF_SOCKBUFSIZE)

       IN_MAX_QUEUED_EVENTS
			  Upper	limit on the queue length per inotify  handle.
			  linux`s /proc/sys/fs/inotify/max_queued_events coun-
			  terpart.    Default	value	16384	(exported   as
			  IN_DEF_MAX_QUEUED_EVENTS)

       IN_MAX_USER_INSTANCES
			  Global upper limit on	 the  number  of  inotify  in-
			  stances    that    can    be	  created.     linux`s
			  /proc/sys/fs/inotify/max_user_instances counterpart.
			  Default    value     2147483646     (exported	    as
			  IN_DEF_MAX_USER_INSTANCES)

inotify_event structure
       struct inotify_event {
	   int	       wd;	 /* Watch descriptor */
	   uint32_t    mask;	 /* Mask of events */
	   uint32_t    cookie;	 /* Unique integer associating related events */
	   uint32_t    len;	 /* Size of name field */
	   char	       name[];	 /* Optional null-terminated name */
       };

inotify	events -
       Following are the masks supported by libinotify implementation.
	     IN_OPEN		 File was opened.
	     IN_ACCESS		 File was accessed (read).
	     IN_ATTRIB		 Metadata changed.
	     IN_CREATE		 File/directory	was created in watched directory.
	     IN_CLOSE_WRITE	 File opened for writing was closed.
	     IN_CLOSE_NOWRITE	 File not opened for writing was closed.
	     IN_DELETE		 File/directory	in watched directory was deleted.
	     IN_DELETE_SELF	 Watched file/directory	was deleted.
	     IN_MODIFY		 File/Directory	was modified.
	     IN_MOVE_SELF	 Watched file/directory	was moved.
	     IN_MOVED_FROM	 A file	in watched directory was moved out.
	     IN_MOVED_TO	 A file	was moved into watched directory.
	     IN_ALL_EVENTS	 Bit mask of all the above events.
	     IN_MOVE		 Equal to IN_MOVED_FROM|IN_MOVED_TO
	     IN_CLOSE		 Equal to IN_CLOSE_WRITE|IN_CLOSE_NOWRITE

       IN_DELETE_SELF  and IN_MOVE_SELF	can occur only for watched file/direc-
       tory.  Other events can be marked for a file/directory in a watched di-
       recotry.	In that	case the name of the file for which event is generated
       can be read by 'name' field in inotify_event structure.

       Following are additional	bits that can be  set  in  mask	 when  calling
       inotify_add_watch() -

       IN_DONT_FOLLOW	  Don't	derefernce path	name if	its symlink.

       IN_EXCL_UNLINK	  Do not generate events for unlinked childrens. (Cur-
			  rently not supported).

       IN_MASK_ADD	  Add event mask for watch for given pathname.

       IN_ONESHOT	  Remove watch after retrieving	one event.

       IN_ONLYDIR	  Only watch the pathname if it	is a directory.

       Following bits may be set by mask field returned	by read(3)

       IN_IGNORED	  Watch	 for  removed  (explicitely,  revoked  or  un-
			  mounted).

       IN_ISDIR		  Subject of this event	is a directory.

       IN_Q_OVERFLOW	  Event	queue has overflowed.

       IN_UNMOUNT	  File system containing  watched  file/directory  was
			  unmounted.

DIRECT MODE
       In this mode the	fd handed over to the user isn't a read()able one, but
       is  actually  a kqueue fd.  This	allows to reduce some copying overhead
       at the cost of being incompatible with how Linux	inotify	fd works.  The
       mode is activated by passing IN_DIRECT to inotify_init1().

       libinotify_direct_readv() is a replacement for the read call in	direct
       mode.   Pass  it	 an  array of struct iovec* of desired size to fill it
       with lists of events.  Each struct iovec* points	to an array of structs
       terminated with a null iovec (iov_base =	NULL).	It is the  caller  re-
       sponsibility to free these arrays.

       libinotify_free_iovec()	Frees  a list of iovec structs returned	by the
       previous	call.

       libinotify_direct_close() is a replacement for the close	call in	direct
       mode.

SEE ALSO
       read(3)

HISTORY
       inotify first appeared in Linux 2.6.13

FreeBSD	Ports 14.quarterly	 July 22, 2024			 LIBINOTIFY(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=inotify_rm_watch&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help