File:  [DragonFly] / src / share / man / man9 / VOP_LINK.9
Revision 1.3: download - view: text, annotated - select for diffs
Sun Jul 27 05:36:06 2003 UTC (11 years, 4 months ago) by hmp
Branches: MAIN
CVS tags: HEAD
mdoc(7) assorted fixes:

	- Nuke usage of .Ar from Section 9.  The `.Ar' macro
	  should only be used for userland manual pages.

	- Replace usage of `.Ar' with `.Va' or `.Vt' as necessary.

    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_LINK.9,v 1.9.2.3 2001/12/17 11:30:18 ru Exp $
   30: .\" $DragonFly: src/share/man/man9/VOP_LINK.9,v 1.3 2003/07/27 05:36:06 hmp Exp $
   31: .\"
   32: .Dd July 24, 1996
   33: .Os
   34: .Dt VOP_LINK 9
   35: .Sh NAME
   36: .Nm VOP_LINK
   37: .Nd create a new name for a file
   38: .Sh SYNOPSIS
   39: .In sys/param.h
   40: .In sys/vnode.h
   41: .Ft int
   42: .Fn VOP_LINK "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp"
   43: .Sh DESCRIPTION
   44: This links a new name in the specified directory to an existing file.
   45: .Pp
   46: Its arguments are:
   47: .Bl -tag -width 8n
   48: .It Fa dvp
   49: the vnode of the directory
   50: .It Fa vp
   51: the vnode of the file to be linked
   52: .It Fa cnp
   53: pathname information about the file
   54: .El
   55: .Pp
   56: The pathname info must be released on exit.  The directory and
   57: file vnodes should NOT be released on exit.
   58: .Sh LOCKS
   59: The directory,
   60: .Fa dvp
   61: is locked on entry and should remain locked on return.
   62: The file
   63: .Fa vp
   64: is not locked on entry and should remain that way on return.
   65: If your VOP code locks
   66: .Fa vp ,
   67: it must be sure to unlock prior to returning.
   68: .Sh RETURN VALUES
   69: Zero is returned if the file was linked successfully, otherwise an
   70: error is returned.
   71: .Sh PSEUDOCODE
   72: .Bd -literal
   73: int
   74: vop_link(struct vnode *dvp, struct vnode *vp, struct componentname *cnp)
   75: {
   76:     int error = 0;
   77: 
   78:     if (vp->v_mount != dvp->v_mount) {
   79: 	VOP_ABORTOP(dvp, cnp);
   80: 	error = EXDEV;
   81: 	goto out2;
   82:     }
   83:     if (vp != dvp && (error = VOP_LOCK(vp))) {
   84: 	VOP_ABORTOP(dvp, cnp);
   85: 	goto out2;
   86:     }
   87: 
   88:     /*
   89:      * now that we've locked vp, we have to use out1 instead of out2
   90:      */
   91: 
   92:     if (vp would have too many links) {
   93: 	VOP_ABORTOP(dvp, cnp);
   94: 	error = EMLINK;
   95: 	goto out1;
   96:     }
   97: 
   98:     if (vp is immutable) {
   99: 	VOP_ABORTOP(dvp, cnp);
  100: 	error = EPERM;
  101: 	goto out1;
  102:     }
  103: 
  104:     /*
  105:      * Increment link count of vp and write back the on-disc version of it.
  106:      */
  107:     ...;
  108: 
  109:     if (!error) {
  110: 	/*
  111: 	 * Add the new name to the directory.
  112: 	 */
  113: 	...;
  114:     }
  115: 
  116:     free(cnp->cn_pnbuf, M_NAMEI);
  117: out1:
  118:     if (vp != dvp)
  119: 	VOP_UNLOCK(vp);
  120: out2:
  121: 
  122:     return error;
  123: }
  124: .Ed
  125: .Sh ERRORS
  126: .Bl -tag -width Er
  127: .It Bq Er EPERM
  128: the file is immutable
  129: .El
  130: .Sh SEE ALSO
  131: .Xr vnode 9 ,
  132: .Xr vn_lock 9
  133: .Sh AUTHORS
  134: This man page was originally written by
  135: .An Doug Rabson .