xref: /freebsd/share/man/man9/VOP_CREATE.9 (revision ce834215a70ff69e7e222827437116eee2f9ac6f)
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.\" $Id: VOP_CREATE.9,v 1.3 1997/03/07 03:32:22 mpp Exp $
30.\"
31.Dd July 24, 1996
32.Os
33.Dt VOP_CREATE 9
34.Sh NAME
35.Nm VOP_CREATE ,
36.Nm VOP_MKNOD ,
37.Nm VOP_MKDIR ,
38.Nm VOP_SYMLINK
39.Nd create a file, socket, fifo, device, directory or symlink
40.Sh SYNOPSIS
41.Fd #include <sys/param.h>
42.Fd #include <sys/vnode.h>
43.Fd #include <sys/namei.h>
44.Ft int
45.Fn VOP_CREATE "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap"
46.Ft int
47.Fn VOP_MKNOD "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap"
48.Ft int
49.Fn VOP_MKDIR "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap"
50.Ft int
51.Fn VOP_SYMLINK "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" "char *target"
52.Sh DESCRIPTION
53These entry points create a new file, socket, fifo, device, directory or symlink
54in a given directory.
55.Pp
56The arguments are:
57.Bl -tag -width target
58.It Ar dvp
59the locked vnode of the directory
60.It Ar vpp
61the address of a variable where the resulting locked vnode should be stored
62.It Ar cnp
63the pathname component created
64.It Ar vap
65the attributes that the new object should be created with
66.It Ar target
67the pathname of the target of the symlink
68.El
69.Pp
70These entry points are called after
71.Xr VOP_LOOKUP 9
72when an object is being created.
73Normally,
74.Xr VOP_LOOKUP 9
75will have set the
76.Dv SAVENAME
77flag in
78.Fa cnp->cn_flags
79to keep the memory pointed to by
80.Fa cnp->cn_pnbuf
81valid.
82If an error is detected when creating the file,
83then this memory will be freed.
84If the file is created successfully, then it will be freed unless the
85.Dv SAVESTART
86flag is specified in
87.Fa cnp .
88.Sh LOCKS
89The directory,
90.Fa dvp
91should be locked on entry and will be unlocked and released on exit.
92If the call is successful, the new object will be returned locked,
93unless the call is
94.Xr VOP_MKNOD 9
95or
96.Xr VOP_SYMLINK 9
97in which case the new object is not returned at all.
98It is not clear why
99.Xr VOP_MKNOD 9
100and
101.Xr VOP_SYMLINK 9
102need a
103.Fa *vpp
104argument at all.
105.Sh RETURN VALUES
106If successful, the vnode for the new object is placed in
107.Fa *vpp
108and zero is returned.  Otherwise, an appropriate error is returned.
109.Sh PSEUDOCODE
110.Bd -literal
111int
112vop_create(struct vnode *dvp,
113	   struct vnode **vpp,
114	   struct componentname *cnp
115	   struct vattr *vap)
116{
117    int mode = MAKEIMODE(vap->va_type, vap->va_mode);
118    struct vnode *vp;
119    int error;
120
121    *vpp = NULL;
122    if ((mode & IFMT) == 0)
123	mode |= IFREG;
124
125    error = VOP_VALLOC(dvp, mode, cnp->cn_cred, &vp);
126    if (error) {
127	free(cnp->cn_pnbuf, M_NAMEI);
128	vput(dvp);
129	return error;
130    }
131
132    /*
133     * Update the permissions for the new vnode, including
134     * copying the group from the directory.
135     */
136    ...;
137
138#ifdef QUOTA
139    /*
140     * Possibly check quota information.
141     */
142    ...;
143#endif
144
145    /*
146     * Enter new vnode in directory, taking care that the vnode
147     * hits the disk before the directory contents are changed.
148     */
149    error = ...;
150
151    if (error)
152	goto bad;
153
154    if ((cnp->cn_flags & SAVESTART) == 0)
155	free(cnp->cn_pnbuf, M_NAMEI);
156    vput(dvp);
157    *vpp = vp;
158
159    return 0;
160
161bad:
162    /*
163     * Write error occurred trying to update the inode
164     * or the directory so must deallocate the inode.
165     */
166    free(cnp->cn_pnbuf, M_NAMEI);
167    vput(vp);
168
169    /*
170     * Deallocate filesystem resources for vp.
171     */
172    ...;
173
174    vput(dvp);
175
176    return error;
177}
178.Ed
179.Sh ERRORS
180.Bl -tag -width Er
181.It Bq Er ENOSPC
182The filesystem is full.
183.It Bq Er EDQUOT
184Quota exceeded.
185.El
186.Sh SEE ALSO
187.Xr VOP_LOOKUP 9 ,
188.Xr VOP_VALLOC 9
189.Sh HISTORY
190The function
191.Nm
192appeared in
193.Bx 4.3 .
194.Sh SEE ALSO
195.Xr vnode 9
196.Sh AUTHORS
197This man page was written by Doug Rabson.
198