xref: /freebsd/share/man/man9/VOP_CREATE.9 (revision 71fe318b852b8dfb3e799cb12ef184750f7f8eac)
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$
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.In sys/param.h
42.In sys/vnode.h
43.In 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
91will be locked on entry and must remain locked on return.
92If the call is successful, the new object will be returned locked.
93.Sh RETURN VALUES
94If successful, the vnode for the new object is placed in
95.Fa *vpp
96and zero is returned.  Otherwise, an appropriate error is returned.
97.Sh PSEUDOCODE
98.Bd -literal
99int
100vop_create(struct vnode *dvp,
101	   struct vnode **vpp,
102	   struct componentname *cnp
103	   struct vattr *vap)
104{
105    int mode = MAKEIMODE(vap->va_type, vap->va_mode);
106    struct vnode *vp;
107    int error;
108
109    *vpp = NULL;
110    if ((mode & IFMT) == 0)
111	mode |= IFREG;
112
113    error = SOMEFS_VALLOC(dvp, mode, cnp->cn_cred, &vp);
114    if (error) {
115	free(cnp->cn_pnbuf, M_NAMEI);
116	vput(dvp);
117	return error;
118    }
119
120    /*
121     * Update the permissions for the new vnode, including
122     * copying the group from the directory.
123     */
124    ...;
125
126#ifdef QUOTA
127    /*
128     * Possibly check quota information.
129     */
130    ...;
131#endif
132
133    /*
134     * Enter new vnode in directory, taking care that the vnode
135     * hits the disk before the directory contents are changed.
136     */
137    error = ...;
138
139    if (error)
140	goto bad;
141
142    if ((cnp->cn_flags & SAVESTART) == 0)
143	free(cnp->cn_pnbuf, M_NAMEI);
144    vput(dvp);
145    *vpp = vp;
146
147    return 0;
148
149bad:
150    /*
151     * Write error occurred trying to update the inode
152     * or the directory so must deallocate the inode.
153     */
154    free(cnp->cn_pnbuf, M_NAMEI);
155    vput(vp);
156
157    /*
158     * Deallocate filesystem resources for vp.
159     */
160    ...;
161
162    vput(dvp);
163
164    return error;
165}
166.Ed
167.Sh ERRORS
168.Bl -tag -width Er
169.It Bq Er ENOSPC
170The filesystem is full.
171.It Bq Er EDQUOT
172The user's filesystem space or inode quota would be exceeded.
173.El
174.Sh SEE ALSO
175.Xr VOP_LOOKUP 9
176.Sh HISTORY
177The function
178.Nm
179appeared in
180.Bx 4.3 .
181.Sh SEE ALSO
182.Xr vnode 9
183.Sh AUTHORS
184This man page was written by
185.An Doug Rabson .
186