ufdcreate Kernel Service

Purpose

Allocates and initializes a file descriptor.

Syntax

#include <fcntl.h>
#include <sys/types.h>
#include <sys/file.h>

int ufdcreate (flags, ops, datap, type, fdp, cnp)

int flags; struct fileops * ops; void * datap; short type; int * fdp; struct ucred *crp;

Parameters

Item	Description
flags	Specifies the flags to save in a file structure. The file structure is defined in the sys/file.h file. If a read or write subroutine is called with the file descriptor returened by this routine, the FREAD and FWRITE flags must be set appropriately. Valid flags are defined in the fcntl.h file.
ops	Points to the list of subsystem-supplied routines to call for the file system operations: read/write, ioctl, select, fstat, and close. The fileops structure is defined in the sys/file.h file. See "File Operations" for more information.
datap	Points to type-dependent structures. The system saves this pointer in the file structure. As a result, the pointer is available to the file operations when they are called.
type	Specifies the unique type value for the file structure. Valid types are listed in the sys/file.h file.
fdp	Points to an integer field where the file descriptor is stored on successful return.
crp	Points to a credentials structure. This pointer is saved in the file struct for use in subsequent operations. It must be a valid ucred struct. The crref() kernel service can be used to obtain a ucred struct.

Description

The ufdcreate kernel service provides a file interface to kernel extensions. Kernel extensions use this service to create a file descriptor and file structure pair. Also, this service allows kernel extensions to provide their own file descriptor-based system calls, enabling read/write, ioctl, select, fstat, and close operations on objects outside the file system. The ufdcreate kernel services does not require the extension to understand or conform to the synchronization requirements of the logical file system (LFS).

The ufdcreate kernel service provides a file descriptor to the caller and creates the underlying file structure. The caller must include pointers to subsystem-supplied routines for the read/write, ioctl, select, fstat, and close operations. If any of the operations are not needed by the calling subsystem, then the caller must provide a pointer to an appropriate errno value. Typically, the EOPNOTSUPP value is used for this purpose. See "File Operations" for information about the requirements for the subsystem-supplied routines.

Removing a File Descriptor

There is no corresponding operation to remove a file descriptor (and the attendant structures) created by the ufdcreate kernel service. To remove a file descriptor, use a call to the close subroutine. The close subroutine can be called from a routine or from within the kernel or kernel extension. If the close is not called, the file is closed when the process exits.

Once a call is made to the ufdcreate kernel service, the file descriptor is considered open before the call to the service returns. When a close or exit subroutine is called, the close file operation specified on the call to the ufdcreate interface is called.

File Operations

The ufdcreate kernel service allows kernel extensions to provide their own file descriptor-based system calls, enabling read/write, ioctl, select, fstat, and close operations on objects outside the file system. The fileops structure defined in the sys/file.h file provides interfaces for these routines.

read/write Requirements

The read/write operation manages input and output to the object specified by the fp parameter. The actions taken by this operation are dependent on the object type. The syntax for the operation is as follows:

#include <sys/types.h>
#include <sys/uio.h>

int (*fo_rw) (fp, rw, uiop, ext)

struct file *fp;
enum uio_rw rw;
struct uio *uiop;
int ext;

The parameters have the following values:

Value	Description
fp	Points to the file structure. This structure corresponds to the file descriptor used on the read or write subroutine.
rw	Contains a UIO_READ value for a read operation or UIO_WRITE value for a write operation.
uiop	Points to a uio structure. This structure describes the location and size information for the input and output requested. The uio structure is defined in the uio.h file.
ext	Specifies subsystem-dependent information. If the readx or writex subroutine is used, the value passed by the operation is passed through to this subroutine. Otherwise, the value is 0.

If successful, the fo_rw operation returns a value of 0. A nonzero return value should be programmed to indicate an error. See the sys/errno.h file for a list of possible values.

Note: On successful return, the uiop->uio_resid field must be updated to include the number of bytes of data actually transferred.

ioctl Requirements

The ioctl operation provides object-dependent special command processing. The ioctl subroutine performs a variety of control operations on the object associated with the specified open file structure. This subroutine is typically used with character or block special files and returns an error for ordinary files.

The control operation provided by the ioctl operation is specific to the object being addressed, as are the data type and contents of the arg parameter.

The syntax for the ioctl operation is as follows:

#include <sys/types.h>
#include <sys/ioctl.h>

int (*fo_ioctl) (fp, cmd, arg, ext, kflag)

struct file *fp;
int cmd, ext, kflag;
caddr_t arg;

The parameters have the following values:

Value	Description
fp	Points to the file structure. This structure corresponds to the file descriptor used by the ioctl subroutine.
cmd	Defines the specific request to be acted upon by this routine.
arg	Contains data that is dependent on the cmd parameter.
ext	Specifies subsystem-specific information. If the ioctlx subroutine is used, the value passed by the application is passed through to this subroutine. Otherwise, the value is 0.
kflag	Determines where the call is made from. The kflag parameter has the value FKERNEL (from the fcntl.h file) if this routine is called through the fp_ioctl interface. Otherwise, its value is 0.

If successful, the fo_ioctl operation returns a value of 0. For errors, the fo_ioctl operation should return a nonzero return value to indicate an error. Refer to the sys/errno.h file for the list of possible values.

select Requirements

The select operation performs a select operation on the object specified by the fp parameter. The syntax for this operation is as follows:

#include <sys/types.h>

int (*fo_select) (fp, corl, reqevents, rtneventsp, notify)

struct file *fp;
int corl;
ushort reqevents, *rtneventsp;
void (notify) ();

The parameters have the following values:

Value	Description
fp	Points to the file structure. This structure corresponds to the file descriptor used by the select subroutine.
corl	Specifies the ID used for correlation in the selnotify kernel service.
reqevents	Identifies the events to check. The poll and select functions define three standard event flags and one informational flag. The sys/poll.h file details the event bit definition. See the fp_select kernel service for information about the possible flags.
rtneventsp	Indicates the returned events pointer. This parameter, passed by reference, indicates the events that are true at the current time. The returned event bits include the request events and an error event indicator.
notify	Points to a routine to call when the specified object invokes the selnotify kernel service for an outstanding asynchronous select or poll event request. If no routine is to be called, this parameter must be null.

If successful, the fo_select operation returns a value of 0. This operation should return a nonzero return value to indicate an error. Refer to the sys/errno.h file for the list of possible values.

fstat Requirements

The fstat operation fills in an attribute structure. Depending on the object type specified by the fp parameter, many fields in the structure may not be applicable. The value passed back from this operation is dependent upon both the object type and what any routine that understands the type is expecting. The syntax for this operation is as follows:

#include <sys/types.h>

int (*fo_fstat) (fp, sbp)

struct file *fp;
struct stat *sbp;

The parameters have the following values:

Value	Description
fp	Points to the file structure. This structure corresponds to the file descriptor used by the stat subroutine.
sbp	Points to the stat structure to be filled in by this operation. The address supplied is in kernel space.

If successful, the fo_fstat operation returns a value of 0. A nonzero return value should be programmed to indicate an error. Refer to the sys/errno.h file for the list of possible values.

close Requirements

The close operation invalidates routine access to objects specified by the fp parameter and releases any data associated with that access. This operation is called from the close subroutine code when the file structure use count is decremented to 0. For example, if there are multiple accesses to an object (created by the dup, fork, or other subsystem-specific operation), the close subroutine calls the close operation when it determines that there is no remaining access through the file structure being closed.

A file descriptor is considered open once a file descriptor and file structure have been set up by the LFS. The close file operation is called whenever a close or exit is specified. As a result, the close operation must be able to close an object that is not fully open, depending on what the caller did before the file structure was initialized.

The syntax for the close operation is as follows:

#include <sys/file.h>

int (*fo_close) (fp)
struct file *fp;

The parameter is:

Item	Description
fp	Points to the file structure. This structure corresponds to the file descriptor used by the close subroutine.

If successful, the fo_close operation returns a value of 0. This operation should return a nonzero return value to indicate an error. Refer to the sys/errno.h file for the list of possible values.

Execution Environment

The ufdcreate kernel service can be called from the process environment only.

Return Values

If the ufdcreate kernel service succeeds, it returns a value of 0. If the kernel service fails, it returns a nonzero value and sets the errno global variable.

Error Codes

The ufdcreate kernel service fails if one or more of the following errors occur:

Error	Description
EINVAL	The ops parameter is null, or the fileops structure does not have entries for for every operation.
EMFILE	All file descriptors for the process have already been allocated.
ENFILE	The system file table is full.