world leader in high performance signal processing
Trace: » filesystems

Linux Filesystems API

The Linux VFS

The Filesystem types

The Directory Cache

Inode Handling

Registration and Superblocks

File Locks

Other Functions

The proc filesystem

sysctl interface

proc filesystem interface

The Filesystem for Exporting Kernel Objects

  • sysfs_create_file - create an attribute file for an object.

Synopsis:

int sysfs_create_file ( struct kobject * kobj )

Arguments:

  • kobj - object we're creating for.
  • attr - attribute descriptor.
  • sysfs_add_file_to_group - add an attribute file to a pre-existing group.

Synopsis:

int sysfs_add_file_to_group ( struct kobject * kobj )

Arguments:

  • kobj - object we're acting for.
  • attr - attribute descriptor.
  • group - group name.
  • sysfs_chmod_file - update the modified mode value on an object attribute.

Synopsis:

int sysfs_chmod_file ( struct kobject * kobj )

Arguments:

  • kobj - object we're acting for.
  • attr - attribute descriptor.
  • mode - file permissions.
  • sysfs_remove_file - remove an object attribute.

Synopsis:

void sysfs_remove_file ( struct kobject * kobj )

Arguments:

  • kobj - object we're acting for.
  • attr - attribute descriptor.

Description:

Hash the attribute name and kill the victim.

  • sysfs_remove_file_from_group - remove an attribute file from a group.

Synopsis:

void sysfs_remove_file_from_group ( struct kobject * kobj )

Arguments:

  • kobj - object we're acting for.
  • attr - attribute descriptor.
  • group - group name.
  • sysfs_schedule_callback - helper to schedule a callback for a kobject

Synopsis:

int sysfs_schedule_callback ( struct kobject * kobj )

Arguments:

  • kobj - object we're acting for.
  • func - callback function to invoke later.
  • data - argument to pass to func.
  • owner - module owning the callback code

Description:

sysfs attribute methods must not unregister themselves or their parent kobject (which would amount to the same thing). Attempts to do so will deadlock, since unregistration is mutually exclusive with driver callbacks.

Instead methods can call this routine, which will attempt to allocate and schedule a workqueue request to call back func with data as its argument in the workqueue's process context. kobj will be pinned until func returns.

Returns 0 if the request was submitted, -ENOMEM if storage could not be allocated, -ENODEV if a reference to owner isn't available, -EAGAIN if a callback has already been scheduled for kobj.

  • sysfs_create_link - create symlink between two objects.

Synopsis:

int sysfs_create_link ( struct kobject * kobj )

Arguments:

  • kobj - object whose directory we're creating the link in.
  • target - object we're pointing to.
  • name - name of the symlink.
  • sysfs_remove_link - remove symlink in object's directory.

Synopsis:

void sysfs_remove_link ( struct kobject * kobj )

Arguments:

  • kobj - object we're acting for.
  • name - name of the symlink to remove.
  • sysfs_create_bin_file - create binary file for object.

Synopsis:

int sysfs_create_bin_file ( struct kobject * kobj )

Arguments:

  • kobj - object.
  • attr - attribute descriptor.
  • sysfs_remove_bin_file - remove binary file for object.

Synopsis:

void sysfs_remove_bin_file ( struct kobject * kobj )

Arguments:

  • kobj - object.
  • attr - attribute descriptor.

The debugfs filesystem

debugfs interface

The Linux Journalling API

Overview

Data Types

The journalling layer uses typedefs to 'hide' the concrete definitions of the structures used. As a client of the JBD layer you can just rely on the using the pointer as a magic cookie of some sort. Obviously the hiding is not enforced as this is 'C'.

Functions

The functions here are split into two groups those that affect a journal as a whole, and those which are used to manage transactions

See also

Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie

Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie

splice API

splice is a method for moving blocks of data around inside the kernel, without continually transferring them between the kernel and user space.

  • splice_to_pipe - fill passed data into a pipe

Synopsis:

ssize_t splice_to_pipe ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to fill
  • spd - data to fill

Description:

spd contains a map of pages and len/offset tuples, along with the struct pipe_buf_operations associated with these pages. This function will link that data to the pipe.

  • generic_file_splice_read - splice data from file to a pipe

Synopsis:

ssize_t generic_file_splice_read ( struct file * in )

Arguments:

  • in - file to splice from
  • ppos - position in in
  • pipe - pipe to splice to
  • len - number of bytes to splice
  • flags - splice modifier flags

Description:

Will read pages from given file and fill them into a pipe. Can be used as long as the address_space operations for the source implements a readpage hook.

  • splice_from_pipe_feed - feed available data from a pipe to a file

Synopsis:

int splice_from_pipe_feed ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to splice from
  • sd - information to actor
  • actor - handler that splices the data

Description:

This function loops over the pipe and calls actor to do the actual moving of a single struct pipe_buffer to the desired destination. It returns when there's no more buffers left in the pipe or if the requested number of bytes (sd→total_len) have been copied. It returns a positive number (one) if the pipe needs to be filled with more data, zero if the required number of bytes have been copied and -errno on error.

This, together with splice_from_pipe_{begin,end,next}, may be used to implement the functionality of __splice_from_pipe when locking is required around copying the pipe buffers to the destination.

  • splice_from_pipe_next - wait for some data to splice from

Synopsis:

int splice_from_pipe_next ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to splice from
  • sd - information about the splice operation

Description:

This function will wait for some data and return a positive value (one) if pipe buffers are available. It will return zero or -errno if no more data needs to be spliced.

  • splice_from_pipe_begin - start splicing from pipe

Synopsis:

void splice_from_pipe_begin ( struct splice_desc * sd )

Arguments:

  • sd - information about the splice operation

Description:

This function should be called before a loop containing splice_from_pipe_next and splice_from_pipe_feed to initialize the necessary fields of sd.

  • splice_from_pipe_end - finish splicing from pipe

Synopsis:

void splice_from_pipe_end ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to splice from
  • sd - information about the splice operation

Description:

This function will wake up pipe writers if necessary. It should be called after a loop containing splice_from_pipe_next and splice_from_pipe_feed.

  • __splice_from_pipe - splice data from a pipe to given actor

Synopsis:

ssize_t __splice_from_pipe ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to splice from
  • sd - information to actor
  • actor - handler that splices the data

Description:

This function does little more than loop over the pipe and call actor to do the actual moving of a single struct pipe_buffer to the desired destination. See pipe_to_file, pipe_to_sendpage, or pipe_to_user.

  • splice_from_pipe - splice data from a pipe to a file

Synopsis:

ssize_t splice_from_pipe ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to splice from
  • out - file to splice to
  • ppos - position in out
  • len - how many bytes to splice
  • flags - splice modifier flags
  • actor - handler that splices the data

Description:

See __splice_from_pipe. This function locks the pipe inode, otherwise it's identical to __splice_from_pipe.

  • generic_file_splice_write - splice data from a pipe to a file

Synopsis:

ssize_t generic_file_splice_write ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe info
  • out - file to write to
  • ppos - position in out
  • len - number of bytes to splice
  • flags - splice modifier flags

Description:

Will either move or copy pages (determined by flags options) from the given pipe inode to the given file.

  • generic_splice_sendpage - splice data from a pipe to a socket

Synopsis:

ssize_t generic_splice_sendpage ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - pipe to splice from
  • out - socket to write to
  • ppos - position in out
  • len - number of bytes to splice
  • flags - splice modifier flags

Description:

Will send len bytes from the pipe to a network socket. No data copying is involved.

  • splice_direct_to_actor - splices data directly between two non-pipes

Synopsis:

ssize_t splice_direct_to_actor ( struct file * in )

Arguments:

  • in - file to splice from
  • sd - actor information on where to splice to
  • actor - handles the data splicing

Description:

This is a special case helper to splice directly between two points, without requiring an explicit pipe. Internally an allocated pipe is cached in the process, and reused during the lifetime of that process.

  • do_splice_direct - splices data directly between two files

Synopsis:

long do_splice_direct ( struct file * in )

Arguments:

  • in - file to splice from
  • ppos - input file offset
  • out - file to splice to
  • len - number of bytes to splice
  • flags - splice modifier flags

Description:

For use by do_sendfile. splice can easily emulate sendfile, but doing it in the application would incur an extra system call (splice in + splice out, as compared to just sendfile). So this helper can splice directly through a process-private pipe.

pipes API

Pipe interfaces are all for in-kernel (builtin image) use. They are not exported for use by modules.

  • struct pipe_buffer - a linux kernel pipe buffer

Synopsis:

struct pipe_buffer {
  struct page * page;
  unsigned int offset;
  unsigned int len;
  const struct pipe_buf_operations * ops;
  unsigned int flags;
  unsigned long private;
};  

Members:

  • page - the page containing the data for the pipe buffer
  • offset - offset of data inside the page
  • len - length of data inside the page
  • ops - operations associated with this buffer. See pipe_buf_operations.
  • flags - pipe buffer flags. See above.
  • private - private data owned by the ops.
  • struct pipe_inode_info - a linux kernel pipe

Synopsis:

struct pipe_inode_info {
  wait_queue_head_t wait;
  unsigned int nrbufs;
  unsigned int curbuf;
  struct page * tmp_page;
  unsigned int readers;
  unsigned int writers;
  unsigned int waiting_writers;
  unsigned int r_counter;
  unsigned int w_counter;
  struct fasync_struct * fasync_readers;
  struct fasync_struct * fasync_writers;
  struct inode * inode;
  struct pipe_buffer bufs[PIPE_BUFFERS];
};  

Members:

  • wait - reader/writer wait point in case of empty/full pipe
  • nrbufs - the number of non-empty pipe buffers in this pipe
  • curbuf - the current pipe buffer entry
  • tmp_page - cached released page
  • readers - number of current readers of this pipe
  • writers - number of current writers of this pipe
  • waiting_writers - number of writers blocked waiting for room
  • r_counter - reader counter
  • w_counter - writer counter
  • fasync_readers - reader side fasync
  • fasync_writers - writer side fasync
  • inode - inode this pipe is attached to
  • bufs[PIPE_BUFFERS] - the circular array of pipe buffers
  • generic_pipe_buf_map - virtually map a pipe buffer

Synopsis:

void * generic_pipe_buf_map ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - the pipe that the buffer belongs to
  • buf - the buffer that should be mapped
  • atomic - whether to use an atomic map

Description:

This function returns a kernel virtual address mapping for the pipe_buffer passed in buf. If atomic is set, an atomic map is provided and the caller has to be careful not to fault before calling the unmap function.

Note that this function occupies KM_USER0 if atomic != 0.

  • generic_pipe_buf_unmap - unmap a previously mapped pipe buffer

Synopsis:

void generic_pipe_buf_unmap ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - the pipe that the buffer belongs to
  • buf - the buffer that should be unmapped
  • map_data - the data that the mapping function returned

Description:

This function undoes the mapping that →map provided.

  • generic_pipe_buf_steal - attempt to take ownership of a pipe_buffer

Synopsis:

int generic_pipe_buf_steal ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - the pipe that the buffer belongs to
  • buf - the buffer to attempt to steal

Description:

This function attempts to steal the struct page attached to buf. If successful, this function returns 0 and returns with the page locked. The caller may then reuse the page for whatever he wishes; the typical use is insertion into a different file page cache.

  • generic_pipe_buf_get - get a reference to a struct pipe_buffer

Synopsis:

void generic_pipe_buf_get ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - the pipe that the buffer belongs to
  • buf - the buffer to get a reference to

Description:

This function grabs an extra reference to buf. It's used in in the tee system call, when we duplicate the buffers in one pipe into another.

  • generic_pipe_buf_confirm - verify contents of the pipe buffer

Synopsis:

int generic_pipe_buf_confirm ( struct pipe_inode_info * info )

Arguments:

  • info - the pipe that the buffer belongs to
  • buf - the buffer to confirm

Description:

This function does nothing, because the generic pipe code uses pages that are always good when inserted into the pipe.

  • generic_pipe_buf_release - put a reference to a struct pipe_buffer

Synopsis:

void generic_pipe_buf_release ( struct pipe_inode_info * pipe )

Arguments:

  • pipe - the pipe that the buffer belongs to
  • buf - the buffer to put a reference to

Description:

This function releases a reference to buf.

About This Book

Authors

Legal Notice

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of Linux.