share/man/man9/VOP_CREATE.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 1996 Doug Rabson
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD: src/share/man/man9/VOP_CREATE.9,v 1.9.2.1 2001/12/17 11:30:18 ru Exp $
  30 .\" $DragonFly: src/share/man/man9/VOP_CREATE.9,v 1.3 2003/07/27 05:36:06 hmp Exp $
  31 .\"
  32 .Dd July 24, 1996
  33 .Os
  34 .Dt VOP_CREATE 9
  35 .Sh NAME
  36 .Nm VOP_CREATE ,
  37 .Nm VOP_MKNOD ,
  38 .Nm VOP_MKDIR ,
  39 .Nm VOP_SYMLINK
  40 .Nd create a file, socket, fifo, device, directory or symlink
  41 .Sh SYNOPSIS
  42 .In sys/param.h
  43 .In sys/vnode.h
  44 .In sys/namei.h
  45 .Ft int
  46 .Fn VOP_CREATE "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap"
  47 .Ft int
  48 .Fn VOP_MKNOD "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap"
  49 .Ft int
  50 .Fn VOP_MKDIR "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap"
  51 .Ft int
  52 .Fn VOP_SYMLINK "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" "char *target"
  53 .Sh DESCRIPTION
  54 These entry points create a new file, socket, fifo, device, directory or symlink
  55 in a given directory.
  56 .Pp
  57 The arguments are:
  58 .Bl -tag -width target
  59 .It Fa dvp
  60 the locked vnode of the directory
  61 .It Fa vpp
  62 the address of a variable where the resulting locked vnode should be stored
  63 .It Fa cnp
  64 the pathname component created
  65 .It Fa vap
  66 the attributes that the new object should be created with
  67 .It Fa target
  68 the pathname of the target of the symlink
  69 .El
  70 .Pp
  71 These entry points are called after
  72 .Xr VOP_LOOKUP 9
  73 when an object is being created.
  74 Normally,
  75 .Xr VOP_LOOKUP 9
  76 will have set the
  77 .Dv SAVENAME
  78 flag in
  79 .Fa cnp->cn_flags
  80 to keep the memory pointed to by
  81 .Fa cnp->cn_pnbuf
  82 valid.
  83 If an error is detected when creating the file,
  84 then this memory will be freed.
  85 If the file is created successfully, then it will be freed unless the
  86 .Dv SAVESTART
  87 flag is specified in
  88 .Fa cnp .
  89 .Sh LOCKS
  90 The directory,
  91 .Fa dvp
  92 will be locked on entry and must remain locked on return.
  93 If the call is successful, the new object will be returned locked.
  94 .Sh RETURN VALUES
  95 If successful, the vnode for the new object is placed in
  96 .Fa *vpp
  97 and zero is returned.  Otherwise, an appropriate error is returned.
  98 .Sh PSEUDOCODE
  99 .Bd -literal
 100 int
 101 vop_create(struct vnode *dvp,
 102            struct vnode **vpp,
 103            struct componentname *cnp
 104            struct vattr *vap)
 105 {
 106     int mode = MAKEIMODE(vap->va_type, vap->va_mode);
 107     struct vnode *vp;
 108     int error;
 109
 110     *vpp = NULL;
 111     if ((mode & IFMT) == 0)
 112         mode |= IFREG;
 113
 114     error = SOMEFS_VALLOC(dvp, mode, cnp->cn_cred, &vp);
 115     if (error) {
 116         free(cnp->cn_pnbuf, M_NAMEI);
 117         vput(dvp);
 118         return error;
 119     }
 120
 121     /*
 122      * Update the permissions for the new vnode, including
 123      * copying the group from the directory.
 124      */
 125     ...;
 126
 127 #ifdef QUOTA
 128     /*
 129      * Possibly check quota information.
 130      */
 131     ...;
 132 #endif
 133
 134     /*
 135      * Enter new vnode in directory, taking care that the vnode
 136      * hits the disk before the directory contents are changed.
 137      */
 138     error = ...;
 139
 140     if (error)
 141         goto bad;
 142
 143     if ((cnp->cn_flags & SAVESTART) == 0)
 144         free(cnp->cn_pnbuf, M_NAMEI);
 145     vput(dvp);
 146     *vpp = vp;
 147
 148     return 0;
 149
 150 bad:
 151     /*
 152      * Write error occurred trying to update the inode
 153      * or the directory so must deallocate the inode.
 154      */
 155     free(cnp->cn_pnbuf, M_NAMEI);
 156     vput(vp);
 157
 158     /*
 159      * Deallocate filesystem resources for vp.
 160      */
 161     ...;
 162
 163     vput(dvp);
 164
 165     return error;
 166 }
 167 .Ed
 168 .Sh ERRORS
 169 .Bl -tag -width Er
 170 .It Bq Er ENOSPC
 171 The filesystem is full.
 172 .It Bq Er EDQUOT
 173 Quota exceeded.
 174 .El
 175 .Sh SEE ALSO
 176 .Xr VOP_LOOKUP 9
 177 .Sh HISTORY
 178 The function
 179 .Nm
 180 appeared in
 181 .Bx 4.3 .
 182 .Sh SEE ALSO
 183 .Xr vnode 9
 184 .Sh AUTHORS
 185 This man page was written by
 186 .An Doug Rabson .